Revision as of 15:46, 7 July 2009

Introduction

Teneo provides integration with EclipseLink to support persistence of arbitrary EMF models with JPA. The original goal of this integration was to allow developers to map EMF generated classes with standard JPA to existing databases (so called 'meet-in-the-middle' mapping). This is an important feature if you're building an application on an existing database. However Teneo also supports a full model driven development approach that supports generating the classes, JPA mappings, and database schema from an EMF model.

Getting Started with Teneo-EclipseLink in Eclipse 3.5 (Galileo)

Configuring your Development Environment

1. Download the Eclipse 3.5 (Galileo) Modeling Tools distribution which includes all of the necessary features or download another distribution that includes EMF and PDE (e.g., Eclipse Classic or Eclipse IDE for Java EE Developers) and install the following features from the Galileo update site: http://download.eclipse.org/releases/galileo

• Teneo EclipseLink
• EclipseLink JPA

You now have all the necessary components installed to begin developing with Teneo EclipseLink.

Running the Expanded Library Example

A greatly expanded version of the classic EMF Library example was built during the development of Teneo EclipseLink for testing purposes. The expanded Library provides a rich example that you can serve as a reference as you develop your own Teneo EclipseLink applications.

Obtaining the Example

The Library example will be made available for download as a zip (real soon now) but for now you'll have to check it out from the Teneo CVS respository. The CVS How To page describes how to connect to each of the top level project CVS repositories. Teneo is part of EMF so you'll want to connect to the Modeling CVS repository. The projects you'll want to check out to try out the example are in /cvsroot/modeling/org.eclipse.emf/org.eclipse.emf.teneo. The repository path is /cvsroot/modeling.

• examples/org.eclipse.emf.teneo.eclipselink.examples.library
• tests/org.eclipse.emf.teneo.eclipselink.examples.library.orm.tests

This example is configured to use Apache Derby embedded database which you can download from the Eclipse Orbit project. Download the org.apache.derby plugin and place it in your ECLIPSE_HOME/dropins folder. If you have the Eclipse IDE open you'll need to Reload your target platform or restart.

Running AllTests

Run the Junit Plug-in Test org.eclipse.emf.teneo.eclipselink.examples.library.orm.tests.AllTests which is located in the org.eclipse.emf.teneo.eclipselink.examples.library.orm.tests project.

You should see EclipseLink log messages about JPA mapping defaults, SQL to create the database schema from the mappings, and then the individual tests will run and you'll see even more SQL. You should see 54 of 54 tests run green (at the time this is written).

Understanding JPA Mapping for EMF

Mapping in XML

Because you may regenerate classes from your Ecore model, you should do all mapping in XML. The use of annotations is not recommended as they will be lost if you regenerate. You can certainly use them but remember you have been warned.

Field or Property Access

Regardless of what access type you specify, Teneo will adjust your mappings to use a hybrid access approach. To take advantage of lazy initialization, Teneo will configure property access when reading an attribute from a Enity. But to avoid firing events when constructing an object, Teneo wil configure direct field access when setting an attribute.

OneToMany

In JPA 1.0 OneToMany relationships require a 'back reference' from the target of the relationship (i.e., the objects in the collection) back to the owner of the relationship. The back reference should be mapped as a ManyToOne. The back reference mapping varies depending upon whether the many are contained.

OneToMany without EMF Containment

When dealing with a non-containment relationship, the target of the OneToMany mapping will need an attribute holding the back reference which is mapped with a ManyToOne. In the extended Library example, WriterImpl has a non-containment OneToMany relationship with BookImpl. Note that the mapped-by is "author", an attribute of BookImpl that is mapped as a ManyToOne back to WriterImpl.

WriterImpl's books mapping:

   <entity name="Writer" class="WriterImpl">
         ...
         <one-to-many name="books" mapped-by="author" target-entity="BookImpl">
          ...

BookImpl's author mapping:

    <entity name="Book" class="BookImpl" access="FIELD">
        ...
        <many-to-one name="author" target-entity="WriterImpl">
        ...

OneToMany with EMF Containment

In the case of an EMF containment relationship, the back reference to the owning object is maintained in the eContainer attribute. In the Library example, a LibraryImpl has an EList of WriterImpls which in JPA is mapped as a OneToMany. Because LibraryImpl->WriterImpl is a containment relationship, each WriterImpl's eContainer reference will point to it's owning LibraryImpl.

LibraryImpl's writers mapping:

    <entity name="Library" class="LibraryImpl">
        ...
	<one-to-many name="writers" target-entity="WriterImpl" mapped-by="eContainer">
        ...

WriterImpl's back reference to it's eContainer:

    <entity name="Writer" class="WriterImpl">
        ...
        <many-to-one name="eContainer" target-entity="LibraryImpl">
        ...

Generating the orm.xml from the model (top-to-bottom mapping)

To support a top-to-bottom mapping approach Teneo makes it possible to generate the orm.xml from the ecore model. There are two ways to generate the orm.xml:

1. By right-clicking the ecore file and selecting the submenu Teneo > Generate orm. See below for a full description.
2. Programmatically by instantiating the org.eclipse.emf.teneo.jpa.convert.ORMGenerator class and calling a specific method on the class.

Each of these methods is discussed separately.

JPA Annotated Model

The input for both methods is a JPA annotated model. Teneo will automatically annotate the model with JPA annotations. So manual annotations are only required if certain default behavior needs to be overridden.

More documentation on how to annotate an Ecore model with annotations can be found here:

• JPA Format
• Examples

Note that for EclipseLink practically all standard JPA annotations are supported.

For more information see this presentation on EclipseLink - Teneo which was done at EclipseCon 2009.

Generating the orm.xml through the menu

To generate the orm.xml through the menu the following steps have to be setup/done:

• generate the model code (standard EMF action), the generated model code will be present in a specific Java project, called the model project
• add the following two dependencies to the model project: open the MANIFEST.MF file in the model project's META-INF directory and go to the dependency tab. Then add the following two dependencies:
  • org.apache.commons.logging
  • org.eclipse.emf.teneo.orm

• right-click on the ecore file and choose the Teneo > Generate orm submenu. The system now generates an orm.xml file in the same folder as the ecore file.

Note: the above logic assumes that the ecore file is present in the same Java project as the generated model code.

Generating the orm.xml through the menu is quick. The main disadvantage is that you can not pass specific persistence options to control the mapping behavior. The available persistence options are described here

Generating the orm.xml programmatically

Generating the orm.xml in a programmatic way has as main advantage that the mapping logic can be influenced by passing | Persistence Options. For more details on the PersistenceOptions check out the PersistenceOptions source code and javadoc.

To generate programmatically the class ORMGenerator (org.eclipse.emf.teneo.jpa.convert.ORMGenerator) class is used. The source code below gives an example of a possible use:

final Properties props = new Properties();
props.setProperty(PersistenceOptions.SQL_TABLE_NAME_PREFIX, "EMFLIB_");
final ORMGenerator converter = new ORMGenerator();
final String orm = converter.generateORM(
		new EPackage[] { DataPackage.eINSTANCE }, converter
				.getDefaultPersistenceOptions(props));
System.err.println(orm);

To walk you through the code. As the orm.xml is generated programmatically,there is the opportunity to set specific persistence options. In this case the table name prefix is set. Then a new instance of the ORMGenerator is created. In the generate call: converter.generateORM two arguments are passed:

1. the array of EPackages for which an orm is generated

• the properties, note the specific way to get the default persistence options from the GenerateORM instance itself. This is required if you want to make use of default settings which make sense for EclipseLink. The default Persistence Options are shown below.

The generateORM method returns the orm.xml as a String. This String can be saved to a file system.

The default persistenceoptions which are common in the ORMGenerator:

props.setProperty(PersistenceOptions.SQL_NAME_ESCAPE_CHARACTER, "");
props.setProperty(PersistenceOptions.EMAP_AS_TRUE_MAP, "false");
props.setProperty(PersistenceOptions.SET_DEFAULT_CASCADE_ON_NON_CONTAINMENT,"true");
props.setProperty(PersistenceOptions.CASCADE_POLICY_ON_NON_CONTAINMENT, "REFRESH,PERSIST,MERGE");
props.setProperty(PersistenceOptions.ID_FEATURE_AS_PRIMARY_KEY, "false");
props.setProperty(PersistenceOptions.SQL_CASE_STRATEGY, "uppercase");