diff --git a/tooling/metamodel-generator/pom.xml b/tooling/metamodel-generator/pom.xml index eb816facce..0306c9059c 100644 --- a/tooling/metamodel-generator/pom.xml +++ b/tooling/metamodel-generator/pom.xml @@ -236,15 +236,6 @@ src/main/assembly/dist.xml - - - make-assembly - site - - assembly - - - org.apache.maven.plugins @@ -254,7 +245,7 @@ true true true - package deploy + 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 diff --git a/tooling/metamodel-generator/src/main/assembly/dist.xml b/tooling/metamodel-generator/src/main/assembly/dist.xml index d65a8d8785..70ea0b5987 100644 --- a/tooling/metamodel-generator/src/main/assembly/dist.xml +++ b/tooling/metamodel-generator/src/main/assembly/dist.xml @@ -22,7 +22,6 @@ dist tar.gz - tar.bz2 zip @@ -34,22 +33,6 @@ - - - readme.txt - / - true - - - license.txt - / - - - issues.txt - / - - - target @@ -66,16 +49,17 @@ target/site/apidocs docs/api + + target/docbook/publish + docs/reference + . true - *.txt **/target/** - *.iml - diff --git a/tooling/metamodel-generator/src/main/docbook/en-US/master.xml b/tooling/metamodel-generator/src/main/docbook/en-US/master.xml index f061583f88..3d5708a196 100644 --- a/tooling/metamodel-generator/src/main/docbook/en-US/master.xml +++ b/tooling/metamodel-generator/src/main/docbook/en-US/master.xml @@ -49,51 +49,212 @@
What is it about? - 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. + JPA 2 defines a new typesafe Criteria 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 + JSR 269 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. + + + JPA 2 annotated entity + + @Entity public class Order { + @Id + Integer id; + @ManyToOne + Customer customer; + @OneToMany + Set<Item> items; + BigDecimal totalCost; + + // standard setter/getter methods + ... +} + + + + Matching metamodel class for entity + <classname>Order</classname> + + @StaticMetamodel(Order.class) +public class Order_ { + public static volatile SingularAttribute<Order, Integer> id; + public static volatile SingularAttribute<Order, Customer> customer; + public static volatile SetAttribute<Order, Item> items; + public static volatile SingularAttribute<Order, BigDecimal> totalCost; +} + + + + Example of typesafe query using the metamodel class + <classname>Order_</classname> + + CriteriaBuilder cb = entityManager.getCriteriaBuilder(); +CriteriaQuery<Order> cq = cb.createQuery(Order.class); +SetJoin<Order, Item> itemNode = cq.from(Order.class).join(Order_.orderItems); +cq.where( cb.equal(itemNode.get(Item_.id), 5 ) ).distinct(true); + +
-
- Installation +
+ Canonical Metamodel -
- Prerequisites + The structure of the metamodel classes is described in the JPA 2 specification + and its definition is included for completeness in the following + paragraphs . Feel free to skip ahead to + if you are not interested into the gory details. - -
+ The annotation processor produces for every managed class in the + persistence unit a metamodel class based on these rules: + + + + For each managed class X in package + p, a metamodel class X_ in package p is + created. + + + + The name of the metamodel class is derived from the name of + the managed class by appending "_" to the name of the managed + class. + + + + The metamodel class X_ must be + annotated with the + javax.persistence.StaticMetamodel + annotation. + + + + If class X extends another class + S, where S is the + most derived managed class (i.e., entity or mapped superclass) + extended by X, then class + X_ must extend class + S_, where S_ is the + metamodel class created for S. + + + + For every persistent non-collection-valued attribute y + declared by class X, where the type of y is + Y, the metamodel class must contain a + declaration as follows: public static volatile SingularAttribute<X, Y> y; + + + + For every persistent collection-valued attribute z declared + by class X, where the element type of z is + Z, the metamodel class must contain a + declaration as follows: + + if the collection type of z is java.util.Collection, + then public static volatile CollectionAttribute<X, Z> z; + + + + if the collection type of z is java.util.Set, then + public static volatile SetAttribute<X, Z> z; + + + + if the collection type of z is java.util.List, then + public static volatile ListAttribute<X, Z> z; + + + + if the collection type of z is java.util.Map, then + public static volatile MapAttribute<X, K, Z> z; + where K is the type of the key of the map in class X + + + + Import statements must be included for the needed + javax.persistence.metamodel types as appropriate + and all classes X, Y, + Z, and K.
- + Usage + The jar file for the annotation processor can be found in the + JBoss Maven repository + under: + + + Maven dependency for Hibernate Static Metamodel Generator + + <dependency> + <groupId>org.hibernate</groupId> + <artifactId>hibernate-jpamodelgen</artifactId> + <version>1.0.0</version> +</dependency> + + + Alternatively, a full distribution package can be downloaded from + SourceForge. + 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 Java's + Service Provider contract and the fact the the Hibernate Static + Metamodel Generator jar files contains the file javax.annotation.processing.Processor in the - META-INF/services listing - org.hibernate.jpamodelgen.JPAMetaModelEntityProcessor - as annotation processor. + META-INF/services directory. The fully qualified name + of the processor itself is: + org.hibernate.jpamodelgen.JPAMetaModelEntityProcessor. + + The use of a Java 6 compiler is a prerequisite. +
Usage from the command line -
+
Usage with Ant
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.
+ 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. + shows how the Ant Javac + Task can be configured to just run annotation + processing. + Ant Javac Task configuration + + <javac srcdir="${src.dir}" + destdir="${target.dir}" + failonerror="false" + fork="true" + classpath="${classpath}"> + <compilerarg value="-proc:only"/> +</javac> + The option -proc:only instructs the + compiler to just run the annotation processing. You can also completely + disable processing by specifying -proc:none. + Run 'javac -help' to see which other + annotation processor relevant options can be specified. +
Usage with Maven
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: + 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: Maven compiler plugin configuration - direct @@ -105,7 +266,7 @@ <source>1.6</source> <target>1.6</target> <compilerArguments> - <processor>org.hibernate.jpamodelgen.JPAMetaModelEntityProcessor</processor> + <emphasis role="bold"><processor>org.hibernate.jpamodelgen.JPAMetaModelEntityProcessor</processor></emphasis> </compilerArguments> </configuration> </plugin></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 @@ -126,16 +291,22 @@ <configuration> <source>1.6</source> <target>1.6</target> - <compilerArgument>-proc:none</compilerArgument> + <compilerArgument>-proc:none</compilerArgument> </configuration> </plugin> - and use the maven-annotation-plugin for annotation processing (you - will need the following additional maven repositories - - maven-annotation-plugin and jfrog): + Once disabled, the maven-annotation-plugin + for annotation processing (you will need the following additional maven + repositories - maven-annotation-plugin + and jfrog) + can be used. The configuration can be seen in . - + Maven compiler plugin configuration with maven-annotation-plugin @@ -181,9 +352,19 @@
Usage within the IDE + 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. +
Idea + 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. + - -
Eclipse + 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. + NetBeans - 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. + TODO
- Options + Processor specific options - The annotaton processor accepts a series of custom properties - which can be passed to the processor execution in the format + The Hibernate Static Metamodel Generator accepts a series of + custom options which can be passed to the processor in the format -A[property]=[value]. The supported properties are: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 + + For further usage question or problems consult the Hibernate + Forum. For bug reports use the METAGEN project in the Hibernate Jira instance. + Feedback is always welcome. +