HHH-8483 Adding creation of metamodelgen ascidoc to the build. Removing obsolete docbook files
This commit is contained in:
Hardy Ferentschik
Strong Liu
parent
197ef85ef7
commit
0d643af4f5
|
|
@ -53,10 +53,6 @@ jdocbook {
|
||||||
manual {
|
manual {
|
||||||
masterSourceDocumentName = 'HIBERNATE_-_Relational_Persistence_for_Idiomatic_Java.xml'
|
masterSourceDocumentName = 'HIBERNATE_-_Relational_Persistence_for_Idiomatic_Java.xml'
|
||||||
}
|
}
|
||||||
|
|
||||||
metamodelgen {
|
|
||||||
masterSourceDocumentName = 'master.xml'
|
|
||||||
}
|
|
||||||
}
|
}
|
||||||
|
|
||||||
// todo : make this part of gradle-jdocbook.
|
// todo : make this part of gradle-jdocbook.
|
||||||
|
|
@ -72,17 +68,7 @@ stageStyles_devguide.doLast {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
stageStyles_metamodelgen.doLast {
|
[ 'devguide', 'manual', 'quickstart' ].each { bookName ->
|
||||||
logger.lifecycle( "Staging metamodelgen-specific style resources")
|
|
||||||
copy {
|
|
||||||
from project.file( 'src/main/docbook/metamodelgen/en-US/images' )
|
|
||||||
into project.file( "${buildDir}/docbook/stage/metamodelgen/images" )
|
|
||||||
include '*.png'
|
|
||||||
includeEmptyDirs = false
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
[ 'devguide', 'manual', 'quickstart', 'metamodelgen' ].each { bookName ->
|
|
||||||
tasks[ "stageStyles_$bookName" ].doLast {
|
tasks[ "stageStyles_$bookName" ].doLast {
|
||||||
logger.lifecycle( "Staging local style resources")
|
logger.lifecycle( "Staging local style resources")
|
||||||
copy {
|
copy {
|
||||||
|
|
@ -127,19 +113,17 @@ File[] dirList(File dir) {
|
||||||
|
|
||||||
|
|
||||||
// asciidoctor ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
// asciidoctor ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
// - aggregator
|
|
||||||
task asciidoctor(type: Task, group: 'Documentation')
|
|
||||||
|
|
||||||
|
|
||||||
// - ServiceRegistry guide
|
|
||||||
task generateRegistryGuide(type: Task, group: 'Documentation')
|
|
||||||
asciidoctor.dependsOn generateRegistryGuide
|
|
||||||
|
|
||||||
task generateRegistryGuideHtml(type: org.asciidoctor.gradle.AsciidoctorTask, group: 'Documentation') {
|
task generateRegistryGuideHtml(type: org.asciidoctor.gradle.AsciidoctorTask, group: 'Documentation') {
|
||||||
description = 'Generates the ServiceRegistry topical guide in HTML format.'
|
description = 'Generates the ServiceRegistry topical guide in HTML format.'
|
||||||
backend = 'html5'
|
backend = 'html5'
|
||||||
sourceDir = file( 'src/main/asciidoc/topical/registries' )
|
sourceDir = file( 'src/main/asciidoc/topical/registries' )
|
||||||
// sourceDocumentName = 'ServiceRegistries.adoc'
|
outputDir = new File("$buildDir/asciidoc/topical/html")
|
||||||
|
}
|
||||||
|
|
||||||
|
task generateMetamodelgenGuideHtml(type: org.asciidoctor.gradle.AsciidoctorTask, group: 'Documentation') {
|
||||||
|
description = 'Generates the Metamodel Generator topical guide in HTML format.'
|
||||||
|
backend = 'html5'
|
||||||
|
sourceDir = file( 'src/main/asciidoc/topical/metamodelgen' )
|
||||||
outputDir = new File("$buildDir/asciidoc/topical/html")
|
outputDir = new File("$buildDir/asciidoc/topical/html")
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|
@ -152,4 +136,8 @@ tasks.withType(org.asciidoctor.gradle.AsciidoctorTask) { docTask ->
|
||||||
experimental: true
|
experimental: true
|
||||||
]
|
]
|
||||||
]
|
]
|
||||||
}
|
}
|
||||||
|
|
||||||
|
// - aggregator
|
||||||
|
task asciidoctor(type: Task, group: 'Documentation')
|
||||||
|
asciidoctor.dependsOn generateRegistryGuideHtml, generateMetamodelgenGuideHtml
|
||||||
|
|
@ -3,9 +3,6 @@
|
||||||
:version: CURRENT-VERSION
|
:version: CURRENT-VERSION
|
||||||
:toc:
|
:toc:
|
||||||
|
|
||||||
[[introduction]]
|
|
||||||
|
|
||||||
|
|
||||||
[[whatisit]]
|
[[whatisit]]
|
||||||
== What is it about?
|
== What is it about?
|
||||||
|
|
||||||
Binary file not shown.
|
Before Width: | Height: | Size: 173 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 365 KiB |
|
|
@ -1,638 +0,0 @@
|
||||||
<?xml version="1.0" encoding="UTF-8"?>
|
|
||||||
<!--
|
|
||||||
~ JBoss, Home of Professional Open Source
|
|
||||||
~ Copyright 2010, Red Hat, Inc. and/or its affiliates, and individual contributors
|
|
||||||
~ by the @authors tag. See the copyright.txt in the distribution for a
|
|
||||||
~ full listing of individual contributors.
|
|
||||||
~
|
|
||||||
~ Licensed under the Apache License, Version 2.0 (the "License");
|
|
||||||
~ you may not use this file except in compliance with the License.
|
|
||||||
~ You may obtain a copy of the License at
|
|
||||||
~ http://www.apache.org/licenses/LICENSE-2.0
|
|
||||||
~ Unless required by applicable law or agreed to in writing, software
|
|
||||||
~ distributed under the License is distributed on an "AS IS" BASIS,
|
|
||||||
~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
||||||
~ See the License for the specific language governing permissions and
|
|
||||||
~ limitations under the License.
|
|
||||||
-->
|
|
||||||
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
|
|
||||||
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
|
|
||||||
<!ENTITY version "WORKING">
|
|
||||||
<!ENTITY today "TODAY">
|
|
||||||
<!ENTITY copyrightYear "2010">
|
|
||||||
<!ENTITY copyrightHolder "Red Hat Inc.">
|
|
||||||
<!ENTITY jpa2Ref "<citation><xref linkend="JPA2"/></citation>">
|
|
||||||
<!ENTITY jsr269Ref "<citation><xref linkend="JSR_269"/></citation>">
|
|
||||||
]>
|
|
||||||
<book lang="en">
|
|
||||||
<bookinfo>
|
|
||||||
<title>Hibernate JPA 2 Metamodel Generator</title>
|
|
||||||
|
|
||||||
<subtitle>Reference Guide</subtitle>
|
|
||||||
|
|
||||||
<releaseinfo>&version;</releaseinfo>
|
|
||||||
|
|
||||||
<pubdate>&today;</pubdate>
|
|
||||||
|
|
||||||
<productnumber>&version;</productnumber>
|
|
||||||
|
|
||||||
<copyright>
|
|
||||||
<year>©rightYear;</year>
|
|
||||||
|
|
||||||
<holder>©rightHolder;</holder>
|
|
||||||
</copyright>
|
|
||||||
|
|
||||||
<authorgroup>
|
|
||||||
<author>
|
|
||||||
<firstname>Hardy</firstname>
|
|
||||||
|
|
||||||
<surname>Ferentschik</surname>
|
|
||||||
</author>
|
|
||||||
</authorgroup>
|
|
||||||
</bookinfo>
|
|
||||||
|
|
||||||
<toc></toc>
|
|
||||||
|
|
||||||
<chapter id="introduction">
|
|
||||||
<title>Introduction</title>
|
|
||||||
|
|
||||||
<section id="whatisit">
|
|
||||||
<title>What is it about?</title>
|
|
||||||
|
|
||||||
<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. For developers
|
|
||||||
it is important that the task of the metamodel generation can be
|
|
||||||
automated. Hibernate Static Metamodel Generator is an annotation
|
|
||||||
processor based on the &jsr269Ref; with the task of creating JPA 2
|
|
||||||
static metamodel classes. The following example show two JPA 2 entities
|
|
||||||
<classname>Order</classname> and <classname>Item</classname>, together
|
|
||||||
with the metamodel class <classname>Order_</classname> and a typesafe
|
|
||||||
query.</para>
|
|
||||||
|
|
||||||
<example id="jpa2-entity-example">
|
|
||||||
<title>JPA 2 annotated entities <classname>Order</classname> and
|
|
||||||
<classname>Item</classname></title>
|
|
||||||
|
|
||||||
<programlisting language="JAVA" role="JAVA">
|
|
||||||
@Entity
|
|
||||||
public class Order {
|
|
||||||
@Id
|
|
||||||
@GeneratedValue
|
|
||||||
Integer id;
|
|
||||||
|
|
||||||
@ManyToOne
|
|
||||||
Customer customer;
|
|
||||||
|
|
||||||
@OneToMany
|
|
||||||
Set<Item> items;
|
|
||||||
BigDecimal totalCost;
|
|
||||||
|
|
||||||
// standard setter/getter methods
|
|
||||||
...
|
|
||||||
}
|
|
||||||
|
|
||||||
@Entity
|
|
||||||
public class Item {
|
|
||||||
@Id
|
|
||||||
@GeneratedValue
|
|
||||||
Integer id;
|
|
||||||
|
|
||||||
int quantity;
|
|
||||||
|
|
||||||
@ManyToOne
|
|
||||||
Order order;
|
|
||||||
|
|
||||||
// standard setter/getter methods
|
|
||||||
...
|
|
||||||
}
|
|
||||||
</programlisting>
|
|
||||||
</example>
|
|
||||||
|
|
||||||
<example id="metamodel-class-example">
|
|
||||||
<title>Metamodel class <classname>Order_</classname></title>
|
|
||||||
|
|
||||||
<programlisting language="JAVA" role="JAVA">
|
|
||||||
@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">
|
|
||||||
<title>Typesafe citeria query</title>
|
|
||||||
|
|
||||||
<programlisting language="JAVA" role="JAVA">
|
|
||||||
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);
|
|
||||||
|
|
||||||
</programlisting>
|
|
||||||
</example>
|
|
||||||
|
|
||||||
<tip>
|
|
||||||
<para>The Metamodel Generator also takes into consideration xml
|
|
||||||
configuration specified in orm.xml or mapping files specified in
|
|
||||||
persistence.xml. However, if all configuration is in XML you need to
|
|
||||||
add in at least on of the mapping file the following persistence unit
|
|
||||||
metadata:<programlisting><persistence-unit-metadata>
|
|
||||||
<xml-mapping-metadata-complete/>
|
|
||||||
</persistence-unit-metadata></programlisting></para>
|
|
||||||
</tip>
|
|
||||||
</section>
|
|
||||||
|
|
||||||
<section>
|
|
||||||
<title>Canonical Metamodel</title>
|
|
||||||
|
|
||||||
<para>The structure of the metamodel classes is described in the
|
|
||||||
&jpa2Ref;, but for completeness the definition is repeated 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 <classname>X</classname> in package
|
|
||||||
p, a metamodel class <classname>X_</classname> 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 <classname>X_</classname> must be
|
|
||||||
annotated with the
|
|
||||||
<classname>javax.persistence.StaticMetamodel</classname>
|
|
||||||
annotation.</para>
|
|
||||||
</listitem>
|
|
||||||
|
|
||||||
<listitem>
|
|
||||||
<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 <classname>X</classname>, where the type of y is
|
|
||||||
<classname>Y</classname>, the metamodel class must contain a
|
|
||||||
declaration as follows:</para>
|
|
||||||
|
|
||||||
<programlisting>public static volatile SingularAttribute<X, Y> y;</programlisting>
|
|
||||||
</listitem>
|
|
||||||
|
|
||||||
<listitem>
|
|
||||||
<para>For every persistent collection-valued attribute z declared
|
|
||||||
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</para>
|
|
||||||
|
|
||||||
<programlisting>public static volatile CollectionAttribute<X, Z> z;</programlisting>
|
|
||||||
</listitem>
|
|
||||||
|
|
||||||
<listitem>
|
|
||||||
<para>if the collection type of z is java.util.Set,
|
|
||||||
then</para>
|
|
||||||
|
|
||||||
<programlisting>public static volatile SetAttribute<X, Z> z;</programlisting>
|
|
||||||
</listitem>
|
|
||||||
|
|
||||||
<listitem>
|
|
||||||
<para>if the collection type of z is java.util.List,
|
|
||||||
then</para>
|
|
||||||
|
|
||||||
<programlisting>public static volatile ListAttribute<X, Z> z;</programlisting>
|
|
||||||
</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>
|
|
||||||
|
|
||||||
<chapter id="chapter-usage">
|
|
||||||
<title>Usage</title>
|
|
||||||
|
|
||||||
<para>The jar file for the annotation processor can be found in the <ulink
|
|
||||||
url="http://repository.jboss.com/">JBoss Maven repository</ulink> using
|
|
||||||
<xref linkend="maven-dependency" />.</para>
|
|
||||||
|
|
||||||
<example id="maven-dependency">
|
|
||||||
<title>Maven dependency</title>
|
|
||||||
|
|
||||||
<programlisting language="XML" role="XML"><dependency>
|
|
||||||
<groupId>org.hibernate</groupId>
|
|
||||||
<artifactId>hibernate-jpamodelgen</artifactId>
|
|
||||||
<version>1.0.0</version>
|
|
||||||
</dependency></programlisting>
|
|
||||||
</example>
|
|
||||||
|
|
||||||
<para>Alternatively, a full distribution package can be downloaded from
|
|
||||||
<ulink
|
|
||||||
url="http://sourceforge.net/projects/hibernate/files/hibernate-jpamodelgen">SourceForge</ulink>.</para>
|
|
||||||
|
|
||||||
<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
|
|
||||||
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>
|
|
||||||
|
|
||||||
<section id="usage-ant">
|
|
||||||
<title>Usage with Ant</title>
|
|
||||||
|
|
||||||
<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 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 Ant's
|
|
||||||
<ulink url="http://ant.apache.org/manual/CoreTasks/javac.html">Javac
|
|
||||||
Task</ulink> can be configured to just run annotation
|
|
||||||
processing.</para>
|
|
||||||
|
|
||||||
<example id="javac-task-example">
|
|
||||||
<title>Javac Task configuration</title>
|
|
||||||
|
|
||||||
<programlisting language="XML" role="XML"><javac srcdir="${src.dir}"
|
|
||||||
destdir="${target.dir}"
|
|
||||||
failonerror="false"
|
|
||||||
fork="true"
|
|
||||||
classpath="${classpath}">
|
|
||||||
<compilerarg value="-proc:only"/>
|
|
||||||
</javac></programlisting>
|
|
||||||
</example>
|
|
||||||
|
|
||||||
<para>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>.</para>
|
|
||||||
|
|
||||||
<tip>
|
|
||||||
<para>Run <literal>'javac -help'</literal> to see which other
|
|
||||||
annotation processor relevant options can be specified.</para>
|
|
||||||
</tip>
|
|
||||||
</section>
|
|
||||||
|
|
||||||
<section>
|
|
||||||
<title>Usage with Maven</title>
|
|
||||||
|
|
||||||
<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 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>
|
|
||||||
|
|
||||||
<example>
|
|
||||||
<title>Maven compiler plugin configuration - direct
|
|
||||||
execution</title>
|
|
||||||
|
|
||||||
<programlisting language="XML" role="XML"><plugin>
|
|
||||||
<artifactId>maven-compiler-plugin</artifactId>
|
|
||||||
<configuration>
|
|
||||||
<source>1.6</source>
|
|
||||||
<target>1.6</target>
|
|
||||||
<compilerArguments>
|
|
||||||
<processor>org.hibernate.jpamodelgen.JPAMetaModelEntityProcessor</processor>
|
|
||||||
</compilerArguments>
|
|
||||||
</configuration>
|
|
||||||
</plugin></programlisting>
|
|
||||||
</example>
|
|
||||||
|
|
||||||
<para>The maven-compiler-plugin approach has the disadvantage that the
|
|
||||||
maven compiler plugin does currently not allow to specify multiple
|
|
||||||
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 id="disable-processing-maven-compiler-plugin">
|
|
||||||
<title>Maven compiler plugin configuration - indirect
|
|
||||||
execution</title>
|
|
||||||
|
|
||||||
<programlisting language="XML" role="XML"><plugin>
|
|
||||||
<artifactId>maven-compiler-plugin</artifactId>
|
|
||||||
<configuration>
|
|
||||||
<source>1.6</source>
|
|
||||||
<target>1.6</target>
|
|
||||||
<compilerArgument>-proc:none</compilerArgument>
|
|
||||||
</configuration>
|
|
||||||
</plugin></programlisting>
|
|
||||||
</example>
|
|
||||||
|
|
||||||
<para>Once disabled, the <ulink
|
|
||||||
url="http://code.google.com/p/maven-annotation-plugin/">maven-processor-plugin</ulink>
|
|
||||||
for annotation processing can be used. The configuration can be seen
|
|
||||||
in <xref linkend="maven-processor-plugin" />.</para>
|
|
||||||
|
|
||||||
<example id="maven-processor-plugin">
|
|
||||||
<title>Configuration with maven-processor-plugin</title>
|
|
||||||
|
|
||||||
<programlisting language="XML" role="XML"><plugin>
|
|
||||||
<groupId>org.bsc.maven</groupId>
|
|
||||||
<artifactId>maven-processor-plugin</artifactId>
|
|
||||||
<version>2.0.5</version>
|
|
||||||
<executions>
|
|
||||||
<execution>
|
|
||||||
<id>process</id>
|
|
||||||
<goals>
|
|
||||||
<goal>process</goal>
|
|
||||||
</goals>
|
|
||||||
<phase>generate-sources</phase>
|
|
||||||
<configuration>
|
|
||||||
<processors>
|
|
||||||
<processor>org.hibernate.jpamodelgen.JPAMetaModelEntityProcessor</processor>
|
|
||||||
</processors>
|
|
||||||
</configuration>
|
|
||||||
</execution>
|
|
||||||
</executions>
|
|
||||||
<dependencies>
|
|
||||||
<dependency>
|
|
||||||
<groupId>org.hibernate</groupId>
|
|
||||||
<artifactId>hibernate-jpamodelgen</artifactId>
|
|
||||||
<version>&version;</version>
|
|
||||||
</dependency>
|
|
||||||
</dependencies>
|
|
||||||
</plugin></programlisting>
|
|
||||||
</example>
|
|
||||||
</section>
|
|
||||||
</section>
|
|
||||||
|
|
||||||
<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>
|
|
||||||
|
|
||||||
<para>Intellij Idea contains from version 9.x onwards a specific
|
|
||||||
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"
|
|
||||||
fileref="idea-annotation-processor-config.png"
|
|
||||||
scalefit="" />
|
|
||||||
</imageobject>
|
|
||||||
|
|
||||||
<imageobject role="html">
|
|
||||||
<imagedata depth="" fileref="idea-annotation-processor-config.png"
|
|
||||||
scalefit="1" />
|
|
||||||
</imageobject>
|
|
||||||
</mediaobject>
|
|
||||||
|
|
||||||
<para>In the annotation processor configuration, enable annotation
|
|
||||||
processing and select obtain from project classpath. Add the
|
|
||||||
annotation processor name
|
|
||||||
<classname>org.hibernate.jpamodelgen.JPAMetaModelEntityProcessor</classname>
|
|
||||||
(and optionally the annotation processor options). Select the
|
|
||||||
module(s) containing your entities. If you have configured Maven as
|
|
||||||
recommended, it is best to select the same output directory for the
|
|
||||||
generated classes. At the time of writing, it is
|
|
||||||
<filename>target/generated-sources/apt</filename>. That way, the
|
|
||||||
generated classes will be available in IntelliJ Idea.</para>
|
|
||||||
</section>
|
|
||||||
|
|
||||||
<section>
|
|
||||||
<title>Eclipse</title>
|
|
||||||
|
|
||||||
<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>
|
|
||||||
<imageobject role="fo">
|
|
||||||
<imagedata align="center" contentdepth="" contentwidth="150mm"
|
|
||||||
fileref="eclipse-annotation-processor-config.png"
|
|
||||||
scalefit="" />
|
|
||||||
</imageobject>
|
|
||||||
|
|
||||||
<imageobject role="html">
|
|
||||||
<imagedata depth=""
|
|
||||||
fileref="eclipse-annotation-processor-config.png"
|
|
||||||
scalefit="1" />
|
|
||||||
</imageobject>
|
|
||||||
</mediaobject>
|
|
||||||
</section>
|
|
||||||
|
|
||||||
<section>
|
|
||||||
<title>NetBeans</title>
|
|
||||||
|
|
||||||
<para>Netbeans support for annotation processors is at the time of
|
|
||||||
this wrinting still in the making. Refer to NetBeans issues <ulink
|
|
||||||
url="http://www.netbeans.org/issues/show_bug.cgi?id=111065">111065</ulink>,
|
|
||||||
<ulink
|
|
||||||
url="http://www.netbeans.org/issues/show_bug.cgi?id=111293">111293</ulink>
|
|
||||||
and <ulink
|
|
||||||
url="http://www.netbeans.org/issues/show_bug.cgi?id=111294">111294</ulink>.</para>
|
|
||||||
</section>
|
|
||||||
</section>
|
|
||||||
|
|
||||||
<section>
|
|
||||||
<title>Processor specific options</title>
|
|
||||||
|
|
||||||
<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
|
|
||||||
-A[property]=[value])</title>
|
|
||||||
|
|
||||||
<tgroup cols="2">
|
|
||||||
<tbody>
|
|
||||||
<row>
|
|
||||||
<entry><emphasis role="bold">Option name</emphasis></entry>
|
|
||||||
|
|
||||||
<entry><emphasis role="bold">Option value and
|
|
||||||
usage</emphasis></entry>
|
|
||||||
</row>
|
|
||||||
|
|
||||||
<row>
|
|
||||||
<entry>debug</entry>
|
|
||||||
|
|
||||||
<entry>If set to <literal>true</literal> additional trace
|
|
||||||
information will be outputted by the processor</entry>
|
|
||||||
</row>
|
|
||||||
|
|
||||||
<row>
|
|
||||||
<entry>persistenceXml</entry>
|
|
||||||
|
|
||||||
<entry>Per default the processor looks in
|
|
||||||
<filename>/META-INF</filename> for persistence.xml. Specifying
|
|
||||||
this option a <filename>persitence.xml</filename> file from a
|
|
||||||
different location can be specified (has to be on the
|
|
||||||
classpath)</entry>
|
|
||||||
</row>
|
|
||||||
|
|
||||||
<row>
|
|
||||||
<entry>ormXml</entry>
|
|
||||||
|
|
||||||
<entry>Allows to specify additional entity mapping files. The
|
|
||||||
specified value for this option is a comma separated string of
|
|
||||||
mapping file names. Even when this option is specified
|
|
||||||
<filename>/META-INF/orm.xml</filename> is implicit.</entry>
|
|
||||||
</row>
|
|
||||||
|
|
||||||
<row>
|
|
||||||
<entry>lazyXmlParsing</entry>
|
|
||||||
|
|
||||||
<entry>Possible values are <literal>true</literal> or
|
|
||||||
<literal>false</literal>. If set to <literal>true</literal>
|
|
||||||
the annotation processor tries to determine whether any of the
|
|
||||||
xml files has changed between invocations and if unchanged
|
|
||||||
skips the xml parsing. This feature is experimental and
|
|
||||||
contains the risk of wron results in some cases of mixed mode
|
|
||||||
configurations. To determine wether a file has been modified a
|
|
||||||
temporary file
|
|
||||||
<filename>Hibernate-Static-Metamodel-Generator.tmp</filename>
|
|
||||||
is used. This file gets created in the
|
|
||||||
<literal>java.io.tmpdir</literal> directory.</entry>
|
|
||||||
</row>
|
|
||||||
|
|
||||||
<row>
|
|
||||||
<entry>fullyAnnotationConfigured</entry>
|
|
||||||
|
|
||||||
<entry>If set to <literal>true</literal> the processor will
|
|
||||||
ignore <filename>orm.xml</filename> and
|
|
||||||
<filename>persistence.xml.</filename></entry>
|
|
||||||
</row>
|
|
||||||
|
|
||||||
<row>
|
|
||||||
<entry>addGeneratedAnnotation</entry>
|
|
||||||
|
|
||||||
<entry>If set to <literal>true</literal> the processor will
|
|
||||||
add the <classname>@Generated</classname> to the generated
|
|
||||||
Java source file. Adding this annotation using JDK 5will cause
|
|
||||||
a compilation error. In this case set the flag to
|
|
||||||
<constant>false</constant>. The default for this option is
|
|
||||||
<constant>true</constant></entry>
|
|
||||||
</row>
|
|
||||||
|
|
||||||
<row>
|
|
||||||
<entry>addGenerationDate</entry>
|
|
||||||
|
|
||||||
<entry>If set to <constant>true</constant> the generation date
|
|
||||||
of the metamodel class will be inserted in the date parameter
|
|
||||||
of the <classname>@Generated</classname> annotation. The
|
|
||||||
default is <constant>false</constant>. This parameter is
|
|
||||||
ignored if <constant>addGeneratedAnnotation</constant> is set
|
|
||||||
to <constant>false</constant>.</entry>
|
|
||||||
</row>
|
|
||||||
|
|
||||||
<row>
|
|
||||||
<entry>addSuppressWarningsAnnotation</entry>
|
|
||||||
|
|
||||||
<entry>If set to <literal>true</literal> the processor will
|
|
||||||
add <emphasis>@SuppressWarnings("all")</emphasis> to the
|
|
||||||
generated Java source file. Per default this annotation is not
|
|
||||||
generated. See also <ulink
|
|
||||||
url="https://hibernate.onjira.com/browse/METAGEN-50">METAGEN-50</ulink>.</entry>
|
|
||||||
</row>
|
|
||||||
</tbody>
|
|
||||||
</tgroup>
|
|
||||||
</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>
|
|
||||||
|
|
||||||
<bibliography>
|
|
||||||
<title>References</title>
|
|
||||||
|
|
||||||
<biblioentry id="JSR_269">
|
|
||||||
<abbrev id="JSR_269_ABBREV">Pluggable Annotation Processing API</abbrev>
|
|
||||||
|
|
||||||
<title>JSR 269: Pluggable Annotation Processing API</title>
|
|
||||||
|
|
||||||
<copyright>
|
|
||||||
<year>2006</year>
|
|
||||||
|
|
||||||
<holder>SUN MICROSYSTEMS, INC.</holder>
|
|
||||||
</copyright>
|
|
||||||
|
|
||||||
<bibliomisc><email>jsr-269-feedback@sun.com</email> <ulink
|
|
||||||
url="http://jcp.org/en/jsr/detail?id=269">JSR 269 JCP
|
|
||||||
Page</ulink></bibliomisc>
|
|
||||||
</biblioentry>
|
|
||||||
|
|
||||||
<biblioentry id="JPA2">
|
|
||||||
<abbrev id="JPA2_ABBREV">JPA 2 Specification</abbrev>
|
|
||||||
|
|
||||||
<title>JSR 317: <trademark>Java</trademark> Persistence API, Version
|
|
||||||
2.0</title>
|
|
||||||
|
|
||||||
<collab>
|
|
||||||
<collabname>Java Persistence 2.0 Expert Group</collabname>
|
|
||||||
</collab>
|
|
||||||
|
|
||||||
<copyright>
|
|
||||||
<year>2009</year>
|
|
||||||
|
|
||||||
<holder>SUN MICROSYSTEMS, INC.</holder>
|
|
||||||
</copyright>
|
|
||||||
|
|
||||||
<bibliomisc><email>jsr-317-feedback@sun.com</email> <ulink
|
|
||||||
url="http://jcp.org/en/jsr/detail?id=317">JSR 317 JCP
|
|
||||||
Page</ulink></bibliomisc>
|
|
||||||
</biblioentry>
|
|
||||||
</bibliography>
|
|
||||||
</book>
|
|
||||||
Loading…
Reference in New Issue