Transaction.java

/*
 * $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;
  }
}