Teneo/EclipseLink

Introduction

Teneo Eclipselink is not actively maintained anymore (from 2012 onwards).

For using EMF in combination with Eclipselink please check out the EMFT Texo project.

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.

Download - Archived

NOTE: EMF Teneo Eclipselink is available on this download site:

http://archive.eclipse.org/modeling/emf/teneo/updates/1.2.0/interim/archived/

Eclipselink is not actively maintained anymore (from 2012 onwards).

For using EMF in combination with Eclipselink please check out the EMFT Texo project.

Mapping EMF with JPA

For a discussion of how EMF should be mapped with JPA see Understanding JPA Mapping.

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).

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 required dependencies in the model project. Note that different dependency settings apply for different versions of Eclipse.
• Dependency setting when using the 1.1.0 Teneo version shipped with Teneo:
  • org.apache.commons.logging
  • org.eclipse.emf.teneo.orm
  • org.eclipse.emf.teneo.annotations
  • org.eclipse.emf.teneo.eclipse

• Dependency setting when using the M200910160438 build of Teneo or later:
  • 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");

Code Snippet

Here is a code snippet from the eclipselink/teneo test cases which might help:

String query = EclipseLinkURIUtil.createContentsEqualQuery(LibraryPackage.eINSTANCE.getLibrary(),
LibraryPackage.eINSTANCE.getLibrary_Name(), library1.getName());
libraryURI = EclipseLinkURIUtil.createEclipseLinkURI(TEST_PERSISTENCE_UNIT_NAME, query);

// save library model instance in database
ResourceSet resourceSet1 = new ResourceSetImpl();
resourceSet1.getLoadOptions().putAll(getTestPersistenceUnitProperties(this.getClass().getClassLoader()));
libraryResource1 = resourceSet1.createResource(libraryURI);

assertTrue(libraryResource1 instanceof EclipseLinkResourceImpl);

libraryResource1.getContents().add(library1);
libraryResource1.save(Collections.EMPTY_MAP);

the EclipseLinkURIUtil should be available to you to be used.

Tip: EMF-ORM in a Server (non-RCP) Environment

If you are using EMF in a server (non-RCP) environment then it might be interesting to look at the Texo project which works better with EclipseLink than Teneo and still provides a lot of the benefits of EMF (automatic ORM mapping,  xml-serialization, in-memory model, etc.).

More Information

See:

• Teneo CVS, Support, Commit Mailing List and FAQ
• Teneo Continuous Build