[hibernate-commits] Hibernate SVN: r18810 - jpamodelgen/trunk/src/main/docbook/en-US.
hibernate-commits at lists.jboss.org
hibernate-commits at lists.jboss.org
Mon Feb 15 17:40:30 EST 2010
Author: hardy.ferentschik
Date: 2010-02-15 17:40:30 -0500 (Mon, 15 Feb 2010)
New Revision: 18810
Modified:
jpamodelgen/trunk/src/main/docbook/en-US/master.xml
Log:
METAGEN-4
Modified: jpamodelgen/trunk/src/main/docbook/en-US/master.xml
===================================================================
--- jpamodelgen/trunk/src/main/docbook/en-US/master.xml 2010-02-15 21:11:47 UTC (rev 18809)
+++ jpamodelgen/trunk/src/main/docbook/en-US/master.xml 2010-02-15 22:40:30 UTC (rev 18810)
@@ -49,20 +49,126 @@
<section id="whatisit" revision="1">
<title>What is it about?</title>
- <para>Hibernate Static Metamodel Generator is an annotation processor
- with the task of creating the static metamodel classes for JPA 2
- entities. In the following I will show how to integrate the annotation
- processor into your build environment.</para>
+ <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 type safety. This type saftey
+ 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<Item> items;
+ BigDecimal totalCost;
+ ...
+}
+</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<Order, Integer> id;
+ public static volatile SingularAttribute<Order, Customer> customer;
+ public static volatile SetAttribute<Order, Item> items;
+ public static volatile SingularAttribute<Order, BigDecimal> totalCost;
+}
+</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();
+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);
+</programlisting>
+ </example>
</section>
- <section id="installation" revision="1">
- <title>Installation</title>
+ <section>
+ <title>Canonical Metamodel</title>
- <para><section revision="1">
- <title>Prerequisites</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 />
- </section></para>
+ <para><itemizedlist>
+ <listitem>
+ <para>For each managed class X in package p, a metamodel class X_
+ 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 X_ must be annotated with the
+ javax.persistence.Static- Metamodel 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>
+ </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>
+ </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>
+ <listitem>
+ <para>if the collection type of z is java.util.Collection,
+ then <programlisting>public static volatile CollectionAttribute<X, Z> z;</programlisting></para>
+ </listitem>
+
+ <listitem>
+ <para>if the collection type of z is java.util.Set, then
+ <programlisting>public static volatile SetAttribute<X, Z> z;</programlisting></para>
+ </listitem>
+
+ <listitem>
+ <para>if the collection type of z is java.util.List, then
+ <programlisting>public static volatile ListAttribute<X, Z> z;</programlisting></para>
+ </listitem>
+
+ <listitem>
+ <para>if the collection type of z is java.util.Map, then
+ <programlisting>public static volatile MapAttribute<X, K, Z> 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>
@@ -76,8 +182,21 @@
<classname>javax.annotation.processing.Processor</classname> in the
<filename>META-INF/services</filename> listing
<classname>org.hibernate.jpamodelgen.JPAMetaModelEntityProcessor</classname>
- as annotation processor.</para>
+ 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>
+ <example id="maven-dependency" label="">
+ <title>Maven dependency for Hibernate Static Metamodel Generator</title>
+
+ <programlisting><dependency>
+ <groupId>org.hibernate</groupId>
+ <artifactId>hibernate-jpamodelgen</artifactId>
+ <version>1.0.0</version>
+</dependency>
+</programlisting>
+ </example>
+
<section>
<title>Usage from the command line</title>
@@ -181,6 +300,11 @@
<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>
@@ -196,13 +320,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 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>
+
<mediaobject>
<imageobject role="fo">
<imagedata align="center" contentdepth="" contentwidth="150mm"
@@ -221,14 +350,7 @@
<section>
<title>NetBeans</title>
- <para>Of course you also want to have annotation processing available
- 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>
+ <para>TODO</para>
</section>
</section>
More information about the hibernate-commits
mailing list