diff --git a/tooling/metamodel-generator/pom.xml b/tooling/metamodel-generator/pom.xml index 4dac279a2d..eb816facce 100644 --- a/tooling/metamodel-generator/pom.xml +++ b/tooling/metamodel-generator/pom.xml @@ -1,4 +1,6 @@ - + 4.0.0 @@ -28,13 +30,13 @@ org.slf4j slf4j-api 1.5.6 - + org.slf4j slf4j-log4j12 test 1.5.6 - + @@ -161,7 +163,7 @@ maven-surefire-plugin 2.4.3 - true + true sourceBaseDir @@ -255,6 +257,70 @@ package deploy + + org.jboss.maven.plugins + maven-jdocbook-plugin + 2.2.0 + true + + + org.hibernate + hibernate-jdocbook-style + 2.0.0 + jdocbook-style + + + + master.xml + ${basedir}/src/main/docbook + en-US + + ${basedir}/src/main/docbook/en-US/images + + + + pdf + classpath:/xslt/org/hibernate/jdocbook/xslt/pdf.xsl + hibernate-metamodel-generator-reference.pdf + + + html_single + classpath:/xslt/org/hibernate/jdocbook/xslt/xhtml-single.xsl + + index.html + + + html + classpath:/xslt/org/hibernate/jdocbook/xslt/xhtml.xsl + + index.html + + + + true + saxon + + + 1.72.0 + - + + + + + make-doc + site + + resources + generate + + + + + + org.jboss.maven.plugins + maven-jdocbook-style-plugin + 2.0.0 + diff --git a/tooling/metamodel-generator/src/main/docbook/en-US/images/eclipse-annotation-processor-config.png b/tooling/metamodel-generator/src/main/docbook/en-US/images/eclipse-annotation-processor-config.png new file mode 100644 index 0000000000..ba53ad8a38 Binary files /dev/null and b/tooling/metamodel-generator/src/main/docbook/en-US/images/eclipse-annotation-processor-config.png differ diff --git a/tooling/metamodel-generator/src/main/docbook/en-US/images/idea-annotation-processor-config.png b/tooling/metamodel-generator/src/main/docbook/en-US/images/idea-annotation-processor-config.png new file mode 100644 index 0000000000..604d20d162 Binary files /dev/null and b/tooling/metamodel-generator/src/main/docbook/en-US/images/idea-annotation-processor-config.png differ diff --git a/tooling/metamodel-generator/src/main/docbook/en-US/master.xml b/tooling/metamodel-generator/src/main/docbook/en-US/master.xml new file mode 100644 index 0000000000..f061583f88 --- /dev/null +++ b/tooling/metamodel-generator/src/main/docbook/en-US/master.xml @@ -0,0 +1,283 @@ + + + + + + +]> + + + Hibernate Metamodel Generator + + JPA 2 Static Metamodel Annotation Processor + + Reference Guide + + &versionNumber; + + &versionNumber; + + + ©rightYear; + + ©rightHolder; + + + + + + + Introduction + +
+ What is it about? + + 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. +
+ +
+ Installation + +
+ Prerequisites + + +
+
+ + + + Usage + + 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 + javax.annotation.processing.Processor in the + META-INF/services listing + org.hibernate.jpamodelgen.JPAMetaModelEntityProcessor + as annotation processor. + +
+ Usage from the command line + +
+ Usage with Ant +
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.
+ Usage with Maven +
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: + + + Maven compiler plugin configuration - direct + execution + + <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> + + + 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: + + + Maven compiler plugin configuration - indirect + execution + + <plugin> + <artifactId>maven-compiler-plugin</artifactId> + <configuration> + <source>1.6</source> + <target>1.6</target> + <compilerArgument>-proc:none</compilerArgument> + </configuration> +</plugin> + + + and use the maven-annotation-plugin for annotation processing (you + will need the following additional maven repositories - + maven-annotation-plugin and jfrog): + + + Maven compiler plugin configuration with + maven-annotation-plugin + + <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> + +
+ +
+ Usage within the IDE + +
+ Idea + + + + + + + + + + + + +
+ +
+ Eclipse + + + + + + + + + + +
+ +
+ NetBeans + + 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. +
+
+ +
+ Options + + The annotaton processor accepts a series of custom properties + which can be passed to the processor execution in the format + -A[property]=[value]. The supported properties + are: + Annotation processor options (passed via + -A[property]=[value]) + + + + + Option name + + Option value and usage + + + + debug + + if set to true additional trace + information will be outputted by the processor + + + + persistenceXml + + Per default the processor looks in + /META-INF for persistence.xml. Specifying + this option a persitence.xml file from a + different location can be specified (has to be on the + classpath) + + + + ormXml + + 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 + /META-INF/orm.xml is implicit. + + + +
+
+ +