com.smartgwt.client.docs
Interface JpaIntegration

public interface JpaIntegration

Integration with JPA

JPA 1.0 and JPA 2.0 annotated entities can be used as Smart GWT data sources. The implementation class for JPA 1.0 is com.isomorphic.jpa.JPADataSource. The implementation class for JPA 2.0 is com.isomorphic.jpa.JPA2DataSource. Both implementations support search with simple Criteria and AdvancedCriteria.
JPA 1.0 and JPA 2.0 implementations use JPQL for data fetch. Note: MySQL DB - 'like' operator is used in a case insensitive manner. Check MySQL Reference Manual :: C.5.5.1 Case Sensitivity in String Searches for more information.

JPA 2.0 implementation uses Metadata API for data source generation from mapped entities.

JPA configuration

JPA configuration should be specified in the persistence.xml file and placed in the /WEB-INF/classes/META-INF directory.
For JPA 2.0 make sure you correctly declare its usage in persistence.xml:

  <persistence
      version="2.0"
      xmlns="http://java.sun.com/xml/ns/persistence"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd"
  >
  ...
  </persistence>

To use JPA annotated entities you have to create a DataSource with these properties

• serverConstructor - either JPA 1.0 DataSource implementation: com.isomorphic.jpa.JPADataSource or JPA 2.0 implementation: com.isomorphic.jpa.JPA2DataSource
.
• beanClassName - fully qualified class name of JPA entity

For example:

  <DataSource
      ID="countryDS"
      serverConstructor="com.isomorphic.jpa.JPA2DataSource"
      beanClassName="com.smartgwt.sample.showcase.server.jpa.Country"
  >
      <fields>
  <!-- ... Fields definition ... -->
      </fields>
  </DataSource>
  

Supports field definitions with valueXPath settings. Entity property is accessed (by priority):

1. valueXPath - supports only simple XPath definitions: "property/subProperty/subSubProperty"
2. name - most often used when data source field name is the same as entity property name

JPA transactions

JPA provides three mechanisms for transactions: for JEE applications JPA provides integration with JTA (Bean Managed Transactions and Container Managed Transactions); for JSE applications JPA has a native EntityTransaction implementation (Locally Managed Transactions). The transaction mechanism should be configured in the server.properties file by setting property jpa.emfProvider to the fully qualified class name of the provider (implementation of com.isomorphic.jpa.EMFProviderInterface). Smart GWT comes with three implementations:

• com.isomorphic.jpa.EMFProviderLMT - for Locally Managed Transactions. Every fetch or DML operation starts a new transaction and commits after successful execution.
  This implementation reads the jpa.persistenceUnitName property from the server.properties file. The value of this property needs to be set to the name of the persistence unit configured in persistence.xml file. For example:

    jpa.persistenceUnitName: PERSISTENCE_UNIT_NAME
         

• com.isomorphic.jpa.EMFProviderBMT - for Bean Managed Transactions. Every fetch or DML operation acquires the transaction object from the container and starts it.
  This implementation reads two properties from the server.properties file: jpa.entityManager and jpa.entityManagerFactory containing appropriate resource name references configured in /WEB-INF/web.xml. Configuration example:

    <!-- EntityManager resource reference name declaration -->
    <persistence-context-ref>
       <persistence-context-ref-name>persistence/em</persistence-context-ref-name>
       <persistence-unit-name>PERSISTENCE_UNIT_NAME</persistence-unit-name>
    </persistence-context-ref>
   
    <!-- EntityManagerFactory resource reference name declaration -->
     <persistence-unit-ref>
         <persistence-unit-ref-name>persistence/emf</persistence-unit-ref-name>
         <persistence-unit-name>PERSISTENCE_UNIT_NAME</persistence-unit-name>
     </persistence-unit-ref>
   
    #Property values for sample references:
    jpa.entityManager: persistence/em
    jpa.entityManagerFactory: persistence/emf
         

• com.isomorphic.jpa.EMFProviderCMT - for Container Managed Transactions. Every fetch or DML operation acquires the transaction object from the JEE container. After successful method execution the container commits the transaction. In case of execution failure tx.setRollbackOnly() is used to notify container to rollback the transaction.
  This implementation reads two properties from the server.properties file: jpa.entityManager and jpa.entityManagerFactory containing appropriate resource name references configured in /META-INF/ejb-jar.xml. Configuration example:

    <?xml version="1.0" encoding="UTF-8"?>
    <ejb-jar
         version = "3.0"
         xmlns = "http://java.sun.com/xml/ns/javaee"
         xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation = "http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/ejb-jar_3_0.xsd">
         <enterprise-beans>
             <session>
                 <ejb-name>TestEJB</ejb-name>
                 <persistence-context-ref>
                     <persistence-context-ref-name>persistence/em</persistence-context-ref-name>
                     <persistence-unit-name>PERSISTENCE_UNIT_NAME</persistence-unit-name>
                 </persistence-context-ref>
                 <persistence-unit-ref>
                     <persistence-unit-ref-name>persistence/emf</persistence-unit-ref-name>
                     <persistence-unit-name>PERSISTENCE_UNIT_NAME</persistence-unit-name>
                 </persistence-unit-ref>
            </session>
        </enterprise-beans>
    </ejb-jar>
   
    #Property values for sample references:
    jpa.entityManager: persistence/em
    jpa.entityManagerFactory: persistence/emf
         

• com.isomorphic.jpa.EMFProviderNoTransactions - transactions are not used.
  From the server.properties file this implementation reads the jpa.persistenceUnitName property which must containt the name of persistence unit configured in persistence.xml file. For example:

    jpa.persistenceUnitName: PERSISTENCE_UNIT_NAME
         

You can set jpa.emfProvider to your own implementation of com.isomorphic.jpa.EMFProviderInterface if you have specific requirements for transaction handling. EMF will instantiate provided implementation on initialization (static) and will use same instance every time. By using own implementation you can have complete control over creating/using EntityManagerFactory and EntityManager instances. For example: you can create EMFProviderSpring which will look-up EntityManagerFactory and EntityManager instances in Spring and will feed it to JPADataSource.

Additional configurations:

In case you have several persistence units defined in your persistence.xml you can have additional configurations in server.properties file. Additional configurations (prefixed with jpa.) should have name, emfProvider property and other properties required by specified EMF provider implementation. For example:

  jpa.configName.emfProvider: com.isomorphic.jpa.EMFProviderLMT
  jpa.configName.persistenceUnitName: ANOTHER_PERSISTENCE_UNIT_NAME

To use additional JPA configuration you have to set jpaConfig property in data source definition:

  <DataSource
      ID="countryDS"
      serverConstructor="com.isomorphic.jpa.JPA2DataSource"
      beanClassName="com.smartgwt.sample.showcase.server.jpa.Country"
      jpaConfig="configName"
  >

Transaction management:

• Operating under RPCManager (DSRequest has reference to RPCManager):
  • If participating in automatic transactions:
    • retrieves existing transaction from RPCManager (if available);
    • starts new transaction (if not found in RPCManager);
  • If one transaction per operation is used - starts new transaction;
  • Registers itself to DSRequest.registerCallback() for onSuccess()/ onFailure() execution to commit/roll back transaction;
  • Sets DSRequest.setFreeOnExecute() to false to postpone releasing of EntityManager avoiding lazy loading exceptions when creating JS response and traversing through persistent object tree;
  • Registers itself to RPCManager.registerFreeResourcesHandler() for freeResources() execution to release EntityManager.
  
  If you want to use same EntityManager and transaction in your custom data source implementation you can acquire it by

  JPAConnectionHolder holder = DataSource.getTransactionObject(req, EMF.TRANSACTION_ATTR);

  JPAConnectionHolder instance contains references to entity manager and transaction object used by JPADataSource. You should never commit/rollback automatic transaction. Overall commit/rollback will be issued by RPCManager and will be handled by JPADataSource object which started transaction.
• Operating without RPCManager:
  • starts new transaction;
  • commits/rolls back transaction and releases EntityManager if DSRequest.setFreeOnExecute() is set to true (defalut);
  • relies on calling code to call onSuccess()/onFailure() to commit/roll back transaction and to call freeResources() to release EntityManager.
    Example code for data source operation execution with manual transaction handling:

                   DSRequest req = new DSRequest("myDS", "fetch");
                   req.setFreeOnExecute(false);
                   DSResponse resp = req.execute();
                   List dataList = resp.getDataList();
                   //... traverse through persistent object tree
                   // Commit current transaction.
                   ((JPADataSource) r.getDataSource()).onSuccess();
                   // Release entity manager.
                   ((JPADataSource) r.getDataSource()).freeResources(req);
               

JPA relations

JPA data sources transparently support JPA 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 the database.

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

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

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

Notes on bidirectional relations:

• When the encapsulated related entity is sent to the client it will not have a reference to the parent object (to avoid recursion).
• When performing updates, make sure you update the entity that "owns" the relation. All changes to "non-owning" relations are silently discarded.

Implementations are not thread-safe. Datasource acquiring mechanism ensures that a single instance of this class will be used in one thread only.