<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % CustomDTD SYSTEM "../../../../../../docbook/custom.dtd">
%CustomDTD;
]>
<chapter id="using_hibernate">
    <title>Using Teiid with Hibernate</title>
    <section>
        <title>Limitations</title>
        <itemizedlist>
        	<listitem>
        		<para>Many Hibernate use cases assume a data source has the ability (with proper user permissions) 
        to process Data Definition Language (DDL) statements like CREATE TABLE and DROP TABLE 
        as well as Data Manipulation Language (DML) statements like SELECT, UPDATE, INSERT and DELETE. 
        Teiid can handle a broad range of DML, but does not support directly support DDL against a particular source.</para>
        	</listitem>
        	<listitem>
        		<para>Sequence and Identity generation are not supported.  
        		Identifier generation based upon table values, such as the hilo generator, require that the identifier table(s) be exposed through Teiid.  
        		The GUID identifier generation strategy is directly supported.</para>
        	</listitem>
        </itemizedlist>
    </section>
    
    <section>
        <title>Configuration</title>
        <para>For the most part, interacting with Teiid VDBs (Virtual Databases) from Hibernate is no 
        different from working with any other type of data source.  
        First you must place Teiid JDBC API client JAR file and Teiid's hibernate dialect JAR in Hibernate’s classpath.  
        These files can be found in <code>&lt;jboss-install&gt;/server/&lt;profile&gt;/lib</code> directory. </para>
        <itemizedlist>
            <listitem><para>teiid-&versionNumber;-client.jar</para></listitem>
            <listitem><para>teiid-hibernate-dialect-&versionNumber;.jar</para></listitem>
        </itemizedlist>
        
        <para>These JAR files have the <code>org.teiid.dialect.TeiidDialect</code> and <code>org.teiid.jdbc.TeiidDriver</code> and 
        <code>org.teiid.jdbc.TeiidDataSource</code> classes.</para>
        
        <orderedlist>
        <para>You then configure Hibernate (via hibernate.cfg.xml) as follows:</para>
        <listitem>
        	<para>Specify the Teiid driver 
        class in the "connection.driver_class" property:

       <programlisting><![CDATA[<property name="connection.driver_class">
     org.teiid.jdbc.TeiidDriver
</property>]]></programlisting>         
        	</para>
        </listitem>
        <listitem>        
       <para>Specify the URL for the VDB in the "connection.url" property 
       (replacing terms in angle brackets with the appropriate values):
       
       <programlisting><![CDATA[<property name="connection.url">
	jdbc:teiid:<vdb-name>@mm://<host>:<port>;user=<user-name>;password=<password>
</property>]]></programlisting>
       <note><para>Be sure to use a <xref linkend="local_connection"/> if Hibernate is in the same VM as the application server.</para></note>
       </para>      
       </listitem>
       <listitem>
       <para>Specify the Teiid dialect class in the “dialect” property:
       
       <programlisting><![CDATA[<property name="dialect">
	org.teiid.dialect.TeiidDialect
</property>]]></programlisting>      
       </para>
       <para>Alternatively, if you put your connection properties in <code>hibernate.properties</code> 
       instead of <code>hibernate.cfg.xml</code>, they would look like this: </para>
       
       <programlisting><![CDATA[hibernate.connection.driver_class=org.teiid.jdbc.TeiidDriver
hibernate.connection.url=jdbc:teiid:<vdb-name>@mm://<host>:<port>
hibernate.connection.username=<user-name>
hibernate.connection.password=<password>
hibernate.dialect=org.teiid.dialect.TeiidDialect]]></programlisting>    
       </listitem>
       </orderedlist>  
                
       <para>Note also that since your VDBs will likely contain multiple source and view models 
       with identical table names, you will need to fully qualify table names 
       specified in Hibernate mapping files:</para>         
       
       <programlisting><![CDATA[<class name="<Class name>" table="<Source/view model name>.[<schema name>.]<Table name>">
	...
</class>]]></programlisting>
       
       <example>
       <title>Example Mapping</title>
       <programlisting><![CDATA[<class name="org.teiid.example.Publisher" table="BOOKS.BOOKS.PUBLISHERS">
	...
</class>]]></programlisting>
       </example>
    </section>
    
</chapter>