Teneo/Hibernate/ModelRelational/Annotations Format

Teneo makes it possible to override the default mapping with JPA annotations in the model. Teneo allows two ways to specify EJB3/JPA-like annotations:

1. using the java annotations syntax in EAnnotations (ecore and xsd) (examples)
2. a separate xml document (examples).

This page shows examples of both approaches.

A JPA Annotation can have different targets: TYPE, METHOD and FIELD (see the EJB3/JPA spec). 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 (see here for more information).

Note: when specifying enumerated values then the constant value of the enumeration should be used without the annotation class name. For example the annotation: @Cache(usage = CacheConcurrencyStrategy.NONSTRICT_READ_WRITE) should (in Teneo) be written as: @Cache(usage = NONSTRICT_READ_WRITE) (without quotes)

JPA Annotations in EAnnotations using the java annotation syntax

The EAnnotations should adhere to the following format:

• The source must be: teneo.jpa. Note, Teneo will always consider all annotations starting with teneo.jpa and teneo.mapping (deprecated). You can also configure your own annotation source, see the PersistenceOptions.EXTRA_ANNOTATION_SOURCES and the section on annotation sets below.
• The key must be: appinfo or value

See here for examples of how to define eannotations in Ecore or in a XML Schema file.

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!

You can tell Teneo where to find the xml file by setting the resource path (to the xml file) in this persistence option: PersistenceOptions.PERSISTENCE_XML (teneo.mapping.persistence_xml), see this options page for this and the other Teneo options.

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.

The example project (org.eclipse.emf.cdo.examples.hibernate.server) makes use of an annotations xml file. See the config/cdo-server.xml and the annotations xml file in the META-INF directory.

Simple Annotation Example

An example of an JPA annotation without a key-value pair is the Embedded annotation.

In a XML Schema model the Embedded annotation is specified as follows:

<xsd:element name="secondEmbedded" type="this:Embeddable">
	<xsd:annotation>
		<xsd:appinfo source="teneo.jpa">@Embedded</xsd:appinfo>
	</xsd:annotation>
</xsd:element>

An example of a (different) simple annotation in xml:

 
<eclass name="Name">
	<embeddable />
</eclass>

Annotation with key-value

An example of an EJB3 annotation with a key-value pair is the Basic annotation.

In a XML Schema model the Basic annotation is specified as follows:

<xsd:element name="myOptionalBasic" type="xsd:string">
	<xsd:annotation>
		<xsd:appinfo source="teneo.jpa">@Basic(optional=true fetch=EAGER)</xsd:appinfo>
	</xsd:annotation>
</xsd:element>

An example of a (different) key-value annotation in xml:

<property name="head">
	<one-to-one fetch="EAGER" target-entity="Head" optional="true" cascade="ALL" />
</property>

As you can see this example uses the property tag. The property tag is a convenience tag which can be used to in place of both an EAttribute and an EReference tag.

Complex Annotation with multi-level structure

An example of a more complex annotation is the SecondaryTable annotation which can contain a pkJoinColumns annotation:

<xsd:annotation>
	<xsd:appinfo source="teneo.jpa">
		@SecondaryTable(name="THETONER" pkJoinColumns={@PrimaryKeyJoinColumn(name="PRINTER_ID")})
	</xsd:appinfo>
</xsd:annotation>

An example of a (different) more complex annotation in xml:

 
<eclass name="Employee">
	<association-override name="address">
		<join-column name="employee_address_id"/>
	</association-override>
</eclass>

Multiple sets of annotations in one model

It can make sense to have multiple sets of annotations in your model and disable or enable them when needed. For example to have different mappings for different databases.

Teneo will always map all annotations with a source starting with teneo.jpa and teneo.mapping (deprecated).

You can configure additional annotation sources to be considered using the PersistenceOptions.EXTRA_ANNOTATION_SOURCES option. The value of this option is a comma delimited list of sources. Teneo will then also consider all annotations which have a source equal to one of the sources defined in the PersistenceOptions.EXTRA_ANNOTATION_SOURCES option.

There is another option which plays a role here: PersistenceOptions.EXTRA_ANNOTATIONS_OVERRIDES_DEFAULT. If set to true then the extra annotations are considered to override the default annotations, so if there is an extra-source-annotation then the default annotation is not used.

For standard Teneo these options can be passed when creating the datatore (dataStore.setProperties(...)).

For usage of Teneo within CDO (see the CDO Hibernate Store), these options can be set in the cdo-server.xml file which configures the hibernate store.