Added: websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_integration.html ============================================================================== --- websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_integration.html (added) +++ websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_integration.html Fri Jan 6 19:19:20 2017 @@ -0,0 +1,447 @@ +<html><head> + <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> + <title>Chapter 14. Third Party Integration</title><base href="display"><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="manual.html" title="Apache OpenJPA 2.4 User's Guide"><link rel="up" href="ref_guide.html" title="Part 3. Reference Guide"><link rel="prev" href="ch29s04.html" title="4. Configuration Properties"><link rel="next" href="ref_guide_integration_dbcp.html" title="2. Apache Commons DBCP"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 14. + Third Party Integration + </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch29s04.html">Prev</a> </td><th width="60%" align="center">Part 3. Reference Guide</th><td width="20%" align="right"> <a accesskey="n" href="ref_guide_integration_dbcp.html">Next</a></td></tr></table><hr></div><div class="chapter" id="ref_guide_integration"><div class="titlepage"><div><div><h2 class="title">Chapter 14. + Third Party Integration + </h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="ref_guide_integration.html#ref_guide_integration_ant">1. + Apache Ant + </a></span></dt><dd><dl><dt><span class="section"><a href="ref_guide_integration.html#ref_guide_integration_conf">1.1. + Common Ant Configuration Options + </a></span></dt><dt><span class="section"><a href="ref_guide_integration.html#ref_guide_integration_enhance">1.2. + Enhancer Ant Task + </a></span></dt><dt><span class="section"><a href="ref_guide_integration.html#ref_guide_integration_appidtool">1.3. + Application Identity Tool Ant Task + </a></span></dt><dt><span class="section"><a href="ref_guide_integration.html#ref_guide_integration_mappingtool">1.4. + Mapping Tool Ant Task + </a></span></dt><dt><span class="section"><a href="ref_guide_integration.html#ref_guide_integration_revmappingtool">1.5. + Reverse Mapping Tool Ant Task + </a></span></dt><dt><span class="section"><a href="ref_guide_integration.html#ref_guide_integration_schematool">1.6. + Schema Tool Ant Task + </a></span></dt></dl></dd><dt><span class="section"><a href="ref_guide_integration_dbcp.html">2. + Apache Commons DBCP + </a></span></dt><dd><dl><dt><span class="section"><a href="ref_guide_integration_dbcp.html#ref_guide_integration_dbcp_conf">2.1. + Apache Commons DBCP Configuration Options + </a></span></dt></dl></dd></dl></div> + + <p> +OpenJPA provides a number of mechanisms for integrating with third-party tools. +The following chapter will illustrate these integration features. + </p> + <div class="section" id="ref_guide_integration_ant"><div class="titlepage"><div><div><h2 class="title" style="clear: both">1. + Apache Ant + </h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="ref_guide_integration.html#ref_guide_integration_conf">1.1. + Common Ant Configuration Options + </a></span></dt><dt><span class="section"><a href="ref_guide_integration.html#ref_guide_integration_enhance">1.2. + Enhancer Ant Task + </a></span></dt><dt><span class="section"><a href="ref_guide_integration.html#ref_guide_integration_appidtool">1.3. + Application Identity Tool Ant Task + </a></span></dt><dt><span class="section"><a href="ref_guide_integration.html#ref_guide_integration_mappingtool">1.4. + Mapping Tool Ant Task + </a></span></dt><dt><span class="section"><a href="ref_guide_integration.html#ref_guide_integration_revmappingtool">1.5. + Reverse Mapping Tool Ant Task + </a></span></dt><dt><span class="section"><a href="ref_guide_integration.html#ref_guide_integration_schematool">1.6. + Schema Tool Ant Task + </a></span></dt></dl></div> + + <a class="indexterm" name="d5e17101"></a> + <p> +Ant is a very popular tool for building Java projects. It is similar to the +<code class="literal">make</code> 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 <a class="ulink" href="http://ant.apache.org/"; target="_top"> http://ant.apache.org/ +</a>. 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 <code class="filename">build.xml</code> files. + </p> + <p> +OpenJPA provides pre-built Ant task definitions for all bundled tools: + </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p> +<a class="link" href="ref_guide_integration.html#ref_guide_integration_enhance" title="1.2. Enhancer Ant Task">Enhancer Task</a> + </p> + </li><li class="listitem"> + <p> +<a class="link" href="ref_guide_integration.html#ref_guide_integration_appidtool" title="1.3. Application Identity Tool Ant Task">Application Identity Tool Task +</a> + </p> + </li><li class="listitem"> + <p> +<a class="link" href="ref_guide_integration.html#ref_guide_integration_mappingtool" title="1.4. Mapping Tool Ant Task">Mapping Tool Task</a> + </p> + </li><li class="listitem"> + <p> +<a class="link" href="ref_guide_integration.html#ref_guide_integration_revmappingtool" title="1.5. Reverse Mapping Tool Ant Task">Reverse Mapping Tool Task +</a> + </p> + </li><li class="listitem"> + <p> +<a class="link" href="ref_guide_integration.html#ref_guide_integration_schematool" title="1.6. Schema Tool Ant Task">Schema Tool Task</a> + </p> + </li></ul></div> + <p> +The source code for all the Ant tasks is provided with the distribution under +the <code class="filename">src</code> directory. This allows you to customize various +aspects of the Ant tasks in order to better integrate into your development +environment. + </p> + <div class="section" id="ref_guide_integration_conf"><div class="titlepage"><div><div><h3 class="title">1.1. + Common Ant Configuration Options + </h3></div></div></div> + + <a class="indexterm" name="d5e17128"></a> + <p> +All OpenJPA tasks accept a nested <code class="literal">config</code> element, which +defines the configuration environment in which the specified task will run. The +attributes for the <code class="literal">config</code> tag are defined by the +<a class="ulink" href="../javadoc/org/apache/openjpa/jdbc/conf/JDBCConfiguration.html" target="_top"> +<code class="classname">JDBCConfiguration</code></a> bean methods. Note that +excluding the <code class="literal">config</code> element will cause the Ant task to use +the default system configuration mechanism, such as the configuration defined in +the <code class="filename">org.apache.openjpa.xml</code> file. + </p> + <p> +Following is an example of how to use the nested <code class="literal">config</code> tag +in a <code class="filename">build.xml</code> file: + </p> + <div class="example" id="ref_guide_integration_conf_config"><p class="title"><b>Example 14.1. + Using the <config> Ant Tag + </b></p><div class="example-contents"> + +<pre class="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> +</pre> + </div></div><br class="example-break"> + <p> +It is also possible to specify a <code class="literal">properties</code> or <code class="literal"> +propertiesFile</code> attribute on the <code class="literal">config</code> tag, which +will be used to locate a properties resource or file. The resource will be +loaded relative to the current CLASSPATH. + </p> + <div class="example" id="ref_guide_integration_props"><p class="title"><b>Example 14.2. + Using the Properties Attribute of the <config> Tag + </b></p><div class="example-contents"> + +<pre class="programlisting"> +<mappingtool> + <fileset dir="${basedir}"> + <include name="**/model/*.java"/> + </fileset> + <config properties="openjpa-dev.xml"/> +</mappingtool> +</pre> + </div></div><br class="example-break"> + <div class="example" id="ref_guide_integration_propsfile"><p class="title"><b>Example 14.3. + Using the PropertiesFile Attribute of the <config> Tag + </b></p><div class="example-contents"> + +<pre class="programlisting"> +<mappingtool> + <fileset dir="${basedir}"> + <include name="**/model/*.java"/> + </fileset> + <config propertiesFile="../conf/openjpa-dev.xml"/> +</mappingtool> +</pre> + </div></div><br class="example-break"> + <p> +Tasks also accept a nested <code class="literal">classpath</code> element, which you can +use in place of the default classpath. The <code class="literal">classpath</code> argument +behaves the same as it does for Ant's standard <code class="literal">javac</code> 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 <code class="literal">classpath</code> element that includes +the target class directory needs to be included so the enhancer and mapping tool +can locate the relevant classes. + </p> + <p> +Following is an example of using a <code class="literal">classpath</code> tag: + </p> + <div class="example" id="ref_guide_integration_conf_classpath"><p class="title"><b>Example 14.4. + Using the <classpath> Ant Tag + </b></p><div class="example-contents"> + +<pre class="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> +</pre> + </div></div><br class="example-break"> + <p> +Finally, tasks that invoke code-generation tools like the application identity +tool and reverse mapping tool accept a nested <code class="literal">codeformat</code> +element. See the code formatting documentation in +<a class="xref" href="ref_guide_conf_devtools.html#ref_guide_conf_devtools_format" title="3.1. Code Formatting">Section 3.1, “ + Code Formatting + ”</a> for a list of code +formatting attributes. + </p> + <div class="example" id="ref_guide_integration_conf_codeformat"><p class="title"><b>Example 14.5. + Using the <codeformat> Ant Tag + </b></p><div class="example-contents"> + +<pre class="programlisting"> +<reversemappingtool package="com.xyz.jdo" directory="${basedir}/src"> + <codeformat tabSpaces="4" spaceBeforeParen="true" braceOnSameLine="false"/> +</reversemappingtool> +</pre> + </div></div><br class="example-break"> + </div> + <div class="section" id="ref_guide_integration_enhance"><div class="titlepage"><div><div><h3 class="title">1.2. + Enhancer Ant Task + </h3></div></div></div> + + <a class="indexterm" name="d5e17172"></a> + <a class="indexterm" name="d5e17175"></a> + <p> +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 +<a class="link" href="ref_guide_pc_enhance.html" title="2. Enhancement"><code class="classname"> +org.apache.openjpa.enhance.PCEnhancer</code></a>. + </p> + <p> +The enhancer task accepts a nested <code class="literal">fileset</code> tag to specify the +files that should be processed. You can specify <code class="filename">.java</code> or +<code class="filename">.class</code> files. If you do not specify any files, the task +will run on the classes listed in your <code class="filename">persistence.xml</code> or +<a class="link" href="ref_guide_conf_openjpa.html#openjpa.MetaDataFactory" title="5.48. openjpa.MetaDataFactory"><code class="literal"> +openjpa.MetaDataFactory</code></a> 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. + </p> + <p> +Following is an example of using the enhancer task in a <code class="filename">build.xml +</code> file: + </p> + <div class="example" id="ref_guide_integration_enhance_task"><p class="title"><b>Example 14.6. + Invoking the Enhancer from Ant + </b></p><div class="example-contents"> + +<pre class="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> +</pre> + </div></div><br class="example-break"> + </div> + <div class="section" id="ref_guide_integration_appidtool"><div class="titlepage"><div><div><h3 class="title">1.3. + Application Identity Tool Ant Task + </h3></div></div></div> + + <a class="indexterm" name="d5e17195"></a> + <a class="indexterm" name="d5e17198"></a> + <p> +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 +<a class="link" href="ref_guide_pc_oid.html#ref_guide_pc_appid_appidtool" title="Example 5.8. Using the Application Identity Tool"><code class="classname"> +org.apache.openjpa.enhance.ApplicationIdTool</code></a>. + </p> + <p> +The application identity tool task accepts a nested <code class="literal">fileset</code> +tag to specify the files that should be processed. You can specify <code class="filename"> +.java</code> or <code class="filename">.class</code> files. If you do not specify any +files, the task will run on the classes listed in your <code class="filename">persistence.xml +</code> file or <a class="link" href="ref_guide_conf_openjpa.html#openjpa.MetaDataFactory" title="5.48. openjpa.MetaDataFactory"><code class="literal"> +openjpa.MetaDataFactory</code></a> property. + </p> + <p> +Following is an example of using the application identity tool task in a +<code class="filename">build.xml</code> file: + </p> + <div class="example" id="ref_guide_integration_appidtool_task"><p class="title"><b>Example 14.7. + Invoking the Application Identity Tool from Ant + </b></p><div class="example-contents"> + +<pre class="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> +</pre> + </div></div><br class="example-break"> + </div> + <div class="section" id="ref_guide_integration_mappingtool"><div class="titlepage"><div><div><h3 class="title">1.4. + Mapping Tool Ant Task + </h3></div></div></div> + + <a class="indexterm" name="d5e17218"></a> + <a class="indexterm" name="d5e17221"></a> + <p> +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 <a class="link" href="ref_guide_mapping.html#ref_guide_mapping_mappingtool" title="1. Forward Mapping"> +<code class="classname">org.apache.openjpa.jdbc.meta.MappingTool</code></a>. + </p> + <p> +The mapping tool task accepts a nested <code class="literal">fileset</code> tag to specify +the files that should be processed. You can specify <code class="filename">.java</code> +or <code class="filename">.class</code> files. If you do not specify any files, the task +will run on the classes listed in your <code class="filename">persistence.xml</code> file +or <a class="link" href="ref_guide_conf_openjpa.html#openjpa.MetaDataFactory" title="5.48. openjpa.MetaDataFactory"><code class="literal"> +openjpa.MetaDataFactory</code></a> property. + </p> + <p> +Following is an example of a <code class="filename">build.xml</code> target that invokes +the mapping tool: + </p> + <div class="example" id="ref_guide_integration_mappingtool_task"><p class="title"><b>Example 14.8. + Invoking the Mapping Tool from Ant + </b></p><div class="example-contents"> + +<pre class="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> +</pre> + </div></div><br class="example-break"> + </div> + <div class="section" id="ref_guide_integration_revmappingtool"><div class="titlepage"><div><div><h3 class="title">1.5. + Reverse Mapping Tool Ant Task + </h3></div></div></div> + + <a class="indexterm" name="d5e17241"></a> + <a class="indexterm" name="d5e17244"></a> + <p> +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 +<a class="link" href="ref_guide_pc_reverse.html#ref_guide_pc_reverse_reversemappingtool" title="Example 7.9. Using the Reverse Mapping Tool"><code class="classname"> +org.apache.openjpa.jdbc.meta.ReverseMappingTool</code></a>. + </p> + <p> +Following is an example of a <code class="filename">build.xml</code> target that invokes +the reverse mapping tool: + </p> + <div class="example" id="ref_guide_integration_revmappingtool_task"><p class="title"><b>Example 14.9. + Invoking the Reverse Mapping Tool from Ant + </b></p><div class="example-contents"> + +<pre class="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> +</pre> + </div></div><br class="example-break"> + </div> + <div class="section" id="ref_guide_integration_schematool"><div class="titlepage"><div><div><h3 class="title">1.6. + Schema Tool Ant Task + </h3></div></div></div> + + <a class="indexterm" name="d5e17257"></a> + <a class="indexterm" name="d5e17260"></a> + <p> +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 +<a class="link" href="ref_guide_schema_schematool.html" title="13. Schema Tool"><code class="classname"> +org.apache.openjpa.jdbc.schema.SchemaTool</code></a>. + </p> + <p> +Following is an example of a <code class="filename">build.xml</code> target that invokes +the schema tool: + </p> + <div class="example" id="ref_guide_integration_schematool_task"><p class="title"><b>Example 14.10. + Invoking the Schema Tool from Ant + </b></p><div class="example-contents"> + +<pre class="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> +</pre> + </div></div><br class="example-break"> + </div> + </div> + + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch29s04.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ref_guide.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ref_guide_integration_dbcp.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">4. Configuration Properties </td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top"> 2. + Apache Commons DBCP + </td></tr></table></div></body></html> \ No newline at end of file
Added: websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_integration_dbcp.html ============================================================================== --- websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_integration_dbcp.html (added) +++ websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_integration_dbcp.html Fri Jan 6 19:19:20 2017 @@ -0,0 +1,52 @@ +<html><head> + <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> + <title>2. Apache Commons DBCP</title><base href="display"><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="manual.html" title="Apache OpenJPA 2.4 User's Guide"><link rel="up" href="ref_guide_integration.html" title="Chapter 14. Third Party Integration"><link rel="prev" href="ref_guide_integration.html" title="Chapter 14. Third Party Integration"><link rel="next" href="ref_guide_optimization.html" title="Chapter 15. Optimization Guidelines"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">2. + Apache Commons DBCP + </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_integration.html">Prev</a> </td><th width="60%" align="center">Chapter 14. + Third Party Integration + </th><td width="20%" align="right"> <a accesskey="n" href="ref_guide_optimization.html">Next</a></td></tr></table><hr></div><div class="section" id="ref_guide_integration_dbcp"><div class="titlepage"><div><div><h2 class="title" style="clear: both">2. + Apache Commons DBCP + </h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="ref_guide_integration_dbcp.html#ref_guide_integration_dbcp_conf">2.1. + Apache Commons DBCP Configuration Options + </a></span></dt></dl></div> + + <a class="indexterm" name="d5e17273"></a> + <p> +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 <code class="literal">openjpa-all.jar</code> artifact and the binary assembly contains copies of <a class="ulink" href="http://commons.apache.org/dbcp/"; target="_top">Apache Commons DBCP</a>, which provides a robust connection pooling implementation. + </p> + + <div class="section" id="ref_guide_integration_dbcp_conf"><div class="titlepage"><div><div><h3 class="title">2.1. + Apache Commons DBCP Configuration Options + </h3></div></div></div> + + <a class="indexterm" name="d5e17280"></a> + <p> +The <a class="link" href="ref_guide_dbsetup_thirdparty.html" title="2. Using a Third-Party DataSource">JDBC DataSource configuration options</a> that we will need to modify in order to use Apache Commons DBCP for connection pooling are: +</p><pre class="programlisting"> + connectionDriverName="org.apache.commons.dbcp.BasicDataSource" + connectionProperties="DriverClassName=<prior connectionDriverName>, ..." +</pre><p> +Additional Commons DBCP arguments can be provided in the connectionProperties value, such as: +</p><pre class="programlisting"> + MaxActive=10,MaxIdle=5,MinIdle=2,MaxWait=60000 +</pre><p> +Please visit the Commons DBCP website for the entire list of <a class="ulink" href="http://commons.apache.org/dbcp/configuration.html"; target="_top">configuration options</a> and explanations. + </p> + + <div class="example" id="ref_guide_integration_dbcp_derby"><p class="title"><b>Example 14.11. + Using Commons DBCP with Apache Derby + </b></p><div class="example-contents"> + +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: +<pre class="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"/> +</pre> +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. + </div></div><br class="example-break"> + </div> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ref_guide_integration.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ref_guide_integration.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ref_guide_optimization.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 14. + Third Party Integration + </td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 15. + Optimization Guidelines + </td></tr></table></div></body></html> \ No newline at end of file Added: websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_intro.html ============================================================================== --- websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_intro.html (added) +++ websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_intro.html Fri Jan 6 19:19:20 2017 @@ -0,0 +1,36 @@ +<html><head> + <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> + <title>Chapter 1. Introduction</title><base href="display"><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="manual.html" title="Apache OpenJPA 2.4 User's Guide"><link rel="up" href="ref_guide.html" title="Part 3. Reference Guide"><link rel="prev" href="ref_guide.html" title="Part 3. Reference Guide"><link rel="next" href="ref_guide_conf.html" title="Chapter 2. Configuration"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 1. + Introduction + </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide.html">Prev</a> </td><th width="60%" align="center">Part 3. Reference Guide</th><td width="20%" align="right"> <a accesskey="n" href="ref_guide_conf.html">Next</a></td></tr></table><hr></div><div class="chapter" id="ref_guide_intro"><div class="titlepage"><div><div><h2 class="title">Chapter 1. + Introduction + </h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="ref_guide_intro.html#ref_guide_intro_audience">1. + Intended Audience + </a></span></dt></dl></div> + + <p> +OpenJPA is a JDBC-based implementation of the JPA standard. +This document is a reference for the configuration and use of OpenJPA. + </p> + <div class="section" id="ref_guide_intro_audience"><div class="titlepage"><div><div><h2 class="title" style="clear: both">1. + Intended Audience + </h2></div></div></div> + + <p> +This document is intended for OpenJPA developers. It +assumes strong knowledge of Java, familiarity with the eXtensible Markup +Language (XML), and an understanding of JPA. If you are not familiar with JPA, +please read the <a class="link" href="jpa_overview_intro.html" title="Chapter 1. Introduction">JPA Overview</a> before +proceeding. + + </p> + <p> +Certain sections of this guide cover advanced topics such as custom +object-relational mapping, enterprise integration, and using OpenJPA with +third-party tools. These sections assume prior experience with the relevant +subject. + </p> + </div> +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ref_guide.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ref_guide.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ref_guide_conf.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Part 3. Reference Guide </td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 2. + Configuration + </td></tr></table></div></body></html> \ No newline at end of file Added: websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_inverses.html ============================================================================== --- websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_inverses.html (added) +++ websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_inverses.html Fri Jan 6 19:19:20 2017 @@ -0,0 +1,114 @@ +<html><head> + <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> + <title>5. Managed Inverses</title><base href="display"><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="manual.html" title="Apache OpenJPA 2.4 User's Guide"><link rel="up" href="ref_guide_pc.html" title="Chapter 5. Persistent Classes"><link rel="prev" href="ref_guide_pc_oid.html" title="4. Object Identity"><link rel="next" href="ref_guide_pc_scos.html" title="6. Persistent Fields"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">5. + Managed Inverses + </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_pc_oid.html">Prev</a> </td><th width="60%" align="center">Chapter 5. + Persistent Classes + </th><td width="20%" align="right"> <a accesskey="n" href="ref_guide_pc_scos.html">Next</a></td></tr></table><hr></div><div class="section" id="ref_guide_inverses"><div class="titlepage"><div><div><h2 class="title" style="clear: both">5. + Managed Inverses + </h2></div></div></div> + + <a class="indexterm" name="d5e12471"></a> + <p> +Bidirectional relations are an essential part of data modeling. +<a class="xref" href="jpa_overview_mapping.html" title="Chapter 13. Mapping Metadata">Chapter 13, <i> + Mapping Metadata + </i></a> in the JPA Overview explains how to +use the <code class="literal">mappedBy</code> annotation attribute to form bidirectional +relations that also share datastore storage in JPA. + </p> + <p> +OpenJPA also allows you to define purely logical bidirectional relations. The +<a class="ulink" href="../javadoc/org/apache/openjpa/persistence/InverseLogical.html" target="_top"> +<code class="classname">org.apache.openjpa.persistence.InverseLogical</code></a> +annotation names a logical inverse in JPA metadata. + </p> + <div class="example" id="ref_guide_inverses_logicalex"><p class="title"><b>Example 5.9. + Specifying Logical Inverses + </b></p><div class="example-contents"> + + <p> +<code class="literal">Magazine.coverPhoto</code> and <code class="literal">Photograph.mag</code> are +each mapped to different foreign keys in their respective tables, but form a +logical bidirectional relation. Only one of the fields needs to declare the +other as its logical inverse, though it is not an error to set the logical +inverse of both fields. + </p> +<pre class="programlisting"> +import org.apache.openjpa.persistence.*; + +@Entity +public class Magazine { + + @OneToOne + private Photograph coverPhoto; + + ... +} + +@Entity +public class Photograph { + + @OneToOne + @InverseLogical("coverPhoto") + private Magazine mag; + + ... +} +</pre> + </div></div><br class="example-break"> + <p> +Java does not provide any native facilities to ensure that both sides of a +bidirectional relation remain consistent. Whenever you set one side of the +relation, you must manually set the other side as well. + </p> + <p> +By default, OpenJPA behaves the same way. OpenJPA does not automatically +propagate changes from one field in bidirectional relation to the other field. +This is in keeping with the philosophy of transparency, and also provides higher +performance, as OpenJPA does not need to analyze your object graph to correct +inconsistent relations. + </p> + <p> + <a class="indexterm" name="d5e12489"></a> +If convenience is more important to you than strict transparency, however, you +can enable inverse relation management in OpenJPA. Set the +<a class="link" href="ref_guide_conf_openjpa.html#openjpa.InverseManager" title="5.41. openjpa.InverseManager"><code class="classname">openjpa.InverseManager +</code></a> plugin property to <code class="literal">true</code> for standard +management. Under this setting, OpenJPA detects changes to either side of a +bidirectional relation (logical or physical), and automatically sets the other +side appropriately on flush. + </p> + <div class="example" id="ref_guide_inversesex"><p class="title"><b>Example 5.10. + Enabling Managed Inverses + </b></p><div class="example-contents"> + +<pre class="programlisting"> +<property name="openjpa.InverseManager" value="true"/> +</pre> + </div></div><br class="example-break"> + <p> +The inverse manager has options to log a warning or throw an exception when it +detects an inconsistent bidirectional relation, rather than correcting it. To +use these modes, set the manager's <code class="literal">Action</code> property to +<code class="literal">warn</code> or <code class="literal">exception</code>, respectively. + </p> + <p> +By default, OpenJPA excludes <a class="link" href="ref_guide_pc_scos.html#ref_guide_pc_scos_proxy_lrs" title="6.4.2. Large Result Set Proxies"> large +result set fields</a> from management. You can force large result set fields +to be included by setting the <code class="literal">ManageLRS</code> plugin property to +<code class="literal">true</code>. + </p> + <div class="example" id="ref_guide_inverses_logex"><p class="title"><b>Example 5.11. + Log Inconsistencies + </b></p><div class="example-contents"> + +<pre class="programlisting"> +<property name="openjpa.InverseManager" value="true(Action=warn)"/> +</pre> + </div></div><br class="example-break"> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ref_guide_pc_oid.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ref_guide_pc.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ref_guide_pc_scos.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">4. + Object Identity + </td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top"> 6. + Persistent Fields + </td></tr></table></div></body></html> \ No newline at end of file Added: websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_locking.html ============================================================================== --- websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_locking.html (added) +++ websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_locking.html Fri Jan 6 19:19:20 2017 @@ -0,0 +1,403 @@ +<html><head> + <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> + <title>3. Object Locking</title><base href="display"><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="manual.html" title="Apache OpenJPA 2.4 User's Guide"><link rel="up" href="ref_guide_runtime.html" title="Chapter 9. Runtime Extensions"><link rel="prev" href="ref_guide_runtime_jpa.html" title="2. JPA Extensions"><link rel="next" href="ref_guide_savepoints.html" title="4. Savepoints"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">3. + Object Locking + </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_runtime_jpa.html">Prev</a> </td><th width="60%" align="center">Chapter 9. + Runtime Extensions + </th><td width="20%" align="right"> <a accesskey="n" href="ref_guide_savepoints.html">Next</a></td></tr></table><hr></div><div class="section" id="ref_guide_locking"><div class="titlepage"><div><div><h2 class="title" style="clear: both">3. + Object Locking + </h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="ref_guide_locking.html#ref_guide_locking_default">3.1. + Configuring Default Locking + </a></span></dt><dt><span class="section"><a href="ref_guide_locking.html#ref_guide_locking_runtime">3.2. + Configuring Lock Levels at Runtime + </a></span></dt><dt><span class="section"><a href="ref_guide_locking.html#ref_guide_locking_apis">3.3. + Object Locking APIs + </a></span></dt><dt><span class="section"><a href="ref_guide_locking.html#ref_guide_locking_lockmgr">3.4. + Lock Manager + </a></span></dt><dt><span class="section"><a href="ref_guide_locking.html#ref_guide_locking_rules">3.5. + Rules for Locking Behavior + </a></span></dt><dt><span class="section"><a href="ref_guide_locking.html#ref_guide_locking_issues">3.6. + Known Issues and Limitations + </a></span></dt></dl></div> + + <a class="indexterm" name="d5e15547"></a> + <p> +Controlling how and when objects are locked is an important part of maximizing +the performance of your application under load. This section describes OpenJPA's +APIs for explicit locking, as well as its rules for implicit locking. + </p> + <div class="section" id="ref_guide_locking_default"><div class="titlepage"><div><div><h3 class="title">3.1. + Configuring Default Locking + </h3></div></div></div> + + <a class="indexterm" name="d5e15552"></a> + <p> + <a class="indexterm" name="d5e15556"></a> + <a class="indexterm" name="d5e15559"></a> + <a class="indexterm" name="d5e15561"></a> +You can control OpenJPA's default transactional read and write lock levels +through the <a class="link" href="ref_guide_conf_openjpa.html#openjpa.ReadLockLevel" title="5.60. openjpa.ReadLockLevel"><code class="literal"> +openjpa.ReadLockLevel</code></a> and +<a class="link" href="ref_guide_conf_openjpa.html#openjpa.WriteLockLevel" title="5.71. openjpa.WriteLockLevel"><code class="literal">openjpa.WriteLockLevel</code> +</a> configuration properties. Each property accepts a value of <code class="literal"> +none</code>, <code class="literal">read</code>, <code class="literal">write</code>, +<code class="literal">optimistic</code>, <code class="literal">optimistic-force-increment</code>, +<code class="literal">pessimistic-read</code>, <code class="literal">pessimistic-write</code>, +<code class="literal">pessimistic-force-increment</code>, or a number +corresponding to a lock level defined by the +<a class="link" href="ref_guide_locking.html#ref_guide_locking_lockmgr" title="3.4. Lock Manager">lock manager</a> in use. These +properties apply only to non-optimistic transactions; during optimistic +transactions, OpenJPA never locks objects by default. + </p> + <p> + <a class="indexterm" name="d5e15577"></a> + <a class="indexterm" name="d5e15579"></a> +You can control the default amount of time OpenJPA will wait when trying to +obtain locks through the <a class="link" href="ref_guide_conf_openjpa.html#openjpa.LockTimeout" title="5.43. openjpa.LockTimeout"><code class="literal"> +openjpa.LockTimeout</code></a> configuration property. Set this property +to the number of milliseconds you are willing to wait for a lock before OpenJPA +will throw an exception, or to -1 for no limit. It defaults to -1. + </p> + <div class="example" id="ref_guide_locking_default_conf"><p class="title"><b>Example 9.3. + Setting Default Lock Levels + </b></p><div class="example-contents"> + +<pre class="programlisting"> +<property name="openjpa.ReadLockLevel" value="none"/> +<property name="openjpa.WriteLockLevel" value="write"/> +<property name="openjpa.LockTimeout" value="30000"/> +</pre> + </div></div><br class="example-break"> + </div> + <div class="section" id="ref_guide_locking_runtime"><div class="titlepage"><div><div><h3 class="title">3.2. + Configuring Lock Levels at Runtime + </h3></div></div></div> + + <a class="indexterm" name="d5e15589"></a> + <p> +At runtime, you can override the default lock levels through the <code class="classname"> +FetchPlan</code> interface described above. At the beginning of each +datastore transaction, OpenJPA initializes the <code class="classname"> EntityManager +</code>'s fetch plan with the default lock levels and timeouts described +in the previous section. By changing the fetch plan's locking properties, you +can control how objects loaded at different points in the transaction are +locked. You can also use the fetch plan of an individual <code class="classname">Query +</code> to apply your locking changes only to objects loaded through that +<code class="classname">Query</code>. + </p> +<pre class="programlisting"> +public LockModeType getReadLockMode(); +public FetchPlan setReadLockMode(LockModeType mode); +public LockModeType getWriteLockMode(); +public FetchPlan setWriteLockMode(LockModeType mode); +long getLockTimeout(); +FetchPlan setLockTimeout(long timeout); +</pre> + <p> +Controlling locking through these runtime APIs works even during optimistic +transactions. At the end of the transaction, OpenJPA resets the fetch plan's +lock levels to <code class="literal">none</code>. You cannot lock objects outside of a +transaction. + </p> + <div class="example" id="ref_guide_locking_fetch"><p class="title"><b>Example 9.4. + Setting Runtime Lock Levels + </b></p><div class="example-contents"> + +<pre class="programlisting"> +import org.apache.openjpa.persistence.*; + +... + +EntityManager em = ...; +em.getTransaction().begin(); + +// load stock we know we're going to update at write lock mode +Query q = em.createQuery("select s from Stock s where symbol = :s"); +q.setParameter("s", symbol); +OpenJPAQuery oq = OpenJPAPersistence.cast(q); +FetchPlan fetch = oq.getFetchPlan(); +fetch.setReadLockMode(LockModeType.WRITE); +fetch.setLockTimeout(3000); // 3 seconds +Stock stock = (Stock) q.getSingleResult(); + +// load an object we don't need locked at none lock mode +fetch = OpenJPAPersistence.cast(em).getFetchPlan(); +fetch.setReadLockMode(null); +Market market = em.find(Market.class, marketId); + +stock.setPrice(market.calculatePrice(stock)); +em.getTransaction().commit(); +</pre> + </div></div><br class="example-break"> + </div> + <div class="section" id="ref_guide_locking_apis"><div class="titlepage"><div><div><h3 class="title">3.3. + Object Locking APIs + </h3></div></div></div> + + <a class="indexterm" name="d5e15605"></a> + <p> +In addition to allowing you to control implicit locking levels, OpenJPA provides +explicit APIs to lock objects and to retrieve their current lock level. + </p> +<pre class="programlisting"> +public LockModeType OpenJPAEntityManager.getLockMode(Object pc); +</pre> + <p> +Returns the level at which the given object is currently locked. + </p> + <p> +In addition to the standard +<a class="ulink" href="http://download.oracle.com/javaee/6/api/javax/persistence/EntityManager.html"; target="_top"> +<code class="methodname">EntityManager.lock(Object, LockModeType)</code></a> +method, the +<a class="ulink" href="../javadoc/org/apache/openjpa/persistence/OpenJPAEntityManager.html" target="_top"> +<code class="classname">OpenJPAEntityManager</code></a> exposes the following +methods to lock objects explicitly: + </p> +<pre class="programlisting"> +public void lock(Object pc); +public void lock(Object pc, LockModeType mode, long timeout); +public void lockAll(Object... pcs); +public void lockAll(Object... pcs, LockModeType mode, long timeout); +public void lockAll(Collection pcs); +public void lockAll(Collection pcs, LockModeType mode, long timeout); +</pre> + <p> +Methods that do not take a lock level or timeout parameter default to the +current fetch plan. The example below demonstrates these methods in action. + </p> + <div class="example" id="ref_guide_locking_explicit"><p class="title"><b>Example 9.5. + Locking APIs + </b></p><div class="example-contents"> + +<pre class="programlisting"> +import org.apache.openjpa.persistence.*; + +// retrieve the lock level of an object +OpenJPAEntityManager oem = OpenJPAPersistence.cast(em); +Stock stock = ...; +LockModeType level = oem.getLockMode(stock); +if (level == OpenJPAModeType.WRITE) ... + +... + +oem.setOptimistic(true); +oem.getTransaction().begin(); + +// override default of not locking during an opt trans to lock stock object +oem.lock(stock, LockModeType.WRITE, 1000); +stock.setPrice(market.calculatePrice(stock)); + +oem.getTransaction().commit(); +</pre> + </div></div><br class="example-break"> + </div> + <div class="section" id="ref_guide_locking_lockmgr"><div class="titlepage"><div><div><h3 class="title">3.4. + Lock Manager + </h3></div></div></div> + + <a class="indexterm" name="d5e15623"></a> + <p> + <a class="indexterm" name="d5e15627"></a> +OpenJPA delegates the actual work of locking objects to the system's +<a class="ulink" href="../javadoc/org/apache/openjpa/kernel/LockManager.html" target="_top"><code class="classname"> +org.apache.openjpa.kernel.LockManager</code></a>. This plugin is +controlled by the <a class="link" href="ref_guide_conf_openjpa.html#openjpa.LockManager" title="5.42. openjpa.LockManager"><code class="literal"> +openjpa.LockManager</code></a> configuration property. You can write your +own lock manager, or use one of the bundled options: + </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p> +<code class="literal">mixed</code>: This is an alias for the +<a class="ulink" href="../javadoc/org/apache/openjpa/jdbc/kernel/MixedLockManager.html" target="_top"> +<code class="classname">org.apache.openjpa.jdbc.kernel.MixedLockManager</code> +</a>, which implements the JPA 2.0 specification entity locking behaviors. +It combines both the optimistic and pessimistic semantics controlled by +lock mode argument in methods define in the EntityManager +and Query interfaces or OpenJPA lock level properties. + </p> + <p> +The <code class="literal">mixed</code> LockManager inherits all the properties available +from <code class="literal">version</code> and <code class="literal">pessimistic</code> LockManagers. +For example: <code class="literal">VersionCheckOnReadLock</code> and +<code class="literal">VersionUpdateOnWriteLock</code> properties. + </p> + <p> +This is the default <code class="literal">openjpa.LockManager</code> setting in OpenJPA. + </p> + </li><li class="listitem"> + <p> +<code class="literal">pessimistic</code>: This is an alias for the +<a class="ulink" href="../javadoc/org/apache/openjpa/jdbc/kernel/PessimisticLockManager.html" target="_top"> +<code class="classname">org.apache.openjpa.jdbc.kernel.PessimisticLockManager</code> +</a>, which +uses SELECT FOR UPDATE statements (or the database's equivalent) to lock the +database rows corresponding to locked objects. This lock +manager does not distinguish between read locks and write locks; all locks are +write locks. + </p> + <p> +The <code class="literal">pessimistic</code> LockManager can be configured to additionally +perform the version checking and incrementing behavior of the <code class="literal">version +</code> lock manager described below by setting its <code class="literal"> +VersionCheckOnReadLock</code> and <code class="literal">VersionUpdateOnWriteLock</code> +properties: + </p> +<pre class="programlisting"> +<property name="openjpa.LockManager" value="pessimistic(VersionCheckOnReadLock=true,VersionUpdateOnWriteLock=true)"/> +</pre> + </li><li class="listitem"> + <p> +<code class="literal">version</code>: This is an alias for the +<a class="ulink" href="../javadoc/org/apache/openjpa/kernel/VersionLockManager.html" target="_top"> +<code class="classname">org.apache.openjpa.kernel.VersionLockManager</code></a>. +This lock manager does not perform any exclusive locking, but instead ensures +read consistency by verifying that the version of all read-locked instances is +unchanged at the end of the transaction. Furthermore, a write lock will force an +increment to the version at the end of the transaction, even if the object is +not otherwise modified. This ensures read consistency with non-blocking +behavior. + </p> + </li><li class="listitem"> + <p> +<code class="literal">none</code>: This is an alias for the +<a class="ulink" href="../javadoc/org/apache/openjpa/kernel/NoneLockManager.html" target="_top"> +<code class="classname">org.apache.openjpa.kernel.NoneLockManager</code></a>, which +does not perform any locking at all. + </p> + </li></ul></div> + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + <p> +In order for the <code class="literal">version</code> or <code class="literal">mixed</code> lock +managers to prevent the dirty +read phenomenon, the underlying data store's transaction isolation level must be +set to the equivalent of "read committed" or higher. + </p> + </div> + <div class="example" id="ref_guide_locking_disable"><p class="title"><b>Example 9.6. + Disabling Locking + </b></p><div class="example-contents"> + +<pre class="programlisting"> +<property name="openjpa.LockManager" value="none"/> +</pre> + </div></div><br class="example-break"> + </div> + <div class="section" id="ref_guide_locking_rules"><div class="titlepage"><div><div><h3 class="title">3.5. + Rules for Locking Behavior + </h3></div></div></div> + + <a class="indexterm" name="d5e15677"></a> + <a class="indexterm" name="d5e15680"></a> + <p> +Advanced persistence concepts like lazy-loading and object uniquing create +several locking corner-cases. The rules below outline OpenJPA's implicit locking +behavior in these cases. + </p> + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> + <p> +When an object's state is first read within a transaction, the object is locked +at the fetch plan's current read lock level. Future reads of additional lazy +state for the object will use the same read lock level, even if the fetch plan's +level has changed. + </p> + </li><li class="listitem"> + <p> +When an object's state is first modified within a transaction, the object is +locked at the write lock level in effect when the object was first read, even if +the fetch plan's level has changed. If the object was not read previously, the +current write lock level is used. + </p> + </li><li class="listitem"> + <p> +When objects are accessed through a persistent relation field, the related +objects are loaded with the fetch plan's current lock levels, not the lock +levels of the object owning the field. + </p> + </li><li class="listitem"> + <p> +Whenever an object is accessed within a transaction, the object is re-locked at +the current read lock level. The current read and write lock levels become those +that the object "remembers" according to rules one and two above. + </p> + </li><li class="listitem"> + <p> +If you lock an object explicitly through the APIs demonstrated above, it is +re-locked at the specified level. This level also becomes both the read and +write level that the object "remembers" according to rules one and two above. + </p> + </li><li class="listitem"> + <p> +When an object is already locked at a given lock level, re-locking at a lower +level has no effect. Locks cannot be downgraded during a transaction. + </p> + </li></ol></div> + </div> + <div class="section" id="ref_guide_locking_issues"><div class="titlepage"><div><div><h3 class="title">3.6. + Known Issues and Limitations + </h3></div></div></div> + + <a class="indexterm" name="d5e15699"></a> + <p> +Due to performance concerns and database limitations, locking cannot be perfect. +You should be aware of the issues outlined in this section, as they may affect +your application. + </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p> +Typically, during optimistic transactions OpenJPA does not start an actual +database transaction until you flush or the optimistic transaction commits. This +allows for very long-lived transactions without consuming database resources. +When using the pessimistic lock manager, however, OpenJPA must begin a database +transaction whenever you decide to lock an object during an optimistic +transaction. This is because the pessimistic lock manager uses database locks, +and databases cannot lock rows without a transaction in progress. OpenJPA will +log an INFO message to the <code class="literal">openjpa.Runtime</code> logging channel +when it begins a datastore transaction just to lock an object. + </p> + </li><li class="listitem"> + <p> +In order to maintain reasonable performance levels when loading object state, +OpenJPA can only guarantee that an object is locked at the proper lock level +<span class="emphasis"><em>after</em></span> the state has been retrieved from the database. This +means that it is technically possible for another transaction to "sneak in" and +modify the database record after OpenJPA retrieves the state, but before it +locks the object. The only way to positively guarantee that the object is locked +and has the most recent state to refresh the object after locking it. + </p> + <p> +When using the pessimistic lock manager, the case above can only occur when +OpenJPA cannot issue the state-loading SELECT as a locking statement due to +database limitations. For example, some databases cannot lock SELECTs that use +joins. The pessimistic lock manager will log an INFO message to the <code class="literal"> +openjpa.Runtime</code> logging channel whenever it cannot lock the initial +SELECT due to database limitations. By paying attention to these log messages, +you can see where you might consider using an object refresh to guarantee that +you have the most recent state, or where you might rethink the way you load the +state in question to circumvent the database limitations that prevent OpenJPA +from issuing a locking SELECT in the first place. + </p> + </li><li class="listitem"> + <p> +When using the pessimistic lock manager and named queries you will see the following +<code class="literal">WARNING</code> message logged if you do not specify a lockMode on the named query +or you explicitly set it to <code class="literal">LockModeType.NONE</code>. When using the pessimistic +lock manager a <code class="literal">LockModeType.NONE</code> will always be promoted to <code class="literal">LockModeType.READ</code>. +</p><pre class="programlisting"> +WARN [main] openjpa.MetaData - Encountered a read lock level less than LockModeType.READ when processing the NamedQuery annotation "findEmployeeById" in class "org.apache.openjpa.persistence.lockmgr.LockEmployee". Setting query lock level to LockModeType.READ. +</pre><p> +If you are using the pessimistic lock manager and you truly do want to set the lock mode to NONE for a +given query, you can use a fetch plan to do so. +</p><pre class="programlisting"> +OpenJPAQuery q = em.createNamedQuery("findEmployeeById"); +FetchPlan fp = q.getFetchPlan(); +fp.setReadLockMode(LockModeType.NONE); +</pre><p> + </p> + </li></ul></div> + </div> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ref_guide_runtime_jpa.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ref_guide_runtime.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ref_guide_savepoints.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">2. + JPA Extensions + </td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top"> 4. + Savepoints + </td></tr></table></div></body></html> \ No newline at end of file Added: websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_logging.html ============================================================================== --- websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_logging.html (added) +++ websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_logging.html Fri Jan 6 19:19:20 2017 @@ -0,0 +1,193 @@ +<html><head> + <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> + <title>Chapter 3. Logging and Auditing</title><base href="display"><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="manual.html" title="Apache OpenJPA 2.4 User's Guide"><link rel="up" href="ref_guide.html" title="Part 3. Reference Guide"><link rel="prev" href="ref_guide_conf_jdbc.html" title="6. OpenJPA JDBC Properties"><link rel="next" href="ref_guide_logging_openjpa.html" title="2. OpenJPA Logging"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 3. + Logging and Auditing + </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_conf_jdbc.html">Prev</a> </td><th width="60%" align="center">Part 3. Reference Guide</th><td width="20%" align="right"> <a accesskey="n" href="ref_guide_logging_openjpa.html">Next</a></td></tr></table><hr></div><div class="chapter" id="ref_guide_logging"><div class="titlepage"><div><div><h2 class="title">Chapter 3. + Logging and Auditing + </h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="ref_guide_logging.html#ref_guide_logging_channels">1. + Logging Channels + </a></span></dt><dt><span class="section"><a href="ref_guide_logging_openjpa.html">2. + OpenJPA Logging + </a></span></dt><dt><span class="section"><a href="ref_guide_logging_noop.html">3. + Disabling Logging + </a></span></dt><dt><span class="section"><a href="ref_guide_logging_log4j.html">4. + Log4J + </a></span></dt><dt><span class="section"><a href="ref_guide_logging_commons.html">5. + Apache Commons Logging + </a></span></dt><dd><dl><dt><span class="section"><a href="ref_guide_logging_commons.html#ref_guide_logging_jdk14">5.1. + JDK java.util.logging + </a></span></dt></dl></dd><dt><span class="section"><a href="ref_guide_logging_slf4j.html">6. + SLF4J + </a></span></dt><dt><span class="section"><a href="ref_guide_logging_custom.html">7. + Custom Log + </a></span></dt><dt><span class="section"><a href="ref_guide_audit.html">8. OpenJPA Audit</a></span></dt><dd><dl><dt><span class="section"><a href="ref_guide_audit.html#d5e9425">8.1. Configuration</a></span></dt><dt><span class="section"><a href="ref_guide_audit.html#d5e9447">8.2. Developing custom auditing</a></span></dt></dl></dd></dl></div> + + <a class="indexterm" name="d5e9185"></a> + <a class="indexterm" name="d5e9187"></a> + <p> +Logging is an important means of gaining insight into your application's runtime +behavior. OpenJPA provides a flexible logging system that integrates with many +existing runtime systems, such as application servers and servlet runners. + </p> + <p> +There are five built-in logging plugins: a +<a class="link" href="ref_guide_logging_openjpa.html" title="2. OpenJPA Logging">default logging framework</a> that +covers most needs, a <a class="link" href="ref_guide_logging_log4j.html" title="4. Log4J"> Log4J</a> +delegate, a <a class="link" href="ref_guide_logging_slf4j.html" title="6. SLF4J"> SLF4J</a> +delegate, an <a class="link" href="ref_guide_logging_commons.html" title="5. Apache Commons Logging"> Apache Commons Logging +</a> delegate, and a <a class="link" href="ref_guide_logging_noop.html" title="3. Disabling Logging">no-op</a> +implementation for disabling logging. + </p> + <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3> + <p> +Logging can have a negative impact on performance. Disable verbose logging (such +as logging of SQL statements) before running any performance tests. It is +advisable to limit or disable logging for a production system. You can disable +logging altogether by setting the <code class="literal">openjpa.Log</code> property to +<code class="literal">none</code>. + </p> + </div> + <div class="section" id="ref_guide_logging_channels"><div class="titlepage"><div><div><h2 class="title" style="clear: both">1. + Logging Channels + </h2></div></div></div> + + <a class="indexterm" name="d5e9202"></a> + <p> +Logging is done over a number of <span class="emphasis"><em>logging channels</em></span>, each of +which has a <span class="emphasis"><em>logging level</em></span> which controls the verbosity of +log messages recorded for the channel. OpenJPA uses the following logging +channels: + </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p> +<code class="literal">openjpa.Tool</code>: Messages issued by the OpenJPA command line +and Ant tools. Most messages are basic statements detailing which classes or +files the tools are running on. Detailed output is only available via the +logging category the tool belongs to, such as <code class="literal">openjpa.Enhance</code> +for the enhancer (see <a class="xref" href="ref_guide_pc_enhance.html" title="2. Enhancement">Section 2, “ + Enhancement + ”</a>) or <code class="literal"> +openjpa.MetaData</code> for the mapping tool (see +<a class="xref" href="ref_guide_mapping.html#ref_guide_mapping_mappingtool" title="1. Forward Mapping">Section 1, “ + Forward Mapping + ”</a>). This logging category +is provided so that you can get a general idea of what a tool is doing without +having to manipulate logging settings that might also affect runtime behavior. + </p> + </li><li class="listitem"> + <p> + <a class="indexterm" name="d5e9218"></a> +<code class="literal">openjpa.Enhance</code>: Messages pertaining to enhancement and +runtime class generation. + </p> + </li><li class="listitem"> + <p> + <a class="indexterm" name="d5e9224"></a> +<code class="literal">openjpa.MetaData</code>: Details about the generation of metadata +and object-relational mappings. + </p> + </li><li class="listitem"> + <p> +<code class="literal">openjpa.Runtime</code>: General OpenJPA runtime messages. + </p> + </li><li class="listitem"> + <p> + <a class="indexterm" name="d5e9233"></a> +<code class="literal">openjpa.Query</code>: Messages about queries. Query strings and any +parameter values, if applicable, will be logged to the <code class="literal">TRACE</code> +level at execution time. Information about possible performance concerns will be +logged to the <code class="literal">INFO</code> level. + </p> + </li><li class="listitem"> + <p> + <a class="indexterm" name="d5e9241"></a> +<code class="literal">openjpa.DataCache</code>: Messages from the L2 data cache plugins. + </p> + </li><li class="listitem"> + <p> + <a class="indexterm" name="d5e9247"></a> +<code class="literal">openjpa.jdbc.JDBC</code>: JDBC connection information. General JDBC +information will be logged to the <code class="literal">TRACE</code> level. Information +about possible performance concerns will be logged to the <code class="literal">INFO +</code> level. + </p> + </li><li class="listitem"> + <p> + <a class="indexterm" name="d5e9255"></a> +<code class="literal">openjpa.jdbc.SQL</code>: This is the most common logging channel to +use. Detailed information about the execution of SQL statements will be sent to +the <code class="literal">TRACE</code> level. It is useful to enable this channel if you +are curious about the exact SQL that OpenJPA issues to the datastore. +</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> +The SQL issued to the database may contain sensitive information. By default the +parameter values used in the prepared statements generated by OpenJPA will not +be printed in the SQL log - instead you will see a ? for each value. The actual +values may be printed by adding <code class="literal">PrintParameters=True</code> to the +<a class="link" href="ref_guide_conf_openjpa.html#openjpa.ConnectionFactoryProperties" title="5.15. openjpa.ConnectionFactoryProperties"> +<code class="literal">openjpa.ConnectionFactoryProperties</code></a> property. Also +see <a class="link" href="ref_guide_dbsetup.html#ref_guide_dbsetup_builtin" title="1. Using the OpenJPA DataSource"><code class="literal">Using the OpenJPA +DataSource</code></a> +</div><p> + </p> + <p> +When using the built-in OpenJPA logging facilities, you can enable SQL logging +by adding <code class="literal">SQL=TRACE</code> to your <code class="literal">openjpa.Log</code> +property. + </p> + <p> +OpenJPA can optionally reformat the logged SQL to make it easier to read. To +enable pretty-printing, add <code class="literal">PrettyPrint=true</code> to the +<a class="link" href="ref_guide_conf_openjpa.html#openjpa.ConnectionFactoryProperties" title="5.15. openjpa.ConnectionFactoryProperties"><code class="literal"> +openjpa.ConnectionFactoryProperties</code></a> property. You can control +how many columns wide the pretty-printed SQL will be with the <code class="literal"> +PrettyPrintLineLength</code> property. The default line length is 60 columns. + </p> + <p> +While pretty printing makes things easier to read, it can make output harder to +process with tools like grep. + </p> + <p> +Pretty-printing properties configuration might look like so: + </p> +<pre class="programlisting"> +<property name="openjpa.Log" value="SQL=TRACE"/> +<property name="openjpa.ConnectionFactoryProperties" + value="PrettyPrint=true, PrettyPrintLineLength=72"/> +</pre> + </li><li class="listitem"> + <p> + <a class="indexterm" name="d5e9279"></a> +<code class="literal">openjpa.jdbc.SQLDiag</code>: This logging channel provides additional +information about entity actitvies such as create, find, update or delete, and eager +loading of relation or field properties. If you enable this channel, it is recommended +that <code class="literal">openjpa.jdbc.SQL</code> channel is also enabled. +The additional trace can help you relate the entity activities to the execution of +SQL statements that OpenJPA issued to the datastore. + </p> + <p> +When using the built-in OpenJPA logging facilities, you can enable SQLDiag logging +by adding <code class="literal">SQLDiag=TRACE</code> to your <code class="literal">openjpa.Log</code> +property. + </p> + </li><li class="listitem"> + <p> + <a class="indexterm" name="d5e9289"></a> +<code class="literal">openjpa.jdbc.Schema</code>: Details about operations on the +database schema. + </p> + </li></ul></div> + </div> + + + + + + + + + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ref_guide_conf_jdbc.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ref_guide.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ref_guide_logging_openjpa.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">6. + OpenJPA JDBC Properties + </td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top"> 2. + OpenJPA Logging + </td></tr></table></div></body></html> \ No newline at end of file Added: websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_logging_commons.html ============================================================================== --- websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_logging_commons.html (added) +++ websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_logging_commons.html Fri Jan 6 19:19:20 2017 @@ -0,0 +1,93 @@ +<html><head> + <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> + <title>5. Apache Commons Logging</title><base href="display"><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="manual.html" title="Apache OpenJPA 2.4 User's Guide"><link rel="up" href="ref_guide_logging.html" title="Chapter 3. Logging and Auditing"><link rel="prev" href="ref_guide_logging_log4j.html" title="4. Log4J"><link rel="next" href="ref_guide_logging_slf4j.html" title="6. SLF4J"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">5. + Apache Commons Logging + </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_logging_log4j.html">Prev</a> </td><th width="60%" align="center">Chapter 3. + Logging and Auditing + </th><td width="20%" align="right"> <a accesskey="n" href="ref_guide_logging_slf4j.html">Next</a></td></tr></table><hr></div><div class="section" id="ref_guide_logging_commons"><div class="titlepage"><div><div><h2 class="title" style="clear: both">5. + Apache Commons Logging + </h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="ref_guide_logging_commons.html#ref_guide_logging_jdk14">5.1. + JDK java.util.logging + </a></span></dt></dl></div> + + <a class="indexterm" name="d5e9366"></a> + <p> +Set the <code class="literal">openjpa.Log</code> property to <code class="literal">commons</code> to +use the <a class="ulink" href="http://commons.apache.org/logging/"; target="_top"> Apache +Commons Logging</a> thin library for issuing log messages. The +Commons Logging library act as a wrapper around a number of popular logging +APIs, including the +<a class="ulink" href="http://logging.apache.org/log4j/1.2/index.html"; target="_top"> Jakarta Log4J +</a> project, and the native +<a class="ulink" href="http://download.oracle.com/javase/6/docs/api/java/util/logging/package-summary.html"; target="_top"> +java.util.logging</a> package in JDK. + </p> + <p> +When using the Commons Logging framework in conjunction with Log4J, +configuration will be the same as was discussed in the Log4J section above. + </p> + <div class="section" id="ref_guide_logging_jdk14"><div class="titlepage"><div><div><h3 class="title">5.1. + JDK java.util.logging + </h3></div></div></div> + + <a class="indexterm" name="d5e9378"></a> + <p> +When using JDK logging in conjunction with OpenJPA's Commons Logging +support, logging will proceed through Java's built-in logging provided by the +<a class="ulink" href="http://download.oracle.com/javase/6/docs/api/java/util/logging/package-summary.html"; target="_top"> +java.util.logging</a> package. For details on configuring the built-in +logging system, please see the +<a class="ulink" href="http://download.oracle.com/javase/6/docs/technotes/guides/logging/overview.html"; target="_top"> +Java Logging Overview</a>. + </p> + <p> +By default, JDK's logging package looks in the <code class="filename"> +JAVA_HOME/lib/logging.properties</code> file for logging configuration. This +can be overridden with the <code class="literal">java.util.logging.config.file</code> +system property. For example: + </p> +<pre class="programlisting"> +java -Djava.util.logging.config.file=mylogging.properties com.company.MyClass +</pre> + <div class="example" id="ref_guide_logging_jdk14_propfile"><p class="title"><b>Example 3.5. + JDK Log Properties + </b></p><div class="example-contents"> + +<pre class="programlisting"> +# specify the handlers to create in the root logger +# (all loggers are children of the root logger) +# the following creates two handlers +handlers=java.util.logging.ConsoleHandler, java.util.logging.FileHandler + +# set the default logging level for the root logger +.level=ALL + +# set the default logging level for new ConsoleHandler instances +java.util.logging.ConsoleHandler.level=INFO + +# set the default logging level for new FileHandler instances +java.util.logging.FileHandler.level=ALL + +# set the default formatter for new ConsoleHandler instances +java.util.logging.ConsoleHandler.formatter=java.util.logging.SimpleFormatter + +# set the default logging level for all OpenJPA logs +openjpa.Tool.level=INFO +openjpa.Runtime.level=INFO +openjpa.Remote.level=INFO +openjpa.DataCache.level=INFO +openjpa.MetaData.level=INFO +openjpa.Enhance.level=INFO +openjpa.Query.level=INFO +openjpa.jdbc.SQL.level=INFO +openjpa.jdbc.SQLDiag.level=INFO +openjpa.jdbc.JDBC.level=INFO +openjpa.jdbc.Schema.level=INFO +</pre> + </div></div><br class="example-break"> + </div> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ref_guide_logging_log4j.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ref_guide_logging.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ref_guide_logging_slf4j.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">4. + Log4J + </td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top"> 6. + SLF4J + </td></tr></table></div></body></html> \ No newline at end of file
