Teneo/Hibernate/ModelRelational/Annotations Format

The CDO Hibernate Store uses Teneo to generate the mapping for Hibernate. 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 (examples)
2. a separate xml document (examples).

This page will show 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! The xsd for the XML annotations can be downloaded here.

A number of examples of annotations in xml can be found 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.

When initializing a HbDataStore the location of the xml annotation file should be passed using the persistenceoption: PersistenceOptions.PERSISTENCE_XML. The location should be a resource path.

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:

Invalid language.

You need to specify a language like this: <source lang="html4strict">...</source>

Supported languages for syntax highlighting:

4cs, 6502acme, 6502kickass, 6502tasm, 68000devpac, abap, actionscript, actionscript3, ada, algol68, apache, applescript, apt_sources, arm, asm, asp, asymptote, autoconf, autohotkey, autoit, avisynth, awk, bascomavr, bash, basic4gl, bf, bibtex, blitzbasic, bnf, boo, c, c_loadrunner, c_mac, caddcl, cadlisp, cfdg, cfm, chaiscript, cil, clojure, cmake, cobol, coffeescript, cpp, cpp-qt, csharp, css, cuesheet, d, dcl, dcpu16, dcs, delphi, diff, div, dos, dot, e, ecmascript, eiffel, email, epc, erlang, euphoria, f1, falcon, fo, fortran, freebasic, freeswitch, fsharp, gambas, gdb, genero, genie, gettext, glsl, gml, gnuplot, go, groovy, gwbasic, haskell, haxe, hicest, hq9plus, html4strict, html5, icon, idl, ini, inno, intercal, io, j, java, java5, javascript, jquery, kixtart, klonec, klonecpp, latex, lb, ldif, lisp, llvm, locobasic, logtalk, lolcode, lotusformulas, lotusscript, lscript, lsl2, lua, m68k, magiksf, make, mapbasic, matlab, mirc, mmix, modula2, modula3, mpasm, mxml, mysql, nagios, netrexx, newlisp, nsis, oberon2, objc, objeck, ocaml, ocaml-brief, octave, oobas, oorexx, oracle11, oracle8, otj, oxygene, oz, parasail, parigp, pascal, pcre, per, perl, perl6, pf, php, php-brief, pic16, pike, pixelbender, pli, plsql, postgresql, povray, powerbuilder, powershell, proftpd, progress, prolog, properties, providex, purebasic, pycon, pys60, python, q, qbasic, rails, rebol, reg, rexx, robots, rpmspec, rsplus, ruby, sas, scala, scheme, scilab, sdlbasic, smalltalk, smarty, spark, sparql, sql, stonescript, systemverilog, tcl, teraterm, text, thinbasic, tsql, typoscript, unicon, upc, urbi, uscript, vala, vb, vbnet, vedit, verilog, vhdl, vim, visualfoxpro, visualprolog, whitespace, whois, winbatch, xbasic, xml, xorg_conf, xpp, yaml, z80, zxbasic

<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:

Invalid language.

You need to specify a language like this: <source lang="html4strict">...</source>

Supported languages for syntax highlighting:

4cs, 6502acme, 6502kickass, 6502tasm, 68000devpac, abap, actionscript, actionscript3, ada, algol68, apache, applescript, apt_sources, arm, asm, asp, asymptote, autoconf, autohotkey, autoit, avisynth, awk, bascomavr, bash, basic4gl, bf, bibtex, blitzbasic, bnf, boo, c, c_loadrunner, c_mac, caddcl, cadlisp, cfdg, cfm, chaiscript, cil, clojure, cmake, cobol, coffeescript, cpp, cpp-qt, csharp, css, cuesheet, d, dcl, dcpu16, dcs, delphi, diff, div, dos, dot, e, ecmascript, eiffel, email, epc, erlang, euphoria, f1, falcon, fo, fortran, freebasic, freeswitch, fsharp, gambas, gdb, genero, genie, gettext, glsl, gml, gnuplot, go, groovy, gwbasic, haskell, haxe, hicest, hq9plus, html4strict, html5, icon, idl, ini, inno, intercal, io, j, java, java5, javascript, jquery, kixtart, klonec, klonecpp, latex, lb, ldif, lisp, llvm, locobasic, logtalk, lolcode, lotusformulas, lotusscript, lscript, lsl2, lua, m68k, magiksf, make, mapbasic, matlab, mirc, mmix, modula2, modula3, mpasm, mxml, mysql, nagios, netrexx, newlisp, nsis, oberon2, objc, objeck, ocaml, ocaml-brief, octave, oobas, oorexx, oracle11, oracle8, otj, oxygene, oz, parasail, parigp, pascal, pcre, per, perl, perl6, pf, php, php-brief, pic16, pike, pixelbender, pli, plsql, postgresql, povray, powerbuilder, powershell, proftpd, progress, prolog, properties, providex, purebasic, pycon, pys60, python, q, qbasic, rails, rebol, reg, rexx, robots, rpmspec, rsplus, ruby, sas, scala, scheme, scilab, sdlbasic, smalltalk, smarty, spark, sparql, sql, stonescript, systemverilog, tcl, teraterm, text, thinbasic, tsql, typoscript, unicon, upc, urbi, uscript, vala, vb, vbnet, vedit, verilog, vhdl, vim, visualfoxpro, visualprolog, whitespace, whois, winbatch, xbasic, xml, xorg_conf, xpp, yaml, z80, zxbasic

<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:

Invalid language.

You need to specify a language like this: <source lang="html4strict">...</source>

Supported languages for syntax highlighting:

4cs, 6502acme, 6502kickass, 6502tasm, 68000devpac, abap, actionscript, actionscript3, ada, algol68, apache, applescript, apt_sources, arm, asm, asp, asymptote, autoconf, autohotkey, autoit, avisynth, awk, bascomavr, bash, basic4gl, bf, bibtex, blitzbasic, bnf, boo, c, c_loadrunner, c_mac, caddcl, cadlisp, cfdg, cfm, chaiscript, cil, clojure, cmake, cobol, coffeescript, cpp, cpp-qt, csharp, css, cuesheet, d, dcl, dcpu16, dcs, delphi, diff, div, dos, dot, e, ecmascript, eiffel, email, epc, erlang, euphoria, f1, falcon, fo, fortran, freebasic, freeswitch, fsharp, gambas, gdb, genero, genie, gettext, glsl, gml, gnuplot, go, groovy, gwbasic, haskell, haxe, hicest, hq9plus, html4strict, html5, icon, idl, ini, inno, intercal, io, j, java, java5, javascript, jquery, kixtart, klonec, klonecpp, latex, lb, ldif, lisp, llvm, locobasic, logtalk, lolcode, lotusformulas, lotusscript, lscript, lsl2, lua, m68k, magiksf, make, mapbasic, matlab, mirc, mmix, modula2, modula3, mpasm, mxml, mysql, nagios, netrexx, newlisp, nsis, oberon2, objc, objeck, ocaml, ocaml-brief, octave, oobas, oorexx, oracle11, oracle8, otj, oxygene, oz, parasail, parigp, pascal, pcre, per, perl, perl6, pf, php, php-brief, pic16, pike, pixelbender, pli, plsql, postgresql, povray, powerbuilder, powershell, proftpd, progress, prolog, properties, providex, purebasic, pycon, pys60, python, q, qbasic, rails, rebol, reg, rexx, robots, rpmspec, rsplus, ruby, sas, scala, scheme, scilab, sdlbasic, smalltalk, smarty, spark, sparql, sql, stonescript, systemverilog, tcl, teraterm, text, thinbasic, tsql, typoscript, unicon, upc, urbi, uscript, vala, vb, vbnet, vedit, verilog, vhdl, vim, visualfoxpro, visualprolog, whitespace, whois, winbatch, xbasic, xml, xorg_conf, xpp, yaml, z80, zxbasic

<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.

---

Wikis: CDO | Net4j | EMF | Eclipse