Author: david.lloyd(a)jboss.com
Date: 2009-01-14 22:43:01 -0500 (Wed, 14 Jan 2009)
New Revision: 4813
Modified:
remoting-txn/trunk/src/main/java/org/jboss/remoting/txn/TransactionalClient.java
remoting-txn/trunk/src/main/java/org/jboss/remoting/txn/TransactionalClientSource.java
remoting-txn/trunk/src/main/java/org/jboss/remoting/txn/TxnReply.java
remoting-txn/trunk/src/main/java/org/jboss/remoting/txn/TxnRequest.java
remoting-txn/trunk/src/main/java/org/jboss/remoting/txn/impl/TransactionalClientImpl.java
Log:
Lots o javadoc
Modified:
remoting-txn/trunk/src/main/java/org/jboss/remoting/txn/TransactionalClient.java
===================================================================
---
remoting-txn/trunk/src/main/java/org/jboss/remoting/txn/TransactionalClient.java 2009-01-15
01:32:33 UTC (rev 4812)
+++
remoting-txn/trunk/src/main/java/org/jboss/remoting/txn/TransactionalClient.java 2009-01-15
03:43:01 UTC (rev 4813)
@@ -29,14 +29,40 @@
import java.io.IOException;
/**
+ * A transactional communications client. The client may be associated with state
maintained by the local and/or remote side.
+ * The client is additionally associated with a transactional resource.
*
+ * @param <I> the request type
+ * @param <O> the reply type
*/
public interface TransactionalClient<I, O> extends Client<I, O> {
+
+ /**
+ * Start a local transaction.
+ *
+ * @throws IOException if an error occurs
+ */
void start() throws IOException;
+ /**
+ * Commit a local transaction.
+ *
+ * @throws IOException if an error occurs
+ */
void commit() throws IOException;
+ /**
+ * Roll back a local transaction.
+ *
+ * @throws IOException if an error occurs
+ */
void rollback() throws IOException;
- XAResource getXaResource();
+ /**
+ * Get an {@code XAResource} which can be used to enlist this client's resource
in a
+ * distributed transaction.
+ *
+ * @return the {@code XAResource}
+ */
+ XAResource getXAResource();
}
Modified:
remoting-txn/trunk/src/main/java/org/jboss/remoting/txn/TransactionalClientSource.java
===================================================================
---
remoting-txn/trunk/src/main/java/org/jboss/remoting/txn/TransactionalClientSource.java 2009-01-15
01:32:33 UTC (rev 4812)
+++
remoting-txn/trunk/src/main/java/org/jboss/remoting/txn/TransactionalClientSource.java 2009-01-15
03:43:01 UTC (rev 4813)
@@ -26,9 +26,18 @@
import java.io.IOException;
/**
+ * A source for new transactional Remoting clients.
*
+ * @param <I> the request type
+ * @param <O> the reply type
*/
public interface TransactionalClientSource<I, O> extends ClientSource<I, O>
{
+ /**
+ * Create a new transactional communications context.
+ *
+ * @return a new transactional client
+ * @throws IOException if an error occurs
+ */
TransactionalClient<I, O> createClient() throws IOException;
}
Modified: remoting-txn/trunk/src/main/java/org/jboss/remoting/txn/TxnReply.java
===================================================================
--- remoting-txn/trunk/src/main/java/org/jboss/remoting/txn/TxnReply.java 2009-01-15
01:32:33 UTC (rev 4812)
+++ remoting-txn/trunk/src/main/java/org/jboss/remoting/txn/TxnReply.java 2009-01-15
03:43:01 UTC (rev 4813)
@@ -25,134 +25,264 @@
import javax.transaction.xa.Xid;
/**
- *
+ * A reply to a request for a transaction operation on a transactional client.
*/
public interface TxnReply {
+ /**
+ * Accept a visitor.
+ *
+ * @param visitor the visitor
+ * @param param a parameter to pass to the visitor method
+ * @param <I> the type of the visitor parameter
+ * @param <O> the return type of the visitor
+ * @return the value returned by the visitor
+ */
<I, O> O accept(Visitor<I, O> visitor, I param);
+ /**
+ * A visitor for {@code TxnReply} types.
+ *
+ * @param <I> the type of the visitor parameter
+ * @param <O> the return type of the visitor
+ */
interface Visitor<I, O> {
- O visit(ResourceManagerId id, I param);
+ /**
+ * Handle a {@code ResourceManagerId} instance.
+ *
+ * @param reply the reply
+ * @param param the visitor parameter
+ * @return the visitor return value
+ */
+ O visit(ResourceManagerId reply, I param);
- O visit(Timeout id, I param);
+ /**
+ * Handle a {@code Timeout} instance.
+ *
+ * @param reply the reply
+ * @param param the visitor parameter
+ * @return the visitor return value
+ */
+ O visit(Timeout reply, I param);
- O visit(Prepared prepared, I param);
+ /**
+ * Handle a {@code Prepared} instance.
+ *
+ * @param reply the reply
+ * @param param the visitor parameter
+ * @return the visitor return value
+ */
+ O visit(Prepared reply, I param);
+ /**
+ * Handle a {@code Recover} instance.
+ *
+ * @param reply the reply
+ * @param param the visitor parameter
+ * @return the visitor return value
+ */
O visit(Recover reply, I param);
+ /**
+ * Handle a {@code TimeoutSet} instance.
+ *
+ * @param reply the reply
+ * @param param the visitor parameter
+ * @return the visitor return value
+ */
O visit(TimeoutSet reply, I param);
+ /**
+ * Handle a {@code Success} instance.
+ *
+ * @param reply the reply
+ * @param param the visitor parameter
+ * @return the visitor return value
+ */
O visit(Success reply, I param);
}
/**
+ * A reply to a request to get the resource manager ID.
*
+ * @see javax.transaction.xa.XAResource#isSameRM(javax.transaction.xa.XAResource)
*/
final class ResourceManagerId implements TxnReply {
private final Object id;
+ /**
+ * Construct a new instance.
+ *
+ * @param id the resource manager ID
+ */
public ResourceManagerId(final Object id) {
this.id = id;
}
+ /**
+ * Get the resource manager ID.
+ *
+ * @return the resource manager ID
+ */
public Object getId() {
return id;
}
+ /** {@inheritDoc} */
public <I, O> O accept(final Visitor<I, O> visitor, final I param) {
return visitor.visit(this, param);
}
}
/**
+ * A reply to a request to get the currently configured transaction timeout.
*
+ * @see javax.transaction.xa.XAResource#getTransactionTimeout()
*/
final class Timeout implements TxnReply {
private final int timeout;
+ /**
+ * Construct a new instance.
+ *
+ * @param timeout the timeout
+ */
public Timeout(final int timeout) {
this.timeout = timeout;
}
+ /**
+ * Get the timeout.
+ *
+ * @return the timeout
+ */
public int getTimeout() {
return timeout;
}
+ /** {@inheritDoc} */
public <I, O> O accept(final Visitor<I, O> visitor, final I param) {
return visitor.visit(this, param);
}
}
/**
+ * A reply to a request to prepare a distributed transaction.
*
+ * @see javax.transaction.xa.XAResource#prepare(javax.transaction.xa.Xid)
*/
final class Prepared implements TxnReply {
private final int vote;
+ /**
+ * Construct a new instance.
+ *
+ * @param vote the vote
+ */
public Prepared(final int vote) {
this.vote = vote;
}
+ /**
+ * Get the vote.
+ *
+ * @return the vote
+ */
public int getVote() {
return vote;
}
+ /** {@inheritDoc} */
public <I, O> O accept(final Visitor<I, O> visitor, final I param) {
return visitor.visit(this, param);
}
}
/**
+ * A reply to a request to get transaction IDs to recover.
*
+ * @see javax.transaction.xa.XAResource#recover(int)
*/
final class Recover implements TxnReply {
private final Xid[] resources;
+ /**
+ * Construct a new instance.
+ *
+ * @param resources the resources to recover
+ */
public Recover(final Xid[] resources) {
this.resources = resources;
}
+ /**
+ * Get the resources to recover.
+ *
+ * @return the resources to recover
+ */
public Xid[] getResources() {
return resources;
}
+ /** {@inheritDoc} */
public <I, O> O accept(final Visitor<I, O> visitor, final I param) {
return visitor.visit(this, param);
}
}
/**
+ * A reply to a request to set the transaction timeout.
*
+ * @see javax.transaction.xa.XAResource#setTransactionTimeout(int)
*/
final class TimeoutSet implements TxnReply {
private final boolean success;
+ /**
+ * The timeout was set successfully.
+ */
+ public static final TimeoutSet SUCCESS = new TimeoutSet(true);
+ /**
+ * The timeout could not be set.
+ */
+ public static final TimeoutSet FAILED = new TimeoutSet(false);
- public TimeoutSet(final boolean success) {
+ private TimeoutSet(final boolean success) {
this.success = success;
}
+ /**
+ * Get whether the timeout was set successfully.
+ *
+ * @return {@code true} if the timeout was set successfully.
+ */
public boolean getSuccess() {
return success;
}
+ /** {@inheritDoc} */
public <I, O> O accept(final Visitor<I, O> visitor, final I param) {
return visitor.visit(this, param);
}
}
/**
- *
+ * A general successful reply.
*/
final class Success implements TxnReply {
+
+ /**
+ * Get the single instance.
+ */
public static final Success INSTANCE = new Success();
private Success() {
}
+ /** {@inheritDoc} */
public <I, O> O accept(final Visitor<I, O> visitor, final I param) {
return visitor.visit(this, param);
}
Modified: remoting-txn/trunk/src/main/java/org/jboss/remoting/txn/TxnRequest.java
===================================================================
--- remoting-txn/trunk/src/main/java/org/jboss/remoting/txn/TxnRequest.java 2009-01-15
01:32:33 UTC (rev 4812)
+++ remoting-txn/trunk/src/main/java/org/jboss/remoting/txn/TxnRequest.java 2009-01-15
03:43:01 UTC (rev 4813)
@@ -28,301 +28,578 @@
* A request for a transaction operation on a transactional client.
*/
public interface TxnRequest {
+
+ /**
+ * Accept a visitor.
+ *
+ * @param visitor the visitor
+ * @param param a parameter to pass to the visitor method
+ * @param <I> the type of the visitor parameter
+ * @param <O> the return type of the visitor
+ * @return the value returned by the visitor
+ */
<I, O> O accept(Visitor<I, O> visitor, I param);
+ /**
+ * A visitor for {@code TxnRequest} types.
+ *
+ * @param <I> the type of the visitor parameter
+ * @param <O> the return type of the visitor
+ */
interface Visitor<I, O> {
+ /**
+ * Handle a {@code CommitXA} instance.
+ *
+ * @param request the request
+ * @param param the visitor parameter
+ * @return the visitor return value
+ */
O visit(CommitXA request, I param);
+ /**
+ * Handle a {@code EndXA} instance.
+ *
+ * @param request the request
+ * @param param the visitor parameter
+ * @return the visitor return value
+ */
O visit(EndXA request, I param);
+ /**
+ * Handle a {@code ForgetXA} instance.
+ *
+ * @param request the request
+ * @param param the visitor parameter
+ * @return the visitor return value
+ */
O visit(ForgetXA request, I param);
+ /**
+ * Handle a {@code GetTimeout} instance.
+ *
+ * @param request the request
+ * @param param the visitor parameter
+ * @return the visitor return value
+ */
O visit(GetTimeout request, I param);
+ /**
+ * Handle a {@code PrepareXA} instance.
+ *
+ * @param request the request
+ * @param param the visitor parameter
+ * @return the visitor return value
+ */
O visit(PrepareXA request, I param);
+ /**
+ * Handle a {@code Recover} instance.
+ *
+ * @param request the request
+ * @param param the visitor parameter
+ * @return the visitor return value
+ */
O visit(Recover request, I param);
+ /**
+ * Handle a {@code RollbackXA} instance.
+ *
+ * @param request the request
+ * @param param the visitor parameter
+ * @return the visitor return value
+ */
O visit(RollbackXA request, I param);
+ /**
+ * Handle a {@code SetTimeout} instance.
+ *
+ * @param request the request
+ * @param param the visitor parameter
+ * @return the visitor return value
+ */
O visit(SetTimeout request, I param);
+ /**
+ * Handle a {@code StartXA} instance.
+ *
+ * @param request the request
+ * @param param the visitor parameter
+ * @return the visitor return value
+ */
O visit(StartXA request, I param);
+ /**
+ * Handle a {@code Wrapped} instance.
+ *
+ * @param request the request
+ * @param param the visitor parameter
+ * @return the visitor return value
+ */
O visit(Wrapped request, I param);
+ /**
+ * Handle a {@code GetResourceManagerId} instance.
+ *
+ * @param request the request
+ * @param param the visitor parameter
+ * @return the visitor return value
+ */
O visit(GetResourceManagerId request, I param);
+ /**
+ * Handle a {@code StartLocal} instance.
+ *
+ * @param request the request
+ * @param param the visitor parameter
+ * @return the visitor return value
+ */
O visit(StartLocal request, I param);
+ /**
+ * Handle a {@code CommitLocal} instance.
+ *
+ * @param request the request
+ * @param param the visitor parameter
+ * @return the visitor return value
+ */
O visit(CommitLocal request, I param);
+ /**
+ * Handle a {@code RollbackLocal} instance.
+ *
+ * @param request the request
+ * @param param the visitor parameter
+ * @return the visitor return value
+ */
O visit(RollbackLocal request, I param);
}
/**
+ * A request to commit a local transaction.
*
+ * @see TransactionalClient#commit()
*/
final class CommitLocal implements TxnRequest {
+
+ /**
+ * The single instance.
+ */
public static final CommitLocal INSTANCE = new CommitLocal();
private CommitLocal() {
}
+ /** {@inheritDoc} */
public <I, O> O accept(final Visitor<I, O> visitor, final I param) {
return visitor.visit(this, param);
}
}
/**
+ * A request to end the work performed on behalf of a distributed transaction.
*
+ * @see javax.transaction.xa.XAResource#end(javax.transaction.xa.Xid, int)
*/
final class EndXA implements TxnRequest {
private final Xid xid;
private final int flags;
+ /**
+ * Construct a new instance.
+ *
+ * @param xid the transaction ID
+ * @param flags the transaction flags
+ */
public EndXA(final Xid xid, final int flags) {
this.xid = xid;
this.flags = flags;
}
+ /**
+ * Get the XID.
+ *
+ * @return the XID
+ */
public Xid getXid() {
return xid;
}
+ /**
+ * Get the flags.
+ *
+ * @return the flags
+ */
public int getFlags() {
return flags;
}
+ /** {@inheritDoc} */
public <I, O> O accept(final Visitor<I, O> visitor, final I param) {
return visitor.visit(this, param);
}
}
/**
+ * A request to forget about a heurstically completed transaction branch.
*
+ * @see javax.transaction.xa.XAResource#forget(javax.transaction.xa.Xid)
*/
final class ForgetXA implements TxnRequest {
private final Xid xid;
+ /**
+ * Construct a new instance.
+ *
+ * @param xid the transaction ID
+ */
public ForgetXA(final Xid xid) {
this.xid = xid;
}
+ /**
+ * Get the XID.
+ *
+ * @return the XID
+ */
public Xid getXid() {
return xid;
}
+ /** {@inheritDoc} */
public <I, O> O accept(final Visitor<I, O> visitor, final I param) {
return visitor.visit(this, param);
}
}
/**
+ * A request to get the resource manager ID for this resource.
*
+ * @see javax.transaction.xa.XAResource#isSameRM(javax.transaction.xa.XAResource)
*/
final class GetResourceManagerId implements TxnRequest {
+ /**
+ * The single instance.
+ */
public static final GetResourceManagerId INSTANCE = new GetResourceManagerId();
private GetResourceManagerId() {
}
+ /** {@inheritDoc} */
public <I, O> O accept(final Visitor<I, O> visitor, final I param) {
return visitor.visit(this, param);
}
}
/**
+ * A request to get the transaction timeout value.
*
+ * @see javax.transaction.xa.XAResource#getTransactionTimeout()
*/
final class GetTimeout implements TxnRequest {
+ /**
+ * The single instance.
+ */
public static final GetTimeout INSTANCE = new GetTimeout();
private GetTimeout() {
}
+ /** {@inheritDoc} */
public <I, O> O accept(final Visitor<I, O> visitor, final I param) {
return visitor.visit(this, param);
}
}
/**
+ * A request to set the transaction timeout value.
*
+ * @see javax.transaction.xa.XAResource#setTransactionTimeout(int)
*/
final class SetTimeout implements TxnRequest {
private final int timeout;
+ /**
+ * Construct a new instance.
+ *
+ * @param timeout the requested timeout value
+ */
public SetTimeout(final int timeout) {
this.timeout = timeout;
}
+ /**
+ * Get the requested timeout value.
+ *
+ * @return the requested timeout value
+ */
public int getTimeout() {
return timeout;
}
+ /** {@inheritDoc} */
public <I, O> O accept(final Visitor<I, O> visitor, final I param) {
return visitor.visit(this, param);
}
}
/**
+ * A request to prepare a for distributed transaction commit of the given
transaction.
*
+ * @see javax.transaction.xa.XAResource#prepare(javax.transaction.xa.Xid)
*/
final class PrepareXA implements TxnRequest {
private final Xid xid;
+ /**
+ * Construct a new instance.
+ *
+ * @param xid the transaction ID
+ */
public PrepareXA(final Xid xid) {
this.xid = xid;
}
+ /**
+ * Get the transaction ID.
+ *
+ * @return the transaction ID
+ */
public Xid getXid() {
return xid;
}
+ /** {@inheritDoc} */
public <I, O> O accept(final Visitor<I, O> visitor, final I param) {
return visitor.visit(this, param);
}
}
/**
+ * A request to obtain a list of prepared transaction branches from the underlying
resource manager.
*
+ * @see javax.transaction.xa.XAResource#recover(int)
*/
final class Recover implements TxnRequest {
private final int flag;
+ /**
+ * Construct a new instance.
+ *
+ * @param flag the flag(s)
+ */
public Recover(final int flag) {
this.flag = flag;
}
+ /**
+ * Get the flag value.
+ *
+ * @return the flag value
+ */
public int getFlag() {
return flag;
}
+ /** {@inheritDoc} */
public <I, O> O accept(final Visitor<I, O> visitor, final I param) {
return visitor.visit(this, param);
}
}
/**
+ * A request to roll back a local transaction.
*
+ * @see TransactionalClient#rollback()
*/
final class RollbackLocal implements TxnRequest {
+ /**
+ * The single instance.
+ */
public static RollbackLocal INSTANCE = new RollbackLocal();
private RollbackLocal() {
}
+ /** {@inheritDoc} */
public <I, O> O accept(final Visitor<I, O> visitor, final I param) {
return visitor.visit(this, param);
}
}
/**
+ * A request to start a local transaction.
*
+ * @see TransactionalClient#start()
*/
final class StartLocal implements TxnRequest {
+ /**
+ * The single instance.
+ */
public static StartLocal INSTANCE = new StartLocal();
private StartLocal() {
}
+ /** {@inheritDoc} */
public <I, O> O accept(final Visitor<I, O> visitor, final I param) {
return visitor.visit(this, param);
}
}
/**
- *
+ * A wrapped application request.
*/
final class Wrapped implements TxnRequest {
private final Object wrappedRequest;
+ /**
+ * Construct a new instance.
+ *
+ * @param request the application request
+ */
public Wrapped(final Object request) {
wrappedRequest = request;
}
+ /**
+ * Get the wrapped request.
+ *
+ * @return the wrapped request
+ */
public Object getWrappedRequest() {
return wrappedRequest;
}
+ /** {@inheritDoc} */
public <I, O> O accept(final Visitor<I, O> visitor, final I param) {
return visitor.visit(this, param);
}
}
/**
+ * A request to commit a distributed transaction.
*
+ * @see javax.transaction.xa.XAResource#commit(javax.transaction.xa.Xid, boolean)
*/
final class CommitXA implements TxnRequest {
private final Xid xid;
private final boolean onePhase;
+ /**
+ * Construct a new instance.
+ *
+ * @param xid the transaction ID
+ * @param onePhase {@code true} if the commit should be done in a single phase
+ */
public CommitXA(final Xid xid, final boolean onePhase) {
this.xid = xid;
this.onePhase = onePhase;
}
+ /**
+ * Get the transaction ID.
+ *
+ * @return the transaction ID
+ */
public Xid getXid() {
return xid;
}
+ /**
+ * Determine whether a one-phase commit was requested.
+ *
+ * @return {@code true} if a one-phase commit was requested
+ */
public boolean isOnePhase() {
return onePhase;
}
+ /** {@inheritDoc} */
public <I, O> O accept(final Visitor<I, O> visitor, final I param) {
return visitor.visit(this, param);
}
}
/**
+ * A request to roll back a distributed transaction.
*
+ * @see javax.transaction.xa.XAResource#rollback(javax.transaction.xa.Xid)
*/
final class RollbackXA implements TxnRequest {
private final Xid xid;
+ /**
+ * Construct a new instance.
+ *
+ * @param xid the transaction ID
+ */
public RollbackXA(final Xid xid) {
this.xid = xid;
}
+ /**
+ * Get the transaction ID.
+ *
+ * @return the transaction ID
+ */
public Xid getXid() {
return xid;
}
+ /** {@inheritDoc} */
public <I, O> O accept(final Visitor<I, O> visitor, final I param) {
return visitor.visit(this, param);
}
}
/**
+ * A request to start a distributed transaction.
*
+ * @see javax.transaction.xa.XAResource#start(javax.transaction.xa.Xid, int)
*/
final class StartXA implements TxnRequest {
private final Xid xid;
private final int flags;
+ /**
+ * Construct a new instance.
+ *
+ * @param xid the transaction ID
+ * @param flags the flags
+ */
public StartXA(final Xid xid, final int flags) {
this.xid = xid;
this.flags = flags;
}
+ /**
+ * Get the transaction ID.
+ *
+ * @return the transaction ID
+ */
public Xid getXid() {
return xid;
}
+ /**
+ * Get the flags.
+ *
+ * @return the flags
+ */
public int getFlags() {
return flags;
}
Modified:
remoting-txn/trunk/src/main/java/org/jboss/remoting/txn/impl/TransactionalClientImpl.java
===================================================================
---
remoting-txn/trunk/src/main/java/org/jboss/remoting/txn/impl/TransactionalClientImpl.java 2009-01-15
01:32:33 UTC (rev 4812)
+++
remoting-txn/trunk/src/main/java/org/jboss/remoting/txn/impl/TransactionalClientImpl.java 2009-01-15
03:43:01 UTC (rev 4813)
@@ -95,7 +95,7 @@
txnClient.invoke(TxnRequest.RollbackLocal.INSTANCE);
}
- public XAResource getXaResource() {
+ public XAResource getXAResource() {
return remotingXAResource;
}