Jump to: navigation, search

Difference between revisions of "Teneo/Hibernate/GMF"

(Initialization of Teneo)
(Adapting the generated mindmap plguins)
Line 43: Line 43:
 
This section describes how the generated mindmap code was adapted to facilitate the integration with Teneo. These changes have already been made in the projects you can download from cvs.
 
This section describes how the generated mindmap code was adapted to facilitate the integration with Teneo. These changes have already been made in the projects you can download from cvs.
  
=== Setting dependendencies on Teneo and Hibernate ====
+
=== Setting dependendencies on Teneo and Hibernate ===
  
 
Additional dependencies have to be set in the org.eclipse.gmf.examples.mindmap MANIFEST.MF file:
 
Additional dependencies have to be set in the org.eclipse.gmf.examples.mindmap MANIFEST.MF file:
Line 71: Line 71:
  
 
Both the annotations.xml and teneo.properties file must be checked/flagged in the build.properties file so that they are copied to the build folder. To be sure check the contents of the build folder to ensure that these files are present.
 
Both the annotations.xml and teneo.properties file must be checked/flagged in the build.properties file so that they are copied to the build folder. To be sure check the contents of the build folder to ensure that these files are present.
 +
 +
=== StoreController: initializing the Teneo layer ===
 +
The StoreController class initializes the Teneo layer using the properties in the teneo.properties file.
 +
 +
The class starts with a declaration of the uri to connect to the database:
 +
<source lang="java">
 +
public static final URI DATABASE_URI = URI.createURI("hbxml://?dsname=mindmap&query1=from Map&query2=from Diagram");
 +
</source>
 +
This uri has some specific parts: 1) the dsname parameter is the name of datastore (see below), 2) the queries in the uri ensure that the resource loads the Mindmap Map and the GMF Diagram as roots in the resource. The uri starts with hbxml to ensure that the HibernateXMLResource is used.
 +
 +
The next piece of code can be found in the initializeDataStore method:
 +
<source lang="java">
 +
// create and register the datastore using the mindmap name
 +
final HbSessionDataStore localDataStore = new HbSessionDataStore();
 +
localDataStore.setName("mindmap");
 +
HbHelper.INSTANCE.register(localDataStore);
 +
</source>
 +
This code creates a datastore and registers it in the global datastore registry. There the HibernateXMLResource can find it using the dsname parameter and its value: mindmap.
 +
 +
A number of EPackages have to be registered with Teneo to persist the mindmap data as well as the GMF diagram data:
 +
<source lang="java">
 +
// now register the epackages. There are four epackages:
 +
// 1) the model itself
 +
// 2) the GMF model
 +
// 3) the ecore model because GMF depends on it
 +
// 4) and the ecore XML type package
 +
final EPackage[] ePackages = new EPackage[] { MindmapPackage.eINSTANCE,
 +
NotationPackage.eINSTANCE, EcorePackage.eINSTANCE,
 +
XMLTypePackage.eINSTANCE };
 +
localDataStore.setEPackages(ePackages);
 +
</source>
 +
 +
The following code loads the teneo.properties and directs Teneo to use the annotations.xml file to influence the mapping to the relational model:
 +
 +
<source lang="java">
 +
final Properties props = new Properties();
 +
props.load(this.getClass().getResourceAsStream("teneo.properties"));
 +
 +
// handle multiple inheritance in the GMF model
 +
props.setProperty(PersistenceOptions.PERSISTENCE_XML,
 +
"annotations.xml");
 +
 +
localDataStore.setProperties(props);
 +
</source>
 +
 +
Note that it is possible that the annotations.xml and teneo.properties file are not found. In that case you can try to put them in the root of the source tree and let the build process copy them from there. In that case the references to these names in the source code have to be changed to resp. "/teneo.properties" and "/annotations.xml".
 +
 +
In GMF there is a difference between the generated code and the in-memory model. Teneo can not handle this out of the box and requires a different property handler (the GMFEListPropertyHandler from above) to handle this correctly. The following code registers this property handler using the Teneo extension mechanism (see here for more info on Teneo extensions).
 +
<source lang="java">
 +
// solve a specific issue with the GMF model
 +
localDataStore.getExtensionManager().registerExtension(
 +
EListPropertyHandler.class.getName(),
 +
GMFEListPropertyHandler.class.getName());
 +
</source>
 +
As a last step the actual Teneo initialization has to take place. This step will also create the database tables.
 +
<source lang="java">
 +
localDataStore.initialize();
 +
// print the hibernate mapping
 +
System.err.println(localDataStore.getMappingXML());
 +
</source>
 +
The StoreController class will initialize the Teneo layer when it is used for the first time.
 +
 +
=== Initialize Teneo when plugin starts ===
 +
To initialize Teneo when the diagram plugin starts add the following code to the start method of the generated MindmapDiagramEditorPlugin: StoreController.getInstance().initializeDataStore(). To stop the Teneo layer when the plugin stops, add this to the stop method: StoreController.getInstance().closeDataStore.

Revision as of 06:13, 3 March 2010

This tutorial describes how the generated GMF editor can be adapted to operate on a relational database. Both the diagram data and the model data will be stored in the same relational database.

From the GMF website:

The Eclipse Graphical Modeling Framework (GMF) provides a generative component and runtime infrastructure for developing graphical editors based on EMF and GEF. The project aims to provide these components, in addition to exemplary tools for select domain models which illustrate its capabilities.

This tutorial shows you how to adapt the plugins from the GMF mindmap tutorial to operate on a relational database using hibernate. The chosen approach is to make very small changes to the generated code and is not necessarily focused on an elegant or optimal solution.

The result of this tutorial will be a displayed as a menu option in Eclipse which directly opens the editor on a relational database.

For additional information regarding GMF and Teneo (next to this tutorial), see the description provided in this bugzilla.


Org.eclipse.emf.teneo.gmf.example.png


Initial Setup

This tutorial assumes that you have a running Eclipse with EMF and Teneo installed. In addition the Teneo dependencies (incl. hsqldb and mysql drivers) should be installed. See the Download & Install page for more information.

The tutorial uses hsqldb but it can easily be changed to use mysql or another database. For other databases than hsqldb and mysql you need to take make sure that the jdbc driver is in the classpath of the org.eclipse.gmf.examples.edit project.

For mysql and other non-in-memory databases you have to create the database up-front (so not the tables inside the database but just the database itself). For this tutorial the database name should be: library.

Also GMF needs to be installed.

The GMF tutorial makes use of another set of example projects. These projects can be found in the gmf folder of the examples folder in cvs:

  • dev.eclipse.org
  • /cvsroot/modeling
  • org.eclipse.emf/org.eclipse.emf.teneo/examples/gmf

There are 3 projects:

  • org.eclipse.gmf.examples.edit
  • org.eclipse.gmf.examples.mindmap
  • org.eclipse.gmf.examples.mindmap.diagram

Download all three projects into your workspace.

Adapting the generated mindmap plguins

This section describes how the generated mindmap code was adapted to facilitate the integration with Teneo. These changes have already been made in the projects you can download from cvs.

Setting dependendencies on Teneo and Hibernate

Additional dependencies have to be set in the org.eclipse.gmf.examples.mindmap MANIFEST.MF file:


Org.eclipse.emf.teneo.gmf.dependencies.png


Note: the additional dependencies have been re-exported for convenience.

Initialization of Teneo

The Teneo layer has to be activated when the diagram editor starts. Note that this code assumes that database has been created. This example uses mysql/hsqldb, replace the relevant options for your specific database.

As a first step a new separate java package has been created in the org.eclipse.gmf.examples.mindmap.diagram plugin: org.eclipse.gmf.examples.mindmap.diagram.db. Three classes are present in this package (see the files in the ):

  • StoreController: this class initializes and manages one Teneo datastore.

an annotations.xml file to map the GMF model to a relational store (download here). This file contains hints to Teneo on how to map the GMF model. It is required because the GMF model contains multiple-inheritance structures which can not be translated automatically to a relational store. See below for some more information.

  • a specific EList property handler: this is to solve a minor technical detail with the GMF generated code and the GMF model, see here for more details.
  • OpenbMindmapDBEditor: implements the menu choice to open a mindmap editor.


Org.eclipse.emf.teneo.gmf.new.files.png


Then in the root of the src folder, 2 files are of importance:

  • teneo.properties: contains hibernate and teneo properties. This file contains database connection information which probably has to be adapted to your specific case.
  • annotations.xml: there are a number of GMF types (ShapeStyle, DiagramStyle and ConnectorStyle) which inherit from multiple other GMF types as well as the EMF EObject type. The EObject type is listed as the first supertype of these types. This means that Teneo will place these types in the EObject type hierarchy when mapping to a relational store. This will not work as for GMF these types are primarily subtypes of Style. The annotations.xml file in this tutorial ensures that the mentioned Style types are placed in the correct hierarchy (in the relational model).

Both the annotations.xml and teneo.properties file must be checked/flagged in the build.properties file so that they are copied to the build folder. To be sure check the contents of the build folder to ensure that these files are present.

StoreController: initializing the Teneo layer

The StoreController class initializes the Teneo layer using the properties in the teneo.properties file.

The class starts with a declaration of the uri to connect to the database:

public static final URI DATABASE_URI = URI.createURI("hbxml://?dsname=mindmap&query1=from Map&query2=from Diagram");

This uri has some specific parts: 1) the dsname parameter is the name of datastore (see below), 2) the queries in the uri ensure that the resource loads the Mindmap Map and the GMF Diagram as roots in the resource. The uri starts with hbxml to ensure that the HibernateXMLResource is used.

The next piece of code can be found in the initializeDataStore method:

// create and register the datastore using the mindmap name
final HbSessionDataStore localDataStore = new HbSessionDataStore();
localDataStore.setName("mindmap");
HbHelper.INSTANCE.register(localDataStore);

This code creates a datastore and registers it in the global datastore registry. There the HibernateXMLResource can find it using the dsname parameter and its value: mindmap.

A number of EPackages have to be registered with Teneo to persist the mindmap data as well as the GMF diagram data:

// now register the epackages. There are four epackages:
// 1) the model itself
// 2) the GMF model
// 3) the ecore model because GMF depends on it
// 4) and the ecore XML type package
final EPackage[] ePackages = new EPackage[] { MindmapPackage.eINSTANCE,
		NotationPackage.eINSTANCE, EcorePackage.eINSTANCE,
		XMLTypePackage.eINSTANCE };
localDataStore.setEPackages(ePackages);

The following code loads the teneo.properties and directs Teneo to use the annotations.xml file to influence the mapping to the relational model:

final Properties props = new Properties();
props.load(this.getClass().getResourceAsStream("teneo.properties"));
 
// handle multiple inheritance in the GMF model
props.setProperty(PersistenceOptions.PERSISTENCE_XML,
		"annotations.xml");
 
localDataStore.setProperties(props);

Note that it is possible that the annotations.xml and teneo.properties file are not found. In that case you can try to put them in the root of the source tree and let the build process copy them from there. In that case the references to these names in the source code have to be changed to resp. "/teneo.properties" and "/annotations.xml".

In GMF there is a difference between the generated code and the in-memory model. Teneo can not handle this out of the box and requires a different property handler (the GMFEListPropertyHandler from above) to handle this correctly. The following code registers this property handler using the Teneo extension mechanism (see here for more info on Teneo extensions).

// solve a specific issue with the GMF model
localDataStore.getExtensionManager().registerExtension(
		EListPropertyHandler.class.getName(),
		GMFEListPropertyHandler.class.getName());

As a last step the actual Teneo initialization has to take place. This step will also create the database tables.

localDataStore.initialize();
// print the hibernate mapping
System.err.println(localDataStore.getMappingXML());

The StoreController class will initialize the Teneo layer when it is used for the first time.

Initialize Teneo when plugin starts

To initialize Teneo when the diagram plugin starts add the following code to the start method of the generated MindmapDiagramEditorPlugin: StoreController.getInstance().initializeDataStore(). To stop the Teneo layer when the plugin stops, add this to the stop method: StoreController.getInstance().closeDataStore.