You are viewing a plain text version of this content. The canonical link for it is here.
Posted to ojb-dev@db.apache.org by ar...@apache.org on 2004/05/05 15:15:30 UTC

cvs commit: db-ojb/forrest/src/documentation/content/xdocs/docu repository.xml faq.xml connection.xml basic-technique.xml

arminw      2004/05/05 06:15:30

  Modified:    forrest/src/documentation/content/xdocs site.xml
               forrest/src/documentation/content/xdocs/docu repository.xml
                        faq.xml connection.xml basic-technique.xml
  Log:
  add more docs (connection handling section), update docs
  
  Revision  Changes    Path
  1.9       +9 -3      db-ojb/forrest/src/documentation/content/xdocs/site.xml
  
  Index: site.xml
  ===================================================================
  RCS file: /home/cvs/db-ojb/forrest/src/documentation/content/xdocs/site.xml,v
  retrieving revision 1.8
  retrieving revision 1.9
  diff -u -r1.8 -r1.9
  --- site.xml	4 May 2004 14:19:04 -0000	1.8
  +++ site.xml	5 May 2004 13:15:30 -0000	1.9
  @@ -69,6 +69,7 @@
               <faq label="FAQ's" href="faq.html" description="Frequently Asked Questions">
                   <apis href="#apis"/>
                   <optimistic-locking href="#optimisticLocking"/>
  +                <performSQL href="#performSQL"/>
               </faq>
               <javadoc label="Javadoc" href="ext:javadoc" description=""/>
           </start>
  @@ -93,6 +94,7 @@
               <repository label="Repository Metadata" href="repository.html" description="">
                   <descriptor-repository href="#descriptor-repository"/>
                   <jdbc-connection-descriptor href="#jdbc-connection-descriptor"/>
  +                <connection-pool href="#connection-pool"/>
                   <class-descriptor href="#class-descriptor"/>
                   <field-descriptor href="#field-descriptor"/>
                   <custom-attribute href="#custom-attribute"/>
  @@ -129,7 +131,10 @@
               <deployment label="Deployment" href="deployment.html" description="">
                   <additional-jars href="#additional-jars"/>
               </deployment>
  -            <connection label="Connection handling" href="connection.html" description=""/>
  +            <connection label="Connection handling" href="connection.html" description="">
  +                <connection-pooling href="#connection-pooling"/>
  +                <obtain-connection href="#obtain-connection"/>
  +            </connection>
               <object-cache label="Object Cache" href="objectcache.html" description=""/>
               <sequence-manager label="Sequence Manager" href="sequencemanager.html" description=""/>
               <lock-manager label="Lock Manager" href="lockmanager.html" description="">
  @@ -166,7 +171,6 @@
   
       <!-- Usage example: <link href="ext:jakarta/tomcat">XXX</link> -->
       <external-refs>
  -        <!-- TODO fix this link -->
           <api href="api/">
               <javadoc href="index.html"/>
               <metadata-manager href="org/apache/ojb/broker/metadata/MetadataManager.html"/>
  @@ -218,6 +222,8 @@
           <jakarta href="http://jakarta.apache.org/">
               <tomcat href="tomcat/"/>
               <commons-logging href="commons/logging/"/>
  +            <commons-pool href="commons/pool/"/>
  +            <commons-dbcp href="commons/dbcp/"/>
               <jcs href="http://jakarta.apache.org/turbine/jcs/index.html"/>
               <jetspeed-2 href="http://portals.apache.org/jetspeed-2/"/>
           </jakarta>
  
  
  
  1.5       +2 -2      db-ojb/forrest/src/documentation/content/xdocs/docu/repository.xml
  
  Index: repository.xml
  ===================================================================
  RCS file: /home/cvs/db-ojb/forrest/src/documentation/content/xdocs/docu/repository.xml,v
  retrieving revision 1.4
  retrieving revision 1.5
  diff -u -r1.4 -r1.5
  --- repository.xml	4 May 2004 14:19:03 -0000	1.4
  +++ repository.xml	5 May 2004 13:15:30 -0000	1.5
  @@ -438,7 +438,7 @@
                   </section>
               </section>
   
  -
  +            <anchor id="connection-pool"/>
               <section>
                   <title>connection-pool</title>
                   <p>
  
  
  
  1.5       +8 -60     db-ojb/forrest/src/documentation/content/xdocs/docu/faq.xml
  
  Index: faq.xml
  ===================================================================
  RCS file: /home/cvs/db-ojb/forrest/src/documentation/content/xdocs/docu/faq.xml,v
  retrieving revision 1.4
  retrieving revision 1.5
  diff -u -r1.4 -r1.5
  --- faq.xml	27 Apr 2004 20:32:29 -0000	1.4
  +++ faq.xml	5 May 2004 13:15:30 -0000	1.5
  @@ -1066,23 +1066,8 @@
               </question>
               <answer>
                   <p>
  -                    OJB does connection pooling per default, expect for datasources. Datasources never will be pooled.
  -                    <br/>
  -                    Responsible for managing the connections in OJB are implementations of the
  -                    <code>org.apache.ojb.broker.accesslayer.ConnectionFactory.java</code>
  -                    interface. There are several implementations shipped with OJB called
  -                    <code>org.apache.ojb.broker.accesslayer.ConnectionFactoryXXXImpl.java</code>.
  -                    You can find among other things a none pooling implementation and a implementation
  -                    using jakarta-DBCP api.
  -                    <br/>
  -                    To manage the connection pooling define in your
  -                    <code>jdbc-connection-descriptor</code> a
  -                    <code>connection-pool</code> element. Here you can specify which
  -                    <code>ConnectionFactory</code> implementation
  -                    should be used. More info see
  -                    <link href="site:repository">repository section</link>
  -                    or
  -                    <link href="ext:ojb/repository.dtd">repository.dtd</link>.
  +                    Please have a look in section
  +                    <link href="site:connection/connection-pooling">Connection Handling</link>.
                   </p>
               </answer>
           </faq>
  @@ -1094,42 +1079,8 @@
               </question>
               <answer>
                   <p>
  -                    The PB-api enabled the possibility to obtain a connection from the current
  -                    used
  -                    <code>PersistenceBroker</code> instance:
  -                </p>
  -                <source>
  -PersistenceBroker broker = PersistenceBrokerFactory.
  -createPersistenceBroker(myKey);
  -broker.beginTransaction();
  -// do something
  -
  -Connection con = broker.serviceConnectionManager().getConnection();
  -// perform your connction action and do more
  -
  -broker.commitTransaction();
  -broker.close();
  -                </source>
  -                <p>
  -                    Do not close or commit the connection, this will be done by OJB when tx commit/abort
  -                    was called.
  -                </p>
  -                <p>
  -                    If no transaction was running, it is possible to release connection after
  -                    use by calling
  -                </p>
  -                <source>
  -pBroker.serviceConnectionManager().releaseConnection();
  -                </source>
  -                <p>
  -                    This cleanup the used connection, e.g. returns it to pool. (
  -                    <em>Never do a con.close() call!!</em>)
  -                    <br/>
  -                    If you don't do any connection cleanup, at the latest connection was released on PB.close() call.
  -                </p>
  -                <p>
  -                    See ditto
  -                    <link href="#performSQL">Is it possible to perform my own sql-queries in OJB?</link>.
  +                    Please have a look in section
  +                    <link href="site:connection/obtain-connection">Connection Handling</link>.
                   </p>
               </answer>
           </faq>
  @@ -1157,9 +1108,7 @@
   
   Iterator iter2 = broker.getIteratorByQuery(q2);
   // or
  -Collection col2 = broker.getCollectionByQuery(q2);
  -                </source>
  -
  +Collection col2 = broker.getCollectionByQuery(q2);</source>
               </answer>
           </faq>
   
  @@ -1175,10 +1124,9 @@
   <?xml version="1.0" encoding="UTF-8"?>
   <!DOCTYPE descriptor-repository SYSTEM "repository.dtd">
   
  -<descriptor-repository version="0.9.9" isolation-level="read-uncommitted">
  +<descriptor-repository version="1.0" isolation-level="read-uncommitted">
   
  -</descriptor-repository>
  -                ]]></source>
  +</descriptor-repository>]]></source>
                   <p>
                       Now you have to declare the
                       <code>jdbc-connection-descriptor</code> and
  
  
  
  1.2       +208 -1    db-ojb/forrest/src/documentation/content/xdocs/docu/connection.xml
  
  Index: connection.xml
  ===================================================================
  RCS file: /home/cvs/db-ojb/forrest/src/documentation/content/xdocs/docu/connection.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- connection.xml	22 Apr 2004 19:29:50 -0000	1.1
  +++ connection.xml	5 May 2004 13:15:30 -0000	1.2
  @@ -32,16 +32,223 @@
               </p>
           </section>
   
  +        <anchor id="connection-factory"/>
           <section><title>ConnectionFactory</title>
               <p>
  +                The <code>org.apache.ojb.broker.accesslayer.ConnectionFactory</code> interface implementation
  +                is a pluggable component (via the <link href="ext:ojb.properties">OJB.properties</link> file
  +                - more about <link href="site:ojb-properties">the OJB.properties file here</link>) responsible
  +                for creation/lookup and release of connections.
  +            </p>
  +            <source><![CDATA[
  +public interface ConnectionFactory
  +{
  +    Connection lookupConnection(JdbcConnectionDescriptor jcd) throws LookupException;
  +
  +    void releaseConnection(JdbcConnectionDescriptor jcd, Connection con);
   
  +    void releaseAllResources();
  +}]]></source>
  +            <p>
  +                To enable a specific <em>ConnectionFactory</em> implementation class in <em>OJB.properties</em>
  +                file, set property <em>ConnectionFactoryClass</em>:
  +            </p>
  +            <source><![CDATA[
  +ConnectionFactoryClass=org.apache.ojb.broker.accesslayer.ConnectionFactoryPooledImpl]]></source>
  +            <p>
  +                OJB was shipped with a bunch of different implementation classes which can be used in
  +                different situations, e.g. creation of connection instances is costly, so pooling
  +                of connection will increase performance.
               </p>
  +            <p>
  +                To make it more easier to implement own <em>ConnectionFactory</em> classes an abstract base
  +                class called <code>org.apache.ojb.broker.accesslayer.ConnectionFactoryAbstractImpl</code> exists,
  +                most shipped implementation classes inherited from this class.
  +            </p>
  +            <note>
  +                All shipped implementation with support for connection pooling only pool direct obtained connections,
  +                <em>DataSources</em> will <strong>never</strong> be pooled.
  +            </note>
  +            <section>
  +                <title>ConnectionFactoryPooledImpl</title>
  +                <p>
  +                    An <em>ConnectionFactory</em> implementation using <link href="ext:commons-pool">commons-pool</link>
  +                    to pool the requested connections. On lookup call a connection was borrowed from pool and
  +                    returned on the release call. This implementation was used
  +                    as <em>default</em> setting in <link href="ext:ojb.properties">OJB.properties</link> file.
  +                </p>
  +                <p>
  +                    This implementation allows a wide range off different settings, more info about the configuration
  +                    properties <link href="site:repository/connection-pool">can be found in
  +                    metadata repository <em>connection-pool</em> section</link>.
  +                </p>
  +            </section>
  +
  +            <section>
  +                <title>ConnectionFactoryNotPooledImpl</title>
  +                <p>
  +                    The name is programm, this implementation creates a new connection on each request
  +                    and close it on release call. All
  +                    <link href="site:repository/connection-pool"><em>connection-pool</em></link> settings
  +                    are ignored by this implementation.
  +                </p>
  +            </section>
  +
  +            <section>
  +                <title>ConnectionFactoryManagedImpl</title>
  +                <p>
  +                    This is a specific implementation for use in <em>managed environments</em> like J2EE conform
  +                    application server. In managed environments it is <strong>mandatory</strong> to use
  +                    <em>DataSource</em> provided by the application server.
  +                </p>
  +                <p>
  +                    All
  +                    <link href="site:repository/connection-pool"><em>connection-pool</em></link> settings
  +                    are ignored by this implementation.
  +                </p>
  +            </section>
  +
  +            <section>
  +                <title>ConnectionFactoryDBCPImpl</title>
  +                <p>
  +                    An implementation using <link href="ext:commons-dbcp">commons-dbcp</link> to pool
  +                    the connections.
  +                </p>
  +                <p>
  +                    This implementation allows a wide range off different settings, more info about the configuration
  +                    properties <link href="site:repository/connection-pool">can be found in
  +                    metadata repository <em>connection-pool</em> section</link>.
  +                </p>
  +            </section>
  +
           </section>
   
           <section><title>ConnectionManager</title>
               <p>
  +                The <code>org.apache.ojb.broker.accesslayer.ConnectionManagerIF</code> interface implementation
  +                is a pluggable component (via the <link href="ext:ojb.properties">OJB.properties</link> file
  +                - more about <link href="site:ojb-properties">the OJB.properties file here</link>) responsible
  +                for managing the connection usage lifecycle and connection status (commit/rollback of connections).
  +            </p>
  +            <source><![CDATA[
  +public interface ConnectionManagerIF
  +{
  +    JdbcConnectionDescriptor getConnectionDescriptor();
  +
  +    Platform getSupportedPlatform();
  +
  +    boolean isAlive(Connection conn);
  +
  +    Connection getConnection() throws LookupException;
  +
  +    boolean isInLocalTransaction();
  +
  +    void localBegin();
   
  +    void localCommit();
  +
  +    void localRollback();
  +
  +    void releaseConnection();
  +
  +    void setBatchMode(boolean mode);
  +
  +    boolean isBatchMode();
  +
  +    void executeBatch();
  +
  +    void executeBatchIfNecessary();
  +
  +    void clearBatch();
  +}]]></source>
  +            <p>
  +                The <em>ConnectionManager</em> was used by the <em>PersistenceBroker</em> to handle
  +                connection usage lifecycle.
               </p>
  +        </section>
  +
  +
  +        <section>
  +            <title>Questions and Answers</title>
  +
  +            <anchor id="connection-pooling"/>
  +            <section>
  +                <title>How does OJB handle connection pooling?</title>
  +                <p>
  +                    OJB does connection pooling per default, expect for datasources.
  +                    Datasources never will be pooled.
  +                </p>
  +                <p>
  +                    Responsible for managing the connections in OJB are implementations of the
  +                    <code>org.apache.ojb.broker.accesslayer.ConnectionFactory.java</code>
  +                    interface. There are several implementations shipped with OJB called
  +                    <code>org.apache.ojb.broker.accesslayer.ConnectionFactoryXXXImpl.java</code>.
  +                    You can find among other things a none pooling implementation and a implementation
  +                    using jakarta-DBCP api.
  +                </p>
  +                <p>
  +                    To manage the connection pooling define in your
  +                    <link href="site:repository/jdbc-connection-descriptor"><em>jdbc-connection-descriptor</em></link>
  +                    a
  +                    <link href="site:repository/connection-pool"><em>connection-pool</em></link> element.
  +                    Here you can specify the properties for the used <em>ConnectionFactory</em> implementation.
  +                    More common info see <link href="site:repository">repository section</link>
  +                    or in <link href="ext:ojb/repository.dtd">repository.dtd</link>.
  +                </p>
  +            </section>
  +
  +            <anchor id="obtain-connection"/>
  +            <section>
  +                <title>Can I directly obtain a
  +                <code>java.sql.Connection</code> within OJB?</title>
  +                <p>
  +                    The PB-api enabled the possibility to obtain a connection from the current
  +                    used
  +                    <code>PersistenceBroker</code> instance:
  +                </p>
  +                <source>
  +PersistenceBroker broker = PersistenceBrokerFactory.
  +createPersistenceBroker(myKey);
  +broker.beginTransaction();
  +// do something
  +
  +Connection con = broker.serviceConnectionManager().getConnection();
  +// perform your connction action and do more
  +
  +broker.commitTransaction();
  +broker.close();
  +                </source>
  +                <note>
  +                    Do not close or commit the connection, this will be done by OJB when PersistenceBroker
  +                    commit-/abortTransaction was called.
  +                </note>
  +                <p>
  +                    If no transaction was running, it is possible to release connection after
  +                    use  by hand when calling
  +                </p>
  +                <source>
  +pBroker.serviceConnectionManager().releaseConnection();
  +                </source>
  +                <p>
  +                    This call cleanup the used connection by pass the instance to release method
  +                    of <link href="#connection-factory"><em>ConnectionFactory</em></link> (this will e.g.
  +                    return connection it to pool or close it).
  +                    If you don't do any connection cleanup at the latest the connection will be released
  +                    on PB.close() call.
  +                </p>
  +                <note>
  +                    Never do a <code>Connection.close()</code> call on the obtained connection instance
  +                    by hand!!
  +                    <br/>
  +                    This will be handled by the
  +                    <link href="#connection-factory"><em>ConnectionFactory</em></link>.
  +                </note>
  +                <p>
  +                    Users who interested in this section also interested in
  +                    <link href="site:faq/performSQL">'Is it possible to perform my own sql-queries in OJB?'</link>.
  +                </p>
  +            </section>
  +
           </section>
       </body>
   </document>
  
  
  
  1.4       +7 -4      db-ojb/forrest/src/documentation/content/xdocs/docu/basic-technique.xml
  
  Index: basic-technique.xml
  ===================================================================
  RCS file: /home/cvs/db-ojb/forrest/src/documentation/content/xdocs/docu/basic-technique.xml,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- basic-technique.xml	28 Apr 2004 08:03:52 -0000	1.3
  +++ basic-technique.xml	5 May 2004 13:15:30 -0000	1.4
  @@ -994,9 +994,12 @@
                       <em>false</em>
                   </li>
               </ul>
  -            <p>
  -                <strong>These default settings are mandatory for proper operation of the ODMG and JDO implementation.</strong>
  -            </p>
  +            <note>
  +                It is mandatory when using the top-level API's (ODMG, OTM, JDO) to set the
  +                <em>default</em> auto-XXX settings (or don't specify the attribute) for proper work.
  +                <br/>
  +                This may change in future.
  +            </note>
               <p>
                   The attribute
                   <em>auto-update</em> and
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: ojb-dev-unsubscribe@db.apache.org
For additional commands, e-mail: ojb-dev-help@db.apache.org