001: // THIS SOFTWARE IS PROVIDED BY SOFTARIS PTY.LTD. AND OTHER METABOSS
002: // CONTRIBUTORS ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING,
003: // BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
004: // FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SOFTARIS PTY.LTD.
005: // OR OTHER METABOSS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
006: // INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
007: // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
008: // OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
009: // LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
010: // NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
011: // EVEN IF SOFTARIS PTY.LTD. OR OTHER METABOSS CONTRIBUTORS ARE ADVISED OF THE
012: // POSSIBILITY OF SUCH DAMAGE.
013: //
014: // Copyright 2000-2005 © Softaris Pty.Ltd. All Rights Reserved.
015: package com.metaboss.enterprise.transaction;
016:
017: /** This interface is somewhat reluctant addition by MetaBoss to the JTA specification.
018: * It provides access to the rich transaction status information.
019: * <p><u>Problem description</u> Java Transaction Architecture (JTA) Specification
020: * defines very simple (almost too simple) transaction status mechanism.
021: * Under this mechanism :
022: * <UL>
023: * <LI> Any transaction participant (eg. server doing some work in transaction) is able to mark
024: * transaction for rollback via UserTransaction.setRollbackOnly() or Transaction.setRollbackOnly() methods.</LI>
025: * <LI> Any transaction participant can check the status of the current transaction via
026: * UserTransaction.getStatus() and Transaction.getStatus() methods.</LI>
027: * </UL>
028: * The facility to communicate more details about cause of rollback is absent. Such details may contain
029: * an identity of the party, which have had a problem and the description of the problem
030: * (may be in form of exception). Absence of this facility forces application programmers to invent
031: * some "on-the-side" mechanisms to carry rich transaction status information in transaction context.
032: * The addition of the cause exception to the java.lang.Throwable in Java 1.4.x offers some opportunity to
033: * use cause in the HeuristicRollbackException to communicate the cause of rollback, but it is only helping the
034: * code which has issued commit() instruction.</p>
035: * <p><u>Solution description</u> In order not to pollute JTA interfaces, separate ExtendedTransactionStatus
036: * interface is introduced. The instance of this interface is obtainable via JNDI alongside with
037: * javax.transaction.Transaction and javax.transaction.UserTransaction. This interface provides
038: * facility to store and retrieve rollback cause together with transaction status. Because this interface is
039: * an addition to JTA - it's usage (or decision not to use) remains entirely an application discretion.
040: * We envisage that if and when JTA specification is enhanced (say UserTransaction and Transaction objects
041: * will have similar facility in their interfaces) we will offer clients a smooth transition along the following lines:
042: * <OL>
043: * <LI>At this stage com.metaboss.enterprise.transaction.ExtendedTransactionStatus will be the only
044: * component able to deliver this functionality. The implementation will reside in MetaBoss run-time libraries.
045: * ExtendedTransactionStatus does not override JTA status management facilities, JTA components will have to be
046: * used for setting transactions to rollback status and checking basic transaction status. This means that
047: * client application code will be 100% compliant with J2EE and any other Java standard in this area.</LI>
048: * <LI>After JTA Interfaces are enhanced and able to offer similar facilities, the
049: * com.metaboss.enterprise.transaction.ExtendedTransactionStatus interface will continue to offer this facility
050: * but it will be deprecated and internal implementation will revert to JTA. If and when this occurs,
051: * changes and schedule for deprecation and ultimate retirement of this interface will be communicated to clients.</LI>
052: * <LI>After a while (say one or two major release cycles or 12 month) com.metaboss.enterprise.transaction.ExtendedTransactionStatus
053: * will be retired. There may also be some interim release where com.metaboss.enterprise.transaction.ExtendedTransactionStatus is present, but
054: * each and every method throws javax.transaction.NotSupportedException</LI>
055: * </OL></p>
056: * <p><u>Usage description</u>
057: * To set transaction to rollback only after failure has occurred :
058: * <p><code><pre>
059: * import javax.naming.Context;
060: * import javax.naming.InitialContext;
061: * import javax.transaction.Transaction;
062: * import com.metaboss.enterprise.transaction.ExtendedTransactionStatus;
063: * ...............................
064: * ...............................
065: * try
066: * {
067: * ...............................
068: * ...............................
069: * }
070: * catch(SomeBadException lShowStopperException)
071: * {
072: * Context lContext = new javax.naming.InitialContext();
073: * Transaction lTransaction = (Transaction)lContext.lookup(com.metaboss.enterprise.transaction.Transaction.COMPONENT_URL);
074: * ExtendedTransactionStatus lExtendedTransactionStatus = (ExtendedTransactionStatus)lContext.lookup(com.metaboss.enterprise.transaction.ExtendedTransactionStatus.COMPONENT_URL);
075: * lTransaction.setRollbackOnly();
076: * lExtendedTransactionStatus.setRollbackCause(lShowStopperException);
077: * }
078: * </pre></code></p>
079: * To check extended status after failure has occurred :
080: * <p><code><pre>
081: * import javax.naming.Context;
082: * import javax.naming.InitialContext;
083: * import javax.transaction.UserTransaction;
084: * import javax.transaction.HeuristicRollbackException;
085: * import com.metaboss.enterprise.transaction.ExtendedTransactionStatus;
086: * ...............................
087: * ...............................
088: * Context lContext = new javax.naming.InitialContext();
089: * try
090: * {
091: * UserTransaction lUserTransaction = (UserTransaction)lContext.lookup(com.metaboss.enterprise.transaction.UserTransaction.COMPONENT_URL);
092: * ...............................
093: * ...............................
094: * ...............................
095: * lUserTransaction.commit();
096: * }
097: * catch(HeuristicRollbackException lRollbackException)
098: * {
099: * try
100: * {
101: * ExtendedTransactionStatus lExtendedTransactionStatus = (ExtendedTransactionStatus)lContext.lookup(com.metaboss.enterprise.transaction.ExtendedTransactionStatus.COMPONENT_URL);
102: * Throwable lRollbackCauseException = lExtendedTransactionStatus.getRollbackCause();
103: * if (lRollbackCauseException != null)
104: * {
105: * // Obtained ExtendedTransactionStatus object, and it has information about cause.
106: * // Cause is known. Analyse it or report it
107: * ...............................
108: * ...............................
109: * }
110: * else
111: * {
112: * // Obtained ExtendedTransactionStatus object, but it does not have information about cause.
113: * // Cause is unknown. Report this situation somehow
114: * ...............................
115: * ...............................
116: * }
117: * }
118: * catch(javax.naming.NamingException lNamingException)
119: * {
120: * // Unable to obtain ExtendedTransactionStatus object.
121: * // Cause is unknown. Report this situation somehow
122: * ...............................
123: * ...............................
124: * }
125: * }
126: * </pre></code></p>
127: */
128: public interface ExtendedTransactionStatus {
129: /** Naming URL of the factory component */
130: public static final String COMPONENT_URL = "component:/com.metaboss.enterprise.transaction.ExtendedTransactionStatus";
131:
132: /** Saves rollback cause. Can only be called once after transaction status is already set to rollback only.
133: * @exception javax.transaction.SystemException thrown if this operation encountered some sort of system error preventing it from completion
134: * @exception javax.transaction.NotSupportedException thrown if this mechanism is not supported.
135: * @exception java.lang.IllegalStateException thrown if current thread is not associated with transaction, transaction is not market for rollback or
136: * rollback cause for this transaction has been stored already.
137: */
138: public void setRollbackCause(Throwable pCause)
139: throws javax.transaction.SystemException,
140: javax.transaction.NotSupportedException,
141: java.lang.IllegalStateException;
142:
143: /** Retrieves rollback cause. Can be called at any time, but may return null meaning that
144: * cause has not been stored. The reasons may be that transaction has not been rolled back,
145: * no one has actually stored the cause etc..
146: * @exception javax.transaction.SystemException thrown if this operation encountered some sort of system error preventing it from completion
147: * @exception javax.transaction.NotSupportedException thrown if this mechanism is not supported.
148: * @exception java.lang.IllegalStateException thrown if current thread is not associated with transaction or transaction is not
149: * in one of the roolback states : javax.transaction.Status.STATUS_MARKED_ROLLBACK or javax.transaction.Status.STATUS_ROLLEDBACK
150: * or javax.transaction.Status.STATUS_ROLLING_BACK
151: */
152: public Throwable getRollbackCause()
153: throws javax.transaction.SystemException,
154: javax.transaction.NotSupportedException,
155: java.lang.IllegalStateException;
156: }
|