Skip to main content

[xadisk~svn:541] Javadoc for JIRA issue#76.

  • From: nitin_verma@...
  • To: commits@...
  • Subject: [xadisk~svn:541] Javadoc for JIRA issue#76.
  • Date: Wed, 21 Aug 2013 19:45:03 +0000

Project:    xadisk
Repository: svn
Revision:   541
Author:     nitin_verma
Date:       2013-08-21 19:45:02 UTC
Link:       

Log Message:
------------
Javadoc for JIRA issue#76.
TransactionFailedException extends XASystemException (unchecked exception).



Revisions:
----------
541


Modified Paths:
---------------
trunk/src/org/xadisk/bridge/proxies/interfaces/XAFileSystem.java
trunk/src/org/xadisk/filesystem/exceptions/TransactionFailedException.java
trunk/src/org/xadisk/connector/outbound/XADiskUserLocalTransaction.java
trunk/src/org/xadisk/filesystem/NativeSession.java
trunk/src/org/xadisk/connector/outbound/XADiskLocalTransaction.java
trunk/src/org/xadisk/bridge/proxies/interfaces/Session.java
trunk/src/org/xadisk/filesystem/SessionCommonness.java
trunk/src/org/xadisk/connector/XAResourceImpl.java
trunk/src/org/xadisk/filesystem/workers/CrashRecoveryWorker.java
trunk/src/org/xadisk/bridge/proxies/impl/RemoteSession.java


Diffs:
------
Index: 
trunk/src/org/xadisk/filesystem/exceptions/TransactionFailedException.java
===================================================================
--- 
trunk/src/org/xadisk/filesystem/exceptions/TransactionFailedException.java  
(revision 540)
+++ 
trunk/src/org/xadisk/filesystem/exceptions/TransactionFailedException.java  
(revision 541)
@@ -1,9 +1,34 @@
 package org.xadisk.filesystem.exceptions;
 
+import org.xadisk.bridge.proxies.interfaces.XAFileSystem;
 import org.xadisk.filesystem.TransactionInformation;
 
-public class TransactionFailedException extends XAApplicationException {
+/**
+ * This exception is an unchecked exception thrown when a transaction is not 
able to
+ * continue its work and is left in an inconsistent incomplete state. That 
is, the
+ * transaction did not commit or rollback and will require an administrative
+ * intervention for resolving inconsistency and then marking the transaction 
as
+ * complete. A transaction can fail either during routine XADisk operations 
or
+ * during the recovery phase of XADisk. For the routine cases, the
+ * transaction will keep holding the locks (in-memory) over 
files/directories until
+ * it is marked complete.
+ *
+ * <p> If a transaction fails during recovery, or there are failed 
incomplete transactions
+ * from the time prior to the reboot, the recovery process will wait until 
all these
+ * failed transactions are marked complete.
+ *
+ * <p> A failed transaction can be marked complete using
+ * {@link XAFileSystem#declareTransactionAsComplete(byte[])}. The identifier 
for such
+ * transaction can be obtained either from {@link 
#getTransactionIdentifier()}, or
+ * {@link XAFileSystem#getIdentifiersForFailedTransactions()}.
+ * 
+ * <p> This exception is not expected to occur in general, and indicates a 
severe problem.
+ *
+ * @since 1.2.2
+ */
 
+public class TransactionFailedException extends XASystemException {
+
     private static final long serialVersionUID = 1L;
 
     private byte[] transactionIdentifier;
@@ -13,7 +38,20 @@
         this.transactionIdentifier = xid.getBytes();
     }
 
+    /**
+     * Returns a byte-array identifier with which the transaction can be 
identified
+     * to the XADisk instance for tasks like marking the transaction as 
complete.
+     * @return the transaction identifier in byte-array form.
+     */
     public byte[] getTransactionIdentifier() {
         return transactionIdentifier;
     }
+
+    @Override
+    public String getMessage() {
+        return "The transaction has failed and has not completed commit or 
rollback. The "
+                + "file-system data operated on by the transaction may be in 
inconsistent "
+                + "state. This exception is not expected to occur in 
general, and "
+                + "indicates a severe problem.";
+    }
 }
Index: trunk/src/org/xadisk/filesystem/workers/CrashRecoveryWorker.java
===================================================================
--- trunk/src/org/xadisk/filesystem/workers/CrashRecoveryWorker.java    
(revision 540)
+++ trunk/src/org/xadisk/filesystem/workers/CrashRecoveryWorker.java    
(revision 541)
@@ -29,7 +29,6 @@
 import org.xadisk.filesystem.TransactionLogEntry;
 import org.xadisk.filesystem.TransactionInformation;
 import org.xadisk.filesystem.exceptions.NoTransactionAssociatedException;
-import org.xadisk.filesystem.exceptions.TransactionFailedException;
 import org.xadisk.filesystem.utilities.TransactionLogsUtility;
 
 public class CrashRecoveryWorker implements Work {
@@ -344,7 +343,6 @@
                     session.rollback();
                 }
             } catch (NoTransactionAssociatedException note) {
-            } catch (TransactionFailedException tfe) {
             }
         }
     }
Index: trunk/src/org/xadisk/filesystem/SessionCommonness.java
===================================================================
--- trunk/src/org/xadisk/filesystem/SessionCommonness.java      (revision 540)
+++ trunk/src/org/xadisk/filesystem/SessionCommonness.java      (revision 541)
@@ -10,11 +10,10 @@
 
 import org.xadisk.bridge.proxies.interfaces.Session;
 import org.xadisk.filesystem.exceptions.NoTransactionAssociatedException;
-import org.xadisk.filesystem.exceptions.TransactionFailedException;
 
 public interface SessionCommonness extends Session {
 
-    public void commit(boolean onePhase) throws 
NoTransactionAssociatedException, TransactionFailedException;
+    public void commit(boolean onePhase) throws 
NoTransactionAssociatedException;
     
     public void prepare() throws NoTransactionAssociatedException;
 
Index: trunk/src/org/xadisk/filesystem/NativeSession.java
===================================================================
--- trunk/src/org/xadisk/filesystem/NativeSession.java  (revision 540)
+++ trunk/src/org/xadisk/filesystem/NativeSession.java  (revision 541)
@@ -128,7 +128,6 @@
             this.rollbackCause = rollbackCause;
         } catch (TransactionRolledbackException trbe) {
         } catch (NoTransactionAssociatedException note) {
-        } catch (TransactionFailedException tfe) {
         }
     }
 
@@ -610,8 +609,7 @@
         }
     }
 
-    public void commit(boolean onePhase) throws 
NoTransactionAssociatedException,
-        TransactionFailedException {
+    public void commit(boolean onePhase) throws 
NoTransactionAssociatedException {
         ArrayList<FileInputStream> logInputStreams = new 
ArrayList<FileInputStream>();
         try {
             asynchronousRollbackLock.lock();
@@ -965,7 +963,7 @@
         }
     }
 
-    public void rollback() throws NoTransactionAssociatedException, 
TransactionFailedException {
+    public void rollback() throws NoTransactionAssociatedException {
         ArrayList<FileInputStream> logInputStreams = new 
ArrayList<FileInputStream>();
         try {
             asynchronousRollbackLock.lock();
@@ -1327,7 +1325,7 @@
         }
     }
 
-    public void commit() throws NoTransactionAssociatedException, 
TransactionFailedException {
+    public void commit() throws NoTransactionAssociatedException {
         this.commit(true);
     }
 
Index: trunk/src/org/xadisk/connector/XAResourceImpl.java
===================================================================
--- trunk/src/org/xadisk/connector/XAResourceImpl.java  (revision 540)
+++ trunk/src/org/xadisk/connector/XAResourceImpl.java  (revision 541)
@@ -18,7 +18,6 @@
 import org.xadisk.filesystem.XAFileSystemCommonness;
 import org.xadisk.filesystem.TransactionInformation;
 import org.xadisk.filesystem.exceptions.NoTransactionAssociatedException;
-import org.xadisk.filesystem.exceptions.TransactionFailedException;
 import org.xadisk.filesystem.exceptions.XASystemException;
 import org.xadisk.filesystem.utilities.MiscUtils;
 
@@ -112,8 +111,6 @@
         }
         try {
             sessionOfTransaction.rollback();
-        } catch(TransactionFailedException tfe) {
-            throw 
MiscUtils.createXAExceptionWithCause(XAException.XAER_RMERR, tfe);
         } catch (NoTransactionAssociatedException note) {
             throw 
MiscUtils.createXAExceptionWithCause(XAException.XAER_OUTSIDE, note);
         } catch (XASystemException xase) {
@@ -132,8 +129,6 @@
         }
         try {
             ((SessionCommonness)sessionOfTransaction).commit(onePhase);
-        } catch(TransactionFailedException tfe) {
-            throw 
MiscUtils.createXAExceptionWithCause(XAException.XAER_RMERR, tfe);
         } catch (NoTransactionAssociatedException note) {
             throw 
MiscUtils.createXAExceptionWithCause(XAException.XAER_OUTSIDE, note);
         } catch (XASystemException xase) {
Index: trunk/src/org/xadisk/connector/outbound/XADiskUserLocalTransaction.java
===================================================================
--- trunk/src/org/xadisk/connector/outbound/XADiskUserLocalTransaction.java   
  (revision 540)
+++ trunk/src/org/xadisk/connector/outbound/XADiskUserLocalTransaction.java   
  (revision 541)
@@ -11,7 +11,6 @@
 import javax.resource.spi.ConnectionEvent;
 import org.xadisk.filesystem.exceptions.NoTransactionAssociatedException;
 import org.xadisk.filesystem.FileSystemConfiguration;
-import org.xadisk.filesystem.exceptions.TransactionFailedException;
 
 /**
  * This class is applicable only when invoking XADisk as a JCA Resource 
Adapter.
@@ -47,8 +46,7 @@
      * Commits the local transaction bound to this object.
      * @throws NoTransactionAssociatedException
      */
-    public void commitLocalTransaction() throws 
NoTransactionAssociatedException,
-        TransactionFailedException {
+    public void commitLocalTransaction() throws 
NoTransactionAssociatedException {
         localTxnImpl._commit();
         
mc.raiseUserLocalTransactionEvent(ConnectionEvent.LOCAL_TRANSACTION_COMMITTED);
     }
@@ -57,8 +55,7 @@
      * Rolls back the local transaction bound to this object.
      * @throws NoTransactionAssociatedException
      */
-    public void rollbackLocalTransaction() throws 
NoTransactionAssociatedException,
-        TransactionFailedException {
+    public void rollbackLocalTransaction() throws 
NoTransactionAssociatedException {
         localTxnImpl._rollback();
         
mc.raiseUserLocalTransactionEvent(ConnectionEvent.LOCAL_TRANSACTION_ROLLEDBACK);
     }
Index: trunk/src/org/xadisk/connector/outbound/XADiskLocalTransaction.java
===================================================================
--- trunk/src/org/xadisk/connector/outbound/XADiskLocalTransaction.java 
(revision 540)
+++ trunk/src/org/xadisk/connector/outbound/XADiskLocalTransaction.java 
(revision 541)
@@ -12,7 +12,6 @@
 import javax.resource.spi.LocalTransaction;
 import org.xadisk.filesystem.XAFileSystemCommonness;
 import org.xadisk.filesystem.exceptions.NoTransactionAssociatedException;
-import org.xadisk.filesystem.exceptions.TransactionFailedException;
 
 public class XADiskLocalTransaction implements LocalTransaction {
 
@@ -34,7 +33,7 @@
         _begin();
     }
 
-    void _rollback() throws NoTransactionAssociatedException, 
TransactionFailedException {
+    void _rollback() throws NoTransactionAssociatedException {
         
mc.setTypeOfCurrentTransaction(XADiskManagedConnection.NO_TRANSACTION);
         mc.getSessionOfLocalTransaction().rollback();
     }
@@ -44,12 +43,10 @@
             _rollback();
         } catch (NoTransactionAssociatedException note) {
             throw new ResourceException(note);
-        } catch (TransactionFailedException tfe) {
-            throw new ResourceException(tfe);
         }
     }
 
-    void _commit() throws NoTransactionAssociatedException, 
TransactionFailedException {
+    void _commit() throws NoTransactionAssociatedException {
         
mc.setTypeOfCurrentTransaction(XADiskManagedConnection.NO_TRANSACTION);
         mc.getSessionOfLocalTransaction().commit();
     }
@@ -59,8 +56,6 @@
             _commit();
         } catch (NoTransactionAssociatedException note) {
             throw new ResourceException(note);
-        } catch (TransactionFailedException tfe) {
-            throw new ResourceException(tfe);
         }
     }
 
Index: trunk/src/org/xadisk/bridge/proxies/impl/RemoteSession.java
===================================================================
--- trunk/src/org/xadisk/bridge/proxies/impl/RemoteSession.java (revision 540)
+++ trunk/src/org/xadisk/bridge/proxies/impl/RemoteSession.java (revision 541)
@@ -19,7 +19,6 @@
 import 
org.xadisk.filesystem.exceptions.InsufficientPermissionOnFileException;
 import org.xadisk.filesystem.exceptions.LockingFailedException;
 import org.xadisk.filesystem.exceptions.NoTransactionAssociatedException;
-import org.xadisk.filesystem.exceptions.TransactionFailedException;
 
 public class RemoteSession extends RemoteObjectProxy implements 
SessionCommonness {
 
@@ -357,29 +356,25 @@
         }
     }
 
-    public void commit() throws NoTransactionAssociatedException, 
TransactionFailedException {
+    public void commit() throws NoTransactionAssociatedException {
         this.commit(true);
     }
 
-    public void commit(boolean onePhase) throws 
NoTransactionAssociatedException, TransactionFailedException {
+    public void commit(boolean onePhase) throws 
NoTransactionAssociatedException {
         try {
             invokeRemoteMethod("commit", onePhase);
         } catch (NoTransactionAssociatedException note) {
             throw note;
-        } catch (TransactionFailedException tfe) {
-            throw tfe;
         } catch (Throwable t) {
             throw assertExceptionHandling(t);
         }
     }
 
-    public void rollback() throws NoTransactionAssociatedException, 
TransactionFailedException {
+    public void rollback() throws NoTransactionAssociatedException {
         try {
             invokeRemoteMethod("rollback");
         } catch (NoTransactionAssociatedException note) {
             throw note;
-        } catch (TransactionFailedException tfe) {
-            throw tfe;
         } catch (Throwable t) {
             throw assertExceptionHandling(t);
         }
Index: trunk/src/org/xadisk/bridge/proxies/interfaces/XAFileSystem.java
===================================================================
--- trunk/src/org/xadisk/bridge/proxies/interfaces/XAFileSystem.java    
(revision 540)
+++ trunk/src/org/xadisk/bridge/proxies/interfaces/XAFileSystem.java    
(revision 541)
@@ -11,6 +11,7 @@
 import java.io.IOException;
 import javax.transaction.xa.XAResource;
 import org.xadisk.filesystem.exceptions.RecoveryInProgressException;
+import org.xadisk.filesystem.exceptions.TransactionFailedException;
 import org.xadisk.filesystem.exceptions.XASystemNoMoreAvailableException;
 
 /**
@@ -84,7 +85,21 @@
      */
     public void shutdown() throws IOException;
 
+    /**
+     * Returns a two-dimensional array <i>arr</i> of bytes where each of 
<i>arr[0], arr[1], arr[2]...</i>
+     * represents a transaction identifier in the byte[] form. These 
transactions have failed
+     * during normal operations or during the recovery phase of XADisk.
+     * <p> See {@link TransactionFailedException}.
+     * @return a two-dimensional byte array containing the transaction 
identifiers.
+     * @since 1.2.2
+     */
     public byte[][] getIdentifiersForFailedTransactions();
-    
+
+    /**
+     * Mark the transaction specified by the input 
<i>transactionIdentifier</i> as complete.
+     * <p> See {@link TransactionFailedException}.
+     * @param transactionIdentifier the identifier for the transaction to be 
marked as complete.
+     * @since 1.2.2
+     */
     public void declareTransactionAsComplete(byte[] transactionIdentifier);
 }
Index: trunk/src/org/xadisk/bridge/proxies/interfaces/Session.java
===================================================================
--- trunk/src/org/xadisk/bridge/proxies/interfaces/Session.java (revision 540)
+++ trunk/src/org/xadisk/bridge/proxies/interfaces/Session.java (revision 541)
@@ -11,7 +11,6 @@
 import org.xadisk.connector.outbound.XADiskConnection;
 import org.xadisk.filesystem.FileSystemConfiguration;
 import org.xadisk.filesystem.exceptions.NoTransactionAssociatedException;
-import org.xadisk.filesystem.exceptions.TransactionFailedException;
 
 /**
  * This interface is used to invoke i/o operations on XADisk and to control 
the transaction 
@@ -51,11 +50,11 @@
      * Rolls back the transaction associated with this Session.
      * @throws NoTransactionAssociatedException
      */
-    public void rollback() throws NoTransactionAssociatedException, 
TransactionFailedException;
+    public void rollback() throws NoTransactionAssociatedException;
 
     /**
      * Commits the transaction associated with this Session.
      * @throws NoTransactionAssociatedException
      */
-    public void commit() throws NoTransactionAssociatedException, 
TransactionFailedException;
+    public void commit() throws NoTransactionAssociatedException;
 }





[xadisk~svn:541] Javadoc for JIRA issue#76.

nitin_verma 08/21/2013
 
 
Close
loading
Please Confirm
Close