<?xml version="1.0" encoding="ISO-8859-1"?>
<document url="http://castor.org/howto/how-to-use-castor-in-a-j2ee-cluster.xml">
  <properties>
    <title>How to use Castor JDO's connection proxies</title>
    <abstract>
       General information about using Castor JDO's connection proxies.
    </abstract>
    <status>Final</status>
  </properties>
  <body>
    <title>How to use Castor JDO's connection proxies</title>
    <header>
    </header>

    <section title="Introduction">

        <p>Castor JDO uses the Jakarta Common's Logging package for output information 
        relevant to the execution of a specific JDO operations to a log file. The information 
        output historically included the SQL statements used by Castor to execute the various 
        persistence operations such as loading or updating domain entities. Unfortunately,
        the SQL statements logged did not include any information about the parameters being
        bound to the prepared statements immediately before execution, and hence made it very 
        hard for users of Castor JDO to analyze these in teh case of an issue/problem</p>
        
        <p>To improve this situation, proxy classes for the java.sql.Connection and 
        java.sql.PreparedStatement interfaces have been added, to allow for complete and better JDBC 
        statements to be output to the log files. As this might impose a performance penalty 
        at run-time, we have allowed for this to be turned off completely through the 
        standard Castor property file. </p>
        
        <p>A new property has been added to the Castor property file (castor.properties) 
        to allow configuration of this feature.</p>

    </section>

    <section title="Intended Audience">

        <p>Anyone who wants to use the new JDBC proxy classes with Castor JDO selectively, 
         i.e. enabling and disabling their use.</p>
        
        <p>The example given describes how to turn the use of the proxy classes on/off.</p>
        
    </section>
    
    <section title="Prerequisites">

        <p>You should have a valid <tt>castor.properties</tt> file as part of your application.</p>

    </section>

    <section title="Steps">

        <p>Here is how to proceed.</p>

        <section title="Enable the use of the JDBC proxy classes">

            <p>To enable the use of the JDBC proxy classes described above, please add the 
            following section to your <tt>castor.properties</tt> file.</p>

                <code-panel>
  # True if JDBC proxy classes should be used to enable more detailed logging output of SQL
  # statements; false otherwise (logging of SQL statements will be turned off completely).
  #
  org.exolab.castor.persist.useProxy=true
                </code-panel>

            <p>This instructs Castor JDO to use the JDBC proxy classes and to output 
            full information about the SQL statements used at run-time. When disabled, 
            no logging of SQL statements will occur al all.</p>

        </section>

    </section>
    
    <section title="References">

        <ul>
            <li><a href="conf-lib.html">Configuration of Castor</a></li>
            <li><a href="http://jakarta.apache.org/commons/logging/">Jakarta Common Logging</a></li>
        </ul>
        
    </section>


    </body>
</document>