11:50 a.m.
Author: hardy.ferentschik
Date: 2010-02-11 12:50:02 -0500 (Thu, 11 Feb 2010)
New Revision: 18784
Added:
jpamodelgen/trunk/src/main/docbook/
jpamodelgen/trunk/src/main/docbook/en-US/
jpamodelgen/trunk/src/main/docbook/en-US/images/
jpamodelgen/trunk/src/main/docbook/en-US/images/eclipse-annotation-processor-config.png
jpamodelgen/trunk/src/main/docbook/en-US/images/idea-annotation-processor-config.png
jpamodelgen/trunk/src/main/docbook/en-US/master.xml
Modified:
jpamodelgen/trunk/pom.xml
Log:
METAGEN-4 Added a start for the documentation
Modified: jpamodelgen/trunk/pom.xml
===================================================================
--- jpamodelgen/trunk/pom.xml 2010-02-11 16:16:21 UTC (rev 18783)
+++ jpamodelgen/trunk/pom.xml 2010-02-11 17:50:02 UTC (rev 18784)
@@ -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>
@@ -28,13 +30,13 @@
<groupId>org.slf4j</groupId>
<artifactId>slf4j-api</artifactId>
<version>1.5.6</version>
- </dependency>
+ </dependency>
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-log4j12</artifactId>
<scope>test</scope>
<version>1.5.6</version>
- </dependency>
+ </dependency>
</dependencies>
<licenses>
@@ -161,7 +163,7 @@
<artifactId>maven-surefire-plugin</artifactId>
<version>2.4.3</version>
<configuration>
- <redirectTestOutputToFile>true</redirectTestOutputToFile>
+
<redirectTestOutputToFile>true</redirectTestOutputToFile>
<systemProperties>
<property>
<name>sourceBaseDir</name>
@@ -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>
Added:
jpamodelgen/trunk/src/main/docbook/en-US/images/eclipse-annotation-processor-config.png
===================================================================
(Binary files differ)
Property changes on:
jpamodelgen/trunk/src/main/docbook/en-US/images/eclipse-annotation-processor-config.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added:
jpamodelgen/trunk/src/main/docbook/en-US/images/idea-annotation-processor-config.png
===================================================================
(Binary files differ)
Property changes on:
jpamodelgen/trunk/src/main/docbook/en-US/images/idea-annotation-processor-config.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: jpamodelgen/trunk/src/main/docbook/en-US/master.xml
===================================================================
--- jpamodelgen/trunk/src/main/docbook/en-US/master.xml (rev 0)
+++ jpamodelgen/trunk/src/main/docbook/en-US/master.xml 2010-02-11 17:50:02 UTC (rev
18784)
@@ -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>
Property changes on: jpamodelgen/trunk/src/main/docbook/en-US/master.xml
___________________________________________________________________
Name: svn:keywords
+ Id