Added: incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_deploy.xml URL: http://svn.apache.org/viewvc/incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_deploy.xml?rev=433761&view=auto ============================================================================== --- incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_deploy.xml (added) +++ incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_deploy.xml Tue Aug 22 14:28:53 2006 @@ -0,0 +1,224 @@ + + <chapter id="ref_guide_deploy"> + <title>Deployment</title> + <para> + OpenJPA deployment includes choosing a factory deployment strategy, + and in a managed environment, optionally integrating with your application + server's managed and XA transactions. This chapter examines each aspect + of deployment in turn. + </para> + <section id="ref_guide_deploy_factory"> + <title>Factory Deployment</title> + <para> + OpenJPA offers several + <phrase><classname>EntityManagerFactory</classname></phrase> + + + deployment options. + </para> + <section id="ref_guide_deploy_factory_standalone"> + <title>Standalone Deployment</title> + <indexterm zone="ref_guide_deploy_factory_standalone"> + <primary>deployment</primary> + <secondary>standalone</secondary> + <seealso>Persistence</seealso> + </indexterm> + <para> + The JPA Overview describes the + <classname>javax.persistence.Persistence</classname> class. You + can use <classname>Persistence</classname> to obtain + <classname>EntityManagerFactory</classname> instances, as + demonstrated in <xref linkend="jpa_overview_persistence"/>. + OpenJPA also extends <classname>Persistence</classname> to add + additional <classname>EntityManagerFactory</classname> + creation methods. The + <classname>org.apache.openjpa.persistence.OpenJPAPersistence</classname> class + <ulink url="../../api/openjpa/persistence/OpenJPAPersistence.html"> + Javadoc</ulink> details these extensions. + </para> + <para> + After obtaining the factory, you can cache it for all + <phrase><classname>EntityManager</classname></phrase> + + + creation duties. + </para> + </section> + <section id="ref_guide_deploy_inject"> + <title>EntityManager Injection</title> +<!-- ### EJBDOC --> + <para> + To be decided. + </para> + </section> + <section id="ref_guide_deploy_jca_ejb"> + <title>OpenJPA JCA Deployment</title> + <indexterm zone="ref_guide_deploy_jca_ejb"> + <primary>deployment</primary> + <secondary>JCA</secondary> + <seealso>JCA</seealso> + </indexterm> + <indexterm zone="ref_guide_deploy_jca_ejb"> + <primary>JCA</primary> + <secondary>deployment</secondary> + </indexterm> + <para> + OpenJPA can deploy OpenJPA through the Java Connector Architecture + (JCA) in any JCA-compliant application server that supports + JDK 1.5 (all EJB 3 implementations require JDK 1.5). We present + the deployment steps for the most common servers below. + </para> + <section id="ref_guide_deploy_jca_jpa_weblogic9"> + <title>WebLogic 9</title> + <indexterm zone="ref_guide_deploy_jca_jpa_weblogic9"> + <primary>Weblogic</primary> + </indexterm> + <indexterm zone="ref_guide_deploy_jca_jpa_weblogic9"> + <primary>JCA</primary> + <secondary>Weblogic 9</secondary> + </indexterm> + <para><!-- ### JDO2MIG : everything in system path for now --> + First, ensure that your JDBC driver is in your system classpath. + In addition, you will be adding the OpenJPA and specification API + jars to the system classpath. You can accomplish this by + editing <filename>startWebLogic.sh/.cmd</filename>. + </para> + <warning> + <para>Currently WebLogic ships with an old version + of the EJB 3 libraries. Be sure to put + <filename>org.apache.openjpa.jar</filename> in the <emphasis>beginning + </emphasis> of the <literal>CLASSPATH</literal>.</para> + </warning> + <para> + The next step is to deploy + <filename>openjpa-persistence.rar</filename> from the + <filename>jca/persistence</filename> directory of your OpenJPA + installation. Copy this file to the <filename>autodeploy + </filename> directory of your domain. + </para> + <para> + We will now extract <filename>META-INF/ra.xml</filename> + and <filename>META-INF/weblogic-ra.xml</filename> + to edit our configuration: + </para> + <programlisting format="linespecific"> +jar xvf openjpa-ejb.rar META-INF/ra.xml META-INF/weblogic-ra.xml +</programlisting> + <para> + Now you should configure OpenJPA JCA by editing + <filename>META-INF/ra.xml</filename> substituting + <literal>config-property-value</literal> stanzas + with your own values. You can comment out + properties (config-property stanzas) which you are + not using or you can leave them at their default settings. + Edit <filename>META-INF/weblogic-ra.xml</filename> + to configure the JNDI location to which you + want OpenJPA to be bound. + </para> + <para> + Now we can re-jar the manifest files back into the + <filename>RAR</filename> file. + </para> + <programlisting format="linespecific"> +jar uvf openjpa-ejb.rar META-INF/ra.xml META-INF/weblogic-ra.xml +rm META-INF/ra.xml META-IN/weblogic-ra.xml +rmdir META-INF +</programlisting> + <para> + Now you can start WebLogic and WebLogic should + deploy OpenJPA for you. If you have installed OpenJPA correctly, + at this point, one should be able to see OpenJPA bound to the + JNDI location which you specified earlier. + </para> + </section> + </section> + </section> + <section id="ref_guide_enterprise_xa"> + <title>XA Transactions</title> + <indexterm zone="ref_guide_enterprise_xa"> + <primary>transactions</primary> + <secondary>XA</secondary> + </indexterm> + <indexterm> + <primary>XA transactions</primary> + <see>transactions</see> + </indexterm> + <para> + The X/Open Distributed Transaction Processing (X/Open DTP) + model, designed by <ulink url="http://www.xopen.org";>Open Group</ulink> + (a vendor consortium), defines a standard communication architecture + that provides the following: + </para> + <itemizedlist> + <listitem> + <para> + Concurrent execution of applications on shared resources. + </para> + </listitem> + <listitem> + <para> + Coordination of transactions across applications. + </para> + </listitem> + <listitem> + <para> + Components, interfaces, and protocols that define the + architecture and provide portability of applications. + </para> + </listitem> + <listitem> + <para>Atomicity of transaction systems.</para> + </listitem> + <listitem> + <para> + Single-thread control and sequential function-calling. + </para> + </listitem> + </itemizedlist> + <para> + The X/Open DTP XA standard defines the application programming + interfaces that a resource manager uses to communicate + with a transaction manager. The XA interfaces enable resource + managers to join transactions, to perform two-phase commit, + and to recover in-doubt transactions following a failure. + </para> + <section id="ref_guide_enterprise_xa_req"> + <title>Using OpenJPA with XA Transactions</title> + <para> + OpenJPA supports XA-compliant transactions when used in a properly + configured managed environment. The following components are + required: + </para> + <itemizedlist> + <listitem> + <para> + A managed environment that provides an XA compliant + transaction manager. Examples of this are application + servers such as JBoss and WebLogic. + </para> + </listitem> + <listitem> + <para> + Instances of a <classname>javax.sql.XADataSource</classname> + for each of the <classname>DataSource</classname>s that + OpenJPA will use. + </para> + </listitem> + </itemizedlist> + <para> + Given these components, setting up OpenJPA to participate in + distributed transactions is a simple two-step process: + </para> + <orderedlist> + <listitem> + <para> + Point OpenJPA at an enlisted + <classname>XADataSource</classname>, and configure a + second non-enlisted data source. + See <xref linkend="ref_guide_dbsetup_thirdparty_enlist"/>. + </para> + </listitem> + </orderedlist> + </section> + </section> + </chapter>
Added: incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_integration.xml URL: http://svn.apache.org/viewvc/incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_integration.xml?rev=433761&view=auto ============================================================================== --- incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_integration.xml (added) +++ incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_integration.xml Tue Aug 22 14:28:53 2006 @@ -0,0 +1,419 @@ + + <chapter id="ref_guide_integration"> + <title>Third Party Integration</title> + <para> + OpenJPA provides a number of mechanisms for integrating with third-party + tools. The following chapter will illustrate these integration features. + </para> + <section id="ref_guide_integration_ant"> + <title>Apache Ant</title> + <indexterm zone="ref_guide_integration_ant"> + <primary>Ant</primary> + </indexterm> + <para> + Ant is a very popular tool for building Java projects. It is similar to + the <literal>make</literal> command, but is Java-centric and has + more modern features. Ant is open source, and can be downloaded + from Apache's Ant web page at + <ulink url="http://jakarta.apache.org/ant/";> + http://jakarta.apache.org/ant/</ulink>. + Ant has become the de-facto standard build tool for Java, and + many commercial integrated development environments provide + some support for using ant build files. The remainder of this + section assumes familiarity with writing Ant + <filename>build.xml</filename> files. + </para> + <para> + OpenJPA provides pre-built Ant task definitions for all bundled tools: + </para> + <itemizedlist> + <listitem> + <para> + <link linkend="ref_guide_integration_enhance">Enhancer + Task</link> + </para> + </listitem> + <listitem> + <para> + <link linkend="ref_guide_integration_appidtool">Application + Identity Tool Task</link> + </para> + </listitem> + <listitem> + <para> + <link linkend="ref_guide_integration_mappingtool">Mapping + Tool Task</link> + </para> + </listitem> + <listitem> + <para> + <link linkend="ref_guide_integration_revmappingtool">Reverse + Mapping Tool Task</link> + </para> + </listitem> + <listitem> + <para> + <link linkend="ref_guide_integration_schematool">Schema Tool + Task</link> + </para> + </listitem> + </itemizedlist> + <para> + The source code for all the ant tasks is provided with the distribution + under the <filename>src</filename> directory. This allows you + to customize various aspects of the ant tasks in order to better + integrate into your development environment. + </para> + <section id="ref_guide_integration_conf"> + <title>Common Ant Configuration Options</title> + <indexterm> + <primary>Ant</primary> + <secondary>configuration options</secondary> + </indexterm> + <para> + All OpenJPA tasks accept a nested <literal>config</literal> + element, which defines the configuration environment in which + the specified task will run. The attributes for the + <literal>config</literal> tag are defined by the + <ulink url="../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 + <phrase><filename>org.apache.openjpa.xml</filename></phrase> + + + 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 format="linespecific"> +<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 format="linespecific"> +<mappingtool> + <fileset dir="${basedir}"> + <include name="**/model/*.java"/> + </fileset> + <config properties="openjpa-dev.properties"/> +</mappingtool> +</programlisting> + </example> + <example id="ref_guide_integration_propsfile"> + <title>Using the PropertiesFile Attribute of the <config> + Tag</title> + <programlisting format="linespecific"> +<mappingtool> + <fileset dir="${basedir}"> + <include name="**/model/*.java"/> + </fileset> + <config propertiesFile="../conf/openjpa-dev.properties"/> +</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 format="linespecific"> +<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 format="linespecific"> +<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 <link linkend="ref_guide_pc_enhance"><literal>openjpac</literal></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 <link linkend="openjpa.MetaDataFactory"><literal> + openjpa.MetaDataFactory</literal></link> property. + </para> + <para> + Following is an example of using the enhancer task + in a <filename>build.xml</filename> file: + </para> + <example id="ref_guide_integration_enhance_task"> + <title>Invoking the Enhancer from Ant</title> + <programlisting format="linespecific"> +<target name="enhance"> + <!-- define the openjpac task; this can be done at the top of the --> + <!-- build.xml file, so it will be available for all targets --> + <taskdef name="openjpac" classname="org.apache.openjpa.ant.PCEnhancerTask"/> + + <!-- invoke enhancer on all .jdo files below the current directory --> + <openjpac> + <fileset dir="."> + <include name="**/model/*.java" /> + </fileset> + </openjpac> +</target> +</programlisting> + </example> + </section> + <section id="ref_guide_integration_appidtool"> + <title>Application Identity Tool Ant Task</title> + <indexterm zone="ref_guide_integration_enhance"> + <primary>Ant</primary> + <secondary>application identity tool task</secondary> + </indexterm> + <indexterm zone="ref_guide_integration_enhance"> + <primary>application identity tool</primary> + <secondary>Ant task</secondary> + </indexterm> + <para> + The application identity tool task allows you to invoke the + application identity tool directly from within the Ant build + process. The task's parameters correspond exactly to the long + versions of the command-line arguments to + <link linkend="ref_guide_pc_appid_appidtool"><literal>appidtool</literal></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 <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 format="linespecific"> +<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"><literal> + mappingtool</literal></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 <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 format="linespecific"> +<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"><literal> + reversemappingtool</literal></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 format="linespecific"> +<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"><literal> + schematool</literal></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 format="linespecific"> +<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_maven"> + <title>Maven</title> + <indexterm zone="ref_guide_integration_maven"> + <primary>Maven</primary> + </indexterm> + </section> + </chapter> Added: incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_intro.xml URL: http://svn.apache.org/viewvc/incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_intro.xml?rev=433761&view=auto ============================================================================== --- incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_intro.xml (added) +++ incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_intro.xml Tue Aug 22 14:28:53 2006 @@ -0,0 +1,28 @@ + + <chapter id="ref_guide_intro"> + <title>Introduction</title> + <para> + OpenJPA <phrase>JPA</phrase> is a JDBC-based implementation of the JPA + standard. This document is a reference for the + configuration and use of OpenJPA <phrase>JPA</phrase>. + </para> + <section id="ref_guide_intro_audience"> + <title>Intended Audience</title> + <para> + This document is intended for OpenJPA <phrase>JPA</phrase> 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 + <link linkend="jpa_overview_intro">JPA Overview</link> + before proceeding. We also strongly recommend taking OpenJPA's hands-on + <link linkend="tutorials">tutorials</link> to get comfortable + with OpenJPA basics. + </para> + <para> + 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. + </para> + </section> + </chapter> Added: incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_logging.xml URL: http://svn.apache.org/viewvc/incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_logging.xml?rev=433761&view=auto ============================================================================== --- incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_logging.xml (added) +++ incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_logging.xml Tue Aug 22 14:28:53 2006 @@ -0,0 +1,439 @@ + + <chapter id="ref_guide_logging"> + <title>Logging</title> + <indexterm zone="ref_guide_logging"> + <primary>logging</primary> + </indexterm> + <indexterm zone="ref_guide_logging"> + <primary>Log</primary> + </indexterm> + <para> + 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. + </para> + <para> + There are four built-in logging plugins: a + <link linkend="ref_guide_logging_openjpa">default logging framework</link> + that covers most needs, a <link linkend="ref_guide_logging_log4j"> + Log4J</link> delegate, an <link linkend="ref_guide_logging_commons"> + Apache Commons Logging</link> delegate, and a + <link linkend="ref_guide_logging_noop">no-op</link> implementation for + disabling logging. + </para> + <warning> + <para> + 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 <literal>openjpa.Log</literal> property + to <literal>none</literal>. + </para> + </warning> + <section id="ref_guide_logging_channels"> + <title>Logging Channels</title> + <indexterm zone="ref_guide_logging_channels"> + <primary>logging</primary> + <secondary>channels</secondary> + </indexterm> + <para> + Logging is done over a number of <emphasis>logging channels</emphasis>, + each of which has a <emphasis>logging level</emphasis> which controls + the verbosity of log messages recorded for the channel. OpenJPA uses + the following logging channels: + </para> + <itemizedlist> + <listitem> + <para><literal>openjpa.Tool</literal>: 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 + <literal>openjpa.Enhance</literal> for the enhancer + (see <xref linkend="ref_guide_pc_enhance"/>) or + <literal>openjpa.MetaData</literal> for the mapping tool + (see <xref linkend="ref_guide_mapping_mappingtool"/>). + 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. + </para> + </listitem> + <listitem> + <para><indexterm><primary>configuration</primary><secondary>log messages</secondary></indexterm><literal>openjpa.Configuration</literal>: Messages issued + by the configuration framework. + </para> + </listitem> + <listitem> + <para><indexterm><primary>enhancement</primary><secondary>log messages</secondary></indexterm><literal>openjpa.Enhance</literal>: Messages pertaining to + enhancement and runtime class generation. + </para> + </listitem> + <listitem> + <para><indexterm><primary>metadata</primary><secondary>log messages</secondary></indexterm><literal>openjpa.MetaData</literal>: Details about the generation + of metadata and object-relational mappings. + </para> + </listitem> + <listitem> + <para><literal>openjpa.Runtime</literal>: General OpenJPA runtime messages. + </para> + </listitem> + <listitem> + <para><indexterm><primary>Query</primary><secondary>log messages</secondary></indexterm><literal>openjpa.Query</literal>: Messages about queries. + Query strings and any parameter values, if applicable, will be + logged to the <literal>TRACE</literal> level at execution + time. Information about possible performance concerns + will be logged to the <literal>INFO</literal> level. + </para> + </listitem> + <listitem> + <para><indexterm><primary>remote</primary><secondary>log messages</secondary></indexterm><literal>openjpa.Remote</literal>: Remote connection and execution + messages. + </para> + </listitem> + <listitem> + <para><indexterm><primary>caching</primary><secondary>log messages</secondary></indexterm><literal>openjpa.DataCache</literal>: Messages from the L2 data + cache plugins. + </para> + </listitem> + <listitem> + <para><indexterm><primary>JDBC</primary><secondary>log messages</secondary></indexterm><literal>openjpa.jdbc.JDBC</literal>: JDBC connection information. + General JDBC information will be logged to the <literal>TRACE + </literal> level. Information about possible performance + concerns will be logged to the <literal>INFO</literal> level. + </para> + </listitem> + <listitem> + <para><indexterm><primary>SQL</primary><secondary>log messages</secondary></indexterm><literal>openjpa.jdbc.SQL</literal>: This is the most common + logging channel to use. Detailed information about the + execution of SQL statements will be sent to the + <literal>TRACE</literal> level. It is useful to enable this + channel if you are curious about the exact SQL that OpenJPA + issues to the datastore. + </para> + <para> + When using the built-in OpenJPA logging facilities, you can + enable SQL logging by adding <literal>SQL=TRACE</literal> to + your <literal>openjpa.Log</literal> property. + </para> + <para> + OpenJPA can optionally reformat the logged SQL to + make it easier to read. To enable pretty-printing, + add <literal>PrettyPrint=true</literal> to the + <link linkend="openjpa.ConnectionFactoryProperties"><literal> + openjpa.ConnectionFactoryProperties</literal></link> + property. You can control how many columns wide the + pretty-printed SQL will be with the + <literal>PrettyPrintLineLength</literal> property. The default + line length is 60 columns.</para> + <para> + While pretty printing makes things easier to read, it can make + output harder to process with tools like grep. + </para> + <para> + Pretty-printing properties configuration might look like so: + </para> + <programlisting format="linespecific"> +<property name="openjpa.Log" value="SQL=TRACE"/> +<property name="openjpa.ConnectionFactoryProperties" + value="MaxActive=100, PrettyPrint=true, PrettyPrintLineLength=72"/> +</programlisting> + </listitem> + <listitem> + <para><indexterm><primary>schema</primary><secondary>log messages</secondary></indexterm><literal>openjpa.jdbc.Schema</literal>: Details about operations + on the database schema. + </para> + </listitem> + </itemizedlist> + </section> + <section id="ref_guide_logging_openjpa"> + <title>OpenJPA Logging</title> + <indexterm zone="ref_guide_logging_openjpa"> + <primary>logging</primary> + <secondary>default</secondary> + </indexterm> + <para> + By default, OpenJPA uses a basic logging framework with the following + output format: + </para> + <para><literal>millis</literal><literal>level</literal> [<literal>thread name</literal>] <literal>channel</literal> - <literal>message</literal></para> + <para> + For example, when loading an application that uses OpenJPA, a message + like the following will be sent to the <literal>openjpa.Runtime</literal> + channel: + </para> + <programlisting format="linespecific"> +2107 INFO [main] openjpa.Runtime - Starting OpenJPA 4.0.0 +</programlisting> + <para> + The default logging system accepts the following parameters: + </para> + <itemizedlist> + <listitem> + <para><literal>File</literal>: The name of the file to log to, or + <literal>stdout</literal> or <literal>stderr</literal> to send + messages to standard out and standard error, respectively. + By default, OpenJPA sends log messages to standard error. + </para> + </listitem> + <listitem> + <para><literal>DefaultLevel</literal>: The default logging level of + unconfigured channels. Recognized values are <literal> + TRACE, DEBUG, INFO, WARN,</literal> and <literal>ERROR + </literal>. Defaults to <literal>INFO</literal>. + </para> + </listitem> + <listitem> + <para><literal>DiagnosticContext</literal>: A string that will + be prepended to all log messages. + </para> + </listitem> + <listitem> + <para><literal><channel></literal>: Using the last token of + the <link linkend="ref_guide_logging_channels">logging channel + </link> name, you can configure the log level to + use for that channel. See the examples below. + </para> + </listitem> + </itemizedlist> + <example id="ref_guide_logging_openjpa_std_ex"> + <title>Standard OpenJPA Log Configuration</title> + <programlisting format="linespecific"> +<property name="openjpa.Log" value="DefaultLevel=WARN, Runtime=INFO, Tool=INFO"/> +</programlisting> + </example> + <example id="ref_guide_logging_openjpa_sql_ex"> + <title>Standard OpenJPA Log Configuration + All SQL Statements</title> + <programlisting format="linespecific"> +<property name="openjpa.Log" value="DefaultLevel=WARN, Runtime=INFO, Tool=INFO, SQL=TRACE"/> +</programlisting> + </example> + <example id="ref_guide_logging_openjpa_file"> + <title>Logging to a File</title> + <programlisting format="linespecific"> +<property name="openjpa.Log" value="File=/tmp/org.apache.openjpa.log, DefaultLevel=WARN, Runtime=INFO, Tool=INFO"/> +</programlisting> + </example> + </section> + <section id="ref_guide_logging_noop"> + <title>Disabling Logging</title> + <indexterm zone="ref_guide_logging_noop"> + <primary>logging</primary> + <secondary>disabling</secondary> + </indexterm> + <para> + Disabling logging can be useful to analyze performance without + any I/O overhead or to reduce verbosity at the console. To do + this, set the <literal>openjpa.Log</literal> property + to <literal>none</literal>. + </para> + <para> + Disabling logging permanently, however, will cause all warnings + to be consumed. We recommend using one of the + more sophisticated mechanisms described in this chapter. + </para> + </section> + <section id="ref_guide_logging_log4j"> + <title>Log4J</title> + <indexterm zone="ref_guide_logging_log4j"> + <primary>logging</primary> + <secondary>Log4j</secondary> + </indexterm> + <para> + When <literal>openjpa.Log</literal> is set + to <literal>log4j</literal>, OpenJPA will delegate to Log4J for logging. + In a standalone application, Log4J logging levels are + controlled by a resource named <filename>log4j.properties</filename>, + which should be available as a top-level resource (either at the top + level of a jar file, or in the root of one of + the <literal>CLASSPATH</literal> directories). When deploying to + a web or EJB application server, Log4J configuration is often + performed in a <filename>log4j.xml</filename> file instead of a + properties file. For further details on configuring Log4J, + please see the + <ulink url="http://jakarta.apache.org/log4j/docs/manual.html";>Log4J + Manual</ulink>. We present an example + <filename>log4j.properties</filename> file below. + </para> + <example id="ref_guide_logging_log4j_ex"> + <title>Standard Log4J Logging</title> + <programlisting format="linespecific"> +log4j.rootCategory=WARN, console +log4j.category.openjpa.Tool=INFO +log4j.category.openjpa.Runtime=INFO +log4j.category.openjpa.Remote=WARN +log4j.category.openjpa.DataCache=WARN +log4j.category.openjpa.MetaData=WARN +log4j.category.openjpa.Enhance=WARN +log4j.category.openjpa.Query=WARN +log4j.category.openjpa.jdbc.SQL=WARN +log4j.category.openjpa.jdbc.JDBC=WARN +log4j.category.openjpa.jdbc.Schema=WARN + +log4j.appender.console=org.apache.log4j.ConsoleAppender +</programlisting> + </example> + </section> + <section id="ref_guide_logging_commons"> + <title>Apache Commons Logging</title> + <indexterm zone="ref_guide_logging_commons"> + <primary>logging</primary> + <secondary>Apache Commons</secondary> + </indexterm> + <para> + Set the <literal>openjpa.Log</literal> property to <literal>commons + </literal> to use the + <ulink url="http://jakarta.apache.org/commons/logging.html";> + Apache Jakarta Commons Logging</ulink> thin library for issuing + log messages. The Commons Logging libraries act as a wrapper + around a number of popular logging APIs, including the + <ulink url="http://jakarta.apache.org/log4j/docs/index.html";> + Jakarta Log4J</ulink> project, and the native + <ulink url="http://java.sun.com/j2se/1.4/docs/api/java/util/logging/package-summary.html";> + java.util.logging</ulink> package in JDK 1.4. If neither of these + libraries are available, then logging will fall back to using simple + console logging. + </para> + <para> + When using the Commons Logging framework in conjunction with + Log4J, configuration will be the same as was discussed in the + Log4J section above. + </para> + <section id="ref_guide_logging_jdk14"> + <title>JDK 1.4 java.util.logging</title> + <indexterm zone="ref_guide_logging_jdk14"> + <primary>logging</primary> + <secondary>JDK 1.4</secondary> + </indexterm> + <para> + When using JDK 1.4 or higher in conjunction with OpenJPA's + Commons Logging support, logging will proceed through Java's + built-in logging provided by the + <ulink url="http://java.sun.com/j2se/1.4/docs/api/java/util/logging/package-summary.html";> + java.util.logging</ulink> package. For details on + configuring the built-in logging system, please see the + <ulink url="http://java.sun.com/j2se/1.4/docs/guide/util/logging/overview.html";> + Java Logging Overview</ulink>. + </para> + <para> + By default, JDK 1.4's logging package looks in + the <filename> JAVA_HOME/lib/logging.properties</filename> + file for logging configuration. This can be overridden with + the <literal> java.util.logging.config.file</literal> system + property. For example: + </para> + <programlisting format="linespecific"> +java -Djava.util.logging.config.file=mylogging.properties com.company.MyClass +</programlisting> + <example id="ref_guide_logging_jdk14_propfile"> + <title>JDK 1.4 Log Properties</title> + <programlisting format="linespecific"> +# 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.JDBC.level=INFO +openjpa.jdbc.Schema.level=INFO +</programlisting> + </example> + </section> + </section> + <section id="ref_guide_logging_custom"> + <title>Custom Log</title> + <indexterm zone="ref_guide_logging_custom"> + <primary>logging</primary> + <secondary>custom</secondary> + </indexterm> + <para> + If none of available logging systems meet your needs, you can configure + the logging system with a custom logger. You might use + custom logging to integrate with a proprietary logging framework used + by some applications servers, or for logging to a graphical component + for GUI applications. + </para> + <para> + A custom logging framework must include an implementation of the + <ulink url="../apidocs/org/apache/openjpa/lib/log/LogFactory.html"><classname>org.apache.openjpa.lib.log.LogFactory</classname></ulink> interface. + We present a custom <classname>LogFactory</classname> below. + </para> + <example id="ref_guide_logging_custom_ex"> + <title>Custom Logging Class</title> + <programlisting format="linespecific"> +package com.xyz; + +import org.apache.openjpa.lib.log.*; + +public class CustomLogFactory + implements LogFactory +{ + private String _prefix = "CUSTOM LOG"; + + public void setPrefix (String prefix) + { + _prefix = prefix; + } + + public Log getLog (String channel) + { + // Return a simple extension of AbstractLog that will log + // everything to the System.err stream. Note that this is + // roughly equivalent to OpenJPA's default logging behavior. + return new AbstractLog () + { + protected boolean isEnabled (short logLevel) + { + // log all levels + return true; + } + + protected void log (short type, String message, Throwable t) + { + // just send everything to System.err + System.err.println (_prefix + ": " + type + ": " + + message + ": " + t); + } + }; + } +}</programlisting> + </example> + <para> + To make OpenJPA use your custom log factory, set the + <link linkend="openjpa.Log"><literal>openjpa.Log</literal></link> + configuration property to your factory's full class name. Because + this property is a plugin property (see + <xref linkend="ref_guide_conf_plugins"/>), you can also pass parameters + to your factory. For example, to use the example factory above and + set its prefix to "LOG MSG", you would set the + <literal>openjpa.Log</literal> property to the following string: + </para> + <programlisting format="linespecific"> +com.xyz.CustomLogFactory(Prefix="LOG MSG") +</programlisting> + </section> + </chapter>
