| <?xml version="1.0" encoding="UTF-8"?> |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you 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. |
| --> |
| <chapter id="ref_guide_integration"> |
| <title> |
| Third Party Integration |
| </title> |
| <para> |
| OpenJPA provides a number of mechanisms for integrating with third-party tools. |
| The following chapter will illustrate these integration features. |
| </para> |
| <section id="ref_guide_integration_ant"> |
| <title> |
| Apache Ant |
| </title> |
| <indexterm zone="ref_guide_integration_ant"> |
| <primary> |
| Ant |
| </primary> |
| </indexterm> |
| <para> |
| Ant is a very popular tool for building Java projects. It is similar to the |
| <literal>make</literal> command, but is Java-centric and has more modern |
| features. Ant is open source, and can be downloaded from Apache's Ant web page |
| at <ulink url="http://jakarta.apache.org/ant/"> http://jakarta.apache.org/ant/ |
| </ulink>. Ant has become the de-facto standard build tool for Java, and many |
| commercial integrated development environments provide some support for using |
| ant build files. The remainder of this section assumes familiarity with writing |
| Ant <filename>build.xml</filename> files. |
| </para> |
| <para> |
| OpenJPA provides pre-built Ant task definitions for all bundled tools: |
| </para> |
| <itemizedlist> |
| <listitem> |
| <para> |
| <link linkend="ref_guide_integration_enhance">Enhancer Task</link> |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| <link linkend="ref_guide_integration_appidtool">Application Identity Tool Task |
| </link> |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| <link linkend="ref_guide_integration_mappingtool">Mapping Tool Task</link> |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| <link linkend="ref_guide_integration_revmappingtool">Reverse Mapping Tool Task |
| </link> |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| <link linkend="ref_guide_integration_schematool">Schema Tool Task</link> |
| </para> |
| </listitem> |
| </itemizedlist> |
| <para> |
| The source code for all the ant tasks is provided with the distribution under |
| the <filename>src</filename> directory. This allows you to customize various |
| aspects of the ant tasks in order to better integrate into your development |
| environment. |
| </para> |
| <section id="ref_guide_integration_conf"> |
| <title> |
| Common Ant Configuration Options |
| </title> |
| <indexterm> |
| <primary> |
| Ant |
| </primary> |
| <secondary> |
| configuration options |
| </secondary> |
| </indexterm> |
| <para> |
| All OpenJPA tasks accept a nested <literal>config</literal> element, which |
| defines the configuration environment in which the specified task will run. The |
| attributes for the <literal>config</literal> tag are defined by the |
| <ulink url="../javadoc/org/apache/openjpa/jdbc/conf/JDBCConfiguration.html"> |
| <classname>JDBCConfiguration</classname></ulink> bean methods. Note that |
| excluding the <literal>config</literal> element will cause the Ant task to use |
| the default system configuration mechanism, such as the configuration defined in |
| the <filename>org.apache.openjpa.xml</filename> file. |
| </para> |
| <para> |
| Following is an example of how to use the nested <literal>config</literal> tag |
| in a <filename>build.xml</filename> file: |
| </para> |
| <example id="ref_guide_integration_conf_config"> |
| <title> |
| Using the <config> Ant Tag |
| </title> |
| <programlisting> |
| <mappingtool> |
| <fileset dir="${basedir}"> |
| <include name="**/model/*.java" /> |
| </fileset> |
| <config connectionUserName="scott" connectionPassword="tiger" |
| connectionURL="jdbc:oracle:thin:@saturn:1521:solarsid" |
| connectionDriverName="oracle.jdbc.driver.OracleDriver" /> |
| </mappingtool> |
| </programlisting> |
| </example> |
| <para> |
| It is also possible to specify a <literal>properties</literal> or <literal> |
| propertiesFile</literal> attribute on the <literal>config</literal> tag, which |
| will be used to locate a properties resource or file. The resource will be |
| loaded relative to the current CLASSPATH. |
| </para> |
| <example id="ref_guide_integration_props"> |
| <title> |
| Using the Properties Attribute of the <config> Tag |
| </title> |
| <programlisting> |
| <mappingtool> |
| <fileset dir="${basedir}"> |
| <include name="**/model/*.java"/> |
| </fileset> |
| <config properties="openjpa-dev.xml"/> |
| </mappingtool> |
| </programlisting> |
| </example> |
| <example id="ref_guide_integration_propsfile"> |
| <title> |
| Using the PropertiesFile Attribute of the <config> Tag |
| </title> |
| <programlisting> |
| <mappingtool> |
| <fileset dir="${basedir}"> |
| <include name="**/model/*.java"/> |
| </fileset> |
| <config propertiesFile="../conf/openjpa-dev.xml"/> |
| </mappingtool> |
| </programlisting> |
| </example> |
| <para> |
| Tasks also accept a nested <literal>classpath</literal> element, which you can |
| use in place of the default classpath. The <literal>classpath</literal> argument |
| behaves the same as it does for Ant's standard <literal>javac</literal> element. |
| It is sometimes the case that projects are compiled to a separate directory than |
| the source tree. If the target path for compiled classes is not included in the |
| project's classpath, then a <literal>classpath</literal> element that includes |
| the target class directory needs to be included so the enhancer and mapping tool |
| can locate the relevant classes. |
| </para> |
| <para> |
| Following is an example of using a <literal>classpath</literal> tag: |
| </para> |
| <example id="ref_guide_integration_conf_classpath"> |
| <title> |
| Using the <classpath> Ant Tag |
| </title> |
| <programlisting> |
| <openjpac> |
| <fileset dir="${basedir}/source"> |
| <include name="**/model/*.java" /> |
| </fileset> |
| <classpath> |
| <pathelement location="${basedir}/classes"/> |
| <pathelement location="${basedir}/source"/> |
| <pathelement path="${java.class.path}"/> |
| </classpath> |
| </openjpac> |
| </programlisting> |
| </example> |
| <para> |
| Finally, tasks that invoke code-generation tools like the application identity |
| tool and reverse mapping tool accept a nested <literal>codeformat</literal> |
| element. See the code formatting documentation in |
| <xref linkend="ref_guide_conf_devtools_format"/> for a list of code |
| formatting attributes. |
| </para> |
| <example id="ref_guide_integration_conf_codeformat"> |
| <title> |
| Using the <codeformat> Ant Tag |
| </title> |
| <programlisting> |
| <reversemappingtool package="com.xyz.jdo" directory="${basedir}/src"> |
| <codeformat tabSpaces="4" spaceBeforeParen="true" braceOnSameLine="false"/> |
| </reversemappingtool> |
| </programlisting> |
| </example> |
| </section> |
| <section id="ref_guide_integration_enhance"> |
| <title> |
| Enhancer Ant Task |
| </title> |
| <indexterm zone="ref_guide_integration_enhance"> |
| <primary> |
| Ant |
| </primary> |
| <secondary> |
| enhancer task |
| </secondary> |
| </indexterm> |
| <indexterm zone="ref_guide_integration_enhance"> |
| <primary> |
| enhancer |
| </primary> |
| <secondary> |
| Ant task |
| </secondary> |
| </indexterm> |
| <para> |
| The enhancer task allows you to invoke the OpenJPA enhancer directly from within |
| the Ant build process. The task's parameters correspond exactly to the long |
| versions of the command-line arguments to the |
| <link linkend="ref_guide_pc_enhance"><classname> |
| org.apache.openjpa.enhance.PCEnhancer</classname></link>. |
| </para> |
| <para> |
| The enhancer task accepts a nested <literal>fileset</literal> tag to specify the |
| files that should be processed. You can specify <filename>.java</filename> or |
| <filename>.class</filename> files. If you do not specify any files, the task |
| will run on the classes listed in your <filename>persistence.xml</filename> or |
| <link linkend="openjpa.MetaDataFactory"><literal> |
| openjpa.MetaDataFactory</literal></link> property. |
| </para> |
| <para> |
| Following is an example of using the enhancer task in a <filename>build.xml |
| </filename> file: |
| </para> |
| <example id="ref_guide_integration_enhance_task"> |
| <title> |
| Invoking the Enhancer from Ant |
| </title> |
| <programlisting> |
| <target name="enhance"> |
| <!-- define the openjpac task; this can be done at the top of the --> |
| <!-- build.xml file, so it will be available for all targets --> |
| <taskdef name="openjpac" classname="org.apache.openjpa.ant.PCEnhancerTask"/> |
| |
| <!-- invoke enhancer on all .java files below the model directory --> |
| <openjpac> |
| <fileset dir="."> |
| <include name="**/model/*.java" /> |
| </fileset> |
| </openjpac> |
| </target> |
| </programlisting> |
| </example> |
| </section> |
| <section id="ref_guide_integration_appidtool"> |
| <title> |
| Application Identity Tool Ant Task |
| </title> |
| <indexterm zone="ref_guide_integration_enhance"> |
| <primary> |
| Ant |
| </primary> |
| <secondary> |
| application identity tool task |
| </secondary> |
| </indexterm> |
| <indexterm zone="ref_guide_integration_enhance"> |
| <primary> |
| application identity tool |
| </primary> |
| <secondary> |
| Ant task |
| </secondary> |
| </indexterm> |
| <para> |
| The application identity tool task allows you to invoke the application identity |
| tool directly from within the Ant build process. The task's parameters |
| correspond exactly to the long versions of the command-line arguments to the |
| <link linkend="ref_guide_pc_appid_appidtool"><classname> |
| org.apache.openjpa.enhance.ApplicationIdTool</classname></link>. |
| </para> |
| <para> |
| The application identity tool task accepts a nested <literal>fileset</literal> |
| tag to specify the files that should be processed. You can specify <filename> |
| .java</filename> or <filename>.class</filename> files. If you do not specify any |
| files, the task will run on the classes listed in your <filename>persistence.xml |
| </filename> file or <link linkend="openjpa.MetaDataFactory"><literal> |
| openjpa.MetaDataFactory</literal></link> property. |
| </para> |
| <para> |
| Following is an example of using the application identity tool task in a |
| <filename>build.xml</filename> file: |
| </para> |
| <example id="ref_guide_integration_appidtool_task"> |
| <title> |
| Invoking the Application Identity Tool from Ant |
| </title> |
| <programlisting> |
| <target name="appids"> |
| <!-- define the appidtool task; this can be done at the top of --> |
| <!-- the build.xml file, so it will be available for all targets --> |
| <taskdef name="appidtool" classname="org.apache.openjpa.ant.ApplicationIdToolTask"/> |
| |
| <!-- invoke tool on all .jdo files below the current directory --> |
| <appidtool> |
| <fileset dir="."> |
| <include name="**/model/*.java" /> |
| </fileset> |
| <codeformat spaceBeforeParen="true" braceOnSameLine="false"/> |
| </appidtool> |
| </target> |
| </programlisting> |
| </example> |
| </section> |
| <section id="ref_guide_integration_mappingtool"> |
| <title> |
| Mapping Tool Ant Task |
| </title> |
| <indexterm zone="ref_guide_integration_mappingtool"> |
| <primary> |
| Ant |
| </primary> |
| <secondary> |
| mapping tool task |
| </secondary> |
| </indexterm> |
| <indexterm zone="ref_guide_integration_mappingtool"> |
| <primary> |
| mapping tool |
| </primary> |
| <secondary> |
| Ant task |
| </secondary> |
| </indexterm> |
| <para> |
| The mapping tool task allows you to directly invoke the mapping tool from within |
| the Ant build process. It is useful for making sure that the database schema and |
| object-relational mapping data is always synchronized with your persistent class |
| definitions, without needing to remember to invoke the mapping tool manually. |
| The task's parameters correspond exactly to the long versions of the |
| command-line arguments to the <link linkend="ref_guide_mapping_mappingtool"> |
| <classname>org.apache.openjpa.jdbc.meta.MappingTool</classname></link>. |
| </para> |
| <para> |
| The mapping tool task accepts a nested <literal>fileset</literal> tag to specify |
| the files that should be processed. You can specify <filename>.java</filename> |
| or <filename>.class</filename> files. If you do not specify any files, the task |
| will run on the classes listed in your <filename>persistence.xml</filename> file |
| or <link linkend="openjpa.MetaDataFactory"><literal> |
| openjpa.MetaDataFactory</literal></link> property. |
| </para> |
| <para> |
| Following is an example of a <filename>build.xml</filename> target that invokes |
| the mapping tool: |
| </para> |
| <example id="ref_guide_integration_mappingtool_task"> |
| <title> |
| Invoking the Mapping Tool from Ant |
| </title> |
| <programlisting> |
| <target name="refresh"> |
| <!-- define the mappingtool task; this can be done at the top of --> |
| <!-- the build.xml file, so it will be available for all targets --> |
| <taskdef name="mappingtool" classname="org.apache.openjpa.jdbc.ant.MappingToolTask"/> |
| |
| <!-- add the schema components for all .jdo files below the --> |
| <!-- current directory --> |
| <mappingtool action="buildSchema"> |
| <fileset dir="."> |
| <include name="**/*.jdo" /> |
| </fileset> |
| </mappingtool> |
| </target> |
| </programlisting> |
| </example> |
| </section> |
| <section id="ref_guide_integration_revmappingtool"> |
| <title> |
| Reverse Mapping Tool Ant Task |
| </title> |
| <indexterm zone="ref_guide_integration_revmappingtool"> |
| <primary> |
| Ant |
| </primary> |
| <secondary> |
| reverse mapping tool task |
| </secondary> |
| </indexterm> |
| <indexterm zone="ref_guide_integration_revmappingtool"> |
| <primary> |
| reverse mapping tool |
| </primary> |
| <secondary> |
| Ant task |
| </secondary> |
| </indexterm> |
| <para> |
| The reverse mapping tool task allows you to directly invoke the reverse mapping |
| tool from within Ant. While many users will only run the reverse mapping process |
| once, others will make it part of their build process. The task's parameters |
| correspond exactly to the long versions of the command-line arguments to the |
| <link linkend="ref_guide_pc_reverse_reversemappingtool"><classname> |
| org.apache.openjpa.jdbc.meta.ReverseMappingTool</classname></link>. |
| </para> |
| <para> |
| Following is an example of a <filename>build.xml</filename> target that invokes |
| the reverse mapping tool: |
| </para> |
| <example id="ref_guide_integration_revmappingtool_task"> |
| <title> |
| Invoking the Reverse Mapping Tool from Ant |
| </title> |
| <programlisting> |
| <target name="reversemap"> |
| <!-- define the reversemappingtool task; this can be done at the top of --> |
| <!-- the build.xml file, so it will be available for all targets --> |
| <taskdef name="reversemappingtool" |
| classname="org.apache.openjpa.jdbc.ant.ReverseMappingToolTask"/> |
| |
| <!-- reverse map the entire database --> |
| <reversemappingtool package="com.xyz.model" directory="${basedir}/src" |
| customizerProperties="${basedir}/conf/reverse.properties"> |
| <codeformat tabSpaces="4" spaceBeforeParen="true" braceOnSameLine="false"/> |
| </reversemappingtool> |
| </target> |
| </programlisting> |
| </example> |
| </section> |
| <section id="ref_guide_integration_schematool"> |
| <title> |
| Schema Tool Ant Task |
| </title> |
| <indexterm zone="ref_guide_integration_schematool"> |
| <primary> |
| Ant |
| </primary> |
| <secondary> |
| schema tool task |
| </secondary> |
| </indexterm> |
| <indexterm zone="ref_guide_integration_schematool"> |
| <primary> |
| schema tool |
| </primary> |
| <secondary> |
| Ant task |
| </secondary> |
| </indexterm> |
| <para> |
| The schema tool task allows you to directly invoke the schema tool from within |
| the Ant build process. The task's parameters correspond exactly to the long |
| versions of the command-line arguments to the |
| <link linkend="ref_guide_schema_schematool"><classname> |
| org.apache.openjpa.jdbc.schema.SchemaTool</classname></link>. |
| </para> |
| <para> |
| Following is an example of a <filename>build.xml</filename> target that invokes |
| the schema tool: |
| </para> |
| <example id="ref_guide_integration_schematool_task"> |
| <title> |
| Invoking the Schema Tool from Ant |
| </title> |
| <programlisting> |
| <target name="schema"> |
| <!-- define the schematool task; this can be done at the top of --> |
| <!-- the build.xml file, so it will be available for all targets --> |
| <taskdef name="schematool" classname="org.apache.openjpa.jdbc.ant.SchemaToolTask"/> |
| |
| <!-- add the schema components for all .schema files below the --> |
| <!-- current directory --> |
| <schematool action="add"> |
| <fileset dir="."> |
| <include name="**/*.schema" /> |
| </fileset> |
| </schematool> |
| </target> |
| </programlisting> |
| </example> |
| </section> |
| </section> |
| </chapter> |