// 
// Name
//  $RCSfile: Transaction.java,v $
// 
// COPYRIGHT
//  Copyright 2008-2012 Cloud Software Group, Inc. ALL RIGHTS RESERVED.
//  Cloud Software Group, Inc. Confidential Information
//
// History
//  $Revision: 1.1.2.20 $ $Date: 2012/05/03 17:55:41 $
// 

package com.kabira.platform;

import com.kabira.platform.annotation.Managed;

import java.io.StringWriter;
import java.io.PrintWriter;

/** 
 * Executes code in the context of a transaction.
 *
 * <p> The class should be extended and the abstract {@link Transaction#run}
 * method implemented. When executed via {@link Transaction#execute},
 * all code executed within the <code>run</code> method will be
 * transactional, changes to Managed objects are logged.
 *
 * <p> Object instances that are modified are write locked into the
 * transaction, blocking access from other transactions until the
 * transaction commits or rolls back.
 *
 * <p> If the default {@link IsolationLevel#SERIALIZABLE} Isolation level
 * is used, object instances that are accessed but not modified will be
 * read locked into the transaction. This will allow other transactions
 * to also access and read lock the object, but prevents other
 * transactions from modifying the object.
 *
 * <p> If the {@link IsolationLevel#READ_COMMITTED_SNAPSHOT} Isolation
 * level is used, object instances that are accessed but not modified
 * will have a snapshot of the data taken when first accessed in the
 * transaction. All subseqeunt accesses to the object data within the
 * same transaction will use this snapshot in order to present a
 * consistent view of the data. This will allow other transactions to
 * both access and modify the object. If a transaction takes a snapshot,
 * and subsequently attempts to modify the object, the runtime will
 * determine if the object data has been modified by another transaction
 * since the snapshot was taken. If it has been modified, a deadlock
 * exception is thrown in order to retry the transaction.
 *
 * <p> Any deadlocks that occur will automatically cause a roll back of the
 * current transaction, and the code within the <code>run</code> method will
 * be re-executed. This means that any code called within the
 * <code>run</code> method must be transaction safe. If the work done within
 * the <code>run</code> method should not be executed more than once, the work
 * should be deferred until commit time by using a transaction commit
 * trigger.
 *
 * <h3>Exception handling</h3>
 *
 * If the code within the <code>run</code> method throws a {@link
 * Transaction.Rollback} exception with no cause, the
 * <code>execute</code> call will roll back the transaction, and return
 * {@link Transaction.Result#ROLLBACK} to the caller. In order to support
 * exception propagation through the <code>execute</code> method, the
 * following mechanisms can be used:
 * <ul>
 * <li> If an unchecked exception is thrown in the <code>run</code>
 * method, the exception will be rethrown to the caller of <code>execute</code>.
 * <li> If the implementor of the <code>run</code> method wishes to
 * propagate a checked exception, they can throw a Rollback exception
 * with a cause. When caught by <code>execute</code>, the Rollback
 * exception cause and message will be wrapped in a
 * {@link Transaction.InvocationRunException} and thrown back to the caller.
 * </ul>
 * In both cases, the transaction is rolled back before the exception is
 * propagated. 
 */
public abstract class Transaction
{
    /**
     *  Execute method return values.
     */
    public enum Result
    {
        /** Transaction committed. */
        COMMIT,

        /** Transaction rolled back. */
        ROLLBACK
    }

    /**
     *  Transaction isolation levels.
     */
    public enum IsolationLevel
    {
        /**
         * Access data that has been committed. A snapshot of the data is
         * taken when a field is read, but locks are immediately released
         * to allow other transactions to update the data. Multiple
         * accesses to the same field returns the same data, even if the
         * underlying object has been updated in other transactions. If
         * an attempt is made to subsequently update the data after
         * another transaction has made changes, a deadlock exception is
         * thrown to retry the transaction.
         */
        READ_COMMITTED_SNAPSHOT,

        /**
         * All access is serialized using shared read and exclusive
         * write locks.
         */
        SERIALIZABLE
    }

    /**
     *  Invalid transaction state exception.
     *  <p>
     *  Exception thrown if execute() is called with a transaction
     *  already active, or if the transaction services are not available.
     */
    public static class InvalidTransactionState extends java.lang.Error
    {

        /**
         *  Serialization version.
         */
        public final static long serialVersionUID = 1L;

        InvalidTransactionState(String message)
        {
            super(message);
        }
    }

    /**
     *  Not transactional exception.
     *  <p>
     *  Exception thrown if one of the lock methods is called
     *  on a non-transactional object.
     */
    public static class NotTransactional extends java.lang.Error
    {
        /**
         *  Serialization version.
         */
        public final static long serialVersionUID = 1L;

        NotTransactional(String message)
        {
            super(message);
        }
    }

    /**
     *  Rollback exception.
     *  <p>
     *  Exception thrown in the run method to rollback the transaction.
     *  <p>
     *  If constructed with a cause, the cause is propagated through the
     *  execute() call via the InvocationRunException exception. 
     */
    public static class Rollback extends java.lang.Exception
    {
        /**
         *  Serialization version.
         */
        public final static long serialVersionUID = 1L;

        /**
         *  Creates a rollback exception.
         */
        public Rollback()
        {
            super();
        }

        /**
         *  Creates a rollback exception that is propagated to the caller.
         *  @param  cause   The Throwable causing the exception.
         */
        public Rollback(Throwable cause)
        {
            super(cause);
        }

        /**
         *  Creates a rollback exception that is propagated to the caller.
         *  @param  message Message to include in the exception.
         *  @param  cause   The throwable causing the exception.
         */
        public Rollback(String message, Throwable cause)
        {
            super(message, cause);
        }
    }

    /**
     *  Invocation run exception.
     *  <p>
     *  Exception thrown by the execute method when the enclosed
     *  <code>run</code> throws a Rollback exception with a cause.
     */
    public static class InvocationRunException
        extends java.lang.RuntimeException
    {
        /**
         *  Serialization version.
         */
        public final static long serialVersionUID = 1L;

        /**
         *  Creates an exception that is propagated to the caller.
         *  @param  message Message to include in the exception.
         *  @param  cause   The throwable causing the exception.
         */
        public InvocationRunException(String message, Throwable cause)
        {
            super(message, cause);
        }
    }

    /**
     *  Transaction identifier.
     *  <p>
     *  An identifier for the current transaction. Transaction
     *  identifiers are unique per JVM instance.  They are not
     *  unique across JVM restarts.
     *  <p>
     *  Multiple transaction identifiers created in the same
     *  transaction will return the same hash code, and comparisons
     *  using the equals() method will return true.
     *  <p>
     *  Transaction identifiers are provided for logging purposes
     *  only.
     */
    public static class Identifier
    {
        private String  m_id;

        private Identifier()
        {
            m_id = getId();
        }

        /**
         *  Returns a string representation of a transaction identifier.
         *  @return  The string representation of a transaction identifier.
         */
        @Override
        public String toString()
        {
            return m_id;
        }

        /**
         *  Determines if two transaction identifiers are the same.
         *  @param id Transaction identifier to compare
         * @return     True if both objects represent the
         *          same transaction identifier.
         */
        @Override
        public boolean equals(Object id)
        {
            if (!(id instanceof Identifier))
            {
                return false;
            }
            return m_id.equals(((Identifier)id).m_id);
        }

        /**
         *  Returns a hash value for this transaction identifier.
         *  @return     A hash code value for this transaction identifier.
         */
        @Override
        public int hashCode()
        {
            return m_id.hashCode();
        }
    }

    /**
     * The Transaction properties used when executing a transaction
     */
    public final static class Properties
    {
        /**
         * Default constructor, sets properties to default values:
         * <p>
            isolationLevel = {@link IsolationLevel#SERIALIZABLE},
            transactionName is null.
         */
        public Properties()
        {
            //
            // FIX THIS: We can't access the class name of the outer
            // class, the getEnclosingClass() method will always return
            // "Transaction".
            //
            m_isolationLevel = IsolationLevel.SERIALIZABLE;
            m_transactionName = null;
        }
        /**
         * Construct a properties instance with the given isolation level
         * and a null transaction name.
         *
         * @param isolationLevel - Isolation level of transaction
         *  when it executes.
         */
        public Properties(IsolationLevel isolationLevel)
        {
            m_isolationLevel = isolationLevel;
            m_transactionName = null;
        }

        /**
         * Construct a properties instance with the given name and a
         * default isolationLevel of {@link IsolationLevel#SERIALIZABLE}
         *
         * @param transactionName - Name of transaction when it executes.
         */
        public Properties(String transactionName)
        {
            m_transactionName = transactionName;
            m_isolationLevel = IsolationLevel.SERIALIZABLE;
        }

        /**
         * Construct a properties instance with the given name and
         * isolation level.
         *
         * @param transactionName - Name of transaction when it executes.
         * @param isolationLevel - Isolation level of transaction
         *  when it executes.
         */
        public Properties(String transactionName, IsolationLevel isolationLevel)
        {
            m_transactionName = transactionName;
            m_isolationLevel = isolationLevel;
        }
        /**
         * Set the transaction name.
         *
         * @param transactionName - Name of transaction when executed.
         */
        public void setTransactionName(String transactionName)
        {
            m_transactionName = transactionName;
        }
        /**
         * Get the transaction name.
         * <p>
         * If never set, returns null. If passed into the {@link
         * Transaction#execute(Properties)} method as null, the name
         * passed into the {@link Transaction#Transaction(String)}
         * constructor is used, or the calling class name is used if the 
         * default {@link Transaction#Transaction()} constructor was used.
         *
         * @return String containing transaction name.
         */
        public String getTransactionName()
        {
            return m_transactionName;
        }
        /**
         * Set the isolation level.
         *
         * @param isolationLevel - Isolation level of transaction
         *  when it executes.
         */
        public void setIsolationLevel(IsolationLevel isolationLevel)
        {
            m_isolationLevel = isolationLevel;
        }
        /**
         * Get the isolation level.
         *
         * @return Current isolation level.
         */
        public IsolationLevel getIsolationLevel()
        {
            return m_isolationLevel;
        }

        private String m_transactionName;
        private IsolationLevel m_isolationLevel;
    }

    /**
     * Creates a new transaction.
     * @param transactionName - Name associated with the transaction.
     */ 
    public Transaction(final String transactionName)
    {
        m_defaultProperties = new Properties(transactionName);
    }

    /**
     *  Creates a new transaction.
     */ 
    public Transaction()
    {
        m_defaultProperties = new Properties(getClass().getName());
    }

    /**
     *  User defined method that is run in the context of a transaction.
     *  
     *  @exception com.kabira.platform.Transaction.Rollback
     *      Thrown if the transaction should be rolled back
     *      and all changes discarded.
     */
    protected abstract void run() throws Transaction.Rollback;

    /**
     * Executes the user defined method within a transaction. Any
     * deadlocks are transparently retried.
     *
     * @param properties - Properties used when executing the transaction.
     *
     * @return Result of transaction
     *
     * @throws InvalidTransactionState
     *  If a transaction is already active, or the transaction services
     *  are not available.
     * @throws InvocationRunException
     *  The execution of the run method resulted in an exception
     *  that was propagated.
     */
    public final Result execute(Properties properties)
        throws InvalidTransactionState, InvocationRunException
    {
        String transactionName = properties.getTransactionName();
        if (transactionName == null)
        {
            transactionName = getClass().getName();
        }
        assert( properties.getIsolationLevel() ==
                    IsolationLevel.READ_COMMITTED_SNAPSHOT ||
                properties.getIsolationLevel() == 
                    IsolationLevel.SERIALIZABLE );
        int isolationLevel = (properties.getIsolationLevel() ==
                IsolationLevel.READ_COMMITTED_SNAPSHOT)
                    ? ReadCommittedSnapshot : Serializable;

        boolean done = false;
        Result  result = Result.ROLLBACK;

        m_numDeadlocks = 0;

        while (!done)
        {
            begin(transactionName, isolationLevel);
            try
            {
                run();
                prepare();
                commit();
                result = Result.COMMIT;
                done = true;
            }
            catch (Rollback ex)
            {
                abort(null);
                if (ex.getCause() != null)
                {
                    throw new InvocationRunException(
                        ex.getMessage(), ex.getCause());
                }
                done = true;
            }
            catch (com.kabira.ktvm.transaction.DeadlockError ex)
            {
                StringWriter sw = new StringWriter();
                ex.printStackTrace(new PrintWriter(sw));
                abort(sw.toString());
                deadlockBackoff(transactionName, ++m_numDeadlocks);
            }
            catch (java.lang.Error ex)
            {
                abort(null);
                throw ex;
            }
            catch (java.lang.RuntimeException ex)
            {
                abort(null);
                throw ex;
            }
        }
        return result;
    }

    /**
     *  Executes the user defined method within a transaction. Any
     *  deadlocks are transparently retried. 
     * <p>
     * The default isolationLevel of SERIALIZABLE is used for the
     * transaction.
     *
     * @return Result of transaction
     * @throws InvalidTransactionState
     *  If a transaction is already active, or the transaction services
     *  are not available.
     * @throws InvocationRunException
     *  The execution of the run method resulted in an exception
     *  that was propagated.
     */
    public final Result execute()
        throws InvalidTransactionState, InvocationRunException
    {
        return execute(m_defaultProperties);
    }

    /**
     *  Returns the transaction identifier for the current transaction.
     *
     *  This only returns a valid transaction identifier when there
     *  is an active transaction.
     *
     *  @throws java.lang.IllegalAccessError
     *  No active transaction
     *
     *  @return The current transaction identifier.
     */
    public static final Identifier getIdentifier()
        throws IllegalAccessError
    {
        return new Identifier();
    }

    /**
     * Returns the transaction properties for the current transaction.
     *
     * This only returns the properties when there is an active transaction.
     *
     * @throws java.lang.IllegalAccessError
     *  No active transaction
     *
     * @return The properties for the given active transaction.
     */
    public static final Properties getActiveTransactionProperties()
        throws IllegalAccessError
    {
        String transactionName = getTransactionName();

        int ilevel = getIsolationLevel();
        assert( ilevel == ReadCommittedSnapshot || ilevel == Serializable );

        IsolationLevel isolationLevel = (ilevel == ReadCommittedSnapshot)
            ? IsolationLevel.READ_COMMITTED_SNAPSHOT
            : IsolationLevel.SERIALIZABLE;

        return new Properties(transactionName, isolationLevel);
    }

    /**
     *  Determines if a transaction is active.
     *
     *  @return true if a transaction is active, false otherwise.
     */
    public native static boolean isActive();

    /**
     *  Returns the number of deadlocks detected and replayed for the last
     *  call to execute().
     *
     *  @return     The number of detected deadlocks.
     */
    public final int getNumberDeadlocks()
    {
        return m_numDeadlocks;
    }

    /**
     *  Establishes a write lock for the given object.
     *
     *  @param  obj Object to lock.
     *
     *
     *  @throws java.lang.IllegalAccessError
     *  No active transaction
     *
     *  @throws NotTransactional
     *  If the object passed in is not Managed.
     */
    public static final void writeLockObject(Object obj)
        throws IllegalAccessError, NotTransactional
    {
        validateObject(obj, "writeLockObject");
        lockObject(getObjectType(obj), WRITE_LOCK, obj);
    }

    /**
     * Establishes a read lock for the given object.
     * <p>
     * If the current transaction isolation level is {@link
     * IsolationLevel#READ_COMMITTED_SNAPSHOT}, a snapshot of the data is
     * taken and the read lock immediately released.
     *
     * @param  obj Object to lock.
     *
     * @throws java.lang.IllegalAccessError
     *  No active transaction
     *
     * @throws NotTransactional
     *  If the object passed in is not Managed.
     */
    public static final void readLockObject(Object obj)
        throws IllegalAccessError, NotTransactional
    {
        validateObject(obj, "readLockObject");
        lockObject(getObjectType(obj), READ_LOCK, obj);
    }

    /**
     *  Determines if a write lock exists for the given object.
     *
     *  @param  obj Object to examine.
     *
     *  @throws java.lang.IllegalAccessError
     *  No active transaction
     *
     *  @throws NotTransactional
     *  If the object passed in is not Managed.
     *
     *  @return     true if a write lock exists on the given
     *          object, false otherwise.
     */
    public static final boolean hasWriteLock(Object obj)
        throws IllegalAccessError, NotTransactional
    {
        validateObject(obj, "hasWriteLock");
        return hasLock(getObjectType(obj), WRITE_LOCK, obj);
    }

    /**
     * Determines if a read lock exists for the given object.
     * <p>
     * If the current transaction isolation level is {@link
     * IsolationLevel#READ_COMMITTED_SNAPSHOT}, readlocks are immediately
     * released after a snapshot is taken. In this case hasReadLock()
     * will always return false.
     *
     * @param  obj Object to examine
     *
     * @throws java.lang.IllegalAccessError
     *  No active transaction
     *
     * @throws NotTransactional
     *  If the object passed in is not Managed.
     *
     * @return  true if a read lock exists on the given
     *          object, false otherwise.
     */
    public static final boolean hasReadLock(Object obj)
        throws IllegalAccessError, NotTransactional
    {
        validateObject(obj, "hasReadLock");
        return hasLock(getObjectType(obj), READ_LOCK, obj);
    }

    //
    // Determine if this obj passed in is ManagedObject
    //
    @SuppressWarnings("deprecation")
    private static int getObjectType(Object obj)
    {
        Class<?> cl = obj.getClass();
        if (cl.isAnnotationPresent(
                com.kabira.platform.annotation.Distributed.class)
            || cl.isAnnotationPresent(Managed.class))
        {
            return MANAGED_OBJECT;
        }
        return JAVA_OBJECT;
    }

    //
    // Validate the object can be used in a transaction.
    //
    @SuppressWarnings("deprecation")
    private static void validateObject(Object obj, String op)
    {
        Class<?> cl = obj.getClass();
        if ((!cl.isAnnotationPresent(
                com.kabira.platform.annotation.Distributed.class))
            && (!cl.isAnnotationPresent(Managed.class)))
        {
            throw new NotTransactional(op + " cannot be used " +
                "on a non-Managed object");
        }
    }

    //
    // These must match the LockType enum used in the C++ native methods
    //
    private static final int READ_LOCK = 1;
    private static final int WRITE_LOCK = 2;
    //
    // These must match the ObjSrv::TxnIsolationLevel enum used in the C++ native
    // methods.
    //
    private static final int Serializable = 1;
    private static final int ReadCommittedSnapshot = 2;
    //
    // These must match the ObjectType enum used in the C++ native methods
    //
    private static final int JAVA_OBJECT = 1;
    private static final int MANAGED_OBJECT = 2;

    //
    // Used to manage getNumDeadlocks()
    //
    private int m_numDeadlocks;

    //
    // Properties for transaction
    //
    private Properties m_defaultProperties;

    //
    // native methods
    //
    private native static void begin(
        final String transactionName, int isolationLevel)
            throws InvalidTransactionState;
    private native void prepare();
    private native void commit();
    private native static void abort(String st);
    private native static void deadlockBackoff(
        String tranName, int numDeadlocks);
    private native static void lockObject(
        int objType, int lockType, Object obj);
    private native static boolean hasLock(
        int objType, int lockType, Object obj);
    private native static final String getId();
    private native static final String getTransactionName();
    private native static final int getIsolationLevel();
}