From f80bf48a5bb59e359f180f0957338b815449809f Mon Sep 17 00:00:00 2001 From: Hardy Ferentschik Date: Wed, 10 Mar 2010 14:28:56 +0000 Subject: [PATCH] METAGEN-26 Updated readme and docbook sources --- tooling/metamodel-generator/pom.xml | 16 ++--- tooling/metamodel-generator/readme.txt | 66 +++++++------------ .../src/main/docbook/en-US/master.xml | 61 +++++++++-------- 3 files changed, 65 insertions(+), 78 deletions(-) diff --git a/tooling/metamodel-generator/pom.xml b/tooling/metamodel-generator/pom.xml index 90a7bc8a39..3a97c04efc 100644 --- a/tooling/metamodel-generator/pom.xml +++ b/tooling/metamodel-generator/pom.xml @@ -4,9 +4,9 @@ org.hibernate hibernate-jpamodelgen - 1.0.0-SNAPSHOT + 1.1.0-SNAPSHOT - JPA 2 Static-Metamodel Generator + Hibernate JPA 2 Metamodel Generator Annotation Processor to generate JPA 2 static metamodel classes 2009 @@ -15,7 +15,7 @@ org.hibernate.javax.persistence hibernate-jpa-2.0-api - 1.0.0-CR-1 + 1.0.0.Final org.testng @@ -202,12 +202,12 @@ - ${pom.artifactId} + ${java.version} (${java.vendor}) + ${pom.name} + http://www.jboss.org/ ${pom.version} - ${pom.groupId} - ${pom.groupId} - ${pom.url} - JPA2 Model Generator + JBoss by Red Hat, Inc. + http://www.jboss.org/ diff --git a/tooling/metamodel-generator/readme.txt b/tooling/metamodel-generator/readme.txt index 95c79254ce..1a42972111 100644 --- a/tooling/metamodel-generator/readme.txt +++ b/tooling/metamodel-generator/readme.txt @@ -1,65 +1,45 @@ - JPA Model Generator + Hibernate JPA 2 Metamodel Generator What is it? ----------- 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 - 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 - - tests (both via compilation failure and regular assertion failure) + The processor (JPAMetaModelEntityProcessor) processes all classes annotated with @Entity, @MappedSuperclass + or @Embeddable, as well as entities mapped in /META-INF/orm.xml and mapping files specified in persistence.xml. System Requirements ------------------- JDK 1.6 or above. + + + Documentation + ------------- - - Issues - ------ - - See issues.txt + http://docs.jboss.org/hibernate/stable/jpamodelgen/reference/en-US/ - Using JPA Model Generator - ------------------------- + Licensing + --------- - - Copy jpamodelgen-*.jar together will all jar files from lib into the classpath of your application. - 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 -d -sourcepath -processor org.hibernate.jpamodelgen.JPAMetaModelEntityProcessor + Please see the file called license.txt - - * 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 org.hibernate.jpamodelgen.JPAMetaModelEntityProcessor 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 - 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 - - * 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 + Resources + --------- + 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 + + + + + + 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 711527d3f7..f86e4f5e47 100644 --- a/tooling/metamodel-generator/src/main/docbook/en-US/master.xml +++ b/tooling/metamodel-generator/src/main/docbook/en-US/master.xml @@ -19,6 +19,7 @@ + '> @@ -26,20 +27,26 @@ ]> - Hibernate Metamodel Generator - JPA 2 Static Metamodel Annotation Processor + Hibernate JPA 2 Metamodel Generator Reference Guide &version; + &today; &version; ©rightYear; ©rightHolder; + + + Hardy + Ferentschik + + Introduction -
+
What is it about? 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 @@ -51,7 +58,7 @@ JPA 2 annotated entities <classname>Order</classname> and <classname>Item</classname> - + @Entity public class Order { @Id @@ -87,7 +94,7 @@ public class Item { Metamodel class <classname>Order_</classname> - + @StaticMetamodel(Order.class) public class Order_ { public static volatile SingularAttribute<Order, Integer> id; @@ -99,11 +106,12 @@ public class Order_ { Typesafe citeria query - + CriteriaBuilder cb = entityManager.getCriteriaBuilder(); CriteriaQuery<Order> cq = cb.createQuery(Order.class); SetJoin<Order, Item> itemNode = cq.from(Order.class).join(Order_.items); cq.where( cb.equal(itemNode.get(Item_.id), 5 ) ).distinct(true); +
@@ -139,23 +147,24 @@ cq.where( cb.equal(itemNode.get(Item_.id), 5 ) ).distinct(true); 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; + + 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.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.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.List, then + public static volatile ListAttribute<X, Z> z; 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"/>. Maven dependency - <dependency> + <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. + url="http://sourceforge.net/projects/hibernate/files/hibernate-jpamodelgen">SourceForge. 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 Java's @@ -197,7 +206,7 @@ cq.where( cb.equal(itemNode.get(Item_.id), 5 ) ).distinct(true);
Usage from the command line -
+
Usage with Ant 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 @@ -208,12 +217,12 @@ cq.where( cb.equal(itemNode.get(Item_.id), 5 ) ).distinct(true); configured to just run annotation processing. Javac Task configuration - <javac srcdir="${src.dir}" + <javac srcdir="${src.dir}" destdir="${target.dir}" failonerror="false" fork="true" classpath="${classpath}"> - <compilerarg value="-proc:only"/> + <compilerarg value="-proc:only"/> </javac> The option -proc:only 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.
-
+
Usage with Maven 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 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 execution - <plugin> + <plugin> <artifactId>maven-compiler-plugin</artifactId> <configuration> <source>1.6</source> <target>1.6</target> <compilerArguments> - <processor>org.hibernate.jpamodelgen.JPAMetaModelEntityProcessor</processor> + <processor>org.hibernate.jpamodelgen.JPAMetaModelEntityProcessor</processor> </compilerArguments> </configuration> </plugin> - 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 @@ -254,12 +261,12 @@ cq.where( cb.equal(itemNode.get(Item_.id), 5 ) ).distinct(true); linkend="disable-processing-maven-compiler-plugin"/>. Maven compiler plugin configuration - indirect execution - <plugin> + <plugin> <artifactId>maven-compiler-plugin</artifactId> <configuration> <source>1.6</source> <target>1.6</target> - <compilerArgument>-proc:none</compilerArgument> + <compilerArgument>-proc:none</compilerArgument> </configuration> </plugin> @@ -271,8 +278,8 @@ cq.where( cb.equal(itemNode.get(Item_.id), 5 ) ).distinct(true); url="http://www.jfrog.org/artifactory/plugins-releases">jfrog) can be used. The configuration can be seen in . - Maven compiler plugin configuration with maven-annotation-plugin - <plugin> + Configuration with maven-annotation-plugin + <plugin> <groupId>org.bsc.maven</groupId> <artifactId>maven-processor-plugin</artifactId> <executions>