JPA in NiCE

Table of Contents

• The Java Persistence API
• Java Persistence API annotations
• The OSGi runtime configuration for JPA in NiCE
• Maven-Tycho Build Configuration
• References

The Java Persistence API

The Java Persistence Architecture API (JPA) is a Java library for manipulating data with a relational database using annotated Java objects. This process requires setting up a utility method for establishing a connection to the database via EntityManager (produced from an Entity Manager Factory) and adding modifications via annotations to the existing data structure to handle persisted data.

Nevertheless, JPA does have some issues with trying to handle data conversions from an annotated POJO to the respectable query. They are listed below:

• JPA can handle only one dimension of listed data. JPA can not handle multi-dimensional arrays or hashmaps without an adapter.
• JPA can only establish a relational link to generics by specifying abstract classes in relational mapping. Not interfaces.
• If an object in memory is referencing another object that is not a primitive or is not annotated correctly, JPA will not be able to manipulate that data in a database. Therefore, it should be avoided with an annotation to ignore that piece of data for database manipulation (Transient). One-dimensional lists and arrays are an exception!
• Overridden POJO objects during runtime can not be manipulated by JPA.
• There seem to be some restrictive column names within JPA. "Translation" as a column name is restricted. There may be more.

Java Persistence API annotations

Listed below are some sample annotations and definitions used on the data structures within NiCE.

• @Entity - Used to specify if an object is persist-able in a database.
• @Id - Specifies the unique ID column in a database.
• @Table - Specifies the Table Information (such as names) in a database.
• @TableGenerator - Used in specifying how Ids are generated during runtime.
• @OneToOne, OneToMany, ManyToMany, ManyToOne - Used in specifying the directional relationship between one object and the next. One must use fetch = fetchType.EAGER for the associations to reflect for cascading operations.
• @Inheritance - Determines if an object inherits from another object.

The OSGi runtime configuration for JPA in NiCE

NiCE uses the JPA to store data from client-server transactions in an SQL database, and by default, it uses the embedded version of Apache Derby. The exact configuration and persistence headers of the database are defined in two different persistence units: gov.ornl.nice.niceitem and gov.ornl.nice.nicedatastructures. NiCE utilizes two separate databases due to the inability for cross-bundle persistence units. The following is an example of the persistence.xml file (Both pieces are for ITEM):

<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"
    version="2.0" xmlns="http://java.sun.com/xml/ns/persistence">
    <persistence-unit name="gov.ornl.nice.niceitem"
        transaction-type="RESOURCE_LOCAL">

<provider>org.eclipse.persistence.jpa.PersistenceProvider</provider>
<class>gov.ornl.nice.niceitem.item.Item</class>
<class>gov.ornl.nice.niceitem.item.jobLauncher.JobLauncher</class>;
<class>gov.ornl.nice.niceitem.item.jobprofile.JobProfile</class>
<properties>

            <property name="javax.persistence.jdbc.driver" value="org.apache.derby.jdbc.EmbeddedDriver">
            <property name="javax.persistence.jdbc.url" value="jdbc:derby:database/itemDatabase;create=true">
            <property name="javax.persistence.jdbc.user" value="APP" />
            <property name="javax.persistence.jdbc.password" value="APP" />

            <property name="eclipselink.ddl-generation" value="create-tables"/>
            <property name="eclipselink.ddl-generation.output-mode" value="database"/>
            <property name="eclipselink.weaving" value="false" />

            <property name="eclipselink.logging.level" value="OFF" />
            <property name="eclipselink.logging.thread" value="false" />
            <property name="eclipselink.logging.session" value="true" />
            <property name="eclipselink.logging.exceptions" value="true" />
            <property name="eclipselink.logging.timestamp" value="false" />
        </property>
    </persistence-unit>
</persistence>

and the MANIFEST.MF file (note the Meta-Persistence and JPA-PersistenceUnits headers):

Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: NiCEItem
Bundle-SymbolicName: gov.ornl.nice.niceitem
Bundle-Version: 2.0.0
Bundle-RequiredExecutionEnvironment: JavaSE-1.6
Import-Package: com.jcraft.jsch;version="0.1.41",
 gov.ornl.nice.nicedatastructures.NiCEObject,
 gov.ornl.nice.nicedatastructures.componentVisitor,
 gov.ornl.nice.nicedatastructures.form,
 gov.ornl.nice.nicedatastructures.form.geometry,
 gov.ornl.nice.nicedatastructures.form.painfullySimpleForm,
 gov.ornl.nice.nicedatastructures.location,
 gov.ornl.nice.nicedatastructures.resource,
 gov.ornl.nice.nicedatastructures.updateableComposite,
 javax.persistence;jpa="2.0";version="1.1.0",
 org.apache.derby.jdbc
Export-Package: gov.ornl.nice.niceitem.item,
 gov.ornl.nice.niceitem.item.action,
 gov.ornl.nice.niceitem.item.jobLauncher,
 gov.ornl.nice.niceitem.item.jobprofile
Require-Bundle: org.eclipse.core.resources;bundle-version="3.7.100",
 org.eclipse.core.runtime;bundle-version="3.7.0"
Service-Component: OSGi-INF/jobProfileComponent.xml, OSGi-INF/multiLauncherComponent.xml, OSGi-INF/geometryEditorComponent.xml
Meta-Persistence: META-INF/persistence.xml
JPA-PersistenceUnits: gov.ornl.nice.niceitem

The JPA provider for NiCE is the Eclipse Gemini Project. Gemini requires the following bundles to execute, and NiCE uses the associated run levels to ensure that javax.persistence, Derby, and the OSGi Enterprise bundle are running before Gemini, as well as that all of the following bundles are auto-started by the framework.

Bundle	OSGi Run Level	Notes
javax.persistence	1	Must be running before all other JPA-related bundles. Needs 2.0.4+
org.apache.derby	2	Provided with Gemini, version 10.8.2.2
osgi.enterprise	2	OSGi Enterprise bundle
org.eclipse.gemini.dbaccess.derby and org.eclipse.gemini.dbaccess.util 1.1.0RC1	2	Gemini DBAccess plugin (which is in the same feature as osgi.enterprise)
org.eclipse.gemini.jpa	3	Gemini JPA plugin (requires EclipseLink plugins)
org.eclipse.persistence.{antlr,asm,core,jpa, jpa.jpql}	3, jpa.jpql at 4 (start level false)	The five required EclipseLink Plugins for Antlr, ASM, EclipseLink Core, JPA,and dependency jpa.jpql services.
org.eclipse.equinox.simpleconfigurator	1	The Equinox Configurator that starts bundles when the framework starts. It must be in the launch configuration for Gemini to load properly.

The Gemini bundles are available through the Gemini JPA update site, http://download.eclipse.org/gemini/jp.../updates, and the Gemini DBAccess update site, http://download.eclipse.org//gemini/d.../1.1-M3.

It is important to note for testing purposes that the persistence unit must be part of a full bundle and that starting it in a fragment bundle (like a fragment for JUnit tests) does not seem to work. Also, the persistence unit must be activated (run level 4, true) in the pom and run configuration for the testing. Setting it to run level 3 causes some threading issues.

A word of warning. DO NOT USE THE FOLLOWING BUNDLES:

• org.eclipse.persistence.jpa.equinox
• org.eclipse.persistence.jpa.equinox.weaving
• org.eclipse.persistence.jpa.osgi.

These bundles are outdated and can cause some serious issues. Make sure they are not even in the same workspace, if possible (check your feature for deployment and target for development).

Finally, weaving is currently set to off, and the flag DREFRESH_BUNDLES is set to FALSE. This is important for threading issues within the Gemini and JPA architecture. If the refresh is set to true (by default it is true), then the EMFs will lose their references to the entities when the Persistence Units are refreshed during runtime.

Maven-Tycho Build Configuration

In order for the JPA poritions to be run during a build, the build pom.xml must be configured correctly. In particular, the required plugins for JPA must be included in the dependencies and their start levels must be configured (bundleStartLevel under plugin tycho-surefire). See previous section for bundle configuration levels and details on which plugins to incorporate into the pom file.

References

Eclipsepedia "Gemini/JPA/Documentation" http://wiki.eclipse.org/Gemini/JPA/Documentation

Eclipsepedia "Gemini/JPA/Documentation/OtherTopics" http://wiki.eclipse.org/Gemini/JPA/Documentation/OtherTopics

Voegella "Overview with examples of JPA" http://www.vogella.de/articles/JavaPersistenceAPI/article.html

Understanding the JavaWorld... "Another way to set up a class for an entity. With attributes" http://www.javaworld.com/javaworld/jw-01-2008/jw-01-jpa1.html?page=2

Understanding the JavaWorld... "Embedded objects (Normalization)" http://www.javaworld.com/javaworld/jw-01-2008/jw-01-jpa1.html?page=4

More from Oracle on JPA "Overview of JPA API" http://java.sun.com/developer/technicalArticles/J2SE/Desktop/persistenceapi/

Introduction to java persistence "More information on JPA broken down" http://www.javabeat.net/articles/5-introduction-to-java-persistence-apijpa-1.html

JAXB and JPA usage on the same POJO. "It can be done, but this is a poor example" http://www.objectpartners.com/2010/01/25/using-jpa-and-jaxb-annotations-in-the-same-object/

Marshalling "XML data marshalling" http://static.springsource.org/spring-ws/site/reference/html/oxm.html

Dynamic type safe queries "" http://www.ibm.com/developerworks/java/library/j-typesafejpa/index.html

"UML Databases - using UML to represent a database's data structure" http://www.sparxsystems.com/resources/uml_datamodel.html

"Create a JPA class in UML Eclipse" http://www.forum-omondo.com/documentation_eclipseuml_2008/Eclipse_Database/Create_New_JPA_Classes/index.html#2._Create_a_JPA_Class_from_the_Class

CRUD operations "How to update, edit, delete, and get items in a database" http://www.objectdb.com/java/jpa/start/crud

Eclipse Link "JPA" http://www.eclipse.org/eclipselink/jpa.php

Editing JPA Persistence.xml document dynamically: http://ayushsuman.blogspot.com/2010/06/configure-jpa-during-run-time-dynamic.html