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 mk...@apache.org on 2005/04/26 05:42:37 UTC
cvs commit: db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/guides connection.xml repository.xml
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
Re: cvs commit: db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/guides
connection.xml repository.xml
Posted by Martin Kalén <mk...@apache.org>.
Thomas Dudziak wrote:
>>Both connection.xml and repository.xml were encoded in ISO-8859-1/15
>>but had UTF-8 declarations in the XML PI. I have changed the encoding
>>to ISO-8859-15 in both (so Tom can tell med how much in € he will
>>transfer to my bank account). ;-)
>
> Hmm, my account shows -1000€, so I can transfer you that ?!
Um, on second thought, no thanks. :)
> Btw, don't know about IDEA, but for Eclipse there is a decent free XML
> plugin called XmlBuddy which AFAIK honors and checks (?) the encoding.
IDEA has very good integrated XML-editing capabilities for smaller XML
documents (~1MB and smaller in size), it adhers to the file encoding
and is UTF-8 capable. (Since documents are "beautyfied" to the extreme
IDEA will just choke on large document though.)
What I like about jEdit is that it always shows the encoding beeing used
and that it is so easy to switch between encodings for the current buffer
(emacs has the same feature with it's M-x set-buffer-file-coding-system).
In this case, I believe that someone along the line of doc changes
(accidentally) checked the file into CVS with ISO-8859-1 encoding
without changing the XML declaration.
Regards,
Martin
---------------------------------------------------------------------
To unsubscribe, e-mail: ojb-dev-unsubscribe@db.apache.org
For additional commands, e-mail: ojb-dev-help@db.apache.org
Re: cvs commit: db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/guides connection.xml repository.xml
Posted by Thomas Dudziak <to...@gmail.com>.
> Both connection.xml and repository.xml were encoded in ISO-8859-1/15
> but had UTF-8 declarations in the XML PI. I have changed the encoding
> to ISO-8859-15 in both (so Tom can tell med how much in € he will
> transfer to my bank account). ;-)
Hmm, my account shows -1000€, so I can transfer you that ?!
Btw, don't know about IDEA, but for Eclipse there is a decent free XML
plugin called XmlBuddy which AFAIK honors and checks (?) the encoding.
Tom
Re: cvs commit: db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/guides
connection.xml repository.xml
Posted by Martin Kalén <mk...@apache.org>.
Martin Kalén wrote:
>> seems that it's impossible to generate the docs. Forrest fails when
>> validate the documents.
Fixed!
Both connection.xml and repository.xml were encoded in ISO-8859-1/15
but had UTF-8 declarations in the XML PI. I have changed the encoding
to ISO-8859-15 in both (so Tom can tell med how much in € he will
transfer to my bank account). ;-)
Regards,
Martin
P.S. Sorry for not validating the XML outside of my IDE before checking in,
I will try not to forget this on future doc updates.
---------------------------------------------------------------------
To unsubscribe, e-mail: ojb-dev-unsubscribe@db.apache.org
For additional commands, e-mail: ojb-dev-help@db.apache.org
Re: cvs commit: db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/guides
connection.xml repository.xml
Posted by Martin Kalén <mk...@apache.org>.
Armin Waibel wrote:
> seems that it's impossible to generate the docs. Forrest fails when
> validate the documents.
> Think the problem is your name. All documents have UTF-8 encoding, but
> your name include special character. So we have two possibilities:
> - changing encoding in documents to e.g. "ISO-8859-1"
> - write your name without "accent aigu" é --> e
I hope my name is not the problem, but rather the way IntelliJ IDEA's
auto-detection of encoding might have failed to switch the edit buffer
to UTF-8. :-D
Or, it can happen that someone just "invent" the xml declaration
in the PI (ie <?xml ... encoding="foo") although the file in CVS is
in fact _not_ encoded with "foo" charset. (A fault which one will get
away with as long as only USASCII chars are used since they match most
encodings...)
> What do you think?
I will check the document with jEdit (which is really handy in these
cases and can easily convert between all encoding in the JVM)
and fix the encoding problem!
Regards,
Martin
---------------------------------------------------------------------
To unsubscribe, e-mail: ojb-dev-unsubscribe@db.apache.org
For additional commands, e-mail: ojb-dev-help@db.apache.org
Re: cvs commit: db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/guides connection.xml repository.xml
Posted by Thomas Dudziak <to...@gmail.com>.
> seems that it's impossible to generate the docs. Forrest fails when
> validate the documents.
> Think the problem is your name. All documents have UTF-8 encoding, but
> your name include special character. So we have two possibilities:
> - changing encoding in documents to e.g. "ISO-8859-1"
> - write your name without "accent aigu" é --> e
I'd prefer using an ISO encoding, because UTF-8 is not meant for
editing with a simple text editor anyway. But please take ISO-8859-15,
it contains more special characters (e.g. french, finnish, the euro
symbol etc.). FYI the differences are explained in Wikipedia
(http://en.wikipedia.org/wiki/ISO_8859-15).
Tom
---------------------------------------------------------------------
To unsubscribe, e-mail: ojb-dev-unsubscribe@db.apache.org
For additional commands, e-mail: ojb-dev-help@db.apache.org
Re: cvs commit: db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/guides
connection.xml repository.xml
Posted by Armin Waibel <ar...@apache.org>.
Hi Martin,
seems that it's impossible to generate the docs. Forrest fails when
validate the documents.
Think the problem is your name. All documents have UTF-8 encoding, but
your name include special character. So we have two possibilities:
- changing encoding in documents to e.g. "ISO-8859-1"
- write your name without "accent aigu" é --> e
What do you think?
regards,
Armin
---------------------------------------------------------------------
To unsubscribe, e-mail: ojb-dev-unsubscribe@db.apache.org
For additional commands, e-mail: ojb-dev-help@db.apache.org