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