/*

  * $Source$

  * $Revision$

  *

  * Copyright (C) 2000 William Chesters

  *

  * Part of Melati (http://melati.org), a framework for the rapid

  * development of clean, maintainable web applications.

  *

  * Melati is free software; Permission is granted to copy, distribute

  * and/or modify this software under the terms either:

  *

  * a) the GNU General Public License as published by the Free Software

  *    Foundation; either version 2 of the License, or (at your option)

  *    any later version,

  *

  *    or

  *

  * b) any version of the Melati Software License, as published

  *    at http://melati.org

  *

  * You should have received a copy of the GNU General Public License and

  * the Melati Software License along with this program;

  * if not, write to the Free Software Foundation, Inc.,

  * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA to obtain the

  * GNU General Public License and visit http://melati.org to obtain the

  * Melati Software License.

  *

  * Feel free to contact the Developers of Melati (http://melati.org),

  * if you would like to work out a different arrangement than the options

  * outlined here.  It is our intention to allow Melati to be used by as

  * wide an audience as possible.

  *

  * This program is distributed in the hope that it will be useful,

  * but WITHOUT ANY WARRANTY; without even the implied warranty of

  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

  * GNU General Public License for more details.

  *

  * Contact details for copyright holder:

  *

  *     William Chesters <williamc At paneris.org>

  *     http://paneris.org/~williamc

  *     Obrechtstraat 114, 2517VX Den Haag, The Netherlands

  */

 package org.melati.poem.transaction;

 import java.util.Vector;

 import org.melati.poem.UnexpectedExceptionPoemException;

 /**

  * A Transaction.

  */

 public abstract class Transaction {

   /** Index of the Transaction. */

   public final int index;

   /** Mask. */

   public final int mask;

   /** Negative mask. */

   public final int negMask;

   /** The transaction we are waiting on. */

   private Transaction blockedOn = null;

   /** The transactions that are directly waiting on us. */

   private Vector<Transaction> blockees = new Vector<Transaction>();

   /** The transitive closure of the transactions we are waiting on. */

   private int blockedOnMask;

   private int seenCapacityMin = 50;

   private int seenCapacityMax = 1000;

   private Vector<Transactioned> seen = new Vector<Transactioned>(seenCapacityMin);

   private int touchedCapacityMin = 50;

   private int touchedCapacityMax = 1000;

   private Vector<Transactioned> touched = new Vector<Transactioned>();

   private TransactionPool transactionPool;

   /**

    * Constructor.

    * 

    * @param transactionPoolP the pool this transaction belongs to 

    * @param indexP the key for this Transaction 

    */

   public Transaction(TransactionPool transactionPoolP, int indexP) {

     this.transactionPool = transactionPoolP;

     if (indexP > transactionPool.transactionsMax())

       throw new TransactionIndexTooLargeException();

     this.index = indexP;

     mask = 1 << index;

     negMask = ~mask;

   }

   protected abstract void backingCommit();

   protected abstract void backingRollback();

   /**

    * The thread calling block will have to wait

    * until (another thread) calls finish and calls notifyAll.

    */

   synchronized void block(Transaction blockee) {

     blockees.addElement(blockee);

     blockee.blockedOn = this;

     blockee.propagateBlockage();

     try {

       wait();

     }

     catch (InterruptedException e) {

       throw new UnexpectedExceptionPoemException(e);

     }

     finally {

       blockees.removeElement(blockee);

       blockee.blockedOn = null;

       blockee.propagateBlockage();

     }

   }

   private synchronized void propagateBlockage() {

     if (blockedOn == null)

       blockedOnMask = mask;  // we are only waiting on ourself

     else {

       if ((blockedOn.blockedOnMask & mask) != 0)

         throw new WouldDeadlockException();

       blockedOnMask = blockedOn.blockedOnMask | mask;

     }

     for (int i = blockees.size() - 1; i >= 0; --i)

       ((Transaction)blockees.elementAt(i)).propagateBlockage();

   }

   final void notifyTouched(Transactioned persistent) {

     touched.addElement(persistent);

   }

   final void notifySeen(Transactioned persistent) {

     seen.addElement(persistent);

   }

   /**

    * Make persistent ie no longer able to be rolled back.

    */

   public void writeDown() {

     synchronized (touched) {

       for (Transactioned persistent : touched) 

         persistent.writeDown(this);

     }

   }

   private void unSee() {

     synchronized (seen) {

       for (Transactioned persistent : seen)

         persistent.unSee(this);

       if (seen.size() > seenCapacityMax)

         seen = new Vector<Transactioned>(seenCapacityMin);

       else

         seen.setSize(0);

     }

   }

   // This doesn't have to be synchronized.

   private void finish(boolean commit) {

     try {

       if (commit) {

         writeDown();

         backingCommit();

       }

       else

         backingRollback();

       for (Transactioned persistent : touched) { 

           if (commit)

               persistent.commit(this);

             else

               persistent.rollback(this);

       }

     }

     finally {

       if (touched.size() > touchedCapacityMax)

         touched = new Vector<Transactioned>(touchedCapacityMin);

       else

         touched.setSize(0);

       unSee();

       // notifyAll will wake too many threads if some of them are writers, but

       // this is really the best we can do without using heavy Lock-ish objects

       synchronized (this) {

         notifyAll();

       }

     }

   }

   /**

    * Finish up, for example write to database.

    */

   public void commit() {

     try {

       finish(true);

     }

     catch (RuntimeException e) {

       try {

         System.err.println("Rolling back due to " + e);

         finish(false);

       }

       catch (Exception ignore) {

         // Ignore

         ignore = null; // shut PMD up

       }

       throw e;

     }

   }

   /**

    * Finish without commit.

    */

   public void rollback() {

     finish(false);

   }

   /**

    * @return the Transaction we are waiting for

    */

   public Transaction getBlockedOn() {

     return blockedOn;

   }

   /**

    * The transaction index.

    * {@inheritDoc}

    * @see java.lang.Object#toString()

    */

   public String toString() {

     return "transaction" + index;

   }

 }