Difference between revisions of "EMF/Teneo 1.0.4/EclipseLink Support"

Latest revision as of 05:11, 23 March 2009

Teneo 1.0.4 provides support for EclipseLink. The following sections explain the principal features it includes and give advice how they can be used for building model-based applications on top of relational databases.

Creating EclipseLink/JPA Mappings for EMF models

Three possibilities:

• Model-driven
• Meet-in-the-middle
• Schema-driven

Accessing EMF Models in Databases using the EclipseLink Resource and URIs

Understanding the principles

Teneo/EclipseLink provides a full implementation of EMF's Resource interface named EclipseLinkResourceImpl. It enables applications to load and save EMF models from or to relational databases and to manage their lifecycle directly through EMF's built-in persistence API, i.e. the ResourceSet interface. EclipseLinkResourceImpl represents an almost complete abstraction from JPA mappings and EclipseLink runtime APIs and makes accessing models in databases, from an EMF point of view, as natural as loading or saving models from files.

Along with EclipseLinkResourceImpl, a dedicated eclipselink URI protocol and a underlying resource factory named EclipseLinkResourceFactoryImpl have been defined. EclipseLink URIs enable models in databases to be referenced and the EclipseLink resource factory makes sure that instances of EclipseLinkResourceImpl are used to load and save such models.

The EclipseLink URIs provide the information required for accessing models in databases. Compared to accessing models in files there are two major differences:

1. Resource location: In addition to the path or URL of the resource some additional access parameters need to be specified. Most importantly these are JDBC driver, user name, password.
2. Resource contents: Loading models from files is based on the implicit assumption that the file's whole content belongs to the model that is to be loaded. In the case of databases this is assumption doesn't make much sense since they would be used to persist multiple models but not just a single one and EclipseLink resources are expected to contain a subset rather than all of those models. Therefore, the model that is to be accessed within a given database needs to be specified in some way.

For these reasons, EclipseLink URIs are EMF URIs starting with the eclipselink protocol and using the following format:

eclipselink:///persistenceUnitName?contentsQuery

persistenceUnitName is an EclipseLink URI's single and only segment. It specifies the name of the applicable JPA (TODO add reference) persistence unit (TODO add reference) declared in the JPA persistence configuration file (persistence.xml). The persistence configuration file is expected to be provided on the application's classpath; its path or URL therefore doesn't need to be specified explicitly. The persistence unit is an entity providing all necessary parameters for accesssing a given database - including database URL, the JDBC driver to be used, user name and password, etc. - and for initializing the EclipseLink runtime appropriately.

contentsQuery is an EclipseLink URI's query. It yields a query written in JPQL (TODO add reference). It refers to the root object(s) of the model(s) in the given database that will constitute the contents of the underlying EclipseLink resource. Contents queries thereby enable the contents of EclipseLink resources to be limited to any subset of models or even to fragments of models being present in a database.

Putting things into practice

The following sections explain how to use EclipseLink resource and EclipseLink URIs for creating, saving, loading, and unloading EMF models to or from databases. The Library model including a JPA based O/R mapping and a persistence unit named library is used as example.

Saving a model to a new EclipseLink resource

Create sample instance of library model:

 Library library1 = LibraryFactory.eINSTANCE.createLibrary();
 library1.setName("library1");

Create EclipseLink URI for saving/loading library model to/from database:

 String query = EclipseLinkResourceUtil.createContentsEqualQuery(LibraryPackage.eINSTANCE.getLibrary(),LibraryPackage.eINSTANCE.getLibrary_Name(), library1.getName());
 uri = EclipseLinkResourceUtil.createEclipseLinkURI("library", query);

Create an EclipseLink resource for saving the library model instance in the database:

 ResourceSet resourceSet1 = new ResourceSetImpl();
 resourceSet1.getLoadOptions().putAll(getTestPersistenceUnitProperties());
 resource1 = resourceSet1.createResource(uri);

At this point, resource1 yields an instance of EclipseLinkResourceImpl but the resources is not loaded yet. It will change its state to loaded only after having got some contents - in our case the library model instance:

TODO check if database is opened on occasion and explain that

 resource1.getContents().add(library1);

The last step is to call the EclipseLink resource's save method. No specific options are required, that is why we can simply pass null:

 resource1.save(null);

This call will cause EclipseLink to act upon the database and emit appropriate SQL statements for writing the library model instance to the database.

Building Model-based Rich Client Applications on top of Teneo and EclipseLink

--Stephaneberle9.gmail.com 05:16, 16 March 2009 (UTC)