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>
|
||||
|
||||
|
|
@ -255,6 +257,70 @@
|
|||
<goals>package deploy</goals>
|
||||
</configuration>
|
||||
</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>
|
||||
|
||||
<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