METAGEN-4

tooling/metamodel-generator/pom.xml

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

tooling/metamodel-generator/src/main/assembly/dist.xml

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

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

@@ -49,51 +49,212 @@
     <section id="whatisit" revision="1">
       <title>What is it about?</title>
 
-      <para>Hibernate Static Metamodel Generator is an annotation processor
+      <para>JPA 2 defines a new typesafe <classname>Criteria</classname> API
-      with the task of creating the static metamodel classes for JPA 2
+      which allows criteria queries to be constructed in a strongly-typed
-      entities. In the following I will show how to integrate the annotation
+      manner, using metamodel objects to provide type safety. This type saftey
-      processor into your build environment.</para>
+      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">
+    <section>
-      <title>Installation</title>
+      <title>Canonical Metamodel</title>
 
-      <para><section revision="1">
+      <para>The structure of the metamodel classes is described in the <ulink
-          <title>Prerequisites</title>
+      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 />
+      <para>The annotation processor produces for every managed class in the
-        </section></para>
+      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
+    provided a JDK version 6i used and the jar file is added to the classpath.
-    due to Java's Service Provider contract and the fact the the Hibernate
+    This happens due to <ulink
-    Static Metamodel Generator jar files contains the file
+    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
+    <filename>META-INF/services</filename> directory. The fully qualified name
-    <classname>org.hibernate.jpamodelgen.JPAMetaModelEntityProcessor</classname>
+    of the processor itself is:
-    as annotation processor.</para>
+    <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
+      automatically each time the Java compiler is called - provided the jar
-      processor explicitly or disable it you can use the compilerarg option of
+      file is on the classpath. Somtimes it is, however, useful to control the
-      the Javac Task. The supported command javac line options are listed
+      annotation processing in more detail, for example if you exclusively
-      here. <section revision="1">
+      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
+      as part of a Maven build. Again, it will automatically run if you are
-      JDK 6 compiler and the annotation processor jar is on the classpath. In
+      using a JDK 6 compiler and the annotation processor jar is on the
-      case you have more than one annotation processors on your classpath you
+      classpath. In case you have more than one annotation processors on your
-      can explicitly pass the processor option to the compiler plugin:</para>
+      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
+      compiler arguments (<ulink
-      API are suppressed (MCOMPILER-66). A better approach is to disable
+      url="http://jira.codehaus.org/browse/MCOMPILER-62">MCOMPILER-62</ulink>)
-      annotation processing for the compiler plugin:</para>
+      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
+      <para>Once disabled, the <ulink
-      will need the following additional maven repositories -
+      url="http://code.google.com/p/maven-annotation-plugin/">maven-annotation-plugin</ulink>
-      maven-annotation-plugin and jfrog):</para>
+      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
+        <para>TODO</para>
-        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>
       </section>
     </section>
 
     <section>
-      <title>Options</title>
+      <title>Processor specific options</title>
 
-      <para>The annotaton processor accepts a series of custom properties
+      <para>The Hibernate Static Metamodel Generator accepts a series of
-      which can be passed to the processor execution in the format
+      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>