[hibernate-commits] Hibernate SVN: r18811 - in jpamodelgen/trunk: src/main/assembly and 1 other directories.
hibernate-commits at lists.jboss.org
hibernate-commits at lists.jboss.org
Tue Feb 16 12:44:07 EST 2010
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<Item> items;
BigDecimal totalCost;
+
+ // standard setter/getter methods
...
-}
-</programlisting>
+}</programlisting>
</example>
<example id="metamodel-class-example">
@@ -86,15 +87,14 @@
public static volatile SingularAttribute<Order, Customer> customer;
public static volatile SetAttribute<Order, Item> items;
public static volatile SingularAttribute<Order, BigDecimal> 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<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);
@@ -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<X, Y> 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<X, Y> 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<X, Z> 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 @@
<groupId>org.hibernate</groupId>
<artifactId>hibernate-jpamodelgen</artifactId>
<version>1.0.0</version>
-</dependency>
-</programlisting>
+</dependency></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 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> 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><javac srcdir="${src.dir}"
+ destdir="${target.dir}"
+ failonerror="false"
+ fork="true"
+ classpath="${classpath}">
+ <emphasis role="bold"><compilerarg value="-proc:only"/></emphasis>
+</javac></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 @@
<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>
@@ -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-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>
@@ -245,16 +291,22 @@
<configuration>
<source>1.6</source>
<target>1.6</target>
- <compilerArgument>-proc:none</compilerArgument>
+ <emphasis role="bold"><compilerArgument>-proc:none</compilerArgument></emphasis>
</configuration>
</plugin></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>
@@ -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/METAGEN"
+ userlevel="">METAGEN</ulink> project in the Hibernate Jira instance.
+ Feedback is always welcome.</para>
+ </appendix>
</book>
More information about the hibernate-commits
mailing list