DPML Notify

[niclas AT netcompartner.com]

Author: niclas
Date: Wed Feb  9 12:51:19 2005
New Revision: 1760

Added:
   development/laboratory/planet/components/transactions/
   development/laboratory/planet/components/transactions/api/
   development/laboratory/planet/components/transactions/api/build.xml   
(contents, props changed)
   development/laboratory/planet/components/transactions/api/src/
   development/laboratory/planet/components/transactions/api/src/main/
   development/laboratory/planet/components/transactions/api/src/main/net/
   
development/laboratory/planet/components/transactions/api/src/main/net/dpml/
   
development/laboratory/planet/components/transactions/api/src/main/net/dpml/tx/
   
development/laboratory/planet/components/transactions/api/src/main/net/dpml/tx/Transaction.java
   (contents, props changed)
   
development/laboratory/planet/components/transactions/api/src/main/net/dpml/tx/TransactionException.java
   (contents, props changed)
   
development/laboratory/planet/components/transactions/api/src/main/net/dpml/tx/TransactionManager.java
   (contents, props changed)
   development/laboratory/planet/components/transactions/build.xml   
(contents, props changed)
   development/laboratory/planet/components/transactions/impl/
   development/laboratory/planet/components/transactions/impl/build.xml   
(contents, props changed)
   development/laboratory/planet/components/transactions/impl/src/
   development/laboratory/planet/components/transactions/impl/src/main/
   development/laboratory/planet/components/transactions/impl/src/main/net/
   
development/laboratory/planet/components/transactions/impl/src/main/net/dpml/
   
development/laboratory/planet/components/transactions/impl/src/main/net/dpml/tx/
   
development/laboratory/planet/components/transactions/impl/src/main/net/dpml/tx/impl/
   development/laboratory/planet/components/transactions/index.xml   
(contents, props changed)
   development/laboratory/planet/components/transactions/module.xml   
(contents, props changed)
   development/laboratory/planet/components/transactions/spi/
   development/laboratory/planet/components/transactions/spi/build.xml   
(contents, props changed)
   development/laboratory/planet/components/transactions/spi/src/
   development/laboratory/planet/components/transactions/spi/src/main/
   development/laboratory/planet/components/transactions/spi/src/main/net/
   
development/laboratory/planet/components/transactions/spi/src/main/net/dpml/
   
development/laboratory/planet/components/transactions/spi/src/main/net/dpml/tx/
   
development/laboratory/planet/components/transactions/spi/src/main/net/dpml/tx/spi/
   
development/laboratory/planet/components/transactions/spi/src/main/net/dpml/tx/spi/AbortParticipant.java
   (contents, props changed)
   
development/laboratory/planet/components/transactions/spi/src/main/net/dpml/tx/spi/TransactionContext.java
   (contents, props changed)
   
development/laboratory/planet/components/transactions/spi/src/main/net/dpml/tx/spi/TransactionParticipant.java
   (contents, props changed)
Log:
Adding the beginning of generic Transaction support (not DB transactions) to 
the laboratory.

Added: development/laboratory/planet/components/transactions/api/build.xml
==============================================================================
--- (empty file)
+++ development/laboratory/planet/components/transactions/api/build.xml Wed 
Feb  9 12:51:19 2005
@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+
+<project name="dpml-tx-api" default="install" basedir="."
+    xmlns:transit="antlib:net.dpml.transit">
+
+  <transit:import uri="artifact:template:dpml/magic/standard"/>
+
+</project>

Added: 
development/laboratory/planet/components/transactions/api/src/main/net/dpml/tx/Transaction.java
==============================================================================
--- (empty file)
+++ 
development/laboratory/planet/components/transactions/api/src/main/net/dpml/tx/Transaction.java
     Wed Feb  9 12:51:19 2005
@@ -0,0 +1,8 @@
+package net.dpml.tx;
+
+public interface Transaction
+{
+    void commit();
+
+    void rollback();
+}

Added: 
development/laboratory/planet/components/transactions/api/src/main/net/dpml/tx/TransactionException.java
==============================================================================
--- (empty file)
+++ 
development/laboratory/planet/components/transactions/api/src/main/net/dpml/tx/TransactionException.java
    Wed Feb  9 12:51:19 2005
@@ -0,0 +1,45 @@
+/*
+ * Copyright 2004-2005 Niclas Hedhman.
+ *
+ * Licensed  under the  Apache License,  Version 2.0  (the "License");
+ * you may not use  this file  except in  compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed  under the  License is distributed on an "AS IS" BASIS,
+ * WITHOUT  WARRANTIES OR CONDITIONS  OF ANY KIND, either  express  or
+ * implied.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package net.dpml.tx;
+
+/** Exceptions that can occur in Transactions.
+ *  This exception class is abstract, to ensure that more meaningful
+ *  exception classes are created.
+ */
+public abstract class TransactionException extends Exception
+{
+    /** Constructor for exceptions with only a message.
+     * @param message the message of what has happened.
+     */
+    public TransactionException( String message )
+    {
+        super( message );
+    }
+
+    /** Constructor for exceptions with both a message and a underlying
+     *  exception as the cause.
+     * @param message the message of what has happened.
+     * @param cause the exception that is wrapped and the reason for this
+     *              exception to be thrown.
+     */
+    public TransactionException( String message, Throwable cause )
+    {
+        super( message, cause );
+    }
+}

Added: 
development/laboratory/planet/components/transactions/api/src/main/net/dpml/tx/TransactionManager.java
==============================================================================
--- (empty file)
+++ 
development/laboratory/planet/components/transactions/api/src/main/net/dpml/tx/TransactionManager.java
      Wed Feb  9 12:51:19 2005
@@ -0,0 +1,49 @@
+/*
+ * Copyright 2004-2005 Niclas Hedhman.
+ *
+ * Licensed  under the  Apache License,  Version 2.0  (the "License");
+ * you may not use  this file  except in  compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed  under the  License is distributed on an "AS IS" BASIS,
+ * WITHOUT  WARRANTIES OR CONDITIONS  OF ANY KIND, either  express  or
+ * implied.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package net.dpml.tx;
+
+/** The TransactionManager service interface.
+ * The client looks up the TransactionManager and then asks it to prepare
+ * a Transaction. The configuration of the transaction is part of the
+ * transaction manager setup, and not the concern of the client.
+ * The client <b>should</b> release the Transaction after use, and the
+ * TransactionManager implementation <b>should</b> support
+ * automatic clean up of transactions that are abandoned by the client.
+ * If such support can not be provided, this must be clearly indicated
+ * in the implementation's documentation.
+ *
+ * @metro.service type="net.dpml.tx.TransactionManager" version="1.0"
+ */
+public interface TransactionManager
+{
+    /** Prepare a Transaction.
+     *  This means that a transaction is created, and the underlying
+     *  support is established.
+     * @return a Transaction instance that is ready to use.
+     */
+    Transaction prepare();
+
+    /** Releases the Transaction.
+     * The client calls this method when it is no longer interested
+     * in the transaction. The TransactionManager will abort the
+     * transaction if not completed or aborted by the client.
+     */
+    void release( Transaction tx );
+}
+

Added: development/laboratory/planet/components/transactions/build.xml
==============================================================================
--- (empty file)
+++ development/laboratory/planet/components/transactions/build.xml     Wed 
Feb  9 12:51:19 2005
@@ -0,0 +1,25 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!--
+  Copyright 2004 Niclas Hedhman
+
+  Licensed  under the  Apache License,  Version 2.0  (the "License");
+  you may not use  this file  except in  compliance with the License.
+  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed  under the  License is distributed on an "AS IS" BASIS,
+  WITHOUT  WARRANTIES OR CONDITIONS  OF ANY KIND, either  express  or
+  implied.
+
+  See the License for the specific language governing permissions and
+  limitations under the License.
+-->
+
+<project name="dpml-tx" default="default" basedir="."
+    xmlns:transit="antlib:net.dpml.transit">
+
+  <transit:import uri="artifact:template:dpml/magic/reactor"/>
+
+</project>

Added: development/laboratory/planet/components/transactions/impl/build.xml
==============================================================================
--- (empty file)
+++ development/laboratory/planet/components/transactions/impl/build.xml      
  Wed Feb  9 12:51:19 2005
@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+
+<project name="dpml-tx-impl" default="install" basedir="."
+    xmlns:transit="antlib:net.dpml.transit">
+
+  <transit:import uri="artifact:template:dpml/magic/standard"/>
+
+</project>

Added: development/laboratory/planet/components/transactions/index.xml
==============================================================================
--- (empty file)
+++ development/laboratory/planet/components/transactions/index.xml     Wed 
Feb  9 12:51:19 2005
@@ -0,0 +1,82 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!--
+  Copyright 2004 Stephen J McConnell
+  Copyright 2004 Niclas Hedhman
+
+  Licensed  under the  Apache License,  Version 2.0  (the "License");
+  you may not use  this file  except in  compliance with the License.
+  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed  under the  License is distributed on an "AS IS" BASIS,
+  WITHOUT  WARRANTIES OR CONDITIONS  OF ANY KIND, either  express  or
+  implied.
+
+  See the License for the specific language governing permissions and
+  limitations under the License.
+-->
+
+<index key="dpml-tx">
+  <import uri="artifact:module:dpml/metro/dpml-metro#SNAPSHOT"/>
+  <import uri="artifact:module:dpml/magic/dpml-magic#SNAPSHOT"/>
+  <import uri="artifact:module:dpml/transit/dpml-transit#SNAPSHOT"/>
+
+  <project file="module.xml">
+    <info>
+      <group>dpml/components/tx</group>
+      <name>dpml-tx</name>
+      <version>1.0.0</version>
+      <type>module</type>
+    </info>
+    <dependencies>
+      <include key="dpml-metro"/>
+      <include key="dpml-magic"/>
+      <include key="dpml-transit"/>
+    </dependencies>
+  </project>
+
+  <project basedir="api">
+    <info>
+      <group>dpml/components/tx</group>
+      <name>dpml-tx-api</name>
+      <version>1.0.0</version>
+    </info>
+    <dependencies>
+    </dependencies>
+    <plugins>
+      <include key="dpml-meta-tools"/>
+    </plugins>
+  </project>
+
+  <project basedir="spi">
+    <info>
+      <group>dpml/components/tx</group>
+      <name>dpml-tx-spi</name>
+      <version>1.0.0</version>
+    </info>
+    <dependencies>
+      <include key="dpml-tx-api" />
+    </dependencies>
+    <plugins>
+      <include key="dpml-meta-tools"/>
+    </plugins>
+  </project>
+
+  <project basedir="impl">
+    <info>
+      <group>dpml/components/tx</group>
+      <name>dpml-tx-impl</name>
+      <version>1.0.0</version>
+    </info>
+    <dependencies>
+      <include key="dpml-tx-api" />
+      <include key="dpml-tx-spi" />
+    </dependencies>
+    <plugins>
+      <include key="dpml-meta-tools"/>
+    </plugins>
+  </project>
+
+</index>

Added: development/laboratory/planet/components/transactions/module.xml
==============================================================================
--- (empty file)
+++ development/laboratory/planet/components/transactions/module.xml    Wed 
Feb  9 12:51:19 2005
@@ -0,0 +1,58 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!--
+  Copyright 2004 Stephen J McConnell
+  Copyright 2004 Niclas Hedhman
+
+  Licensed  under the  Apache License,  Version 2.0  (the "License");
+  you may not use  this file  except in  compliance with the License.
+  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed  under the  License is distributed on an "AS IS" BASIS,
+  WITHOUT  WARRANTIES OR CONDITIONS  OF ANY KIND, either  express  or
+  implied.
+
+  See the License for the specific language governing permissions and
+  limitations under the License.
+-->
+
+<project name="dpml-tx" default="docs" basedir="."
+    xmlns:transit="antlib:net.dpml.transit"
+    xmlns:x="plugin:dpml/magic/dpml-magic-core">
+
+  <transit:import uri="artifact:template:dpml/magic/standard"/>
+
+  <target name="build" depends="standard.build">
+    <x:module index="index.xml">
+      <header>
+        <svn href="http://paris.dpml.net/svn/development/main/metro"/>
+        <home href="http://www.dpml.net/products/metro"/>
+      </header>
+    </x:module>
+  </target>
+
+  <target name="docs" depends="install, checkstyle, junit-report">
+    <x:javadoc>
+      <link href="http://java.sun.com/j2se/1.4/docs/api"/>
+      <group title="Public API">
+        <package name="net.dpml.tx"/>
+      </group>
+      <group title="Private API">
+        <package name="net.dpml.*"/>
+      </group>
+    </x:javadoc>
+  </target>
+
+  <target name="junit-report">
+    <mkdir dir="target/reports/junit"/>
+    <junitreport todir="target/reports/junit">
+      <fileset dir=".">
+        <include name="**/target/test-reports/TEST-*.xml"/>
+      </fileset>
+      <report format="frames" todir="target/reports/junit"/>
+    </junitreport>
+  </target>
+
+</project>

Added: development/laboratory/planet/components/transactions/spi/build.xml
==============================================================================
--- (empty file)
+++ development/laboratory/planet/components/transactions/spi/build.xml Wed 
Feb  9 12:51:19 2005
@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+
+<project name="dpml-tx-spi" default="install" basedir="."
+    xmlns:transit="antlib:net.dpml.transit">
+
+  <transit:import uri="artifact:template:dpml/magic/standard"/>
+
+</project>

Added: 
development/laboratory/planet/components/transactions/spi/src/main/net/dpml/tx/spi/AbortParticipant.java
==============================================================================
--- (empty file)
+++ 
development/laboratory/planet/components/transactions/spi/src/main/net/dpml/tx/spi/AbortParticipant.java
    Wed Feb  9 12:51:19 2005
@@ -0,0 +1,38 @@
+/*
+ * Copyright 2004-2005 Niclas Hedhman.
+ *
+ * Licensed  under the  Apache License,  Version 2.0  (the "License");
+ * you may not use  this file  except in  compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed  under the  License is distributed on an "AS IS" BASIS,
+ * WITHOUT  WARRANTIES OR CONDITIONS  OF ANY KIND, either  express  or
+ * implied.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package net.dpml.tx.spi;
+
+/** AbortParticipants indicates that they want to be part of a failing
+ * Transaction.
+ * Normally, prepare() is not called by the transaction manager on
+ * sequent participants of the transaction, but certain participants
+ * may want to know that a failing transaction is in progress, such
+ * as loggers.
+ */
+public interface AbortParticipant extends TransactionParticipant
+{
+    /** Called by the transaction manager when another participant,
+     *  earlier in the chain, has signalled ABORT.
+     *  This method is mutually exclusive to the <code>prepare()</code>
+     *  method in the <code>TranactionParticipant</code> interface.
+     * @param context The TransactionContext of the aborting transaction.
+     */
+    int prepareForAbort( TransactionContext context );
+}
+

Added: 
development/laboratory/planet/components/transactions/spi/src/main/net/dpml/tx/spi/TransactionContext.java
==============================================================================
--- (empty file)
+++ 
development/laboratory/planet/components/transactions/spi/src/main/net/dpml/tx/spi/TransactionContext.java
  Wed Feb  9 12:51:19 2005
@@ -0,0 +1,107 @@
+/*
+ * Copyright 2004-2005 Niclas Hedhman.
+ *
+ * Licensed  under the  Apache License,  Version 2.0  (the "License");
+ * you may not use  this file  except in  compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed  under the  License is distributed on an "AS IS" BASIS,
+ * WITHOUT  WARRANTIES OR CONDITIONS  OF ANY KIND, either  express  or
+ * implied.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package net.dpml.tx.spi;
+
+import net.dpml.tx.TransactionException;
+
+/** The TransactionContext holds the data prepared by the participant,
+ *  before the commit.
+ * The TransactionParticipants receive a TransactionContext in each
+ * of the methods, and are expected to store prepared content into
+ * the context. The TransactionContext will ensure that the content
+ * stored in the context will survive 'disaster' if stored as
+ * <code>persistent</code>.
+ * Both the id and the content must be <code>java.io.Serializable</code>
+ * if stored with the persistent flag. And one should only store
+ * without the persistent flag for recoverable resources, such as
+ * network connections.
+ */
+public interface TransactionContext
+{
+    /** Returns the Transaction ID.
+     * The Transaction ID is a unique number generated by the transaction
+     * manager, so that no two transactions within the same manager, uses
+     * the same number. This ID can be used by Transaction Participants
+     * to distinguish between more than one transaction, and used to
+     * construct content IDs.
+     */
+    long getTransactionId();
+
+    /** Returns the Content associated with the <code>id</code>.
+     * The content returned is what has been stored into the context
+     * with the <code>storeContent</code> method.
+     * @param id the identification of the content. See #storeContent() for
+     *           details on how they should be constructed.
+     * @return the content that has previously been stored.
+     * @exception TransactionException if the TransactionContext is
+     *            unable to retrieve the content. This is most
+     *            certainly due to underlying serialization or IO
+     *            exceptions.
+     */
+    Object getContent( Object id )
+        throws TransactionException;
+
+
+    /** Remove content from the context.
+     *  This method is provided to allow for changes to the content
+     *  if needed, but it is not expected to be used much. The content
+     *  is only allowed to be removed IF and only if the same participant
+     *  knows for sure it stored it earlier.
+     * @param id the identification of the content. See #storeContent() for
+     *           details on how they should be constructed.
+     * @return the content that has previously been associated with the
+     *         <code>id</code>.
+     */
+    Object removeContent( Object id )
+        throws TransactionException;
+
+    /** Store arbitrary content into the context for later (commit)
+     *  use.
+     * The content is stored under the given <code>id</code> and
+     * if the <code>persistent</code> flag is true, then <b>both</b>
+     * the <code>id</code> and the <code>content</code> objects
+     * <b>must</b> be Serializable. All content that is not
+     * re-creatable <b>must</b> be persistent, as the transaction
+     * may continue in another JVM, either due to distributed
+     * environment or JVM re-start.
+     * The id must be unique among the TransactionParticipants, and the
+     * recommendation is to use;
+     * <code><pre>
+     *   String id = getClass().getName()
+     *               + ":"
+     *               + ctx.getTransactionId()
+     *               + someLocalKey;
+     * </pre></code>
+     * to ensure both uniqeness within the transaction context, but also
+     * a between transactions, for easier debugging.
+     *
+     * @param id the identification of the content.
+     * @param content the content to be associated with the <code>id</code>.
+     * @param persistent true if the content is not re-creatable between
+     *        calls of <code>prepare()</code> and <code>commit()</code> or
+     *        <code>abort()</code>.
+     * @exception TransactionException if the content could not be stored,
+     *            associated with the <code>id</code>. Underlying exceptions,
+     *            such as serialization and IO exceptions will be wrapped.
+     *            This exception is also thrown if the context already 
contains
+     *            content with the same <code>id</code>.
+     */
+    void storeContent( Object id, Object content, boolean persistent )
+        throws TransactionException;
+}

Added: 
development/laboratory/planet/components/transactions/spi/src/main/net/dpml/tx/spi/TransactionParticipant.java
==============================================================================
--- (empty file)
+++ 
development/laboratory/planet/components/transactions/spi/src/main/net/dpml/tx/spi/TransactionParticipant.java
      Wed Feb  9 12:51:19 2005
@@ -0,0 +1,119 @@
+/*
+ * Copyright 2004-2005 Niclas Hedhman.
+ *
+ * Licensed  under the  Apache License,  Version 2.0  (the "License");
+ * you may not use  this file  except in  compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed  under the  License is distributed on an "AS IS" BASIS,
+ * WITHOUT  WARRANTIES OR CONDITIONS  OF ANY KIND, either  express  or
+ * implied.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package net.dpml.tx.spi;
+
+import net.dpml.tx.TransactionException;
+
+/** The TransactionParticipant is an instance that are part of solving
+ *  a Transaction.
+ * The participants are associated with the <code>TransactionManager</code>,
+ * which will call the participants in the defined order.
+ * The TransactionParticipant will first be called in the <code>prepare()
+ * </code> method, and the participant signals back whether it is prepared
+ * or that it had to abort. If any participant signals an abort, no
+ * further <code>prepare()</code> methods in following participants will
+ * be called, and the TransactionManager will call the <code>abort()</code>
+ * method for each of the already prepared participants, unless they
+ * also signal NO_JOIN.
+ *
+ * @metro.service type="net.dpml.tx.spi.TransactionParticipant" version="1.0"
+ */
+public interface TransactionParticipant
+{
+    /** Signal to the TransactionManager that the participant is unable to
+     *  prepare itself for a <code>commit()</code> method call, and insists
+     *  that the transaction is aborted.
+     */
+    final int TX_ABORTED = 1;
+
+    /** Signal in the <code>prepare()</code> method that it was successful,
+     *  and will be able to succeed on a <code>commit()</code> call.
+     */
+    final int TX_PREPARED = 2;
+
+    /** Returns the name of this <code>TransactionParticipant</code>.
+     *  The name is used to identify the participant in error messages, and
+     *  to locate the resource bundle for error/abort messages.
+     * @return the name of the participant.
+     */
+    String getName();
+
+    /** Called by the <code>TransactionManager</code> to instruct this
+     *  participant to prepare and validate everything required to be
+     *  successful with a <code>commit()</code> method later.
+     *  Typically this means that all operations are actually carried out,
+     *  shared resources are kept locked and that references to those
+     *  operations and resources are stored in the
+     *  <code>TransactionContext</code>.
+     * @param context the TransactionContext where the participants can store
+     *        data between the <code>prepare()</code> and 
<code>commit()</code>
+     *        methods. It is important that the participant itself does not
+     *        contain any state between these methods, as the two calls can
+     *        be separated by different JVM instances.
+     *
+     * @return <code>TX_PREPARED</code> if the opertions have been 
successful,
+     *         and a <code>commit()</code> is very likely to succeed.
+     *         Otherwise TX_ABORTED is returned, and the "urn:tx:error.code"
+     *         has been populated in the <code>TransactionContext</code>
+     *         with the error reference number, and the 
"urn:tx:error.message"
+     *         containing a meaningful message in english (non-localized) or
+     *         the key into a resource bundle with the name obtained from the
+     *         <code>getName()</code> method.
+     */
+    int prepare( TransactionContext context );
+
+    /** Instructs the participant to commit the transaction.
+     * The participant should lookup the references stored in the context, 
and
+     * make those operations permanent. Only under extreme conditions are the
+     * participant allowed to throw an exception, as this would put the
+     * system in an unstable state.
+     * @param context the TransactionContext where the participants can store
+     *        data between the <code>prepare()</code> and 
<code>commit()</code>
+     *        methods. It is important that the participant itself does not
+     *        contain any state between these methods, as the two calls can
+     *        be separated by different JVM instances.
+     *
+     * @exception TransactionException if an unrecoverable, unforeseen and
+     *            unavoidable exception has occurred. The TransactionManager
+     *            is free to deal with this in numerous ways, including but
+     *            not limited to, postponing the transaction for a while,
+     *            cancel/abort the transaction, or restart the JVM.
+     */
+    void commit( TransactionContext context )
+        throws TransactionException;
+
+    /** Instructs the participant to cancel the transaction.
+     * The participant needs to clean up any resources that has been 
allocated
+     * during the <code>prepare()</code> method.
+     *
+     * @param context the TransactionContext where the participants can store
+     *        data between the <code>prepare()</code> and 
<code>commit()</code>
+     *        methods. It is important that the participant itself does not
+     *        contain any state between these methods, as the two calls can
+     *        be separated by different JVM instances.
+     *
+     * @exception TransactionException if an unrecoverable, unforeseen and
+     *            unavoidable exception has occurred. The TransactionManager
+     *            is free to deal with this in numerous ways, including but
+     *            not limited to, postponing the transaction for a while,
+     *            cancel/abort the transaction, or restart the JVM.
+     */
+    void abort( TransactionContext context )
+        throws TransactionException;
+}