openjpa-project/src/doc/manual/ref_guide_integration.xml - openjpa - Git at Google

 <?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://ant.apache.org/"> http://ant.apache.org/
 </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="../../apidocs/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 &lt;config&gt; Ant Tag
                 </title>
 <programlisting>
 &lt;mappingtool&gt;
   &lt;fileset dir="${basedir}"&gt;
     &lt;include name="**/model/*.java" /&gt;
   &lt;/fileset&gt;
   &lt;config connectionUserName="scott" connectionPassword="tiger"
     connectionURL="jdbc:oracle:thin:@saturn:1521:solarsid"
     connectionDriverName="oracle.jdbc.driver.OracleDriver" /&gt;
 &lt;/mappingtool&gt;
 </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 &lt;config&gt; Tag
                 </title>
 <programlisting>
 &lt;mappingtool&gt;
   &lt;fileset dir="${basedir}"&gt;
     &lt;include name="**/model/*.java"/&gt;
   &lt;/fileset&gt;
   &lt;config properties="openjpa-dev.xml"/&gt;
 &lt;/mappingtool&gt;
 </programlisting>
             </example>
             <example id="ref_guide_integration_propsfile">
                 <title>
                     Using the PropertiesFile Attribute of the &lt;config&gt; Tag
                 </title>
 <programlisting>
 &lt;mappingtool&gt;
   &lt;fileset dir="${basedir}"&gt;
     &lt;include name="**/model/*.java"/&gt;
   &lt;/fileset&gt;
   &lt;config propertiesFile="../conf/openjpa-dev.xml"/&gt;
 &lt;/mappingtool&gt;
 </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 &lt;classpath&gt; Ant Tag
                 </title>
 <programlisting>
 &lt;openjpac&gt;
   &lt;fileset dir="${basedir}/source"&gt;
     &lt;include name="**/model/*.java" /&gt;
   &lt;/fileset&gt;
   &lt;classpath&gt;
     &lt;pathelement location="${basedir}/classes"/&gt;
     &lt;pathelement location="${basedir}/source"/&gt;
     &lt;pathelement path="${java.class.path}"/&gt;
   &lt;/classpath&gt;
 &lt;/openjpac&gt;
 </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 &lt;codeformat&gt; Ant Tag
                 </title>
 <programlisting>
 &lt;reversemappingtool package="com.xyz.jdo" directory="${basedir}/src"&gt;
   &lt;codeformat tabSpaces="4" spaceBeforeParen="true" braceOnSameLine="false"/&gt;
 &lt;/reversemappingtool&gt;
 </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. You must, however, supply the
 classpath you wish the enhancer to run with. This classpath must include, at
 minimum, the openjpa jar(s), persistence.xml and the target classes.
             </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>

 &lt;target name="enhance"&gt;
     &lt;!-- Define the classpath to include the necessary files. --&gt;
     &lt;!-- ex. openjpa jars, persistence.xml, orm.xml, and target classes  --&gt;
     &lt;path id="jpa.enhancement.classpath"&gt;
         &lt;!-- Assuming persistence.xml/orm.xml are in resources/META-INF --&gt;
         &lt;pathelement location="resources/" /&gt;

         &lt;!-- Location of the .class files --&gt;
         &lt;pathelement location="bin/" /&gt;

         &lt;!-- Add the openjpa jars --&gt;
         &lt;fileset dir="."&gt;
             &lt;include name="**/lib/*.jar" /&gt;
         &lt;/fileset&gt;
     &lt;/path&gt;


     &lt;!-- define the openjpac task; this can be done at the top of the --&gt;
     &lt;!-- build.xml file, so it will be available for all targets --&gt;
     &lt;taskdef name="openjpac" classname="org.apache.openjpa.ant.PCEnhancerTask" classpathref="jpa.enhancement.classpath" /&gt;

     &lt;!-- invoke enhancer on all .class files below the model directory --&gt;
     &lt;openjpac&gt;
         &lt;classpath refid="jpa.enhancement.classpath" /&gt;
         &lt;fileset dir="."&gt;
             &lt;include name="**/model/*.class" /&gt;
         &lt;/fileset&gt;
     &lt;/openjpac&gt;
     &lt;echo message="Enhancement complete" /&gt;
 &lt;/target&gt;
 </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>
 &lt;target name="appids"&gt;
   &lt;!-- define the appidtool task; this can be done at the top of     --&gt;
   &lt;!-- the build.xml file, so it will be available for all targets   --&gt;
   &lt;taskdef name="appidtool" classname="org.apache.openjpa.ant.ApplicationIdToolTask"/&gt;

   &lt;!-- invoke tool on all .jdo files below the current directory     --&gt;
   &lt;appidtool&gt;
     &lt;fileset dir="."&gt;
       &lt;include name="**/model/*.java" /&gt;
     &lt;/fileset&gt;
     &lt;codeformat spaceBeforeParen="true" braceOnSameLine="false"/&gt;
   &lt;/appidtool&gt;
 &lt;/target&gt;
 </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>
 &lt;target name="refresh"&gt;
   &lt;!-- define the mappingtool task; this can be done at the top of --&gt;
   &lt;!-- the build.xml file, so it will be available for all targets --&gt;
   &lt;taskdef name="mappingtool" classname="org.apache.openjpa.jdbc.ant.MappingToolTask"/&gt;

   &lt;!-- add the schema components for all .jdo files below the      --&gt;
   &lt;!-- current directory                                           --&gt;
   &lt;mappingtool action="buildSchema"&gt;
     &lt;fileset dir="."&gt;
       &lt;include name="**/*.jdo" /&gt;
     &lt;/fileset&gt;
   &lt;/mappingtool&gt;
 &lt;/target&gt;
 </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>
 &lt;target name="reversemap"&gt;
   &lt;!-- define the reversemappingtool task; this can be done at the top of --&gt;
   &lt;!-- the build.xml file, so it will be available for all targets        --&gt;
   &lt;taskdef name="reversemappingtool"
     classname="org.apache.openjpa.jdbc.ant.ReverseMappingToolTask"/&gt;

   &lt;!-- reverse map the entire database --&gt;
   &lt;reversemappingtool package="com.xyz.model" directory="${basedir}/src"
     customizerProperties="${basedir}/conf/reverse.properties"&gt;
     &lt;codeformat tabSpaces="4" spaceBeforeParen="true" braceOnSameLine="false"/&gt;
   &lt;/reversemappingtool&gt;
 &lt;/target&gt;
 </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>
 &lt;target name="schema"&gt;
   &lt;!-- define the schematool task; this can be done at the top of  --&gt;
   &lt;!-- the build.xml file, so it will be available for all targets --&gt;
   &lt;taskdef name="schematool" classname="org.apache.openjpa.jdbc.ant.SchemaToolTask"/&gt;

   &lt;!-- add the schema components for all .schema files below the   --&gt;
   &lt;!-- current directory                                           --&gt;
   &lt;schematool action="add"&gt;
     &lt;fileset dir="."&gt;
       &lt;include name="**/*.schema" /&gt;
     &lt;/fileset&gt;
   &lt;/schematool&gt;
 &lt;/target&gt;
 </programlisting>
             </example>
         </section>
     </section>

     <section id="ref_guide_integration_dbcp">
         <title>
             Apache Commons DBCP
         </title>
         <indexterm zone="ref_guide_integration_dbcp">
             <primary>
                 DBCP
             </primary>
         </indexterm>
         <para>
 OpenJPA does not provide its own JDBC connection pooling, as this should already be supplied to applications running in a Java EE application server in container managed mode.  For Java SE or applications running in application managed mode, the OpenJPA aggregate <literal>openjpa-all.jar</literal> artifact and the binary assembly contains copies of <ulink url="http://commons.apache.org/dbcp/">Apache Commons DBCP</ulink>, which provides a robust connection pooling implementation.
         </para>

         <section id="ref_guide_integration_dbcp_conf">
             <title>
                 Apache Commons DBCP Configuration Options
             </title>
             <indexterm>
                 <primary>
                     DBCP
                 </primary>
                 <secondary>
                     configuration options
                 </secondary>
             </indexterm>
             <para>
 The <link linkend="ref_guide_dbsetup_thirdparty">JDBC DataSource configuration options</link> that we will need to modify in order to use Apache Commons DBCP for connection pooling are:
 <programlisting>
     connectionDriverName="org.apache.commons.dbcp.BasicDataSource"
     connectionProperties="DriverClassName=&lt;prior connectionDriverName&gt;, ..."
 </programlisting>
 Additional Commons DBCP arguments can be provided in the connectionProperties value, such as:
 <programlisting>
     MaxTotal=10,MaxIdle=5,MinIdle=2,MaxWait=60000
 </programlisting>
 Please visit the Commons DBCP website for the entire list of <ulink url="http://commons.apache.org/dbcp/configuration.html">configuration options</ulink> and explanations.
             </para>

             <example id="ref_guide_integration_dbcp_derby">
                 <title>
                     Using Commons DBCP with Apache Derby
                 </title>
 For example, to use Commons DBCP with an Apache Derby database server, we would need to provide the following settings, as either settings in the persistence.xml or as system environment overrides:
 <programlisting>
 &lt;property name="openjpa.ConnectionDriverName" value="org.apache.commons.dbcp.BasicDataSource"/&gt;
 &lt;property name="openjpa.ConnectionProperties" value="DriverClassName=org.apache.derby.jdbc.EmbeddedDriver, Url=jdbc:derby://localhost:1527/openjpa, Username=uid, Password=pwd"/&gt;
 </programlisting>
 Notice that we supplied Username and Password settings, which are required by Commons DBCP for connecting to a database over the network, but can be dummy values if database security is not enabled.
             </example>
         </section>
     </section>
 </chapter>
	<?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://ant.apache.org/"> http://ant.apache.org/
	</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="../../apidocs/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. You must, however, supply the
	classpath you wish the enhancer to run with. This classpath must include, at
	minimum, the openjpa jar(s), persistence.xml and the target classes.
	</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 classpath to include the necessary files. -->
	<!-- ex. openjpa jars, persistence.xml, orm.xml, and target classes -->
	<path id="jpa.enhancement.classpath">
	<!-- Assuming persistence.xml/orm.xml are in resources/META-INF -->
	<pathelement location="resources/" />

	<!-- Location of the .class files -->
	<pathelement location="bin/" />

	<!-- Add the openjpa jars -->
	<fileset dir=".">
	<include name="*/lib/.jar" />
	</fileset>
	</path>


	<!-- 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" classpathref="jpa.enhancement.classpath" />

	<!-- invoke enhancer on all .class files below the model directory -->
	<openjpac>
	<classpath refid="jpa.enhancement.classpath" />
	<fileset dir=".">
	<include name="*/model/.class" />
	</fileset>
	</openjpac>
	<echo message="Enhancement complete" />
	</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>

	<section id="ref_guide_integration_dbcp">
	<title>
	Apache Commons DBCP
	</title>
	<indexterm zone="ref_guide_integration_dbcp">
	<primary>
	DBCP
	</primary>
	</indexterm>
	<para>
	OpenJPA does not provide its own JDBC connection pooling, as this should already be supplied to applications running in a Java EE application server in container managed mode. For Java SE or applications running in application managed mode, the OpenJPA aggregate <literal>openjpa-all.jar</literal> artifact and the binary assembly contains copies of <ulink url="http://commons.apache.org/dbcp/">Apache Commons DBCP</ulink>, which provides a robust connection pooling implementation.
	</para>

	<section id="ref_guide_integration_dbcp_conf">
	<title>
	Apache Commons DBCP Configuration Options
	</title>
	<indexterm>
	<primary>
	DBCP
	</primary>
	<secondary>
	configuration options
	</secondary>
	</indexterm>
	<para>
	The <link linkend="ref_guide_dbsetup_thirdparty">JDBC DataSource configuration options</link> that we will need to modify in order to use Apache Commons DBCP for connection pooling are:
	<programlisting>
	connectionDriverName="org.apache.commons.dbcp.BasicDataSource"
	connectionProperties="DriverClassName=<prior connectionDriverName>, ..."
	</programlisting>
	Additional Commons DBCP arguments can be provided in the connectionProperties value, such as:
	<programlisting>
	MaxTotal=10,MaxIdle=5,MinIdle=2,MaxWait=60000
	</programlisting>
	Please visit the Commons DBCP website for the entire list of <ulink url="http://commons.apache.org/dbcp/configuration.html">configuration options</ulink> and explanations.
	</para>

	<example id="ref_guide_integration_dbcp_derby">
	<title>
	Using Commons DBCP with Apache Derby
	</title>
	For example, to use Commons DBCP with an Apache Derby database server, we would need to provide the following settings, as either settings in the persistence.xml or as system environment overrides:
	<programlisting>
	<property name="openjpa.ConnectionDriverName" value="org.apache.commons.dbcp.BasicDataSource"/>
	<property name="openjpa.ConnectionProperties" value="DriverClassName=org.apache.derby.jdbc.EmbeddedDriver, Url=jdbc:derby://localhost:1527/openjpa, Username=uid, Password=pwd"/>
	</programlisting>
	Notice that we supplied Username and Password settings, which are required by Commons DBCP for connecting to a database over the network, but can be dummy values if database security is not enabled.
	</example>
	</section>
	</section>
	</chapter>