METAGEN-4 Added a start for the documentation
This commit is contained in:
Hardy Ferentschik
Strong Liu
parent
813339a647
commit
7856f66eb9
|
|
@ -1,4 +1,6 @@
|
||||||
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
|
<project xmlns="http://maven.apache.org/POM/4.0.0"
|
||||||
|
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||||||
|
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
|
||||||
|
|
||||||
<modelVersion>4.0.0</modelVersion>
|
<modelVersion>4.0.0</modelVersion>
|
||||||
|
|
||||||
|
|
@ -28,13 +30,13 @@
|
||||||
<groupId>org.slf4j</groupId>
|
<groupId>org.slf4j</groupId>
|
||||||
<artifactId>slf4j-api</artifactId>
|
<artifactId>slf4j-api</artifactId>
|
||||||
<version>1.5.6</version>
|
<version>1.5.6</version>
|
||||||
</dependency>
|
</dependency>
|
||||||
<dependency>
|
<dependency>
|
||||||
<groupId>org.slf4j</groupId>
|
<groupId>org.slf4j</groupId>
|
||||||
<artifactId>slf4j-log4j12</artifactId>
|
<artifactId>slf4j-log4j12</artifactId>
|
||||||
<scope>test</scope>
|
<scope>test</scope>
|
||||||
<version>1.5.6</version>
|
<version>1.5.6</version>
|
||||||
</dependency>
|
</dependency>
|
||||||
</dependencies>
|
</dependencies>
|
||||||
|
|
||||||
<licenses>
|
<licenses>
|
||||||
|
|
@ -161,7 +163,7 @@
|
||||||
<artifactId>maven-surefire-plugin</artifactId>
|
<artifactId>maven-surefire-plugin</artifactId>
|
||||||
<version>2.4.3</version>
|
<version>2.4.3</version>
|
||||||
<configuration>
|
<configuration>
|
||||||
<redirectTestOutputToFile>true</redirectTestOutputToFile>
|
<redirectTestOutputToFile>true</redirectTestOutputToFile>
|
||||||
<systemProperties>
|
<systemProperties>
|
||||||
<property>
|
<property>
|
||||||
<name>sourceBaseDir</name>
|
<name>sourceBaseDir</name>
|
||||||
|
|
@ -255,6 +257,70 @@
|
||||||
<goals>package deploy</goals>
|
<goals>package deploy</goals>
|
||||||
</configuration>
|
</configuration>
|
||||||
</plugin>
|
</plugin>
|
||||||
|
<plugin>
|
||||||
|
<groupId>org.jboss.maven.plugins</groupId>
|
||||||
|
<artifactId>maven-jdocbook-plugin</artifactId>
|
||||||
|
<version>2.2.0</version>
|
||||||
|
<extensions>true</extensions>
|
||||||
|
<dependencies>
|
||||||
|
<dependency>
|
||||||
|
<groupId>org.hibernate</groupId>
|
||||||
|
<artifactId>hibernate-jdocbook-style</artifactId>
|
||||||
|
<version>2.0.0</version>
|
||||||
|
<type>jdocbook-style</type>
|
||||||
|
</dependency>
|
||||||
|
</dependencies>
|
||||||
|
<configuration>
|
||||||
|
<sourceDocumentName>master.xml</sourceDocumentName>
|
||||||
|
<sourceDirectory>${basedir}/src/main/docbook</sourceDirectory>
|
||||||
|
<masterTranslation>en-US</masterTranslation>
|
||||||
|
<imageResource>
|
||||||
|
<directory>${basedir}/src/main/docbook/en-US/images</directory>
|
||||||
|
</imageResource>
|
||||||
|
<formats>
|
||||||
|
<format>
|
||||||
|
<formatName>pdf</formatName>
|
||||||
|
<stylesheetResource>classpath:/xslt/org/hibernate/jdocbook/xslt/pdf.xsl</stylesheetResource>
|
||||||
|
<finalName>hibernate-metamodel-generator-reference.pdf</finalName>
|
||||||
|
</format>
|
||||||
|
<format>
|
||||||
|
<formatName>html_single</formatName>
|
||||||
|
<stylesheetResource>classpath:/xslt/org/hibernate/jdocbook/xslt/xhtml-single.xsl
|
||||||
|
</stylesheetResource>
|
||||||
|
<finalName>index.html</finalName>
|
||||||
|
</format>
|
||||||
|
<format>
|
||||||
|
<formatName>html</formatName>
|
||||||
|
<stylesheetResource>classpath:/xslt/org/hibernate/jdocbook/xslt/xhtml.xsl
|
||||||
|
</stylesheetResource>
|
||||||
|
<finalName>index.html</finalName>
|
||||||
|
</format>
|
||||||
|
</formats>
|
||||||
|
<options>
|
||||||
|
<xincludeSupported>true</xincludeSupported>
|
||||||
|
<xmlTransformerType>saxon</xmlTransformerType>
|
||||||
|
<!-- needed for uri-resolvers; can be ommitted if using 'current' uri scheme -->
|
||||||
|
<!-- could also locate the docbook dependency and inspect its version... -->
|
||||||
|
<docbookVersion>1.72.0</docbookVersion>
|
||||||
|
<localeSeparator>-</localeSeparator>
|
||||||
|
</options>
|
||||||
|
</configuration>
|
||||||
|
<executions>
|
||||||
|
<execution>
|
||||||
|
<id>make-doc</id>
|
||||||
|
<phase>site</phase>
|
||||||
|
<goals>
|
||||||
|
<goal>resources</goal>
|
||||||
|
<goal>generate</goal>
|
||||||
|
</goals>
|
||||||
|
</execution>
|
||||||
|
</executions>
|
||||||
|
</plugin>
|
||||||
|
<plugin>
|
||||||
|
<groupId>org.jboss.maven.plugins</groupId>
|
||||||
|
<artifactId>maven-jdocbook-style-plugin</artifactId>
|
||||||
|
<version>2.0.0</version>
|
||||||
|
</plugin>
|
||||||
</plugins>
|
</plugins>
|
||||||
|
|
||||||
<extensions>
|
<extensions>
|
||||||
|
|
|
||||||
Binary file not shown.
|
After Width: | Height: | Size: 125 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 333 KiB |
|
|
@ -0,0 +1,283 @@
|
||||||
|
<?xml version="1.0" encoding="UTF-8"?>
|
||||||
|
<!-- $Id$ -->
|
||||||
|
<!--
|
||||||
|
~ 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 versionNumber "1.0.0">
|
||||||
|
<!ENTITY copyrightYear "2010">
|
||||||
|
<!ENTITY copyrightHolder "Red Hat Middleware, LLC.">
|
||||||
|
]>
|
||||||
|
<book lang="en">
|
||||||
|
<bookinfo>
|
||||||
|
<title>Hibernate Metamodel Generator</title>
|
||||||
|
|
||||||
|
<subtitle>JPA 2 Static Metamodel Annotation Processor</subtitle>
|
||||||
|
|
||||||
|
<subtitle>Reference Guide</subtitle>
|
||||||
|
|
||||||
|
<releaseinfo>&versionNumber;</releaseinfo>
|
||||||
|
|
||||||
|
<productnumber>&versionNumber;</productnumber>
|
||||||
|
|
||||||
|
<copyright>
|
||||||
|
<year>©rightYear;</year>
|
||||||
|
|
||||||
|
<holder>©rightHolder;</holder>
|
||||||
|
</copyright>
|
||||||
|
</bookinfo>
|
||||||
|
|
||||||
|
<toc></toc>
|
||||||
|
|
||||||
|
<chapter id="introduction">
|
||||||
|
<title>Introduction</title>
|
||||||
|
|
||||||
|
<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>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="installation" revision="1">
|
||||||
|
<title>Installation</title>
|
||||||
|
|
||||||
|
<para><section revision="1">
|
||||||
|
<title>Prerequisites</title>
|
||||||
|
|
||||||
|
<para />
|
||||||
|
</section></para>
|
||||||
|
</section>
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter>
|
||||||
|
<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.</para>
|
||||||
|
|
||||||
|
<section>
|
||||||
|
<title>Usage from the command line</title>
|
||||||
|
|
||||||
|
<para><section 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">
|
||||||
|
<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>
|
||||||
|
|
||||||
|
<para><example>
|
||||||
|
<title>Maven compiler plugin configuration - direct
|
||||||
|
execution</title>
|
||||||
|
|
||||||
|
<programlisting><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>
|
||||||
|
|
||||||
|
<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>
|
||||||
|
|
||||||
|
<example>
|
||||||
|
<title>Maven compiler plugin configuration - indirect
|
||||||
|
execution</title>
|
||||||
|
|
||||||
|
<programlisting><plugin>
|
||||||
|
<artifactId>maven-compiler-plugin</artifactId>
|
||||||
|
<configuration>
|
||||||
|
<source>1.6</source>
|
||||||
|
<target>1.6</target>
|
||||||
|
<compilerArgument>-proc:none</compilerArgument>
|
||||||
|
</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>
|
||||||
|
|
||||||
|
<example>
|
||||||
|
<title>Maven compiler plugin configuration with
|
||||||
|
maven-annotation-plugin</title>
|
||||||
|
|
||||||
|
<programlisting><plugin>
|
||||||
|
<groupId>org.bsc.maven</groupId>
|
||||||
|
<artifactId>maven-processor-plugin</artifactId>
|
||||||
|
<executions>
|
||||||
|
<execution>
|
||||||
|
<id>process</id>
|
||||||
|
<goals>
|
||||||
|
<goal>process</goal>
|
||||||
|
</goals>
|
||||||
|
<phase>generate-sources</phase>
|
||||||
|
<configuration>
|
||||||
|
<!-- source output directory -->
|
||||||
|
<outputDirectory>target/metamodel</outputDirectory>
|
||||||
|
</configuration>
|
||||||
|
</execution>
|
||||||
|
</executions>
|
||||||
|
</plugin>
|
||||||
|
<plugin>
|
||||||
|
<groupId>org.codehaus.mojo</groupId>
|
||||||
|
<artifactId>build-helper-maven-plugin</artifactId>
|
||||||
|
<version>1.3</version>
|
||||||
|
<executions>
|
||||||
|
<execution>
|
||||||
|
<id>add-source</id>
|
||||||
|
<phase>generate-sources</phase>
|
||||||
|
<goals>
|
||||||
|
<goal>add-source</goal>
|
||||||
|
</goals>
|
||||||
|
<configuration>
|
||||||
|
<sources>
|
||||||
|
<source>target/metamodel</source>
|
||||||
|
</sources>
|
||||||
|
</configuration>
|
||||||
|
</execution>
|
||||||
|
</executions>
|
||||||
|
</plugin></programlisting>
|
||||||
|
</example>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section>
|
||||||
|
<title>Usage within the IDE</title>
|
||||||
|
|
||||||
|
<section>
|
||||||
|
<title>Idea</title>
|
||||||
|
|
||||||
|
<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></para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section>
|
||||||
|
<title>Eclipse</title>
|
||||||
|
|
||||||
|
<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>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>
|
||||||
|
</section>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section>
|
||||||
|
<title>Options</title>
|
||||||
|
|
||||||
|
<para>The annotaton processor accepts a series of custom properties
|
||||||
|
which can be passed to the processor execution 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>Option name</entry>
|
||||||
|
|
||||||
|
<entry>Option value and usage</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>
|
||||||
|
</tbody>
|
||||||
|
</tgroup>
|
||||||
|
</table></para>
|
||||||
|
</section>
|
||||||
|
</chapter>
|
||||||
|
</book>
|
||||||
Loading…
Reference in New Issue