Mail Archive Home | jotm-commits List | April 2007 Index
| Date Index | Thread Index |
Date: Tuesday, April 17, 2007 @ 23:49:56
Author: degolf
Path: /cvsroot/jotm/jotm/doc
Modified: howto-integrate-jotm.html
Note to include both jrmp and IIOP stub files to avoid Java memory leak
problem.
---------------------------+
howto-integrate-jotm.html | 121 ++++++++++++++++++++++----------------------
1 files changed, 61 insertions(+), 60 deletions(-)
Index: jotm/doc/howto-integrate-jotm.html
diff -u jotm/doc/howto-integrate-jotm.html:1.6
jotm/doc/howto-integrate-jotm.html:1.7
--- jotm/doc/howto-integrate-jotm.html:1.6 Fri Jun 3 23:17:47 2005
+++ jotm/doc/howto-integrate-jotm.html Tue Apr 17 23:49:55 2007
@@ -9,22 +9,24 @@
<h1>How to integrate <a
href="http://www.objectweb.org/jotm/";>JOTM</a></h1>
<h2>Target audience</h2>
- <p>This howto is intended for project developers who want to
+ <p>This howto is intended for project developers who wants to
integrate JOTM in their Java projects to provide JTA<sup>TM</sup>
support for distributed
transactions.</p>
- <p>It is <em>not</em> intended for JOTM users. For information, on
- how to use JOTM, please refer to the installation and examples guides
+ <p>It is <em>not</em> intended as a general howto for JOTM. For
information, on
+ how to use JOTM, you can check the installation and examples guide
from the <a
href="http://www.objectweb.org/jotm/doc/index.html";>documentation
- page</a> on JOTM web site.</p>
+ page</a> on the JOTM web site.</p>
<h2>1. JOTM definition</h2>
<h3>1.1. What JOTM is</h3>
<ul>
<li>JOTM (Java<sup>TM</sup> Open transaction Manager) is
... <strong>a transaction
- manager written in Java and released under a BSD-style Open Source
- license.</li>
+ manager written in Java and released under an Open Source
+ license (<a
+ href="http://www.gnu.org/copyleft/lesser.html";>LGPL</a>, GNU
+ Lesser General Public License)</strong>.</li>
<li>It is an <strong><a
href="http://www.objectweb.org/";>ObjectWeb consortium</a>
project</strong>. The goal of ObjectWeb is to
@@ -111,7 +113,7 @@
<a
href="http://java.sun.com/j2ee/sdk_1.3/techdocs/api/javax/transaction/xa/package-summary.html";><code>javax.transaction.xa</code></a>
packages).</p>
- <p>Containers start JOTM, access JTA objects and then use them to
+ <p>Containers starts JOTM, access JTA objects and then use them to
provide distributed transactions support.</p>
<h3>2.1. <a
@@ -137,42 +139,42 @@
<ul>
<li><code>public
org.objectweb.transaction.jta.TransactionManager
getTransactionManager()</code>
- - gets a <code>TransactionManager</code> object. The ObjectWeb
+ - gets a <code>TransactionManager</code> object. the ObjectWeb
<a
href="../jdoc/org/objectweb/transaction/jta/TransactionManager.html"><code>TransactionManager</code></a>
- interface extends the JTA interface
- to provide support for late enlistment of resources.</li>
+ interface extends the JTA one
+ to provide support for late enlistment of resources</li>
<li><code>public javax.transaction.UserTransaction
getUserTransaction()</code>
- - gets a JTA <code>UserTransaction</code> object.</li>
+ - gets a JTA <code>UserTransaction</code> object</li>
<li><code>public void stop()</code> - stops the transaction
manager</li>
</ul>
- <h3>2.2. Instanciation of JOTM</h3>
+ <h3>2.2. Instantiation of JOTM</h3>
<p>JOTM defines an object, <a
href="../jdoc/org/objectweb/jotm/Jotm.html"><code>org.objectweb.jotm.Jotm</code></a>,
- implementing <code>org.objectweb.transaction.jta.TMService</code> and
can be used to start
- JOTM. In addition to the <code>TMService</code> methods, there is
+ which implements <code>org.objectweb.transaction.jta.TMService</code>
and can be used to start
+ JOTM. In addition to the <code>TMService</code> methods, it has
a public constructor:</p>
<ul>
<li><code>public Jotm(boolean local, boolean bound)</code> - creates
an instance of
JOTM.
- <p><code>local</code> boolean specifies if the
+ <p>the <code>local</code> boolean states if the
transaction factory used to coordinate
transactions is local to this instance or located on another
instance of JOTM.<br />
- If the transaction factory is local, <code>bound</code> boolean
- specifies if it is bound to a registry and made
+ If the transaction factory is local, the <code>bound</code> boolean
+ states if it should be bound to a registry and made
accessible through <a
href="http://java.sun.com/products/jndi/";>JNDI</a><sup>TM</sup>
- (Java Naming and Directory Interface).</p>
+ (Java Naming and Directory Interfaces).</p>
</li>
</ul>
- <p>The rule to remember is, in one "transaction domain",
- there is one and only
- one JOTM with a local transaction factory. If there are other
- instances, they are created with a remote transaction
- factory and are bound by the JOTM creating them
+ <p>The rule to remember is that, in one "transaction domain",
+ there can be one and only
+ one JOTM with a local transaction factory. If there may be other
+ instances, they have to be created with a remote transaction
+ factory which has been bound by the JOTM which created it
locally.</p>
<h2>3. Integration of JOTM</h2>
- <p>To integrate JOTM in another product, additional libraries
+ <p>To integrate JOTM in another product, some additional libraries
are required.</p>
<h3>3.1. Required libraries</h3>
<p>JOTM requires some libraries and API (they are all in the
@@ -181,15 +183,12 @@
<li><code>jotm.jar</code> - JOTM </li>
<li><code>jotm_jrmp_stubs.jar</code> - JOTM stubs for RMI/JRMP</li>
<li><code>jotm_iiop_stubs.jar</code> - JOTM stubs for RMI/IIOP</li>
- <li><code>carol-2.0.5.jar</code> - <a
href="http://www.objectweb.org/carol/";>CAROL</a> (RMI
+ <li><code>carol.jar</code> - <a
href="http://www.objectweb.org/carol/";>CAROL</a> (RMI
support)</li>
<li><code>jta-spec1_0_1.jar</code> - JTA</li>
<li><code>jts1_0.jar</code> - <a
href="http://java.sun.com/products/jts";>JTS</a><sup>TM</sup> (Java
Transaction Service)</li>
- <li><code>howl-0.1.8.jar</code></li>
+ <li><code>jonas_timer.jar</code> - JOnAS timer</li>
<li><code>commons-logging.jar</code></li>
- <li><code>xapool-1.5.0.jar</code></li>
- <li><code>connector-1.5.jar</code></li>
- <li><code>objectweb-datasource.jar</code></li>
<li><code>log4j.jar</code> - <a
href="http://jakarta.apache.org/log4j/docs/index.html";>Log4J</a><sup>TM</sup></li>
<li><code>commons-cli.jar</code> - <a
href="http://jakarta.apache.org/commons/cli/index.html";>CLI</a><sup>TM</sup>
@@ -197,38 +196,38 @@
(used only by standalone JOTM)</li>
</ul>
<h3>3.2. Classpath setting</h3>
- <p>The classpath requires <code>jotm.jar</code> and the
- jar files of the stubs (<code>jotm_jrmp_stubs.jar</code> and/or
- <code>jotm_iiop_stubs.jar</code>) only.<br /> Other jar files are
- loaded due to the class-path attribute of the <code>jotm.jar</code>
manifest file.
- (The jar files are required to be in the same
- directory as <code>jotm.jar</code>).</p>
+ <p>You need to put only the <code>jotm.jar</code> and the
+ jar files of the stubs (<code>jotm_jrmp_stubs.jar</code> and/or**
+ <code>jotm_iiop_stubs.jar</code>) in the classpath .<br /> The other jar
files will be
+ loaded thanks to the class-path attribute of the manifest file of
+ <code>jotm.jar</code> (the jar files still need to be in the same
+ location as <code>jotm.jar</code>).</p>
<p>JOTM configuration files (RMI support, JNDI properties, trace
configurations,...)
- need to reside in the <a href="../conf/"><code>conf/</code></a> directory
at the same
- level as the <code>lib/</code> directory (the <code>class-path</code>
- attribute of JOTM jar files looks for them in
- <code>../conf/</code> directory.</p>
+ needs to be placed in a <a href="../config/"><code>config/</code></a>
directory at the same
+ level than the <code>lib/</code> directory (the <code>class-path</code>
+ attribute of JOTM jar files will look for them in
+ <code>../config/</code> directory.</p>
+ <p> ** Note: As of April 2007 it was reported that jars for both the
jrmp AND the iiop stubs should be included in the classpath as a workaround
for a memory leak reported on the JOTM forum by Arjan Tijms. The memory leak
is caused by an error in the Sun JVM and may eventually be fixed. See the
JOTM forum entry provided by Arjan Tijms on April 13, 20007, for details.</p>
<h3>3.3. RMI registry</h3>
<p>If you plan to bind JOTM objects such as
<code>UserTransaction</code> or <code>TransactionManager</code> in
- JNDI using RMI registry (<code>rmiregistry</code>), you'll need
+ JNDI by using RMI registry (<code>rmiregistry</code>), you'll need
to start the registry with
- specific permissions required by CAROL. The
- <a href="../conf/java.policy"><code>java.policy</code></a> is found in the
<code>conf/</code>
- directory of the JOTM distribution.<br />
-RMI registry needs both <code>jotm.jar</code> and
+ specific permissions due to use of CAROL. Such a
+ <a href="../config/java.policy"><code>java.policy</code></a> can be found
in the <code>config/</code>
+ directory of JOTM distribution.<br />
+RMI registry will also need to have both <code>jotm.jar</code> and
<code>jotm_jrmp_stubs.jar</code> in its classpath.</p>
-<p>From the <code>lib/</code> directory of JOTM, start the RMI
- registry with the following command: (NOTE! UNIX uses a ':' separator. For
Windows, use ';')</p>
-<pre>rmiregistry -J-classpath
-Jjotm.jar:jotm_jrmp_stubs.jar:commons-cli-1.0.jar:connector-1_5.jar:howl-0.1.8.jar
-J-Djava.security.policy=../conf/java.policy</pre>
-
+<p>From the <code>lib/</code> directory of JOTM, you can start the RMI
+ registry with the following commande:</p>
+<pre>rmiregistry -J-classpath -Jjotm.jar:jotm_jrmp_stubs.jar
-J-Djava.security.policy=../config/java.policy</pre>
<h3>3.4. Embedded JOTM</h3>
- <p>JOTM can be embedded in a "container" (e.g. an EJB container, a
- Servlets container, or with a standalone application) and execute in the
same JVM.</p>
- <p>All you have to do is to create in the container code, a JOTM
- instance with a local transaction factory which is not
+ <p>JOTM can be embedded in a "container" (e.g. an EJB container or a
+ Servlets one or a standalone application) and ran in the same JVM.</p>
+ <p>All you have to do is to create in the code of a container an
+ instance of JOTM with a local transaction factory which is not
bound:</p>
<pre>
try {
@@ -244,20 +243,20 @@
UserTransaction utx = jotm.getUserTransaction();
TransactionManager tm = jotm.getTransactionManager();
</pre>
- <p>It's also up to the container developer to choose to bind these
+ <p>It's also up to the container developper to choose if it wants to bind
these
objects in a registry or if they will only be used inside the same
- JVM. A case example is the <a href="../examples/jdbc/">JDBC example</a>
included in the
- JOTM distribution where <code>TransactionManager</code> is
+ JVM. An example of such a case is the <a href="../examples/jdbc/">JDBC
example</a> included in the
+ JOTM distribution where <code>TransactionManager</code> is only
used locally whereas <code>UserTransaction</code> is bound to a
registry.</p>
<p>For more information, see <a
href="../jdoc/org/objectweb/jotm/Jotm.html"><code>Jotm</code> Javadoc</a>.</p>
<h3> 3.5 Standalone JOTM</h3>
- <p>JOTM can be started as a standalone application. In that
- case, containers can access JTA objects by looking them up in a
+ <p>JOTM can be also started as a standalone application. In that
+ case, containers can access JTA objects by looking up them in a
registry.</p>
<p>To start JOTM as a standalone application, from a command line
interface, type:</p>
<pre>java org.objectweb.jotm.Main [args]</pre>
- with <code>[args]</code> being:</p>
+ with some <code>[args]</code> being:</p>
<ul>
<li><code>-u USER_TRANSACTION_JNDI_NAME</code> - binds a
<code>UserTransaction</code> to the registry with the name
@@ -266,13 +265,15 @@
<code>TransactionManager</code> to the registry with the name
<code>TRANSACTION_MANAGER_JNDI_NAME</code></li>
</ul>
- <p>To have a complete list of available arguments, type:</p>
+ <p>To have a complete list of the available arguments, type:</p>
<pre>java org.objectweb.jotm.Main --help</pre>
<p>Containers can then access those objects by looking up them
through JNDI.</p>
<p>For more information, see <a
href="../jdoc/org/objectweb/jotm/Main.html"><code>Main</code> Javadoc</a>.</p>
<h2>Contacts</h2>
-<p>If you have trouble integrating JOTM, questions, or if you want to
+<p>If you have some trouble to integrate JOTM, any questions or if you want
to
contribute, do not hesitate to contact <a
href="mailto:jotm@xxxxxxxxxxxxx";>us</a>.</p>
</body>
</html>
+
+
| Date Index | Thread Index |
Powered by MHonArc.
Copyright © 2006-2007, OW2 Consortium | contact | webmaster.