CDO/Hibernate Store/Model Relational Mapping
The CDO Hibernate Store can use Teneo for the Model Relational mapping. Teneo generates a mapping for Hibernate on the basis of the ecore model and optional JPA annotations. JPA annotations can be specified directly in the model or in a separate xml.
JPA annotations allow a developer to do many things, an incomplete list of possibilities: determine the naming of columns and tables, enables or prevents join tables, specify embedded components, specify the name of foreign key columns, the inheritance mapping, if an index column is used, the sorting of a collection, enable external references, etc. etc.
Teneo supports all JPA annotations and many Hibernate extensions.
The JPA specification contains a description of each annotation, download it from here (click on the first button, then at a later page select the pdf with the word persistence).
JPA Annotations with a TYPE target can be used for EMF EClasses, annotations with METHOD and FIELD targets can be used for EStructuralFeatures. Note: JPA annotations relevant for a non-reference type java member can also be set on an EDataType.
The Teneo documentation has a detailed description of the format in which annotations can be specified. The main points are summarized here:
Teneo allows two ways to specify EJB3/JPA-like annotations:
- using the java annotations syntax in EAnnotations (ecore and xsd) (examples)
- a separate xml document (examples).
Annotations in the model itself (xsd or ecore)
JPA Annotations are set in the model using the EMF EAnnotation. The EAnnotations should adhere to the following format:
- The source must be: teneo.jpa. You can also configure your own annotation source, see Teneo documentation for details.
- The key must be: appinfo or value
The page: here contains examples of JPA eannotations in Ecore or in a XML Schema file.
JPA Annotations in XSD, some examples
This annotation sets the inheritance mapping strategy for the Address to joined:
<xsd:complexType name="Address" abstract="true"> <xsd:annotation> <xsd:appinfo source="teneo.jpa">@Inheritance(strategy=JOINED)</xsd:appinfo> </xsd:annotation> <xsd:sequence> <xsd:element name="name" type="xsd:string"/> </xsd:sequence> </xsd:complexType>
The following annotation specifies that the association does not need an index column:
<xsd:element name="containedItem" type="this:ContainedItem" maxOccurs="unbounded"> <xsd:annotation> <xsd:appinfo source="teneo.jpa">@OneToMany(indexed=false)</xsd:appinfo> </xsd:annotation> </xsd:element>
Setting JPA Annotations using the Ecore Model Editor
To set an annotation in the ecore model using the Ecore Model Editor do the following:
- open the model in the editor
- right click on the model element (EClass, EStructuralFeature, etc.) on which you want to set a JPA annotation
- do: New Child > EAnnotation
- check in the properties view, there are two fields for the new EAnnotation: references and source. Set source to: teneo.jpa
- right click on the new EAnnotation in the ecore model editor and do: New Child > Details Entry
- click on the new detail entry, the properties view shows a key and value field. Enter the word 'value' in the key field and in the value field enter your annotation, for example: @Id or @Basic. Just as you would set it in Java.
JPA Annotations in XML
JPA annotations can also be specified in a separate xml file. The advantage of this approach is that you can annotate models which are not in your control. The separate annotated xml means that the original model file does not need to be changed. You can even annotate the Ecore model itself!
The xsd for the XML annotations can be downloaded here. The xsd shows that it is possible to specify annotations on EPackage, EClass, EAttribute, EReference and EDataType level. In addition there is a special property element which combines the annotations for EAttribute and EReference. The property tag is a convenience tag which can be used to in place of both an EAttribute and an EReference tag.
A number of examples of annotations in xml can be found here.
When using Teneo within CDO then the location of the annotations xml (a class path location) should be set in the cdo-server.xml using the option: PersistenceOptions.PERSISTENCE_XML. The location should be a resource/class path. When using Teneo stand alone this same option should be used, but then it should be passed to the HbDataStore.setProperties(..) method.
To make the annotations xml file available to the CDO server at runtime you have to place the annotations xml in a separate plugin, see here for more information.
JPA Annotations in the example projects
The CDO Hibernate Store documentation makes use of a number of example projects. The example projects also make use of in-model annotations as well as annotations in a separate XML file.
To see the in-model JPA annotations go to the org.eclipse.emf.cdo.examples.company project and then the model folder. Open the company.ecore file in an ecore model editor, navigate through the model:
- The Product.name EStructuralFeature has an @Id annotation, specifying that this feature is the primary key.
- The Order EClass has an annotation to set the entity name (this name should be used in HQL queries).
- The OrderAddress EClass has a more complex annotation to prevent name clashes when creating the relational schema.
The examples also make use of extra annotations in an annotations.xml. To see this open the org.eclipse.emf.cdo.examples.hibernate.server project and the META-INF folder. There you will find an annotations xml file. The classpath of this file is specified in the cdo-server.xml which you can find the config folder of that same project.
To ensure that the annotations xml file is visible for Teneo/Hibernate a dependency has been set to the org.eclipse.emf.cdo.server.hibernate.teneo (see the MANIFEST.MF).
Teneo JPA Annotations Details
For more information on how to set JPA annotations in your model visit the Teneo Model Relation Mapping Overview page.