db-ojb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From mka...@apache.org
Subject cvs commit: db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/guides connection.xml repository.xml
Date Tue, 26 Apr 2005 03:42:37 GMT
mkalen      2005/04/25 20:42:37

  Modified:    src/doc/forrest/src/documentation/content/xdocs/docu/guides
                        Tag: OJB_1_0_RELEASE connection.xml repository.xml
  Log:
  Update connection handling docs (specifically changes made in OJB-14, OJB-31).
  
  Revision  Changes    Path
  No                   revision
  No                   revision
  1.1.2.3   +107 -81   db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/guides/connection.xml
  
  Index: connection.xml
  ===================================================================
  RCS file: /home/cvs/db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/guides/connection.xml,v
  retrieving revision 1.1.2.2
  retrieving revision 1.1.2.3
  diff -u -r1.1.2.2 -r1.1.2.3
  --- connection.xml	24 Mar 2005 17:54:17 -0000	1.1.2.2
  +++ connection.xml	26 Apr 2005 03:42:37 -0000	1.1.2.3
  @@ -1,6 +1,6 @@
   <?xml version="1.0" encoding="UTF-8"?>
   <!--
  -  Copyright 2002-2004 The Apache Software Foundation
  +  Copyright 2002-2005 The Apache Software Foundation
   
     Licensed under the Apache License, Version 2.0 (the "License");
     you may not use this file except in compliance with the License.
  @@ -19,9 +19,10 @@
   
   <document>
       <header>
  -        <title>OJB - Connection Handling</title>
  +        <title>Connection Handling</title>
           <authors>
               <person name="Armin Waibel" email="arminw@apache.org"/>
  +            <person name="Martin KalÚn" email="mkalen@apache.org"/>
           </authors>
       </header>
   
  @@ -29,8 +30,8 @@
           <section>
               <title>Introduction</title>
               <p>
  -                In this section the connection handling within OJB will be described. OJB
use two
  -                classes which share the connection management:
  +                In this section the connection handling within OJB is described.
  +                The connection management is implemented through two OJB interfaces:
               </p>
               <ul>
                   <li><code>org.apache.ojb.broker.accesslayer.ConnectionFactory</code></li>
  @@ -56,74 +57,90 @@
       void releaseAllResources();
   }]]></source>
               <p>
  -                To enable a specific <em>ConnectionFactory</em> implementation
class in <em>OJB.properties</em>
  -                file, set property <em>ConnectionFactoryClass</em>:
  +                To enable a specific <em>ConnectionFactory</em> implementation
class in the
  +                <em>OJB.properties</em> file, set property <em>ConnectionFactoryClass</em>.
Default:
               </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.
  +                OJB is shipped with several different implementation classes for use in
  +                different situations. The default implementation for example, will pool
  +                created Connection instances for increased performance (since instance
creation
  +                normally makes a database server roundtrip and thus is costly).
               </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.
  +                To make it more easier to implement your own <em>ConnectionFactory</em>
class,
  +                an abstract base class called
  +                <code>org.apache.ojb.broker.accesslayer.ConnectionFactoryAbstractImpl</code>
exists,
  +                most shipped implementation classes inherit 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.
  +                All shipped implementations of <em>ConnectionFactory</em> with
support for
  +                connection pooling will only use object pools for connections obtained
directly
  +                from the JDBC DriverManager. If you are using a <em>DataSource</em>
configuration,
  +                the JNDI DataSource is responsible for pooling.
               </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.
  +                    A <em>ConnectionFactory</em> implementation using
  +                    <link href="ext:commons-pool">commons-pool</link> to pool
the Connection
  +                    instances. On lookupConnection a Connection instance is borrowed from
the
  +                    object pool, and returned on the releaseConnection call.
  +                    This implementation is used as <em>default</em> setting
in the
  +                    <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>.
  +                    This implementation allows a wide range of different settings,
  +                    more info about the configuration properties can be found in the metadata
  +                    repository
  +                    <link href="site:repository/connection-pool"><em>connection-pool</em></link>
  +                    section.
                   </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.
  +                    Implementation that creates a new Connection instance on each lookupConnection
  +                    call and closes (destroys) it on releaseConnection. 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.
  +                    Implementation specifically for use in <em>managed environments</em>
like J2EE
  +                    conformant application servers. In managed environments it is
  +                    <strong>mandatory</strong> to use <em>DataSource</em>
configuration, with
  +                    Connection objects provided by the application server. OJB will not
control
  +                    Connection properties or transaction handling when using this implementation.
                   </p>
                   <p>
                       All
  -                    <link href="site:repository/connection-pool"><em>connection-pool</em></link>
settings
  -                    are ignored by this implementation.
  +                    <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.
  +                    Implementation using <link href="ext:commons-dbcp">commons-dbcp</link>
to pool
  +                    the Connection instances. Since DBCP is using
  +                    <link href="ext:commons-pool">commons-pool</link> internally,
this
  +                    implementation is very similar to <em>ConnectionFactoryPooledImpl</em>,
but
  +                    permits additional configuration for logging abandoned Connection instances
  +                    (usable under development for detecting bad programming patterns).
                   </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>.
  +                    This implementation allows a wide range of different settings,
  +                    more info about the configuration properties can be found in the metadata
  +                    repository
  +                    <link href="site:repository/connection-pool"><em>connection-pool</em></link>
  +                    section.
                   </p>
               </section>
   
  @@ -168,7 +185,7 @@
       void clearBatch();
   }]]></source>
               <p>
  -                The <em>ConnectionManager</em> was used by the <em>PersistenceBroker</em>
to handle
  +                The <em>ConnectionManager</em> is used by the <em>PersistenceBroker</em>
to handle
                   connection usage lifecycle.
               </p>
           </section>
  @@ -181,36 +198,39 @@
               <section>
                   <title>How does OJB handle connection pooling?</title>
                   <p>
  -                    OJB does connection pooling per default, expect for datasources.
  -                    Datasources never will be pooled.
  +                    OJB does connection pooling per default, except for datasources that
are
  +                    never pooled internally by OJB.
  +                    Pooling of Connection instances when configuring OJB with DataSource
  +                    lookup must be configured and performed in the DataSource provider.
                   </p>
                   <p>
  -                    Responsible for managing the connections in OJB are implementations
of the
  +                    The 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>.
  +                    interface are responsible for managing the connections in OJB.
  +                    There are several implementations shipped with OJB called
  +                    <code>org.apache.ojb.broker.accesslayer.ConnectionFactoryImpl.java</code>.
  +                    There is, among others, a non-pooling implementation and an implementation
  +                    using Commons DBCP API.
  +                </p>
  +                <p>
  +                    Configuration of the connection pooling is specified using the
  +                    <link href="site:repository/connection-pool"><em>connection-pool</em></link>
  +                    element for each
  +                    <link href="site:repository/jdbc-connection-descriptor"><em>jdbc-connection-descriptor</em></link>.
  +                    The <em>connection-pool</em> element can be configured
with properties for
  +                    the specific <em>ConnectionFactory</em> implementation
or JDBC driver used.
  +                    For general information about the configuration, see the
  +                    <link href="site:repository">repository section</link>
or read the comments 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>
  +                <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:
  +                    It is possible to obtain a Connection using the PB API and a
  +                    <code>PersistenceBroker</code> instance. Example:
                   </p>
                   <source><![CDATA[
   PersistenceBroker broker = PersistenceBrokerFactory.createPersistenceBroker(myKey);
  @@ -218,47 +238,53 @@
   // do something
   
   Connection con = broker.serviceConnectionManager().getConnection();
  -// perform your connction action and do more
  +// perform your connection action and do more
   // close the created statement and result set
   
   broker.commitTransaction();
   broker.close();]]></source>
                   <p>
  -                    After obtain the connection with
  -                    <code>broker.serviceConnectionManager().getConnection()</code>,
the connection can be used
  -                    in a 'normal' way. The user is responsible for cleanup of created statements
and result
  -                    sets, so close statements and result sets after use.
  +                    After obtaining a Connection with
  +                    <code>broker.serviceConnectionManager().getConnection()</code>,
  +                    the connection can be used for any JDBC operations (except for transaction
  +                    handling, more on this below).
  +                    The user is responsible for cleanup of created Statement and ResultSet
  +                    instances, so be sure to guard your call with a finally clause and
close
  +                    resources after use.
                   </p>
                   <p>
  -                    For read-only operations there is no need to start a PB-tx.
  +                    For read-only operations there is no need to start a PB transaction
  +                    as in the example.
                   </p>
                   <note>
  -                    Do not commit the connection instance, this will be done by OJB when
PersistenceBroker
  -                    commit-/abortTransaction was called.
  -                    <br/>
  -                    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>.
  +                    Do not commit any transactions on the Connection level, this should
be left to
  +                    OJB's PB API and will be performed automatically by calling PersistenceBroker
  +                    commit-/abortTransaction methods.
  +                </note>
  +                <note>
  +                    Do not call <code>Connection.close()</code> on the obtained
Connection,
  +                    this should be left to OJB's
  +                    <link href="#connection-factory"><em>ConnectionFactory</em></link>
and will be
  +                    performed automatically when calling <code>broker.close()</code>.
                   </note>
                   <p>
  -                    If <strong>no</strong> transaction is running, it is possible
to release a connection after
  -                    use by hand with call:
  +                    If <strong>no</strong> transaction is running, it is possible
to release a
  +                    connection "by hand" after use by calling:
                   </p>
                   <source><![CDATA[
  -pBroker.serviceConnectionManager().releaseConnection();]]></source>
  +broker.serviceConnectionManager().releaseConnection();]]></source>
                   <p>
  -                    This call cleanup the used connection and 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).
  +                    This call performs cleanup operations on the used connection and pass
the
  +                    instance to the release method of
  +                    <link href="#connection-factory"><em>ConnectionFactory</em></link>
(this will
  +                    e.g. return the connection to pool or close it).
                   </p>
                   <p>
  -                    If you don't do any connection cleanup at the latest the connection
will be released
  -                    on PB.close() call.
  +                    If you do not do any connection cleanup, the connection will at the
latest be
  +                    released when calling <code>broker.close()</code>.
                   </p>
                   <p>
  -                    Users who interested in this section also interested in
  +                    Users who are interested in this section might also be interested in
                       <link href="site:faq/performSQL">'Is it possible to perform my
own sql-queries in OJB?'</link>.
                   </p>
               </section>
  
  
  
  1.1.2.6   +36 -11    db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/guides/repository.xml
  
  Index: repository.xml
  ===================================================================
  RCS file: /home/cvs/db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/guides/repository.xml,v
  retrieving revision 1.1.2.5
  retrieving revision 1.1.2.6
  diff -u -r1.1.2.5 -r1.1.2.6
  --- repository.xml	24 Mar 2005 17:54:17 -0000	1.1.2.5
  +++ repository.xml	26 Apr 2005 03:42:37 -0000	1.1.2.6
  @@ -1,6 +1,6 @@
   <?xml version="1.0" encoding="UTF-8"?>
   <!--
  -  Copyright 2002-2004 The Apache Software Foundation
  +  Copyright 2002-2005 The Apache Software Foundation
   
     Licensed under the Apache License, Version 2.0 (the "License");
     you may not use this file except in compliance with the License.
  @@ -26,6 +26,7 @@
               <person name="Brian McCallister" email="brianm@apache.org"/>
               <person name="Armin Waibel" email="arminw@apache.org"/>
               <person name="Thomas Dudziak" email="tomdz@apache.org"/>
  +            <person name="Martin KalÚn" email="mkalen@apache.org"/>
           </authors>
       </header>
   
  @@ -443,18 +444,42 @@
               <section>
                   <title>connection-pool</title>
                   <p>
  -                    The
  -                    <em>connection-pool</em> element specifies the connection
pooling parameter. More info
  -                    about the
  -                    <link href="site:connection">connection handling can be found
here</link>.
  +                    The <em>connection-pool</em> element specifies the connection
pooling
  +                    and low-level JDBC driver parameters. More info about the
  +                    <link href="site:connection">connection handling</link>.
  +                </p>
  +                <p>
  +                    Use the
  +                    <link href="#custom-attribute"><em>attribute</em></link>
element to set
  +                    JDBC-level properties.
  +                </p>
  +                <p>
  +                    All attributes with names starting with "jdbc." will be
  +                    passed (without jdbc. prefix) to the JDBC DriverManager
  +                    when creating new Connection objects.
  +                    (Ignored when acquiring Connection objects through
  +                     JNDI DataSource lookup or in managed environments.)
  +                </p>
  +                <p>
  +                    JDBC-level attributes used internally in OJB:
  +                </p>
  +                <p>
  +                    <em>fetchSize</em> - sets a hint in the JDBC driver not
to fetch more than
  +                    specified number of rows per server round trip for any ResultSet.
  +                    Setttings different than the default (0) are especially
  +                    useful to reduce memory footprint when using drivers
  +                    that defaults to not using server-side cursors and
  +                    retrieves all rows to the JDBC client-side driver buffer.
  +                    PostgreSQL JDBC driver is a well-known example of this.
  +                    Many JDBC drivers will ignore this hint.
                   </p>
                   <source><![CDATA[
  -<!ELEMENT connection-pool (documentation? )
  ->
  -                    ]]></source>
  +<!ELEMENT connection-pool (
  +    documentation?,
  +    attribute* )
  +>]]></source>
                   <p>
  -                    Valid attributes for the
  -                    <em>connection-pool</em> element are:
  +                    Valid attributes for the <em>connection-pool</em> element
are:
                   </p>
                   <source><![CDATA[
   <!ATTLIST connection-pool
  
  
  

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


Mime
View raw message