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="[EMAIL PROTECTED]"/>
+ <person name="Martin Kal�n" email="[EMAIL PROTECTED]"/>
</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="[EMAIL PROTECTED]"/>
<person name="Armin Waibel" email="[EMAIL PROTECTED]"/>
<person name="Thomas Dudziak" email="[EMAIL PROTECTED]"/>
+ <person name="Martin Kal�n" email="[EMAIL PROTECTED]"/>
</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: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
