[hibernate-commits] Hibernate SVN: r18811 - in jpamodelgen/trunk: src/main/assembly and 1 other directories.

Author: hardy.ferentschik Date: 2010-02-16 12:44:06 -0500 (Tue, 16 Feb 2010) New Revision: 18811 Modified: jpamodelgen/trunk/pom.xml jpamodelgen/trunk/src/main/assembly/dist.xml jpamodelgen/trunk/src/main/docbook/en-US/master.xml Log: METAGEN-4 - Completed first cut of docs and changed the mave nassembly to include the generated documentation into the dist bundle Modified: jpamodelgen/trunk/pom.xml =================================================================== --- jpamodelgen/trunk/pom.xml 2010-02-15 22:40:30 UTC (rev 18810) +++ jpamodelgen/trunk/pom.xml 2010-02-16 17:44:06 UTC (rev 18811) @@ -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> Modified: jpamodelgen/trunk/src/main/assembly/dist.xml =================================================================== --- jpamodelgen/trunk/src/main/assembly/dist.xml 2010-02-15 22:40:30 UTC (rev 18810) +++ jpamodelgen/trunk/src/main/assembly/dist.xml 2010-02-16 17:44:06 UTC (rev 18811) @@ -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> @@ -67,15 +50,16 @@ <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> Modified: jpamodelgen/trunk/src/main/docbook/en-US/master.xml =================================================================== --- jpamodelgen/trunk/src/main/docbook/en-US/master.xml 2010-02-15 22:40:30 UTC (rev 18810) +++ jpamodelgen/trunk/src/main/docbook/en-US/master.xml 2010-02-16 17:44:06 UTC (rev 18811) @@ -71,9 +71,10 @@ @OneToMany Set&lt;Item&gt; items; BigDecimal totalCost; + + // standard setter/getter methods ... -} -</programlisting> +}</programlisting> </example> <example id="metamodel-class-example"> @@ -86,15 +87,14 @@ 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> +}</programlisting> </example> <example id="criteria-example" label=""> <title>Example of typesafe query using the metamodel class <classname>Order_</classname> </title> - <programlisting>CriteriaBuilder cb = ordersEntityManager.getCriteriaBuilder(); + <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); @@ -105,14 +105,20 @@ <section> <title>Canonical Metamodel</title> - <para>The canonical metamodel classes the annotation processor produces - for every managed class in the persistence unit follow these rules - defined in the JPA 2 specification:</para> + <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>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 X in package p, a metamodel class X_ - 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> @@ -122,27 +128,34 @@ </listitem> <listitem> - <para>The metamodel class X_ must be annotated with the - javax.persistence.Static- Metamodel 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 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.</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 X, where the type of y is Y, the metamodel class - must contain a declaration as follows: <programlisting>public static volatile SingularAttribute&lt;X, Y&gt; y;</programlisting></para> + 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 X, where the element type of z is Z, the metamodel class - must contain a declaration as follows:<itemizedlist> + 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> @@ -172,19 +185,12 @@ </section> </chapter> - <chapter> + <chapter id="chapter-usage"> <title>Usage</title> - <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 - <classname>javax.annotation.processing.Processor</classname> in the - <filename>META-INF/services</filename> listing - <classname>org.hibernate.jpamodelgen.JPAMetaModelEntityProcessor</classname> - as annotation processor. However, a JDK 6 is a prerequisite. The jar file - itself can be found in the <ulink url="http://repository.jboss.com/">JBoss - Maven repository</ulink> under:</para> + <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> @@ -193,26 +199,62 @@ &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> +&lt;/dependency&gt;</programlisting> </example> + <para>Alternatively, a full distribution package can be downloaded from + <ulink url="http://sourceforge.net/">SourceForge</ulink>.<... + + <para>In most cases the annotation processor will automatically run + 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%... + 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> - <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 @@ -224,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> @@ -232,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...>) + and that messages from the Messenger API are suppressed (<ulink + url="http://jira.codehaus.org/browse/MCOMPILER-66">MCOMPILER...>). + 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> @@ -245,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/">mave... + for annotation processing (you will need the following additional maven + repositories - <ulink + url="http://maven-annotation-plugin.googlecode.com/svn/trunk/mavenre... + and <ulink + url="http://www.jfrog.org/artifactory/plugins-releases">jfro...>) + 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> @@ -308,6 +360,11 @@ <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" @@ -325,11 +382,11 @@ <section> <title>Eclipse</title> - <para>In Eclipse from the Galileo release onwards 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 + <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> @@ -355,10 +412,10 @@ </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 @@ -367,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> @@ -402,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/METAG... + userlevel="">METAGEN</ulink> project in the Hibernate Jira instance. + Feedback is always welcome.</para> + </appendix> </book>