arminw 2005/08/17 08:37:09
Modified: src/doc/forrest/src/documentation/content/xdocs/docu/guides
Tag: OJB_1_0_RELEASE advanced-technique.xml
connection.xml deployment.xml
Log:
update docs, describe new connection handling in managed enviroments
Revision Changes Path
No revision
No revision
1.1.2.4 +7 -6
db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/guides/advanced-technique.xml
Index: advanced-technique.xml
===================================================================
RCS file:
/home/cvs/db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/guides/advanced-technique.xml,v
retrieving revision 1.1.2.3
retrieving revision 1.1.2.4
diff -u -r1.1.2.3 -r1.1.2.4
--- advanced-technique.xml 30 Apr 2005 19:38:09 -0000 1.1.2.3
+++ advanced-technique.xml 17 Aug 2005 15:37:09 -0000 1.1.2.4
@@ -754,7 +754,7 @@
implementation must be used (see <link
href="#persistent-field">below</link>).
This class is used by OJB to access the fields when
storing/loading objects. Per default,
OJB uses a direct access implementation
-
(<code>org.apache.ojb.broker.metadata.fieldaccess.PersistentFieldDirectAccessImpl</code>)
which
+
(<code>org.apache.ojb.broker.metadata.fieldaccess.PersistentFieldDirectImpl</code>)
which
requires actual fields to be present.<br/>
In our case, we need an implementation that rather uses
the accessor methods. Since the
<code>PersistentField</code> setting is (currently)
global, you have to check whether
@@ -965,7 +965,7 @@
# and don't have to be declared public or protected
# - PersistentFieldPrivilegedImpl
# Same as above, but does cooperate with AccessController and do not
-# suppress the java language access check.
+# suppress the java language access check (but is slow compared with
direct access).
# - PersistentFieldIntrospectorImpl
# uses JavaBeans compliant calls only to access persistent attributes.
# No Reflection is needed. But for each attribute xxx there must be
@@ -977,14 +977,15 @@
# for each field determines upon first access how to access this
particular field
# (directly, as a bean, as a dyna bean) and then uses that strategy
#
-PersistentFieldClass=org.apache.ojb.broker.metadata.fieldaccess.PersistentFieldDirectAccessImpl
+#PersistentFieldClass=org.apache.ojb.broker.metadata.fieldaccess.PersistentFieldDirectImpl
#PersistentFieldClass=org.apache.ojb.broker.metadata.fieldaccess.PersistentFieldPrivilegedImpl
#PersistentFieldClass=org.apache.ojb.broker.metadata.fieldaccess.PersistentFieldIntrospectorImpl
-#PersistentFieldClass=org.apache.ojb.broker.metadata.fieldaccess.PersistentFieldDynaBeanAccessImpl
+#PersistentFieldClass=org.apache.ojb.broker.metadata.fieldaccess.PersistentFieldDynaBeanImpl
#PersistentFieldClass=org.apache.ojb.broker.metadata.fieldaccess.PersistentFieldAutoProxyImpl
+#(DynaBean implementation does not support nested fields)
#]]></source>
<p>
- E.g. if the PersistentFieldDirectAccessImpl is used there
must be an attribute in the
+ E.g. if the PersistentFieldDirectImpl is used there must be
an attribute in the
persistent class with this name, if the
PersistentFieldIntrospectorImpl is used there must
be a JavaBeans compliant property of this name.
More info about the individual implementation can be found
in <link href="ext:javadoc">javadoc</link>.
1.1.2.5 +5 -1
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.4
retrieving revision 1.1.2.5
diff -u -r1.1.2.4 -r1.1.2.5
--- connection.xml 27 Apr 2005 07:34:25 -0000 1.1.2.4
+++ connection.xml 17 Aug 2005 15:37:09 -0000 1.1.2.5
@@ -112,6 +112,10 @@
<section>
<title>ConnectionFactoryManagedImpl</title>
<p>
+ [EMAIL PROTECTED] since OJB 1.0.4, now OJB automatic
detect the
+ running JTA-transaction and suppress critical method
calls on the
+ used connection]
+ <br/>
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
1.1.2.6 +49 -30
db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/guides/deployment.xml
Index: deployment.xml
===================================================================
RCS file:
/home/cvs/db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/guides/deployment.xml,v
retrieving revision 1.1.2.5
retrieving revision 1.1.2.6
diff -u -r1.1.2.5 -r1.1.2.6
--- deployment.xml 30 Apr 2005 19:38:09 -0000 1.1.2.5
+++ deployment.xml 17 Aug 2005 15:37:09 -0000 1.1.2.6
@@ -288,16 +288,21 @@
<anchor id="j2ee-server"/>
<section>
- <title>Deployment in EJB based applications</title>
+ <title>Deployment in managed environment (e.g. EJB based)</title>
<p>
The above mentioned guidelines concerning
- jar files and placing of the OJB.properties and the
repository.xml
- are valid for EJB environments as well.
+ jar files and placing of the <em>OJB.properties</em> and the
<em>repository.xml</em>
+ are valid for managed/EJB environments as well.
+ <br/>
But apart from these basic steps you'll have to perform some
additional
configurations to integrate OJB into a managed environment.
</p>
<p>
+ <em>Managed environment: Using of OJB in a managed
environment means primarily the cooperation
+ of OJB with the application server JTA service (via JCA or
by using JTA classes).</em>
+ </p>
+ <p>
The instructions to make OJB running within your application
server
should be similar for all server. So the following
instructions for JBoss
should be useful for all user. E.g. most
@@ -312,13 +317,14 @@
<ul>
<li>
<strong>Connection handling:</strong> Lookup DataSource
from your AppServer, only these
- connections will be enlisted in running transactions
+ connections can be enlisted in running transactions (JTA)
</li>
<li>
- <strong>Caching:</strong> Do you need distributed
caching?
+ <strong>Caching:</strong> Do you need caching? Do you
need distributed caching?
</li>
<li>
- <strong>Locking:</strong> Do you need distributed
locking (when using odmg-api)?
+ <strong>Locking:</strong> Do you need distributed
locking (when using odmg-api
+ in clustered environments)?
</li>
</ul>
@@ -327,13 +333,13 @@
<title>Configure OJB for managed environments considering as
JBoss example</title>
<p>
The following steps describe how to configure OJB for
managed environments and
- deploy on a ejb conform Application Server (JBoss) on
the basis of the
+ deploy on a ejb conform Application Server on the basis
of the
<link href="#example-beans">shipped ejb-examples</link>.
In managed environments
- OJB needs some specific properties.
+ OJB needs some specific properties:
</p>
- <anchor id="jboss-ojb.properties"/>
+ <anchor id="j2ee-ojb.properties"/>
<section>
<title>
<strong>1. Adapt OJB.properties file</strong>
@@ -342,15 +348,23 @@
If the PB-api is the only persistence API being used
(no ODMG nor JDO)
and it is
<strong>only</strong> being used in a managed
environment, it is
- strongly recommended to use a special
PersistenceBrokerFactory class, which
- enables PersistenceBroker instances to participate
in the running JTA
- transaction (e.g. this makes PBStateListener proper
work in managed
- environments and enables use of 'autoSync' property
in ObjectCacheDefaultImpl):
+ strongly recommended to use a special
<code>PersistenceBrokerFactory</code> class, which
+ enables <code>PersistenceBroker</code> instances to
participate in the running JTA
+ transaction - e.g. this makes
<code>PBStateListener</code> proper work in managed
+ environments and enables OJB to synchronize the
persistent
+ <link href="site:object-cache">caches</link> (e.g.
the two-level cache):
</p>
<source><![CDATA[
PersistenceBrokerFactoryClass=org.apache.ojb.broker.core.PersistenceBrokerFactorySyncImpl]]></source>
<note>
Don't use this setting in conjunction with any other
top-level api (e.g. ODMG-api).
+ <br/>
+ <br/>
+ If <strong>no permanent caching</strong> (only the
"empty" cache implementation
+ or the "per broker cache") is used and the
<code>PBStateListener</code>
+ is not used to detect tx demarcation, it's possible
to use the default
+ <code>PersistenceBrokerFactory</code>
implementation, because OJB doesn't
+ need to synchronize anything.
</note>
<p>
Your
@@ -362,6 +376,8 @@
</p>
<source><![CDATA[
...
+# only needed when using OJB 1.0.3 or earlier in managed environments. Since
version
+# 1.0.4 OJB detects datasources from managed environments automatically.
ConnectionFactoryClass=
org.apache.ojb.broker.accesslayer.ConnectionFactoryManagedImpl
@@ -374,14 +390,16 @@
<link href="site:connection">
<em>ConnectionFactory</em>
</link> implementation
- was used to by-pass all forbidden method calls in
managed environments.
+ is used in version before 1.0.4 to by-pass all
forbidden method calls in managed environments.
+ Since OJB 1.0.4 datasources from managed
environments are detected automatically
+ by checking the <em>JTA-TxManager</em>.
</p>
<p>
The
- <em>JTATransactionManagerClass</em> set the used
implementation class for transaction
- manager lookup, necessary for for
<code>javax.transaction.TransactionManager</code>
- lookup to participate in running
- <em>JTA transaction</em> via
+ <em>JTATransactionManagerClass</em> property specify
the used implementation
+ class to lookup the <em>transaction manager</em>
used by the application server.
+ The
<code>javax.transaction.TransactionManager</code> is needed to make it possible
+ for OJB to participate in running <em>JTA
transaction</em> via
<code>javax.transaction.Synchronization</code>
interface.
</p>
<p>
@@ -420,7 +438,7 @@
<p>
Do only use
<code>DataSource</code> from the application server
to connect to your database
- (Local used connections do not participate in JTA
transaction).
+ (Local used connections can not participate in JTA
transaction).
</p>
<note>
We strongly recommend to use JBoss 3.2.2 or higher
of the 3.x series of JBoss. With earlier versions of
@@ -457,17 +475,17 @@
</jdbc-connection-descriptor>]]></source>
<p>
- The attribute
- <code>useAutoCommit="0"</code> is mandatory
- in managed environments, because it's in most cases
not
- allowed to change autoCommit state.
+ In OJB versions before <em>1.0.4</em> the attribute
+ <link
href="site:repository/jdbc-connection-descriptor"><code>useAutoCommit="0"</code></link>
+ is mandatory in managed environments, because it's
in most cases not
+ allowed to change the connection's
<em>autoCommit</em> state.
</p>
<note>
- In managed environments you can't use the default
sequence manager (SequenceManagerHighLowImpl)
- of OJB. For alternative sequence manager
implemetation
- <link href="site:sequence-manager">see here</link>.
+ In managed environments you can't use the
<em>default</em> sequence manager
+ implementation (SequenceManagerHighLowImpl) of OJB.
For alternative sequence
+ manager implemetation <link
href="site:sequence-manager">see here</link>.
</note>
</section>
@@ -573,7 +591,7 @@
<p>
Very important thing is cache synchronization with
the database.
When using the ODMG-api or PB-api (with
- <link href="#jboss-ojb.properties">special PBF (see
1.)</link> setting)
+ <link href="#j2ee-ojb.properties">special PBF (see
1.)</link> setting)
it's possible to use all
<link href="site:object-cache">
<code>ObjectCache</code>
@@ -695,7 +713,7 @@
/commons-pool-XXX.jar
/jakarta-regexp-XXX.jar]]></source>
<p>
- Please pay attention on the <link
href="#jboss-ojb.properties">configuration settings</link>
+ Please pay attention on the <link
href="#j2ee-ojb.properties">configuration settings</link>
to make OJB work in managed environments (especially
the OJB.properties settings).
</p>
<note>
@@ -913,6 +931,7 @@
/[ojb required runtime jar]
/OJB.properties
+/OJB-logging.properties
/repository.dtd
/respository_internal.xml
/repository.xml
@@ -1048,7 +1067,7 @@
<p>
<strong>3.</strong> Prepare the OJB.properties file.
Should be similar to
- <link href="#jboss-ojb.properties">jboss</link>.
Expect the
+ <link href="#j2ee-ojb.properties">jboss</link>.
Expect the
following entry:
</p>
<source>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
