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

METAGEN-26 Updated readme and docbook sources

This commit is contained in:
Hardy Ferentschik 2010-03-10 14:28:56 +00:00 committed by Strong Liu
parent 67a89cb2d7
commit f80bf48a5b
3 changed files with 65 additions and 78 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -4,9 +4,9 @@
<groupId>org.hibernate</groupId> <groupId>org.hibernate</groupId>
<artifactId>hibernate-jpamodelgen</artifactId> <artifactId>hibernate-jpamodelgen</artifactId>
<version>1.0.0-SNAPSHOT</version> <version>1.1.0-SNAPSHOT</version>
<name>JPA 2 Static-Metamodel Generator</name> <name>Hibernate JPA 2 Metamodel Generator</name>
<description>Annotation Processor to generate JPA 2 static metamodel classes</description> <description>Annotation Processor to generate JPA 2 static metamodel classes</description>
<inceptionYear>2009</inceptionYear> <inceptionYear>2009</inceptionYear>
@ -15,7 +15,7 @@
<dependency> <dependency>
<groupId>org.hibernate.javax.persistence</groupId> <groupId>org.hibernate.javax.persistence</groupId>
<artifactId>hibernate-jpa-2.0-api</artifactId> <artifactId>hibernate-jpa-2.0-api</artifactId>
<version>1.0.0-CR-1</version> <version>1.0.0.Final</version>
</dependency> </dependency>
<dependency> <dependency>
<groupId>org.testng</groupId> <groupId>org.testng</groupId>
@ -202,12 +202,12 @@
<configuration> <configuration>
<archive> <archive>
<manifestEntries> <manifestEntries>
<Implementation-Title>${pom.artifactId}</Implementation-Title> <Created-By>${java.version} (${java.vendor})</Created-By>
<Implementation-Title>${pom.name}</Implementation-Title>
<Implementation-URL>http://www.jboss.org/</Implementation-URL>
<Implementation-Version>${pom.version}</Implementation-Version> <Implementation-Version>${pom.version}</Implementation-Version>
<Implementation-Vendor>${pom.groupId}</Implementation-Vendor> <Implementation-Vendor>JBoss by Red Hat, Inc.</Implementation-Vendor>
<Implementation-Vendor-Id>${pom.groupId}</Implementation-Vendor-Id> <Implementation-Vendor-Id>http://www.jboss.org/</Implementation-Vendor-Id>
<Implementation-URL>${pom.url}</Implementation-URL>
<Specification-Title>JPA2 Model Generator</Specification-Title>
</manifestEntries> </manifestEntries>
</archive> </archive>
</configuration> </configuration>

66
tooling/metamodel-generator/readme.txt
View File

@ -1,65 +1,45 @@
JPA Model Generator Hibernate JPA 2 Metamodel Generator
What is it? What is it?
----------- -----------
This is a Java 6 annotation processor generating meta model classes for the JPA 2 criteria queries. This is a Java 6 annotation processor generating meta model classes for the JPA 2 criteria queries.
The processor (JPAMetaModelEntityProcessor) processes all classes annotated with @Entity, as well as The processor (JPAMetaModelEntityProcessor) processes all classes annotated with @Entity, @MappedSuperclass
entities mapped in /META-INF/orm.xml and mapping files specified in persistence.xml. or @Embeddable, as well as entities mapped in /META-INF/orm.xml and mapping files specified in persistence.xml.
Status
------
This is an alpha release of the annotation processor. The implemented functionality includes:
- full support for annotations honoring the access type (v2.0)
- support for persistence.xml, orm.xml and <mapping-file>
- tests (both via compilation failure and regular assertion failure)
System Requirements System Requirements
------------------- -------------------
JDK 1.6 or above. JDK 1.6 or above.
Documentation
-------------
http://docs.jboss.org/hibernate/stable/jpamodelgen/reference/en-US/
Issues
------
See issues.txt
Using JPA Model Generator Licensing
------------------------- ---------
- Copy jpamodelgen-*.jar together will all jar files from lib into the classpath of your application. Please see the file called license.txt
The jpamodelgen jar file contains a service file (/META-INF/services/javax.annotation.processing.Processor)
so that the annotation processor will automatically be executed during compilation.
You can also explicitly specify the processor using the -processor flag:
> javac -cp <myclasspath> -d <target> -sourcepath <sources> -processor org.hibernate.jpamodelgen.JPAMetaModelEntityProcessor
* Maven
This distribution contains a pom.xml file showing one of three possible ways to integrate the processor in a maven project.
You can just add <processor>org.hibernate.jpamodelgen.JPAMetaModelEntityProcessor</processor> to the maven-compiler-plugin.
This approach has, however, the shortcoming that messages from the annotation processor are not displayed. This is a known
issue. See also - http://weblogs.java.net/blog/ss141213/archive/2007/11/my_maven_experi.html
The second alternative is the maven-annotation-plugin (http://code.google.com/p/maven-annotation-plugin/). This approach
hasn't been tested yet.
Last but not least, you can use the maven-antrun-plugin to just run the annotation processor and ignore the processor in
in the maven-compiler-plugin via '-proc:none'. This is the approach chosen in the POM for this project.
* Ant Resources
Make sure the annotation processor and its dependencies are in the classpath. Due the service file the processor will be ---------
automatically executed when the javac task executes.
If not try adding <compilerarg value="-processor org.hibernate.jpamodelgen.JPAMetaModelEntityProcessor"/>
* Idea
Again, if in the classpath the JPAMetaModelEntityProcessor should execute automatically. If not add the following under
'Compiler->Java Compiler': -target 1.6 -processor org.hibernate.jpamodelgen.JPAMetaModelEntityProcessor
You can also turn of annotation processing via: -target 1.6 -proc:none
Home Page: http://www.hibernate.org/
Mailing Lists: http://www.hibernate.org/20.html
Source Code: http://anonsvn.jboss.org/repos/hibernate/jpamodelgen/trunk/
Issue Tracking: http://opensource.atlassian.com/projects/hibernate/browse/METAGEN

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

@ -19,6 +19,7 @@
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY version "WORKING"> <!ENTITY version "WORKING">
<!ENTITY today "TODAY">
<!ENTITY copyrightYear "2010"> <!ENTITY copyrightYear "2010">
<!ENTITY copyrightHolder "Red Hat Inc."> <!ENTITY copyrightHolder "Red Hat Inc.">
<!ENTITY jpa2Ref '<citation><xref linkend="JPA2"/></citation>'> <!ENTITY jpa2Ref '<citation><xref linkend="JPA2"/></citation>'>
@ -26,20 +27,26 @@
]> ]>
<book lang="en"> <book lang="en">
<bookinfo> <bookinfo>
<title>Hibernate Metamodel Generator</title> <title>Hibernate JPA 2 Metamodel Generator</title>
<subtitle>JPA 2 Static Metamodel Annotation Processor</subtitle>
<subtitle>Reference Guide</subtitle> <subtitle>Reference Guide</subtitle>
<releaseinfo>&version;</releaseinfo> <releaseinfo>&version;</releaseinfo>
<pubdate>&today;</pubdate>
<productnumber>&version;</productnumber> <productnumber>&version;</productnumber>
<copyright> <copyright>
<year>&copyrightYear;</year> <year>&copyrightYear;</year>
<holder>&copyrightHolder;</holder> <holder>&copyrightHolder;</holder>
</copyright> </copyright>
<authorgroup>
<author>
<firstname>Hardy</firstname>
<surname>Ferentschik</surname>
</author>
</authorgroup>
</bookinfo> </bookinfo>
<toc/> <toc/>
<chapter id="introduction"> <chapter id="introduction">
<title>Introduction</title> <title>Introduction</title>
<section id="whatisit" revision="1"> <section id="whatisit">
<title>What is it about?</title> <title>What is it about?</title>
<para>JPA 2 defines a new typesafe <classname>Criteria</classname> API which allows criteria <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 queries to be constructed in a strongly-typed manner, using metamodel objects to provide
@ -51,7 +58,7 @@
<example id="jpa2-entity-example"> <example id="jpa2-entity-example">
<title>JPA 2 annotated entities <classname>Order</classname> and <title>JPA 2 annotated entities <classname>Order</classname> and
<classname>Item</classname></title> <classname>Item</classname></title>
<programlisting> <programlisting role="JAVA" language="JAVA">
@Entity @Entity
public class Order { public class Order {
@Id @Id
@ -87,7 +94,7 @@ public class Item {
</example> </example>
<example id="metamodel-class-example"> <example id="metamodel-class-example">
<title>Metamodel class <classname>Order_</classname></title> <title>Metamodel class <classname>Order_</classname></title>
<programlisting> <programlisting role="JAVA" language="JAVA">
@StaticMetamodel(Order.class) @StaticMetamodel(Order.class)
public class Order_ { public class Order_ {
public static volatile SingularAttribute&lt;Order, Integer&gt; id; public static volatile SingularAttribute&lt;Order, Integer&gt; id;
@ -99,11 +106,12 @@ public class Order_ {
</example> </example>
<example id="criteria-example"> <example id="criteria-example">
<title>Typesafe citeria query</title> <title>Typesafe citeria query</title>
<programlisting> <programlisting role="JAVA" language="JAVA">
CriteriaBuilder cb = entityManager.getCriteriaBuilder(); CriteriaBuilder cb = entityManager.getCriteriaBuilder();
CriteriaQuery&lt;Order&gt; cq = cb.createQuery(Order.class); CriteriaQuery&lt;Order&gt; cq = cb.createQuery(Order.class);
SetJoin&lt;Order, Item&gt; itemNode = cq.from(Order.class).join(Order_.items); SetJoin&lt;Order, Item&gt; itemNode = cq.from(Order.class).join(Order_.items);
cq.where( cb.equal(itemNode.get(Item_.id), 5 ) ).distinct(true); cq.where( cb.equal(itemNode.get(Item_.id), 5 ) ).distinct(true);
</programlisting> </programlisting>
</example> </example>
</section> </section>
@ -139,23 +147,24 @@ cq.where( cb.equal(itemNode.get(Item_.id), 5 ) ).distinct(true);
<para>For every persistent non-collection-valued attribute y declared by class <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 <classname>X</classname>, where the type of y is <classname>Y</classname>, the
metamodel class must contain a declaration as follows: metamodel class must contain a declaration as follows:
<programlisting>public static volatile SingularAttribute&lt;X, Y&gt; y;</programlisting></para> </para>
<programlisting>public static volatile SingularAttribute&lt;X, Y&gt; y;</programlisting>
</listitem> </listitem>
<listitem> <listitem>
<para>For every persistent collection-valued attribute z declared by class <para>For every persistent collection-valued attribute z declared by class
<classname>X</classname>, where the element type of z is <classname>Z</classname>, <classname>X</classname>, where the element type of z is <classname>Z</classname>,
the metamodel class must contain a declaration as follows:<itemizedlist> the metamodel class must contain a declaration as follows:<itemizedlist>
<listitem> <listitem>
<para>if the collection type of z is java.util.Collection, then <para>if the collection type of z is java.util.Collection, then</para>
<programlisting>public static volatile CollectionAttribute&lt;X, Z&gt; z;</programlisting></para> <programlisting>public static volatile CollectionAttribute&lt;X, Z&gt; z;</programlisting>
</listitem> </listitem>
<listitem> <listitem>
<para>if the collection type of z is java.util.Set, then <para>if the collection type of z is java.util.Set, then</para>
<programlisting>public static volatile SetAttribute&lt;X, Z&gt; z;</programlisting></para> <programlisting>public static volatile SetAttribute&lt;X, Z&gt; z;</programlisting>
</listitem> </listitem>
<listitem> <listitem>
<para>if the collection type of z is java.util.List, then <para>if the collection type of z is java.util.List, then</para>
<programlisting>public static volatile ListAttribute&lt;X, Z&gt; z;</programlisting></para> <programlisting>public static volatile ListAttribute&lt;X, Z&gt; z;</programlisting>
</listitem> </listitem>
<listitem> <listitem>
<para>if the collection type of z is java.util.Map, then <para>if the collection type of z is java.util.Map, then
@ -177,14 +186,14 @@ cq.where( cb.equal(itemNode.get(Item_.id), 5 ) ).distinct(true);
linkend="maven-dependency"/>.</para> linkend="maven-dependency"/>.</para>
<example id="maven-dependency"> <example id="maven-dependency">
<title>Maven dependency </title> <title>Maven dependency </title>
<programlisting>&lt;dependency&gt; <programlisting role="XML" language="XML">&lt;dependency&gt;
&lt;groupId&gt;org.hibernate&lt;/groupId&gt; &lt;groupId&gt;org.hibernate&lt;/groupId&gt;
&lt;artifactId&gt;hibernate-jpamodelgen&lt;/artifactId&gt; &lt;artifactId&gt;hibernate-jpamodelgen&lt;/artifactId&gt;
&lt;version&gt;1.0.0&lt;/version&gt; &lt;version&gt;1.0.0&lt;/version&gt;
&lt;/dependency&gt;</programlisting> &lt;/dependency&gt;</programlisting>
</example> </example>
<para>Alternatively, a full distribution package can be downloaded from <ulink <para>Alternatively, a full distribution package can be downloaded from <ulink
url="http://sourceforge.net/projects/hibernate">SourceForge</ulink>.</para> url="http://sourceforge.net/projects/hibernate/files/hibernate-jpamodelgen">SourceForge</ulink>.</para>
<para>In most cases the annotation processor will automatically run provided <para>In most cases the annotation processor will automatically run provided
the processor jar is added to the classpath and a JDK 6 is used. This happens due to <ulink the processor jar is added to the classpath and a JDK 6 is used. This happens due to <ulink
url="http://java.sun.com/j2se/1.4.2/docs/guide/jar/jar.html#Service%20Provider">Java's url="http://java.sun.com/j2se/1.4.2/docs/guide/jar/jar.html#Service%20Provider">Java's
@ -197,7 +206,7 @@ cq.where( cb.equal(itemNode.get(Item_.id), 5 ) ).distinct(true);
</note></para> </note></para>
<section> <section>
<title>Usage from the command line</title> <title>Usage from the command line</title>
<section id="usage-ant" revision="1"> <section id="usage-ant">
<title>Usage with Ant</title> <title>Usage with Ant</title>
<para>As mentioned before, the annotation processor will run automatically each time the <para>As mentioned before, the annotation processor will run automatically each time the
Java compiler is called, provided the jar file is on the classpath. Sometimes, however, it is Java compiler is called, provided the jar file is on the classpath. Sometimes, however, it is
@ -208,12 +217,12 @@ cq.where( cb.equal(itemNode.get(Item_.id), 5 ) ).distinct(true);
configured to just run annotation processing.</para> configured to just run annotation processing.</para>
<example id="javac-task-example"> <example id="javac-task-example">
<title>Javac Task configuration</title> <title>Javac Task configuration</title>
<programlisting>&lt;javac srcdir="${src.dir}" <programlisting role="XML" language="XML">&lt;javac srcdir="${src.dir}"
destdir="${target.dir}" destdir="${target.dir}"
failonerror="false" failonerror="false"
fork="true" fork="true"
classpath="${classpath}"&gt; classpath="${classpath}"&gt;
<emphasis role="bold">&lt;compilerarg value="-proc:only"/&gt;</emphasis> &lt;compilerarg value="-proc:only"/&gt;
&lt;/javac&gt;</programlisting> &lt;/javac&gt;</programlisting>
</example> </example>
<para>The option <emphasis>-proc:only</emphasis> instructs the compiler to just run the <para>The option <emphasis>-proc:only</emphasis> instructs the compiler to just run the
@ -224,27 +233,25 @@ cq.where( cb.equal(itemNode.get(Item_.id), 5 ) ).distinct(true);
relevant options can be specified.</para> relevant options can be specified.</para>
</tip> </tip>
</section> </section>
<section revision="1"> <section>
<title>Usage with Maven</title> <title>Usage with Maven</title>
<para>There are several ways of running the annotation processor as part of a Maven build. <para>There are several ways of running the annotation processor as part of a Maven build.
Again, it will automatically run if you are using a JDK 6 compiler and the annotation 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 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> your classpath you can explicitly pass the processor option to the compiler plugin:</para>
<para>
<example> <example>
<title>Maven compiler plugin configuration - direct execution</title> <title>Maven compiler plugin configuration - direct execution</title>
<programlisting>&lt;plugin&gt; <programlisting role="XML" language="XML">&lt;plugin&gt;
&lt;artifactId&gt;maven-compiler-plugin&lt;/artifactId&gt; &lt;artifactId&gt;maven-compiler-plugin&lt;/artifactId&gt;
&lt;configuration&gt; &lt;configuration&gt;
&lt;source&gt;1.6&lt;/source&gt; &lt;source&gt;1.6&lt;/source&gt;
&lt;target&gt;1.6&lt;/target&gt; &lt;target&gt;1.6&lt;/target&gt;
&lt;compilerArguments&gt; &lt;compilerArguments&gt;
<emphasis role="bold">&lt;processor&gt;org.hibernate.jpamodelgen.JPAMetaModelEntityProcessor&lt;/processor&gt;</emphasis> &lt;processor&gt;org.hibernate.jpamodelgen.JPAMetaModelEntityProcessor&lt;/processor&gt;
&lt;/compilerArguments&gt; &lt;/compilerArguments&gt;
&lt;/configuration&gt; &lt;/configuration&gt;
&lt;/plugin&gt;</programlisting> &lt;/plugin&gt;</programlisting>
</example> </example>
</para>
<para>The maven-compiler-plugin approach has the disadvantage that the maven compiler plugin <para>The maven-compiler-plugin approach has the disadvantage that the maven compiler plugin
does currently not allow to specify multiple compiler arguments (<ulink does currently not allow to specify multiple compiler arguments (<ulink
url="http://jira.codehaus.org/browse/MCOMPILER-62">MCOMPILER-62</ulink>) and that url="http://jira.codehaus.org/browse/MCOMPILER-62">MCOMPILER-62</ulink>) and that
@ -254,12 +261,12 @@ cq.where( cb.equal(itemNode.get(Item_.id), 5 ) ).distinct(true);
linkend="disable-processing-maven-compiler-plugin"/>.</para> linkend="disable-processing-maven-compiler-plugin"/>.</para>
<example id="disable-processing-maven-compiler-plugin"> <example id="disable-processing-maven-compiler-plugin">
<title>Maven compiler plugin configuration - indirect execution</title> <title>Maven compiler plugin configuration - indirect execution</title>
<programlisting>&lt;plugin&gt; <programlisting role="XML" language="XML">&lt;plugin&gt;
&lt;artifactId&gt;maven-compiler-plugin&lt;/artifactId&gt; &lt;artifactId&gt;maven-compiler-plugin&lt;/artifactId&gt;
&lt;configuration&gt; &lt;configuration&gt;
&lt;source&gt;1.6&lt;/source&gt; &lt;source&gt;1.6&lt;/source&gt;
&lt;target&gt;1.6&lt;/target&gt; &lt;target&gt;1.6&lt;/target&gt;
<emphasis role="bold">&lt;compilerArgument&gt;-proc:none&lt;/compilerArgument&gt;</emphasis> &lt;compilerArgument&gt;-proc:none&lt;/compilerArgument&gt;
&lt;/configuration&gt; &lt;/configuration&gt;
&lt;/plugin&gt;</programlisting> &lt;/plugin&gt;</programlisting>
</example> </example>
@ -271,8 +278,8 @@ cq.where( cb.equal(itemNode.get(Item_.id), 5 ) ).distinct(true);
url="http://www.jfrog.org/artifactory/plugins-releases">jfrog</ulink>) can be used. The 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> configuration can be seen in <xref linkend="maven-processor-plugin"/>.</para>
<example id="maven-processor-plugin"> <example id="maven-processor-plugin">
<title>Maven compiler plugin configuration with maven-annotation-plugin</title> <title>Configuration with maven-annotation-plugin</title>
<programlisting>&lt;plugin&gt; <programlisting role="XML" language="XML">&lt;plugin&gt;
&lt;groupId&gt;org.bsc.maven&lt;/groupId&gt; &lt;groupId&gt;org.bsc.maven&lt;/groupId&gt;
&lt;artifactId&gt;maven-processor-plugin&lt;/artifactId&gt; &lt;artifactId&gt;maven-processor-plugin&lt;/artifactId&gt;
&lt;executions&gt; &lt;executions&gt;