Hibernate
/
hibernate-orm
mirror of https://github.com/hibernate/hibernate-orm
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

METAGEN-7 Assuming now that 'xml-mapping-metadata-complete' is specified for a pure xml configuration. This way I can be more specific in @SupportedAnnotationTypes

This commit is contained in:
Hardy Ferentschik 2010-10-01 14:18:53 +00:00 committed by Strong Liu
parent 489c46b4be
commit 000d5533f4
11 changed files with 645 additions and 177 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

481
tooling/metamodel-generator/src/main/docbook/en-US/master.xml
View File

@ -22,43 +22,60 @@
<!ENTITY today "TODAY">
<!ENTITY copyrightYear "2010">
<!ENTITY copyrightHolder "Red Hat Inc.">
<!ENTITY jpa2Ref '<citation><xref linkend="JPA2"/></citation>'>
<!ENTITY jsr269Ref '<citation><xref linkend="JSR_269"/></citation>'>
<!ENTITY jpa2Ref "<citation><xref linkend=&#34;JPA2&#34;/></citation>">
<!ENTITY jsr269Ref "<citation><xref linkend=&#34;JSR_269&#34;/></citation>">
]>
<book lang="en">
<bookinfo>
<title>Hibernate JPA 2 Metamodel Generator</title>
<subtitle>Reference Guide</subtitle>
<releaseinfo>&version;</releaseinfo>
<pubdate>&today;</pubdate>
<productnumber>&version;</productnumber>
<copyright>
<year>&copyrightYear;</year>
<holder>&copyrightHolder;</holder>
</copyright>
<authorgroup>
<author>
<firstname>Hardy</firstname>
<surname>Ferentschik</surname>
</author>
</authorgroup>
</bookinfo>
<toc/>
<toc></toc>
<chapter id="introduction">
<title>Introduction</title>
<section id="whatisit">
<title>What is it about?</title>
<para>JPA 2 defines a new typesafe <classname>Criteria</classname> API which allows criteria
queries to be constructed in a strongly-typed manner, using metamodel objects to provide
type safety. For developers it is important that the task of the metamodel generation can be
automated. Hibernate Static Metamodel Generator is an annotation processor based on the
&jsr269Ref; with the task of creating JPA 2 static metamodel classes. The following example
show two JPA 2 entities <classname>Order</classname> and <classname>Item</classname>,
together with the metamodel class <classname>Order_</classname> and a typesafe query.</para>
<para>JPA 2 defines a new typesafe <classname>Criteria</classname> API
which allows criteria queries to be constructed in a strongly-typed
manner, using metamodel objects to provide type safety. For developers
it is important that the task of the metamodel generation can be
automated. Hibernate Static Metamodel Generator is an annotation
processor based on the &jsr269Ref; with the task of creating JPA 2
static metamodel classes. The following example show two JPA 2 entities
<classname>Order</classname> and <classname>Item</classname>, together
with the metamodel class <classname>Order_</classname> and a typesafe
query.</para>
<example id="jpa2-entity-example">
<title>JPA 2 annotated entities <classname>Order</classname> and
<classname>Item</classname></title>
<programlisting role="JAVA" language="JAVA">
<classname>Item</classname></title>
<programlisting language="JAVA" role="JAVA">
@Entity
public class Order {
@Id
@ -77,24 +94,26 @@ public class Order {
}
@Entity
public class Item {
public class Item {
@Id
@GeneratedValue
Integer id;
int quantity;
Integer id;
int quantity;
@ManyToOne
Order order;
// standard setter/getter methods
...
}
</programlisting>
</example>
<example id="metamodel-class-example">
<title>Metamodel class <classname>Order_</classname></title>
<programlisting role="JAVA" language="JAVA">
<title>Metamodel class <classname>Order_</classname></title>
<programlisting language="JAVA" role="JAVA">
@StaticMetamodel(Order.class)
public class Order_ {
public static volatile SingularAttribute&lt;Order, Integer&gt; id;
@ -104,9 +123,11 @@ public class Order_ {
}
</programlisting>
</example>
<example id="criteria-example">
<title>Typesafe citeria query</title>
<programlisting role="JAVA" language="JAVA">
<programlisting language="JAVA" role="JAVA">
CriteriaBuilder cb = entityManager.getCriteriaBuilder();
CriteriaQuery&lt;Order&gt; cq = cb.createQuery(Order.class);
SetJoin&lt;Order, Item&gt; itemNode = cq.from(Order.class).join(Order_.items);
@ -114,110 +135,164 @@ cq.where( cb.equal(itemNode.get(Item_.id), 5 ) ).distinct(true);
</programlisting>
</example>
<tip>
<para>The Metamodel Generator also takes into consideration xml
configuration specified in orm.xml or mapping files specified in
persistence.xml. However, if all configuration is in XML you need to
add in at least on of the mapping file the following persistence unit
metadata:<programlisting>&lt;persistence-unit-metadata&gt;
&lt;xml-mapping-metadata-complete/&gt;
&lt;/persistence-unit-metadata&gt;</programlisting></para>
</tip>
</section>
<section>
<title>Canonical Metamodel</title>
<para>The structure of the metamodel classes is described in the &jpa2Ref;, but for completeness the definition
is repeated in the following paragraphs. Feel free to skip ahead to <xref
linkend="chapter-usage"/> if you are not interested into the gory details.</para>
<para>The annotation processor produces for every managed class in the persistence unit a
metamodel class based on these rules:</para>
<para>The structure of the metamodel classes is described in the
&jpa2Ref;, but for completeness the definition is repeated in the
following paragraphs. Feel free to skip ahead to <xref
linkend="chapter-usage" /> if you are not interested into the gory
details.</para>
<para>The annotation processor produces for every managed class in the
persistence unit a metamodel class based on these rules:</para>
<para><itemizedlist>
<listitem>
<para>For each managed class <classname>X</classname> in package p, a metamodel class
<classname>X_</classname> in package p is created.</para>
<para>For each managed class <classname>X</classname> in package
p, a metamodel class <classname>X_</classname> in package p is
created.</para>
</listitem>
<listitem>
<para>The name of the metamodel class is derived from the name of the managed class by
appending "_" to the name of the managed class.</para>
<para>The name of the metamodel class is derived from the name of
the managed class by appending "_" to the name of the managed
class.</para>
</listitem>
<listitem>
<para>The metamodel class <classname>X_</classname> must be annotated with the
<classname>javax.persistence.StaticMetamodel</classname> annotation.</para>
<para>The metamodel class <classname>X_</classname> must be
annotated with the
<classname>javax.persistence.StaticMetamodel</classname>
annotation.</para>
</listitem>
<listitem>
<para>If class <classname>X</classname> extends another class <classname>S</classname>,
where <classname>S</classname> is the most derived managed class (i.e., entity or
mapped superclass) extended by <classname>X</classname>, then class
<classname>X_</classname> must extend class <classname>S_</classname>, where
<classname>S_</classname> is the metamodel class created for
<classname>S</classname>.</para>
<para>If class <classname>X</classname> extends another class
<classname>S</classname>, where <classname>S</classname> is the
most derived managed class (i.e., entity or mapped superclass)
extended by <classname>X</classname>, then class
<classname>X_</classname> must extend class
<classname>S_</classname>, where <classname>S_</classname> is the
metamodel class created for <classname>S</classname>.</para>
</listitem>
<listitem>
<para>For every persistent non-collection-valued attribute y declared by class
<classname>X</classname>, where the type of y is <classname>Y</classname>, the
metamodel class must contain a declaration as follows:
</para>
<programlisting>public static volatile SingularAttribute&lt;X, Y&gt; y;</programlisting>
<para>For every persistent non-collection-valued attribute y
declared by class <classname>X</classname>, where the type of y is
<classname>Y</classname>, the metamodel class must contain a
declaration as follows:</para>
<programlisting>public static volatile SingularAttribute&lt;X, Y&gt; y;</programlisting>
</listitem>
<listitem>
<para>For every persistent collection-valued attribute z declared by class
<classname>X</classname>, where the element type of z is <classname>Z</classname>,
the metamodel class must contain a declaration as follows:<itemizedlist>
<para>For every persistent collection-valued attribute z declared
by class <classname>X</classname>, where the element type of z is
<classname>Z</classname>, the metamodel class must contain a
declaration as follows:<itemizedlist>
<listitem>
<para>if the collection type of z is java.util.Collection, then</para>
<para>if the collection type of z is java.util.Collection,
then</para>
<programlisting>public static volatile CollectionAttribute&lt;X, Z&gt; z;</programlisting>
</listitem>
<listitem>
<para>if the collection type of z is java.util.Set, then</para>
<para>if the collection type of z is java.util.Set,
then</para>
<programlisting>public static volatile SetAttribute&lt;X, Z&gt; z;</programlisting>
</listitem>
<listitem>
<para>if the collection type of z is java.util.List, then</para>
<para>if the collection type of z is java.util.List,
then</para>
<programlisting>public static volatile ListAttribute&lt;X, Z&gt; z;</programlisting>
</listitem>
<listitem>
<para>if the collection type of z is java.util.Map, then
<programlisting>public static volatile MapAttribute&lt;X, K, Z&gt; z;</programlisting>
where K is the type of the key of the map in class X</para>
<programlisting>public static volatile MapAttribute&lt;X, K, Z&gt; z;</programlisting>
where K is the type of the key of the map in class X</para>
</listitem>
</itemizedlist></para>
</listitem>
</itemizedlist>Import statements must be included for the needed
<classname>javax.persistence.metamodel</classname> types as appropriate and all classes
<classname>X</classname>, <classname>Y</classname>, <classname>Z</classname>, and
<classname>K</classname>.</para>
<classname>javax.persistence.metamodel</classname> types as appropriate
and all classes <classname>X</classname>, <classname>Y</classname>,
<classname>Z</classname>, and <classname>K</classname>.</para>
</section>
</chapter>
<chapter id="chapter-usage">
<title>Usage</title>
<para>The jar file for the annotation processor can be found in the <ulink
url="http://repository.jboss.com/">JBoss Maven repository</ulink> using <xref
linkend="maven-dependency"/>.</para>
url="http://repository.jboss.com/">JBoss Maven repository</ulink> using
<xref linkend="maven-dependency" />.</para>
<example id="maven-dependency">
<title>Maven dependency </title>
<programlisting role="XML" language="XML">&lt;dependency&gt;
<title>Maven dependency</title>
<programlisting language="XML" role="XML">&lt;dependency&gt;
&lt;groupId&gt;org.hibernate&lt;/groupId&gt;
&lt;artifactId&gt;hibernate-jpamodelgen&lt;/artifactId&gt;
&lt;version&gt;1.0.0&lt;/version&gt;
&lt;/dependency&gt;</programlisting>
</example>
<para>Alternatively, a full distribution package can be downloaded from <ulink
url="http://sourceforge.net/projects/hibernate/files/hibernate-jpamodelgen">SourceForge</ulink>.</para>
<para>In most cases the annotation processor will automatically run provided
the processor jar is added to the classpath and a JDK 6 is used. This happens due to <ulink
url="http://java.sun.com/j2se/1.4.2/docs/guide/jar/jar.html#Service%20Provider">Java's
Service Provider</ulink> contract and the fact the the Hibernate Static Metamodel Generator
jar files contains the file <classname>javax.annotation.processing.Processor</classname> in
the <filename>META-INF/services</filename> directory. The fully qualified name of the
processor itself is:
<classname>org.hibernate.jpamodelgen.JPAMetaModelEntityProcessor</classname>. <note>
<para>Alternatively, a full distribution package can be downloaded from
<ulink
url="http://sourceforge.net/projects/hibernate/files/hibernate-jpamodelgen">SourceForge</ulink>.</para>
<para>In most cases the annotation processor will automatically run
provided the processor jar is added to the classpath and a JDK 6 is used.
This happens due to <ulink
url="http://java.sun.com/j2se/1.4.2/docs/guide/jar/jar.html#Service%20Provider">Java's
Service Provider</ulink> contract and the fact the the Hibernate Static
Metamodel Generator jar files contains the file
<classname>javax.annotation.processing.Processor</classname> in the
<filename>META-INF/services</filename> directory. The fully qualified name
of the processor itself is:
<classname>org.hibernate.jpamodelgen.JPAMetaModelEntityProcessor</classname>.
<note>
<para>The use of a Java 6 compiler is a prerequisite.</para>
</note></para>
<section>
<title>Usage from the command line</title>
<section id="usage-ant">
<title>Usage with Ant</title>
<para>As mentioned before, the annotation processor will run automatically each time the
Java compiler is called, provided the jar file is on the classpath. Sometimes, however, it is
useful to control the annotation processing in more detail, for example if you
exclusively want to run the processor without compiling any other source files. <xref
linkend="javac-task-example"/> shows how Ant's <ulink
url="http://ant.apache.org/manual/CoreTasks/javac.html">Javac Task</ulink> can be
configured to just run annotation processing.</para>
<para>As mentioned before, the annotation processor will run
automatically each time the Java compiler is called, provided the jar
file is on the classpath. Sometimes, however, it is useful to control
the annotation processing in more detail, for example if you
exclusively want to run the processor without compiling any other
source files. <xref linkend="javac-task-example" /> shows how Ant's
<ulink url="http://ant.apache.org/manual/CoreTasks/javac.html">Javac
Task</ulink> can be configured to just run annotation
processing.</para>
<example id="javac-task-example">
<title>Javac Task configuration</title>
<programlisting role="XML" language="XML">&lt;javac srcdir="${src.dir}"
<programlisting language="XML" role="XML">&lt;javac srcdir="${src.dir}"
destdir="${target.dir}"
failonerror="false"
fork="true"
@ -225,23 +300,33 @@ cq.where( cb.equal(itemNode.get(Item_.id), 5 ) ).distinct(true);
&lt;compilerarg value="-proc:only"/&gt;
&lt;/javac&gt;</programlisting>
</example>
<para>The option <emphasis>-proc:only</emphasis> instructs the compiler to just run the
annotation processing. You can also completely disable processing by specifying
<emphasis>-proc:none</emphasis>.</para>
<para>The option <emphasis>-proc:only</emphasis> instructs the
compiler to just run the annotation processing. You can also
completely disable processing by specifying
<emphasis>-proc:none</emphasis>.</para>
<tip>
<para>Run <literal>'javac -help'</literal> to see which other annotation processor
relevant options can be specified.</para>
<para>Run <literal>'javac -help'</literal> to see which other
annotation processor relevant options can be specified.</para>
</tip>
</section>
<section>
<title>Usage with Maven</title>
<para>There are several ways of running the annotation processor as part of a Maven build.
Again, it will automatically run if you are using a JDK 6 compiler and the annotation
processor jar is on the classpath. In case you have more than one annotation processors on
your classpath you can explicitly pass the processor option to the compiler plugin:</para>
<example>
<title>Maven compiler plugin configuration - direct execution</title>
<programlisting role="XML" language="XML">&lt;plugin&gt;
<para>There are several ways of running the annotation processor as
part of a Maven build. Again, it will automatically run if you are
using a JDK 6 compiler and the annotation processor jar is on the
classpath. In case you have more than one annotation processors on
your classpath you can explicitly pass the processor option to the
compiler plugin:</para>
<example>
<title>Maven compiler plugin configuration - direct
execution</title>
<programlisting language="XML" role="XML">&lt;plugin&gt;
&lt;artifactId&gt;maven-compiler-plugin&lt;/artifactId&gt;
&lt;configuration&gt;
&lt;source&gt;1.6&lt;/source&gt;
@ -251,17 +336,23 @@ cq.where( cb.equal(itemNode.get(Item_.id), 5 ) ).distinct(true);
&lt;/compilerArguments&gt;
&lt;/configuration&gt;
&lt;/plugin&gt;</programlisting>
</example>
<para>The maven-compiler-plugin approach has the disadvantage that the maven compiler plugin
does currently not allow to specify multiple compiler arguments (<ulink
url="http://jira.codehaus.org/browse/MCOMPILER-62">MCOMPILER-62</ulink>) and that
messages from the Messenger API are suppressed (<ulink
url="http://jira.codehaus.org/browse/MCOMPILER-66">MCOMPILER-66</ulink>). A better
approach is to disable annotation processing for the compiler plugin as seen in <xref
linkend="disable-processing-maven-compiler-plugin"/>.</para>
</example>
<para>The maven-compiler-plugin approach has the disadvantage that the
maven compiler plugin does currently not allow to specify multiple
compiler arguments (<ulink
url="http://jira.codehaus.org/browse/MCOMPILER-62">MCOMPILER-62</ulink>)
and that messages from the Messenger API are suppressed (<ulink
url="http://jira.codehaus.org/browse/MCOMPILER-66">MCOMPILER-66</ulink>).
A better approach is to disable annotation processing for the compiler
plugin as seen in <xref
linkend="disable-processing-maven-compiler-plugin" />.</para>
<example id="disable-processing-maven-compiler-plugin">
<title>Maven compiler plugin configuration - indirect execution</title>
<programlisting role="XML" language="XML">&lt;plugin&gt;
<title>Maven compiler plugin configuration - indirect
execution</title>
<programlisting language="XML" role="XML">&lt;plugin&gt;
&lt;artifactId&gt;maven-compiler-plugin&lt;/artifactId&gt;
&lt;configuration&gt;
&lt;source&gt;1.6&lt;/source&gt;
@ -270,16 +361,21 @@ cq.where( cb.equal(itemNode.get(Item_.id), 5 ) ).distinct(true);
&lt;/configuration&gt;
&lt;/plugin&gt;</programlisting>
</example>
<para>Once disabled, the <ulink url="http://code.google.com/p/maven-annotation-plugin/"
>maven-annotation-plugin</ulink> for annotation processing (you will need the following
additional maven repositories: <ulink
url="http://maven-annotation-plugin.googlecode.com/svn/trunk/mavenrepo"
>maven-annotation-plugin</ulink> and <ulink
url="http://www.jfrog.org/artifactory/plugins-releases">jfrog</ulink>) can be used. The
configuration can be seen in <xref linkend="maven-processor-plugin"/>.</para>
<para>Once disabled, the <ulink
url="http://code.google.com/p/maven-annotation-plugin/">maven-annotation-plugin</ulink>
for annotation processing (you will need the following additional
maven repositories: <ulink
url="http://maven-annotation-plugin.googlecode.com/svn/trunk/mavenrepo">maven-annotation-plugin</ulink>
and <ulink
url="http://www.jfrog.org/artifactory/plugins-releases">jfrog</ulink>)
can be used. The configuration can be seen in <xref
linkend="maven-processor-plugin" />.</para>
<example id="maven-processor-plugin">
<title>Configuration with maven-annotation-plugin</title>
<programlisting role="XML" language="XML">&lt;plugin&gt;
<programlisting language="XML" role="XML">&lt;plugin&gt;
&lt;groupId&gt;org.bsc.maven&lt;/groupId&gt;
&lt;artifactId&gt;maven-processor-plugin&lt;/artifactId&gt;
&lt;executions&gt;
@ -318,133 +414,198 @@ cq.where( cb.equal(itemNode.get(Item_.id), 5 ) ).distinct(true);
</example>
</section>
</section>
<section>
<title>Usage within the IDE</title>
<para>Of course you also want to have annotation processing available in your favorite IDE.
The following paragraphs and screenshots show you how to enable the Hibernate Static
Metamodel Generator within your IDE.</para>
<para>Of course you also want to have annotation processing available in
your favorite IDE. The following paragraphs and screenshots show you how
to enable the Hibernate Static Metamodel Generator within your
IDE.</para>
<section>
<title>Idea</title>
<para>Intellij Idea contains from version 9.x onwards a specifc configuration section for
annotation processing under the project settings window. The screenshots show you how to
configure the Hibernate Static Metamodel Generator.</para>
<para>Intellij Idea contains from version 9.x onwards a specifc
configuration section for annotation processing under the project
settings window. The screenshots show you how to configure the
Hibernate Static Metamodel Generator.</para>
<mediaobject>
<imageobject role="fo">
<imagedata align="center" contentdepth="" contentwidth="150mm"
fileref="idea-annotation-processor-config.png" scalefit=""/>
fileref="idea-annotation-processor-config.png"
scalefit="" />
</imageobject>
<imageobject role="html">
<imagedata depth="" fileref="idea-annotation-processor-config.png" scalefit="1"/>
<imagedata depth="" fileref="idea-annotation-processor-config.png"
scalefit="1" />
</imageobject>
</mediaobject>
</section>
<section>
<title>Eclipse</title>
<para>In Eclipse, from the Galileo release onwards, exists an additional configuration
section under Java Compiler. There you can configure all kinds of aspects of annotation
processing. Just check the "Enable annotation processing" option, configure the directory
for the generated sources and finally add the Hibernate Static Metamodel Generator and JPA
2 jar files to the factory path.</para>
<para>In Eclipse, from the Galileo release onwards, exists an
additional configuration section under Java Compiler. There you can
configure all kinds of aspects of annotation processing. Just check
the "Enable annotation processing" option, configure the directory for
the generated sources and finally add the Hibernate Static Metamodel
Generator and JPA 2 jar files to the factory path.</para>
<mediaobject>
<imageobject role="fo">
<imagedata align="center" contentdepth="" contentwidth="150mm"
fileref="eclipse-annotation-processor-config.png" scalefit=""/>
fileref="eclipse-annotation-processor-config.png"
scalefit="" />
</imageobject>
<imageobject role="html">
<imagedata depth="" fileref="eclipse-annotation-processor-config.png" scalefit="1"/>
<imagedata depth=""
fileref="eclipse-annotation-processor-config.png"
scalefit="1" />
</imageobject>
</mediaobject>
</section>
<section>
<title>NetBeans</title>
<para>Netbeans support for annotation processors is at the time of this wrinting still in
the making. Refer to NetBeans issues <ulink
url="http://www.netbeans.org/issues/show_bug.cgi?id=111065">111065</ulink>, <ulink
url="http://www.netbeans.org/issues/show_bug.cgi?id=111293">111293</ulink> and <ulink
url="http://www.netbeans.org/issues/show_bug.cgi?id=111294">111294</ulink>.</para>
<para>Netbeans support for annotation processors is at the time of
this wrinting still in the making. Refer to NetBeans issues <ulink
url="http://www.netbeans.org/issues/show_bug.cgi?id=111065">111065</ulink>,
<ulink
url="http://www.netbeans.org/issues/show_bug.cgi?id=111293">111293</ulink>
and <ulink
url="http://www.netbeans.org/issues/show_bug.cgi?id=111294">111294</ulink>.</para>
</section>
</section>
<section>
<title>Processor specific options</title>
<para>The Hibernate Static Metamodel Generator accepts a series of custom options which can be
passed to the processor in the format <literal>-A[property]=[value]</literal>. The supported
properties are:<table>
<title>Annotation processor options (passed via -A[property]=[value])</title>
<para>The Hibernate Static Metamodel Generator accepts a series of
custom options which can be passed to the processor in the format
<literal>-A[property]=[value]</literal>. The supported properties
are:<table>
<title>Annotation processor options (passed via
-A[property]=[value])</title>
<tgroup cols="2">
<tbody>
<row>
<entry><emphasis role="bold">Option name</emphasis></entry>
<entry><emphasis role="bold">Option value and usage</emphasis></entry>
<entry><emphasis role="bold">Option value and
usage</emphasis></entry>
</row>
<row>
<entry>debug</entry>
<entry>if set to <literal>true</literal> additional trace information will be
outputted by the processor</entry>
<entry>if set to <literal>true</literal> additional trace
information will be outputted by the processor</entry>
</row>
<row>
<entry>persistenceXml</entry>
<entry>Per default the processor looks in <filename>/META-INF</filename> for
persistence.xml. Specifying this option a <filename>persitence.xml</filename> file
from a different location can be specified (has to be on the classpath)</entry>
<entry>Per default the processor looks in
<filename>/META-INF</filename> for persistence.xml. Specifying
this option a <filename>persitence.xml</filename> file from a
different location can be specified (has to be on the
classpath)</entry>
</row>
<row>
<entry>ormXml</entry>
<entry>Allows to specify additional entity mapping files. The specified value for
this option is a comma separated string of mapping file names. Even when this
option is specified <filename>/META-INF/orm.xml</filename> is implicit.</entry>
<entry>Allows to specify additional entity mapping files. The
specified value for this option is a comma separated string of
mapping file names. Even when this option is specified
<filename>/META-INF/orm.xml</filename> is implicit.</entry>
</row>
<row>
<entry>lazyXmlParsing</entry>
<entry>Possible values are <literal>true</literal> or <literal>false</literal>. If
set to <literal>true</literal> the annotation processor tries to determine whether
any of the xml files has changed between invocations and if unchanged skips the
xml parsing. This feature is experimental and contains the risk of wron results in
some cases of mixed mode configurations. To determine wether a file has been
modified a temporary file
<filename>Hibernate-Static-Metamodel-Generator.tmp</filename> is used. This file
gets created in the <literal>java.io.tmpdir</literal> directory.</entry>
<entry>Possible values are <literal>true</literal> or
<literal>false</literal>. If set to <literal>true</literal>
the annotation processor tries to determine whether any of the
xml files has changed between invocations and if unchanged
skips the xml parsing. This feature is experimental and
contains the risk of wron results in some cases of mixed mode
configurations. To determine wether a file has been modified a
temporary file
<filename>Hibernate-Static-Metamodel-Generator.tmp</filename>
is used. This file gets created in the
<literal>java.io.tmpdir</literal> directory.</entry>
</row>
<row>
<entry>fullyAnnotationConfigured</entry>
<entry>if set to <literal>true</literal> the processor will
ignore <filename>orm.xml</filename> and
<filename>persistence.xml.</filename></entry>
</row>
</tbody>
</tgroup>
</table></para>
</section>
</chapter>
<appendix>
<title>Further information</title>
<para>For further usage question or problems consult the <ulink
url="https://forum.hibernate.org/viewforum.php?f=9">Hibernate Forum</ulink>. For bug reports
use the <ulink url="http://opensource.atlassian.com/projects/hibernate/browse/METAGEN"
userlevel="">METAGEN</ulink> project in the Hibernate Jira instance. Feedback is always
welcome.</para>
url="https://forum.hibernate.org/viewforum.php?f=9">Hibernate
Forum</ulink>. For bug reports use the <ulink
url="http://opensource.atlassian.com/projects/hibernate/browse/METAGEN"
userlevel="">METAGEN</ulink> project in the Hibernate Jira instance.
Feedback is always welcome.</para>
</appendix>
<bibliography>
<title>References</title>
<biblioentry id="JSR_269">
<abbrev id="JSR_269_ABBREV">Pluggable Annotation Processing API</abbrev>
<title>JSR 269: Pluggable Annotation Processing API</title>
<copyright>
<year>2006</year>
<holder>SUN MICROSYSTEMS, INC.</holder>
</copyright>
<bibliomisc>
<email>jsr-269-feedback@sun.com</email>
<ulink url="http://jcp.org/en/jsr/detail?id=269">JSR 269 JCP Page</ulink>
</bibliomisc>
<bibliomisc><email>jsr-269-feedback@sun.com</email> <ulink
url="http://jcp.org/en/jsr/detail?id=269">JSR 269 JCP
Page</ulink></bibliomisc>
</biblioentry>
<biblioentry id="JPA2">
<abbrev id="JPA2_ABBREV">JPA 2 Specification</abbrev>
<title>JSR 317: <trademark>Java</trademark> Persistence API, Version 2.0 </title>
<title>JSR 317: <trademark>Java</trademark> Persistence API, Version
2.0</title>
<collab>
<collabname>Java Persistence 2.0 Expert Group</collabname>
</collab>
<copyright>
<year>2009</year>
<holder>SUN MICROSYSTEMS, INC.</holder>
</copyright>
<bibliomisc>
<email>jsr-317-feedback@sun.com</email>
<ulink url="http://jcp.org/en/jsr/detail?id=317">JSR 317 JCP Page</ulink>
</bibliomisc>
<bibliomisc><email>jsr-317-feedback@sun.com</email> <ulink
url="http://jcp.org/en/jsr/detail?id=317">JSR 317 JCP
Page</ulink></bibliomisc>
</biblioentry>
</bibliography>
</book>

30
tooling/metamodel-generator/src/main/java/org/hibernate/jpamodelgen/JPAMetaModelEntityProcessor.java
View File

@ -61,7 +61,9 @@ import static javax.lang.model.SourceVersion.RELEASE_6;
* @author Hardy Ferentschik
* @author Emmanuel Bernard
*/
@SupportedAnnotationTypes("*")
@SupportedAnnotationTypes({
"javax.persistence.Entity", "javax.persistence.MappedSuperclass", "javax.persistence.Embeddable"
})
@SupportedSourceVersion(RELEASE_6)
@SupportedOptions({
JPAMetaModelEntityProcessor.DEBUG_OPTION,
@ -79,9 +81,7 @@ public class JPAMetaModelEntityProcessor extends AbstractProcessor {
private static final Boolean ALLOW_OTHER_PROCESSORS_TO_CLAIM_ANNOTATIONS = Boolean.FALSE;
private boolean xmlProcessed = false;
private Context context;
private boolean fullyAnnotationConfigured = false;
public void init(ProcessingEnvironment env) {
super.init( env );
@ -91,24 +91,28 @@ public class JPAMetaModelEntityProcessor extends AbstractProcessor {
);
String tmp = env.getOptions().get( JPAMetaModelEntityProcessor.FULLY_ANNOTATION_CONFIGURED_OPTION );
fullyAnnotationConfigured = Boolean.parseBoolean( tmp );
boolean fullyAnnotationConfigured = Boolean.parseBoolean( tmp );
if ( !fullyAnnotationConfigured ) {
XmlParser parser = new XmlParser( context );
parser.parseXml();
if ( context.isPersistenceUnitCompletelyXmlConfigured() ) {
createMetaModelClasses();
}
}
}
@Override
public boolean process(final Set<? extends TypeElement> annotations, final RoundEnvironment roundEnvironment) {
if ( roundEnvironment.processingOver() ) {
context.logMessage( Diagnostic.Kind.OTHER, "Last processing round." );
createMetaModelClasses();
context.logMessage( Diagnostic.Kind.OTHER, "Finished processing" );
if ( !context.isPersistenceUnitCompletelyXmlConfigured() ) {
context.logMessage( Diagnostic.Kind.OTHER, "Last processing round." );
createMetaModelClasses();
context.logMessage( Diagnostic.Kind.OTHER, "Finished processing" );
}
return ALLOW_OTHER_PROCESSORS_TO_CLAIM_ANNOTATIONS;
}
if ( !fullyAnnotationConfigured && !xmlProcessed ) {
XmlParser parser = new XmlParser( context );
parser.parseXml();
xmlProcessed = true;
}
if ( context.isPersistenceUnitCompletelyXmlConfigured() ) {
context.logMessage(
Diagnostic.Kind.OTHER,

7
tooling/metamodel-generator/src/main/java/org/hibernate/jpamodelgen/model/ImportContext.java
View File

@ -38,10 +38,9 @@ public interface ImportContext {
*
* @return import string
*/
public abstract String importType(String fqcn);
String importType(String fqcn);
public abstract String staticImport(String fqcn, String member);
public abstract String generateImports();
String staticImport(String fqcn, String member);
String generateImports();
}

41
tooling/metamodel-generator/src/test/java/org/hibernate/jpamodelgen/test/xmlmetacomplete/Dummy.java Normal file
View File

@ -0,0 +1,41 @@
/*
* JBoss, Home of Professional Open Source
* Copyright 2010, Red Hat Middleware LLC, and individual contributors
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
* http://www.apache.org/licenses/LICENSE-2.0
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
// $Id:$
package org.hibernate.jpamodelgen.test.xmlmetacomplete;
import javax.persistence.Entity;
import javax.persistence.Id;
/**
* @author Hardy Ferentschik
*/
@Entity
public class Dummy {
@Id
private long id;
public long getId() {
return id;
}
public void setId(long id) {
this.id = id;
}
}

58
tooling/metamodel-generator/src/test/java/org/hibernate/jpamodelgen/test/xmlmetacomplete/XmlMetaDataCompleteTest.java Normal file
View File

@ -0,0 +1,58 @@
/*
* JBoss, Home of Professional Open Source
* Copyright 2010, Red Hat Middleware LLC, and individual contributors
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
* http://www.apache.org/licenses/LICENSE-2.0
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
// $Id: XmlMappingTest.java 20721 2010-09-27 12:40:10Z hardy.ferentschik $
package org.hibernate.jpamodelgen.test.xmlmetacomplete;
import java.util.HashMap;
import java.util.Map;
import org.testng.annotations.Test;
import org.hibernate.jpamodelgen.JPAMetaModelEntityProcessor;
import org.hibernate.jpamodelgen.test.util.CompilationTest;
import org.hibernate.jpamodelgen.test.util.TestUtil;
import static org.hibernate.jpamodelgen.test.util.TestUtil.assertNoSourceFileGeneratedFor;
/**
* @author Hardy Ferentschik
*/
public class XmlMetaDataCompleteTest extends CompilationTest {
@Test
public void testNoMetaModelGenerated() {
// the xml mapping files used in the example say that the xml data is meta complete. For that
// reason there should be no meta model source file for the annotated Dummy entity
assertNoSourceFileGeneratedFor( Dummy.class );
}
@Override
protected String getPackageNameOfTestSources() {
return XmlMetaDataCompleteTest.class.getPackage().getName();
}
@Override
protected Map<String, String> getProcessorOptions() {
Map<String, String> properties = new HashMap<String, String>();
properties.put(
JPAMetaModelEntityProcessor.PERSISTENCE_XML_OPTION,
TestUtil.fcnToPath( XmlMetaDataCompleteTest.class.getPackage().getName() ) + "/persistence.xml"
);
return properties;
}
}

37
tooling/metamodel-generator/src/test/java/org/hibernate/jpamodelgen/test/xmlonly/XmlOnly.java Normal file
View File

@ -0,0 +1,37 @@
/*
* JBoss, Home of Professional Open Source
* Copyright 2010, Red Hat Middleware LLC, and individual contributors
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
* http://www.apache.org/licenses/LICENSE-2.0
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
// $Id:$
package org.hibernate.jpamodelgen.test.xmlonly;
/**
* @author Hardy Ferentschik
*/
public class XmlOnly {
private long id;
public long getId() {
return id;
}
public void setId(long id) {
this.id = id;
}
}

56
tooling/metamodel-generator/src/test/java/org/hibernate/jpamodelgen/test/xmlonly/XmlOnlyTest.java Normal file
View File

@ -0,0 +1,56 @@
/*
* JBoss, Home of Professional Open Source
* Copyright 2010, Red Hat Middleware LLC, and individual contributors
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
* http://www.apache.org/licenses/LICENSE-2.0
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
// $Id$
package org.hibernate.jpamodelgen.test.xmlonly;
import java.util.HashMap;
import java.util.Map;
import org.testng.annotations.Test;
import org.hibernate.jpamodelgen.JPAMetaModelEntityProcessor;
import org.hibernate.jpamodelgen.test.util.CompilationTest;
import org.hibernate.jpamodelgen.test.util.TestUtil;
import static org.hibernate.jpamodelgen.test.util.TestUtil.assertMetamodelClassGeneratedFor;
/**
* @author Hardy Ferentschik
*/
public class XmlOnlyTest extends CompilationTest {
@Test
public void testMetaModelGeneratedForXmlConiguredEntity() {
assertMetamodelClassGeneratedFor( XmlOnly.class );
}
@Override
protected String getPackageNameOfTestSources() {
return XmlOnlyTest.class.getPackage().getName();
}
@Override
protected Map<String, String> getProcessorOptions() {
Map<String, String> properties = new HashMap<String, String>();
properties.put(
JPAMetaModelEntityProcessor.PERSISTENCE_XML_OPTION,
TestUtil.fcnToPath( XmlOnlyTest.class.getPackage().getName() ) + "/persistence.xml"
);
return properties;
}
}

28
tooling/metamodel-generator/src/test/resources/org/hibernate/jpamodelgen/test/xmlmetacomplete/foo.xml Normal file
View File

@ -0,0 +1,28 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
~ JBoss, Home of Professional Open Source
~ Copyright 2010, Red Hat Middleware LLC, and individual contributors
~ by the @authors tag. See the copyright.txt in the distribution for a
~ full listing of individual contributors.
~
~ Licensed under the Apache License, Version 2.0 (the "License");
~ you may not use this file except in compliance with the License.
~ You may obtain a copy of the License at
~ http://www.apache.org/licenses/LICENSE-2.0
~ Unless required by applicable law or agreed to in writing, software
~ distributed under the License is distributed on an "AS IS" BASIS,
~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
~ See the License for the specific language governing permissions and
~ limitations under the License.
-->
<entity-mappings xmlns="http://java.sun.com/xml/ns/persistence/orm"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/persistence/orm orm_2_0.xsd"
version="2.0"
>
<persistence-unit-metadata>
<xml-mapping-metadata-complete/>
</persistence-unit-metadata>
</entity-mappings>

25
tooling/metamodel-generator/src/test/resources/org/hibernate/jpamodelgen/test/xmlmetacomplete/persistence.xml Normal file
View File

@ -0,0 +1,25 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
~ JBoss, Home of Professional Open Source
~ Copyright 2010, Red Hat Middleware LLC, and individual contributors
~ by the @authors tag. See the copyright.txt in the distribution for a
~ full listing of individual contributors.
~
~ Licensed under the Apache License, Version 2.0 (the "License");
~ you may not use this file except in compliance with the License.
~ You may obtain a copy of the License at
~ http://www.apache.org/licenses/LICENSE-2.0
~ Unless required by applicable law or agreed to in writing, software
~ distributed under the License is distributed on an "AS IS" BASIS,
~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
~ See the License for the specific language governing permissions and
~ limitations under the License.
-->
<persistence xmlns="http://java.sun.com/xml/ns/persistence"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/persistence persistence.xsd" version="2.0">
<persistence-unit name="annotation-processor" transaction-type="JTA">
<mapping-file>/org/hibernate/jpamodelgen/test/xmlmetacomplete/foo.xml</mapping-file>
</persistence-unit>
</persistence>

25
tooling/metamodel-generator/src/test/resources/org/hibernate/jpamodelgen/test/xmlonly/persistence.xml Normal file
View File

@ -0,0 +1,25 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
~ JBoss, Home of Professional Open Source
~ Copyright 2010, Red Hat Middleware LLC, and individual contributors
~ by the @authors tag. See the copyright.txt in the distribution for a
~ full listing of individual contributors.
~
~ Licensed under the Apache License, Version 2.0 (the "License");
~ you may not use this file except in compliance with the License.
~ You may obtain a copy of the License at
~ http://www.apache.org/licenses/LICENSE-2.0
~ Unless required by applicable law or agreed to in writing, software
~ distributed under the License is distributed on an "AS IS" BASIS,
~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
~ See the License for the specific language governing permissions and
~ limitations under the License.
-->
<persistence xmlns="http://java.sun.com/xml/ns/persistence"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/persistence persistence.xsd" version="2.0">
<persistence-unit name="annotation-processor" transaction-type="JTA">
<mapping-file>/org/hibernate/jpamodelgen/test/xmlonly/xmlonly.xml</mapping-file>
</persistence-unit>
</persistence>

34
tooling/metamodel-generator/src/test/resources/org/hibernate/jpamodelgen/test/xmlonly/xmlonly.xml Normal file
View File

@ -0,0 +1,34 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
~ JBoss, Home of Professional Open Source
~ Copyright 2010, Red Hat Middleware LLC, and individual contributors
~ by the @authors tag. See the copyright.txt in the distribution for a
~ full listing of individual contributors.
~
~ Licensed under the Apache License, Version 2.0 (the "License");
~ you may not use this file except in compliance with the License.
~ You may obtain a copy of the License at
~ http://www.apache.org/licenses/LICENSE-2.0
~ Unless required by applicable law or agreed to in writing, software
~ distributed under the License is distributed on an "AS IS" BASIS,
~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
~ See the License for the specific language governing permissions and
~ limitations under the License.
-->
<entity-mappings xmlns="http://java.sun.com/xml/ns/persistence/orm"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/persistence/orm orm_2_0.xsd"
version="2.0"
>
<persistence-unit-metadata>
<xml-mapping-metadata-complete/>
</persistence-unit-metadata>
<package>org.hibernate.jpamodelgen.test.xmlonly</package>
<entity class="XmlOnly" access="FIELD" metadata-complete="true">
<attributes>
<id name="id"/>
</attributes>
</entity>
</entity-mappings>