[JBTM-2806] Javadoc JMS module

songco · Dec 2, 2016 · cda39b3 · cda39b3
1 parent 279d444
commit cda39b3
Show file tree

Hide file tree

Showing 7 changed files with 162 additions and 1 deletion.
diff --git a/ArjunaJTA/jms/src/main/java/org/jboss/narayana/jta/jms/ConnectionClosingSynchronization.java b/ArjunaJTA/jms/src/main/java/org/jboss/narayana/jta/jms/ConnectionClosingSynchronization.java
@@ -28,12 +28,17 @@
 import javax.transaction.Synchronization;
 
 /**
+ * Synchronization to close JMS connection at the end of the transaction.
+ *
  * @author <a href="mailto:gytis@redhat.com">Gytis Trikleris</a>
  */
 public class ConnectionClosingSynchronization implements Synchronization {
 
     private final Connection connection;
 
+    /**
+     * @param connection connection to be closed.
+     */
     public ConnectionClosingSynchronization(Connection connection) {
         this.connection = connection;
     }
@@ -43,6 +48,11 @@ public void beforeCompletion() {
         // Nothing to do
     }
 
+    /**
+     * Close the connection despite the status of the transaction.
+     *
+     * @param status
+     */
     @Override
     public void afterCompletion(int status) {
         if (jtaLogger.logger.isTraceEnabled()) {

diff --git a/ArjunaJTA/jms/src/main/java/org/jboss/narayana/jta/jms/ConnectionFactoryProxy.java b/ArjunaJTA/jms/src/main/java/org/jboss/narayana/jta/jms/ConnectionFactoryProxy.java
@@ -39,11 +39,21 @@ public class ConnectionFactoryProxy implements ConnectionFactory {
 
     private final TransactionHelper transactionHelper;
 
+    /**
+     * @param xaConnectionFactory factory to get XA connection instances.
+     * @param transactionHelper utility to make transaction resources registration easier.
+     */
     public ConnectionFactoryProxy(XAConnectionFactory xaConnectionFactory, TransactionHelper transactionHelper) {
         this.xaConnectionFactory = xaConnectionFactory;
         this.transactionHelper = transactionHelper;
     }
 
+    /**
+     * Get XA connection from the provided factory and wrap it with {@link ConnectionProxy}.
+     *
+     * @return XA connection wrapped with {@link ConnectionProxy}.
+     * @throws JMSException if failure occurred creating XA connection.
+     */
     @Override
     public Connection createConnection() throws JMSException {
         Connection connection = new ConnectionProxy(xaConnectionFactory.createXAConnection(), transactionHelper);
@@ -55,6 +65,14 @@ public Connection createConnection() throws JMSException {
         return connection;
     }
 
+    /**
+     * Get XA connection from the provided factory with credentials and wrap it with {@link ConnectionProxy}.
+     * 
+     * @param userName
+     * @param password
+     * @return XA connection wrapped with {@link ConnectionProxy}.
+     * @throws JMSException if failure occurred creating XA connection.
+     */
     @Override
     public Connection createConnection(String userName, String password) throws JMSException {
         Connection connection = new ConnectionProxy(xaConnectionFactory.createXAConnection(userName, password),

diff --git a/ArjunaJTA/jms/src/main/java/org/jboss/narayana/jta/jms/ConnectionProxy.java b/ArjunaJTA/jms/src/main/java/org/jboss/narayana/jta/jms/ConnectionProxy.java
@@ -47,11 +47,22 @@ public class ConnectionProxy implements Connection {
 
     private final TransactionHelper transactionHelper;
 
+    /**
+     * @param xaConnection XA connection which needs to be proxied.
+     * @param transactionHelper utility to make transaction resources registration easier.
+     */
     public ConnectionProxy(XAConnection xaConnection, TransactionHelper transactionHelper) {
         this.xaConnection = xaConnection;
         this.transactionHelper = transactionHelper;
     }
 
+    /**
+     * Simply create a session with an XA connection if there is no active transaction. Or create a proxied session and register
+     * it with an active transaction.
+     *
+     * @see SessionProxy
+     * @see Connection#createSession(boolean, int)
+     */
     @Override
     public Session createSession(boolean transacted, int acknowledgeMode) throws JMSException {
         if (transactionHelper.isTransactionAvailable()) {
@@ -61,6 +72,12 @@ public Session createSession(boolean transacted, int acknowledgeMode) throws JMS
         return xaConnection.createSession(transacted, acknowledgeMode);
     }
 
+    /**
+     * Simply close the proxied connection if there is no active transaction. Or register a
+     * {@link ConnectionClosingSynchronization} if active transaction exists.
+     * 
+     * @throws JMSException if transaction status check, synchronization registration, or connection closing has failed.
+     */
     @Override
     public void close() throws JMSException {
         if (transactionHelper.isTransactionAvailable()) {
@@ -75,53 +92,106 @@ public void close() throws JMSException {
         }
     }
 
+    /**
+     * Delegate to {@link #xaConnection}
+     *
+     * @see Connection#getClientID()
+     */
     @Override
     public String getClientID() throws JMSException {
         return xaConnection.getClientID();
     }
 
+    /**
+     * Delegate to {@link #xaConnection}
+     *
+     * @see Connection#setClientID(String)
+     */
     @Override
     public void setClientID(String clientID) throws JMSException {
         xaConnection.setClientID(clientID);
     }
 
+    /**
+     * Delegate to {@link #xaConnection}
+     *
+     * @see Connection#getMetaData()
+     */
     @Override
     public ConnectionMetaData getMetaData() throws JMSException {
         return xaConnection.getMetaData();
     }
 
+    /**
+     * Delegate to {@link #xaConnection}
+     *
+     * @see Connection#getExceptionListener()
+     */
     @Override
     public ExceptionListener getExceptionListener() throws JMSException {
         return xaConnection.getExceptionListener();
     }
 
+    /**
+     * Delegate to {@link #xaConnection}
+     *
+     * @see Connection#setExceptionListener(ExceptionListener)
+     */
     @Override
     public void setExceptionListener(ExceptionListener listener) throws JMSException {
         xaConnection.setExceptionListener(listener);
     }
 
+    /**
+     * Delegate to {@link #xaConnection}
+     *
+     * @see Connection#start()
+     */
     @Override
     public void start() throws JMSException {
         xaConnection.start();
     }
 
+    /**
+     * Delegate to {@link #xaConnection}
+     *
+     * @see Connection#stop()
+     */
     @Override
     public void stop() throws JMSException {
         xaConnection.stop();
     }
 
+    /**
+     * Delegate to {@link #xaConnection}
+     *
+     * @see Connection#createConnectionConsumer(Destination, String, ServerSessionPool, int)
+     */
     @Override
     public ConnectionConsumer createConnectionConsumer(Destination destination, String messageSelector,
             ServerSessionPool sessionPool, int maxMessages) throws JMSException {
         return xaConnection.createConnectionConsumer(destination, messageSelector, sessionPool, maxMessages);
     }
 
+    /**
+     * Delegate to {@link #xaConnection}.
+     *
+     * @see Connection#createDurableConnectionConsumer(Topic, String, String, ServerSessionPool, int)
+     */
     @Override
     public ConnectionConsumer createDurableConnectionConsumer(Topic topic, String subscriptionName, String messageSelector,
             ServerSessionPool sessionPool, int maxMessages) throws JMSException {
         return xaConnection.createDurableConnectionConsumer(topic, subscriptionName, messageSelector, sessionPool, maxMessages);
     }
 
+    /**
+     * Create a proxied XA session and enlist its XA resource to the transaction.
+     * <p>
+     * If session's XA resource cannot be enlisted to the transaction, session is closed.
+     *
+     * @return XA session wrapped with {@link SessionProxy}.
+     * @throws JMSException if failure occurred creating XA session or registering its XA resource.
+     */
     private Session createAndRegisterSession() throws JMSException {
         XASession xaSession = xaConnection.createXASession();
         Session session = new SessionProxy(xaSession, transactionHelper);

diff --git a/ArjunaJTA/jms/src/main/java/org/jboss/narayana/jta/jms/SessionClosingSynchronization.java b/ArjunaJTA/jms/src/main/java/org/jboss/narayana/jta/jms/SessionClosingSynchronization.java
@@ -28,12 +28,17 @@
 import javax.transaction.Synchronization;
 
 /**
+ * Synchronization to close JMS session at the end of the transaction.
+ *
  * @author <a href="mailto:gytis@redhat.com">Gytis Trikleris</a>
  */
 public class SessionClosingSynchronization implements Synchronization {
 
     private final Session session;
 
+    /**
+     * @param session session to be closed.
+     */
     public SessionClosingSynchronization(Session session) {
         this.session = session;
     }
@@ -43,6 +48,11 @@ public void beforeCompletion() {
         // Nothing to do
     }
 
+    /**
+     * Close the session despite the status of the transaction.
+     *
+     * @param status
+     */
     @Override
     public void afterCompletion(int status) {
         if (jtaLogger.logger.isTraceEnabled()) {

diff --git a/ArjunaJTA/jms/src/main/java/org/jboss/narayana/jta/jms/SessionProxy.java b/ArjunaJTA/jms/src/main/java/org/jboss/narayana/jta/jms/SessionProxy.java
@@ -46,6 +46,8 @@
 import java.io.Serializable;
 
 /**
+ * Proxy session to wrap around provided {@link XASession}.
+ *
  * @author <a href="mailto:gytis@redhat.com">Gytis Trikleris</a>
  */
 public class SessionProxy implements Session {
@@ -54,11 +56,21 @@ public class SessionProxy implements Session {
 
     private final TransactionHelper transactionHelper;
 
+    /**
+     * @param xaSession XA session that needs to be proxied.
+     * @param transactionHelper utility to make transaction resources registration easier.
+     */
     public SessionProxy(XASession xaSession, TransactionHelper transactionHelper) {
         this.xaSession = xaSession;
         this.transactionHelper = transactionHelper;
     }
 
+    /**
+     * Simply close proxied session if there is no active transaction. Or if transaction exists, delist session's XA resource
+     * and register {@link SessionClosingSynchronization}.
+     * 
+     * @throws JMSException
+     */
     @Override
     public void close() throws JMSException {
         if (transactionHelper.isTransactionAvailable()) {

diff --git a/ArjunaJTA/jms/src/main/java/org/jboss/narayana/jta/jms/TransactionHelper.java b/ArjunaJTA/jms/src/main/java/org/jboss/narayana/jta/jms/TransactionHelper.java
@@ -26,16 +26,43 @@
 import javax.transaction.xa.XAResource;
 
 /**
+ * Utility class to make transaction status checking and resources registration easier.
+ *
  * @author <a href="mailto:gytis@redhat.com">Gytis Trikleris</a>
  */
 public interface TransactionHelper {
 
+    /**
+     * Check if transaction is active. If error occurs wrap an original exception with {@link JMSException}.
+     *
+     * @return whether transaction is active or not.
+     * @throws JMSException if error occurred getting transaction status.
+     */
     boolean isTransactionAvailable() throws JMSException;
 
+    /**
+     * Register synchronization with a current transaction. If error occurs wrap an original exception with
+     * {@link JMSException}.
+     * 
+     * @param synchronization synchronization to be registered.
+     * @throws JMSException if error occurred registering synchronization.
+     */
     void registerSynchronization(Synchronization synchronization) throws JMSException;
 
+    /**
+     * Enlist XA resource to a current transaction. If error occurs wrap an original exception with {@link JMSException}.
+     * 
+     * @param xaResource resource to be enlisted.
+     * @throws JMSException if error occurred enlisting resource.
+     */
     void registerXAResource(XAResource xaResource) throws JMSException;
 
+    /**
+     * Delist XA resource from a current transaction. If error occurs wrap an original exception with {@link JMSException}.
+     * 
+     * @param xaResource resource to be delisted.
+     * @throws JMSException if error occurred delisting resource.
+     */
     void deregisterXAResource(XAResource xaResource) throws JMSException;
 
 }
diff --git a/narayana-full/pom.xml b/narayana-full/pom.xml
@@ -175,6 +175,20 @@
       <scope>compile</scope>
     </dependency>
 
+    <!-- JMS module javadocs -->
+    <dependency>
+      <groupId>org.jboss.narayana.jta</groupId>
+      <artifactId>jms</artifactId>
+      <version>${project.version}</version>
+      <scope>compile</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.jboss.spec.javax.jms</groupId>
+      <artifactId>jboss-jms-api_1.1_spec</artifactId>
+      <version>${version.org.jboss.spec.javax.jms.jboss-jms-api_1.1_spec}</version>
+      <scope>compile</scope>
+    </dependency>
+
     <!-- Ensure these are in the distribution -->
     <dependency>
       <groupId>org.apache.activemq</groupId>
@@ -306,7 +320,7 @@
                   <groups>
                     <group>
                       <title>Core</title>
-                      <packages>com.arjuna.ats.arjuna*:com.arjuna.ats.jdbc*:com.arjuna.ats.txoj*:com.arjuna.common*</packages>
+                      <packages>com.arjuna.ats.arjuna*:com.arjuna.ats.jdbc*:com.arjuna.ats.txoj*:com.arjuna.common*:org.jboss.narayana.jta.jms</packages>
                     </group>
                     <group>
                       <title>JTA</title>