View source for Texo/ORM JPA Annotations Details

__TOC__

== Introduction ==

The Texo ORM generation can be controlled completely through an [[Texo/Code_Generation_Details#What_is_an_Annotations_Model|annotations model]]. The Texo ORM annotation model is directly based on the [http://wiki.eclipse.org/EclipseLink/XSDs ORM 2.0 standard]. The ORM/JPA model annotations make it possible to override/set all ORM 2.0 annotations at model level. You only need to annotate the parts of the model which need extra attention. Texo will automatically add any missing annotations to get to a fully annotated model (while maintaining the manual settings).

== Maintaining ORM model annotations ==

The initial ORM annotations model can be created in the same way as described for code generation, see [[Texo/Code_Generation_Details#How_to_create_an_Annotations_Model|here]]. You start with an empty annotation model and create the nodes in the annotations model to add ORM annotations. 


[[Image:org.eclipse.emf.texo.orm.annotations.model.png|center]]


You can add ORM Annotations at each level of your model: EPackage, EClass, EAttribute, EReference and EDataType. By right clicking on an ORM Annotation node you can see which ORM specific annotations can be added:


[[Image:org.eclipse.emf.texo.adding.orm.annotation.png|center]]


An ORM specific annotations can again have children:


[[Image:org.eclipse.emf.texo.adding.orm.annotation2.png|center]]


'''Note:''' it is possible to specify ORM annotations on an EDataType, these annotations are copied to each EAttribute using that EDataType.

== Texo Mapping Decisions ==

Texo makes the following mapping decisions when generating an orm.xml:
* as a default all access is set at FIELD (this in contrast to the JPA default which is PROPERTY), only interfaces will use the PROPERTY access type.
* join tables are named as: entityname_efeaturename. This in contrast to the JPA default which specifies that a join table should be the concatenation of the names of the 2 tables which are joined. Texo uses a different approach as it provides a more robust naming without collisions.
* Texo will automatically manage which side is the owner in a bi-directional association.
* Texo chooses the entity name (is the same as the EClass name prefixed with the epackage prefix).
* When bi-directional ereferences are ordered (which is the default), i.e. when a java.util.List is used in the generated java code, then the ereferences will be mapped separately with join-columns on both sides of the assocation. So bi-directional ordered associations are not mapped using mapped-by and will use 2 foreign key associations.

== Adding Id/Version features to your model ==

ORM solutions like EclipseLink require that each type has a primary key and preferably a version property. It can be cumbersome to add this to all the types in your system. An easy approach is therefore to:
* create a super type (for example called Identifiable) which has an id and version EFeature
* create an annotation model with a number of ORM annotations:
** map the Identifiable as a so-called MappedSuperclass. This means that the Identifiable type won't have its own table, its efeatures are mapped in the sub type.
** add an Id and Version ORM annotation for the id and version EFeature.
* let all types inherit from this super type. An alternative approach (less recommended though...), instead of using EMF/ecore inheritance you can also let the generated java class inherit from a non-generated class, to accomplish this set the rootExtendsClass code generation property to the java class name of Identifiable. The rootExtendsClass property can be found in the [[Texo/Code_Generation_Details#EPackage_Model_Gen_Features | code generation annotations model]].

An example of a model with an Identifiable and its annotation model can be downloaded here: [[Media:org.eclipse.emf.texo.identifiable.zip|Identifiable.zip]]