com.smartgwt.client.docs
Interface HibernateIntegration

public interface HibernateIntegration

Integration with Hibernate

Smart GWT can integrate with Hibernate in two main ways, both of which are enabled by creating a DataSource descriptor (.ds.xml file) with serverType="hibernate":

• Pre-existing beans: a Smart GWT DataSource can be automatically derived from either a Hibernate-managed bean or the Hibernate mapping. Use schemaBean to derive from the bean or autoDeriveSchema to derive from the mapping. In this case you will initially have a very short .ds.xml per bean - no <fields> are required unless and until you want to override the automatically derived fields.
• "Beanless" mode: Smart GWT can drive Hibernate as a storage layer only, automatically generating Hibernate configuration from a Smart GWT DataSource file (dataSourceID.ds.xml). In this case, you do not write a Java bean or create Hibernate mappings; Hibernate's beanless "dynamic model" mode is used.

Which mode to use is primarily a matter of preference and pre-existing code. However, if you do not have pre-existing code or other special circumstances, the following approach is the most productive:

1. use "beanless" mode, specifying fields in Smart GWT's .ds.xml format (far more compact than a Java bean with a getter and setter for each field)
2. add business logic as needed via DMI, custom server validators, and other approaches covered in the QuickStart Guide
3. call any reusable DMI methods both via your Smart GWT UI and via other, non-UI related Java logic (the DMI methods are now a reusable "data services tier")
4. only create an actual Java bean if you discover re-usable, bean-specific business logic that cannot be encapsulated as a data service (rare)

Hibernate Configuration

You can provide Hibernate configuration to the Smart GWT server in three ways:

• You can place a traditional hibernate.cfg.xml file somewhere on the classpath
• You can have Smart GWT look up a Hibernate Configuration to use. This works in the same way as a ServerObject, and in fact makes use of the ServerObject code. To do this, add ServerObject-compliant properties to your server.properties file, prefixed with hibernate.config. For example:

           hibernate.config.lookupStyle: spring
           hibernate.config.bean: mySessionFactory
    

• You can provide a Hibernate configuration at the level of individual DataSources, by specifying a configBean on the dataSource (this is only applicable if you are using Spring; see below)

If you choose to have Smart GWT lookup the Hibernate configuration, and you specify a lookupStyle of "spring", Smart GWT will make use of a Hibernate SessionFactory configured by Spring. It is possible to set up multiple Hibernate configurations in Spring, and to map individual DataSources to different configurations by making use of the dataSource.configBean property mentioned above. Please note the following caveats:

• DataSource-level Hibernate configuration is intended for unusual cases, such as when the physical data store for one DataSource is actually a different database. Hibernate relations between entities with different configurations do not work
• Whilst it is possible to have traditional mapped beans alongside Smart GWT "beanless" on-the-fly mappings, we cannot share the Hibernate configuration because on-the-fly mapping requires the SessionFactory to be rebuilt for each new mapping. Spring will not allow this, so we fall back to a second Hibernate configuration, specified via a .cfg.xml file as described above, for on-the-fly mappings.

Mapping DSRequest/DSResponse to Hibernate

This integration strategy uses the server-side Java APIs described in ServerDataIntegration. Two complete examples of Hibernate integration are provided in the SDK, one using DMI and one using RPCManager dispatch. Both are accessible from the SDK Explorer as Examples->Server Integration, and both include sample Hibernate configuration as well as a sample UI capable of loading and saving data.

• "Custom DataSource Integration with Hibernate" shows how to create a .jsp that uses RPCManager dispatch to implement all four DataSource request operationTypes via Hibernate for a sample bean.
• "Spring DataSource Integration using DMI to Hibernate" shows how to use Smart GWT Direct Method Invocation (DMI) to implement all four DataSource operations with Hibernate. This particular example uses Spring-based lookup of the target for DMI, however, the same approach will work without Spring - see other DMI examples on the same page for non-Spring methods of DMI target lookup.

As discussed under DMI, whether to use DMI or RPCManager dispatch is largely a matter of preference, however if you are already using Spring, a DMI-based approach is probably a better fit.

serverType:"hibernate"

As with DataSources using Smart GWT's built-in SQL engine, you need only create a DataSource in XML format - no Java classes or other configuration are required. The Admin Console's "Import DataSources" section can be used to import test data into serverType:"hibernate" DataSources in the same manner as SQLDataSources.

Hibernate relations

Hibernate data sources transparently support relations:

• To specify many-to-one relation you have to declare it in data source definition with property foreignKey pointing to releted data source's primary key:

                 <field name="country" foreignKey="countryManyToOne.countryId"/>
             

  Client-side will recieve only ID of related entity while server-side will use real related entity loaded from data base.

  You can instruct data source to send encapsulated related entity by setting type property to the name of related data source:

                 <field name="country" type="countryManyToOne" foreignKey="countryManyToOne.countryId"/>
             

• To specify one-to-many relation you have to declare it in data source definition with property foreignKey pointing to releted data source's primary key and property multiple set to true:

                 <field name="cities" multiple="true" foreignKey="cityOneToMany.cityId"/>
             

  Client-side will recieve only list of related ID's while server-side will use real related entity list loaded from data base.

  You can instruct data source to send list of encapsulated related entities by setting type property to the name of related data source:

                 <field name="cities" multiple="true" type="cityOneToMany" foreignKey="cityOneToMany.cityId"/>
             

  Saving parent entity automatically makes all required Hibernate calls to synchronize underlying list.

Notes on bidirectional relations:

• When encapsulated related entity is sent to client it will not have reference to parent object (avoided recursion).
• Make sure you are updating "owning" side of relation. All changes to "non-owning" relation side are silently discarded.