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

METAGEN-4

This commit is contained in:
Hardy Ferentschik 2010-02-15 22:40:30 +00:00 committed by Strong Liu
parent 787359a073
commit 443ae2de29
3 changed files with 247 additions and 81 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
tooling/metamodel-generator/pom.xml
View File

@ -236,15 +236,6 @@
<descriptor>src/main/assembly/dist.xml</descriptor>
</descriptors>
</configuration>
<executions>
<execution>
<id>make-assembly</id>
<phase>site</phase>
<goals>
<goal>assembly</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
@ -254,7 +245,7 @@
<autoVersionSubmodules>true</autoVersionSubmodules>
<allowTimestampedSnapshots>true</allowTimestampedSnapshots>
<remoteTagging>true</remoteTagging>
<goals>package deploy</goals>
<goals>package deploy javadoc:javadoc org.jboss.maven.plugins:maven-jdocbook-plugin:2.2.0:resources org.jboss.maven.plugins:maven-jdocbook-plugin:2.2.0:generate assembly:assembly</goals>
</configuration>
</plugin>
<plugin>

24
tooling/metamodel-generator/src/main/assembly/dist.xml
View File

@ -22,7 +22,6 @@
<id>dist</id>
<formats>
<format>tar.gz</format>
<format>tar.bz2</format>
<format>zip</format>
</formats>
@ -34,22 +33,6 @@
</dependencySet>
</dependencySets>
<files>
<file>
<source>readme.txt</source>
<outputDirectory>/</outputDirectory>
<filtered>true</filtered>
</file>
<file>
<source>license.txt</source>
<outputDirectory>/</outputDirectory>
</file>
<file>
<source>issues.txt</source>
<outputDirectory>/</outputDirectory>
</file>
</files>
<fileSets>
<fileSet>
<directory>target</directory>
@ -66,16 +49,17 @@
<directory>target/site/apidocs</directory>
<outputDirectory>docs/api</outputDirectory>
</fileSet>
<fileSet>
<directory>target/docbook/publish</directory>
<outputDirectory>docs/reference</outputDirectory>
</fileSet>
<fileSet>
<directory>.</directory>
<outputDirectory/>
<useDefaultExcludes>true</useDefaultExcludes>
<excludes>
<exclude>*.txt</exclude>
<exclude>**/target/**</exclude>
<exclude>*.iml</exclude>
</excludes>
</fileSet>
</fileSets>
</assembly>

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

@ -49,51 +49,212 @@
<section id="whatisit" revision="1">
<title>What is it about?</title>
<para>Hibernate Static Metamodel Generator is an annotation processor
with the task of creating the static metamodel classes for JPA 2
entities. In the following I will show how to integrate the annotation
processor into your build environment.</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. This type saftey
is of course only useful for developers if the task of the metamodel
generation can be automated. Hibernate Static Metamodel Generator is an
annotation processor based on the annotation processing API defined in
<ulink url="???">JSR 269</ulink> with the task of creating the static
metamodel classes for JPA 2 entities. The following examples show a
managed JPA 2 entity, together with is metamodel class and an example
typesafe query.</para>
<example id="jpa2-entity-example">
<title>JPA 2 annotated entity</title>
<programlisting>@Entity public class Order {
@Id
Integer id;
@ManyToOne
Customer customer;
@OneToMany
Set&lt;Item&gt; items;
BigDecimal totalCost;
// standard setter/getter methods
...
}</programlisting>
</example>
<example id="metamodel-class-example">
<title>Matching metamodel class for entity
<classname>Order</classname></title>
<programlisting>@StaticMetamodel(Order.class)
public class Order_ {
public static volatile SingularAttribute&lt;Order, Integer&gt; id;
public static volatile SingularAttribute&lt;Order, Customer&gt; customer;
public static volatile SetAttribute&lt;Order, Item&gt; items;
public static volatile SingularAttribute&lt;Order, BigDecimal&gt; totalCost;
}</programlisting>
</example>
<example id="criteria-example" label="">
<title>Example of typesafe query using the metamodel class
<classname>Order_</classname> </title>
<programlisting>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_.orderItems);
cq.where( cb.equal(itemNode.get(Item_.id), 5 ) ).distinct(true);
</programlisting>
</example>
</section>
<section id="installation" revision="1">
<title>Installation</title>
<section>
<title>Canonical Metamodel</title>
<para><section revision="1">
<title>Prerequisites</title>
<para>The structure of the metamodel classes is described in the <ulink
url="http://jcp.org/en/jsr/detail?id=317">JPA 2 specification</ulink>
and its definition is included for completeness 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 />
</section></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>
</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>
</listitem>
<listitem>
<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>
</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: <programlisting>public static volatile SingularAttribute&lt;X, Y&gt; y;</programlisting></para>
</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>
<listitem>
<para>if the collection type of z is java.util.Collection,
then <programlisting>public static volatile CollectionAttribute&lt;X, Z&gt; z;</programlisting></para>
</listitem>
<listitem>
<para>if the collection type of z is java.util.Set, then
<programlisting>public static volatile SetAttribute&lt;X, Z&gt; z;</programlisting></para>
</listitem>
<listitem>
<para>if the collection type of z is java.util.List, then
<programlisting>public static volatile ListAttribute&lt;X, Z&gt; z;</programlisting></para>
</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>
</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>
</section>
</chapter>
<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>
under:</para>
<example id="maven-dependency" label="">
<title>Maven dependency for Hibernate Static Metamodel Generator</title>
<programlisting>&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/">SourceForge</ulink>.</para>
<para>In most cases the annotation processor will automatically run
provided the annotation processor jar is on the classpath. This happens
due to Java's Service Provider contract and the fact the the Hibernate
Static Metamodel Generator jar files contains the file
provided a JDK version 6i used and the jar file is added to the classpath.
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> listing
<classname>org.hibernate.jpamodelgen.JPAMetaModelEntityProcessor</classname>
as annotation processor.</para>
<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>
<para><section revision="1">
<para><section id="usage-ant" revision="1">
<title>Usage with Ant</title>
</section>As mentioned before, the annotation processor will run
automatically in a Java 6 environment. In case you want configure the
processor explicitly or disable it you can use the compilerarg option of
the Javac Task. The supported command javac line options are listed
here. <section revision="1">
automatically each time the Java compiler is called - provided the jar
file is on the classpath. Somtimes it is, however, 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 the <ulink
url="http://ant.apache.org/manual/CoreTasks/javac.html">Ant Javac
Task</ulink> can be configured to just run annotation
processing.<example id="javac-task-example">
<title>Ant Javac Task configuration </title>
<programlisting>&lt;javac srcdir="${src.dir}"
destdir="${target.dir}"
failonerror="false"
fork="true"
classpath="${classpath}"&gt;
<emphasis role="bold">&lt;compilerarg value="-proc:only"/&gt;</emphasis>
&lt;/javac&gt;</programlisting>
</example>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>.<tip>
<para>Run <literal>'javac -help'</literal> to see which other
annotation processor relevant options can be specified.</para>
</tip><section revision="1">
<title>Usage with Maven</title>
</section>There are several ways of running the annotation processor
as part of a Maven build. 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>
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>
<para><example>
<title>Maven compiler plugin configuration - direct
@ -105,7 +266,7 @@
&lt;source&gt;1.6&lt;/source&gt;
&lt;target&gt;1.6&lt;/target&gt;
&lt;compilerArguments&gt;
&lt;processor&gt;org.hibernate.jpamodelgen.JPAMetaModelEntityProcessor&lt;/processor&gt;
<emphasis role="bold">&lt;processor&gt;org.hibernate.jpamodelgen.JPAMetaModelEntityProcessor&lt;/processor&gt;</emphasis>
&lt;/compilerArguments&gt;
&lt;/configuration&gt;
&lt;/plugin&gt;</programlisting>
@ -113,11 +274,15 @@
<para>The maven-compiler-plugin approach has the disadvantage that the
maven compiler plugin does currently not allow to specify multiple
compiler arguments (MCOMPILER-62) and that messages from the Messenger
API are suppressed (MCOMPILER-66). A better approach is to disable
annotation processing for the compiler plugin:</para>
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>
<example id="disable-processing-maven-compiler-plugin">
<title>Maven compiler plugin configuration - indirect
execution</title>
@ -126,16 +291,22 @@
&lt;configuration&gt;
&lt;source&gt;1.6&lt;/source&gt;
&lt;target&gt;1.6&lt;/target&gt;
&lt;compilerArgument&gt;-proc:none&lt;/compilerArgument&gt;
<emphasis role="bold">&lt;compilerArgument&gt;-proc:none&lt;/compilerArgument&gt;</emphasis>
&lt;/configuration&gt;
&lt;/plugin&gt;</programlisting>
</example>
<para>and use the maven-annotation-plugin for annotation processing (you
will need the following additional maven repositories -
maven-annotation-plugin and jfrog):</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>
<example id="maven-processor-plugin">
<title>Maven compiler plugin configuration with
maven-annotation-plugin</title>
@ -181,9 +352,19 @@
<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>
<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>
<mediaobject>
<imageobject role="fo">
<imagedata align="center" contentdepth="" contentwidth="150mm"
@ -196,13 +377,18 @@
scalefit="1" />
</imageobject>
</mediaobject>
<para></para>
</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>
<mediaobject>
<imageobject role="fo">
<imagedata align="center" contentdepth="" contentwidth="150mm"
@ -221,22 +407,15 @@
<section>
<title>NetBeans</title>
<para>Of course you also want to have annotation processing available
in your favorite IDE. In Eclipse (at least since the latest Galileo
release) exists an additional configuration section under Java
Compiler where 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>TODO</para>
</section>
</section>
<section>
<title>Options</title>
<title>Processor specific options</title>
<para>The annotaton processor accepts a series of custom properties
which can be passed to the processor execution in the format
<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
@ -245,9 +424,10 @@
<tgroup cols="2">
<tbody>
<row>
<entry>Option name</entry>
<entry><emphasis role="bold">Option name</emphasis></entry>
<entry>Option value and usage</entry>
<entry><emphasis role="bold">Option value and
usage</emphasis></entry>
</row>
<row>
@ -280,4 +460,15 @@
</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>
</appendix>
</book>