Pivotal Knowledge Base

Follow

Pivotal GemFire XD Hibernate Dialect

The attached GemFire XD Hibernate dialect file defines the GemFire XD variant of the SQL language. You can use the hibernate dialect file along with the GemFire XD JDBC driver to configure GemFire XD as a database for developing Hibernate projects. 

The topics in this section describe how to install and use the GemFire XD dialect file with Hibernate projects. The examples use the hibernate tutorial files that are available from the Hibernate community site, and the dialect file attached to this article.

Prerequisites

Integrating GemFire XD with a Hibernate project has the following requirements and recommendations:

  • Hibernate 3.1 or later. 
    Note: If you need to use a version of Hibernate prior to 3.1 with GemFire XD, specify the Apache Derby dialect (not the GemFire XD Hibernate dialect) for your project.
  • GemFire XD 1.x installation with the Hibernate dialect file.             
  • (Recommended) JBoss Maven repository for setting up and compiling Hibernate projects. In the examples it is assumed that you have installed Maven in your development environment.             
  • (Recommended) Hibernate tutorial files for following the examples in this section. Unzip the files to a local directory (it is assumed that the files are available at /hibernate-tutorials).

Generate DDL Statements

Generate DDL scripts for your project, either by:

  • Writing new DDL statements in a SQL script file that you can execute using gfxd.
  • Using the gfxd utility to export the DDL from an existing database to a file.  You can then modify the file to add GemFire XD-specific DDL extensions, such as for partitioning and replicating tables.  After modifying the script, use gfxd to import the generated DDL into a GemFire XD database that you will use in your hibernate project.

Note:  See Using GFXD Commands to Export and Import Data in the GemFire XD documentation for instructions and examples of exporting DDL from an existing database, modifying the DDL, and importing the DDL to GemFire XD.

Add the Dialect File and JDBC Driver to Your Project

Both the GemFire XD JDBC thin client driver JAR file and the GemFire XD hibernate dialect file must be available as resources to your hibernate projects.

Procedure

To add the dialect file and JDBC driver to your project, do one of the following:

  • Install these files to your local Maven repository (using a unique groupId and  artifactId) and then reference the resources in project files.
  • Edit your project file to directly specify the local files as system resources. For example, open the /hibernate-tutorials/pom.xml file in a text editor, and add the following system resources:
    ...
       <dependencies>
            <!-- GemFire XD dependencies -->
            <dependency>
              <groupId>com.pivotal</groupId>
              <artifactId>gfxd-client</artifactId>
              <version>1.0</version>
              <scope>system</scope>
              <systemPath>/Pivotal_GemFireXD_10_b46155/lib/gemfirexd-client.jar</systemPath>
            </dependency>
    
            <dependency>
              <groupId>com.pivotal</groupId>
              <artifactId>gfxd-dialect</artifactId>
              <version>1.0</version>
              <scope>system</scope>
              <systemPath>/Pivotal_GemFireXD_10_b46155/lib/gfxdHibernateDialect.jar</systemPath>
            </dependency>
            ...    </dependencies> ...

Note: The above example assumes that you have installed GemFire XD in the /Pivotal_GemFireXD_10_b6155 directory, and that you have copied the Hibernate dialect JAR file into /Pivotal_GemFireXD_10_b46155/lib.  Substitute the correct paths to for your installation.

Configure the Dialect Version and JDBC Connection

The hibernate.cfg.xml file configures JDBC connection information as well as the version of the SQL dialect to use. GemFire XD provides dialect versions to correspond with the feature set of a base snapshot version of Hibernate. Use com.pivotal.gemfirexd.hibernate.GemFireXDDialect for all current (4.1) Hibernate versions.

Procedure

To configure the dialect version:

  1. Specify one of the above strings as the dialect property in hibernate.cfg.xml or hibernate.properties. For example, edit the /hibernate-tutorials/basic/src/test/hibernate.cfg.xml file and change the existing property definition as follows: 
    <!-- SQL dialect -->
    <property name="dialect">com.pivotal.gemfirexd.hibernate.GemFireXDDialect</property>
  2. Define the GemFire XD JDBC driver class and connection properties as you would for other JDBC clients, by specifying the driver class and thin-client connection string. For example, in hibernate.cfg.xml edit connection properties similar to:
<!-- Database connection settings -->
<property name="connection.driver_class">com.pivotal.gemfirexd.jdbc.ClientDriver</property>
<property name="connection.url">jdbc:gemfirexd://localhost:1527</property>
<property name="connection.username">gfxd</property>
<property name="connection.password">gfxd</property>


Note: If you have enabled authentication in GemFire XD, specify a valid username and password combination. If you have not enabled authentication, specify any value for the username and password. Keep in mind that GemFire XD uses the username as the default schema name for creating new tables.

Note: If you are using an older version of Hibernate, specify one of the following GemFire XD dialect versions instead of com.pivotal.gemfirexd.hibernate.GemFireXDDialect:

GemFire XD Dialect Version: Archived Hibernate Version(s):
com.pivotal.gemfirexd.hibernate.v4.v0.GemFireXDDialect

4.0.1.Final

com.pivotal.gemfirexd.hibernate.v3.v6.GemFireXDDialect

3.6.0.Final, 3.6.10

com.pivotal.gemfirexd.hibernate.v3.GemFireXDDialect

3.1.3, 3.2.0GA, 3.2.7, 3.3.0.GA, 3.3.0.SP1, 3.3.1GA, 3.3.2GA, 3.5.1Final

Run the Basic Hibernate Tutorial

After you make the above changes to the Hibernate tutorial files, run the basic Hibernate tutorial with GemFire XD as the database.

Procedure

  1. Ensure that the GemFire XD distributed system is running and that you can connect using the JDBC connection string.
  2. Generate and execute the necessary DDL statements in the target GemFire XD database as described in "Generate DDL Statements" above. See Using GFXD Commands to Export and Import Data for more information and examples.
  3. Change to the basic Hibernate tutorial directory:
    cd /hibernate-tutorials/basic
  4. Build the project and run the basic tutorial:
    mvn test
  5. In the output, verify that the GemFire XD dialect and JDBC driver are used:
    INFO: HHH000401: using driver [com.pivotal.gemfirexd.jdbc.ClientDriver] at URL [jdbc:gemfirexd://localhost:1527]
    Jul 3, 2012 3:15:24 PM org.hibernate.service.jdbc.connections.internal.DriverManagerConnectionProviderImpl configure
    INFO: HHH000046: Connection properties: {user=gfxd, password=****}
    Jul 3, 2012 3:15:24 PM org.hibernate.dialect.Dialect <init>
    INFO: HHH000400: Using dialect: com.pivotal.gemfirexd.hibernate.GemFireXDDialect
    Jul 3, 2012 3:15:24 PM com.pivotal.gemfirexd.hibernate.GemFireXDDialectBase <init>
    
  6. Connect to GemFire XD using gfxd to validate that the table is created:
    $ gfxd
    gfxd> connect client 'localhost:1527';
    gfxd> select * from gfxd.events;
    EVENT_ID            |EVENT_DATE                |TITLE                                                                                                                           
    --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
    1                   |2012-07-03 15:15:24.573   |Our very first event!                                                                                                           
    2                   |2012-07-03 15:15:24.671   |A follow up event                                                                                                               
    
    2 rows selected

    Limitations

    By default, the table DDL that is generated for identity columns uses  the GENERATED ALWAYS AS IDENTITY syntax. You can override this behavior by setting the GFXD_GENERATE_IDENTITY environment variable to "BYDEFAULT". With the "BYDEFAULT" setting, table DDL uses the GENERATED BY DEFAULT IDENTITY syntax for identity columns.

    GemFire XD does not support using the hbm2ddl tool with the hibernate dialect. 

Comments

Powered by Zendesk