package org.xvsm.interfaces;
   
   import java.io.Serializable;
   import java.util.Iterator;
   import java.util.List;
   import java.util.Properties;
   import java.util.TreeMap;
   
   import org.apache.log4j.Logger;
  import org.xvsm.core.ContainerRef;
  import org.xvsm.core.Entry;
  import org.xvsm.internal.exceptions.CannotShiftException;
  import org.xvsm.internal.exceptions.ContainerFullException;
  import org.xvsm.internal.exceptions.CountNotMetException;
  import org.xvsm.internal.exceptions.TransactionLockException;
  import org.xvsm.selectors.Selector;
  import org.xvsm.transactions.Transaction;
  
  /***
   * @author Christian Schreiber, Michael Proestler
   * 
   */
  public abstract class ICoordinator implements Serializable {
  
  	/***
  	 * The logger.
  	 */
  	private static Logger logger = Logger.getLogger(ICoordinator.class);
  
  	/***
  	 * The ContainerRef of the container.
  	 */
  	private ContainerRef cref;
  
  	/***
  	 * A lock object used for synchronisation.
  	 */
  	private Boolean lockObject = false;
  
  	/***
  	 * The current Transaction using this Coordinator.
  	 */
  	private Transaction writeLock;
  
  	/***
  	 * The Transactions that have readLocks on that Coordinator.
  	 */
  	private TreeMap<String, Transaction> readLocks = new TreeMap<String, Transaction>();
  
  	/***
  	 * The properties of this coordinator.
  	 */
  	protected Properties properties = new Properties();
  
  	/***
  	 * Tries to write the given Entry.
  	 * 
  	 * Otherwise {@link ContainerFullException} can be raised.
  	 * 
  	 * @param e
  	 *            The {@link Entry} that will be written.
  	 * @param s
  	 *            the Selector used for writing.
  	 * @param tx
  	 *            A Transaction under which the operation executes
  	 * @throws ContainerFullException
  	 *             thrown when the entry can not be written because there is no
  	 *             free place for it (e.g. full bounded container, vector
  	 *             position already used, key already present).
  	 * @throws TransactionLockException
  	 *             thrown if a lock can not be aquired because another
  	 *             transaction uses it.
  	 */
  	public abstract void write(Entry e, Transaction tx, Selector s)
  			throws ContainerFullException, TransactionLockException;
  
  	/***
  	 * Writes the Entry. If there is no place left, another Entry will be
  	 * deleted (shifted).
  	 * 
  	 * @param e
  	 *            The {@link Entry} that will be written.
  	 * @param s
  	 *            the Selector used for writing.
  	 * @param tx
  	 *            A Transaction under which the operation executes
  	 * @return The shifted {@link Entry} of <code>null</code> if no entry has
  	 *         been shifted.
  	 * @throws CannotShiftException
  	 *             thrown if the coordinator can not decide which entry has to
  	 *             be shifted.
  	 * @throws TransactionLockException
  	 *             thrown if a lock can not be aquired because another
  	 *             transaction uses it.
  	 */
  	public abstract Entry shift(Entry e, Transaction tx, Selector s)
  			throws TransactionLockException, CannotShiftException;
  
  	/***
 	 * Read {@link Entry}s that match with the Selector.
 	 * 
 	 * @param selector
 	 *            The Selector that must match.
 	 * @param tx
 	 *            A Transaction under which the operation executes
 	 * @param entries
 	 *            A {@link List} of {@link Entry}s to operate on. Null if it
 	 *            should operates on all known entries.
 	 * @throws CountNotMetException
 	 *             thrown if there are not enough entries to fulfill the count
 	 *             of the selector.
 	 * @throws TransactionLockException
 	 *             thrown if a lock can not be aquired because another
 	 *             transaction uses it.
 	 * @return a List of all matching entries.
 	 */
 	public abstract List<Entry> read(Transaction tx, Selector selector,
 			List<Entry> entries) throws TransactionLockException,
 			CountNotMetException;
 
 	/***
 	 * Deletes one specific entry.
 	 * 
 	 * @param tx
 	 *            A Transaction under which the operation executes
 	 * @param e
 	 *            The entry to delete.
 	 * @throws TransactionLockException
 	 *             thrown if a lock can not be aquired because another
 	 *             transaction uses it.
 	 */
 	public abstract void delete(Transaction tx, Entry e)
 			throws TransactionLockException;
 
 	/***
 	 * Sets the maximal containersize in the coordinator. Can be used to
 	 * optimize internal structures, and is needed for shift decisions.
 	 * 
 	 * @param maxSize
 	 *            the maximal size of entries in the coordinator.
 	 */
 	public abstract void setMaxContainerSize(int maxSize);
 
 	/***
 	 * Returns the default {@link Selector} for this Coordinator.
 	 * 
 	 * @return the default Selector for this Coordinator.
 	 */
 	public abstract Class<? extends Selector> getDefaultSelector();
 
 	/***
 	 * Commits an existing {@link Transaction} for this container.
 	 * 
 	 * @param tx
 	 *            The {@link Transaction} that should be commited.
 	 * @throws TransactionLockException
 	 *             thrown if a lock can not be aquired.
 	 */
 	public abstract void commit(Transaction tx) throws TransactionLockException;
 
 	/***
 	 * Commits an existing {@link Transaction} for this container.
 	 * 
 	 * @param tx
 	 *            The {@link Transaction} that should be commited.
 	 * @throws TransactionLockException
 	 *             thrown if a lock can not be aquired.
 	 */
 	public abstract void commitSubTransaction(Transaction tx)
 			throws TransactionLockException;
 
 	/***
 	 * Does a rollback on this {@link Transaction}.
 	 * 
 	 * @param tx
 	 *            The {@link Transaction} that should perform a rollback.
 	 * @throws TransactionLockException
 	 *             thrown if a lock can not be aquired.
 	 */
 	public abstract void rollback(Transaction tx)
 			throws TransactionLockException;
 
 	/***
 	 * @return the cref
 	 */
 	public ContainerRef getCref() {
 		return cref;
 	}
 
 	/***
 	 * @param cref
 	 *            the cref to set
 	 */
 	public void setCref(ContainerRef cref) {
 		this.cref = cref;
 	}
 
 	/***
 	 * Aquires the read or write lock for this coordinator.
 	 * 
 	 * @param write
 	 *            if <code>true</code> a writelock will be aquired. This means
 	 *            no readLock is allowed to be set. if <code>false</code> a
 	 *            readlock will be aquired,
 	 * @param tx
 	 *            the transaction which needs the lock
 	 * @throws TransactionLockException
 	 *             thrown if the lock can not be required.
 	 */
 	protected void aquireLock(boolean write, Transaction tx)
 			throws TransactionLockException {
 		if (logger.isDebugEnabled()) {
 			logger.debug("auireLock(" + write + ", " + tx + ")");
 		}
 		synchronized (this.lockObject) {
 			if (this.writeLock != null) {
 				if (!this.writeLock.isAncestorOf(tx)) {
 					if (logger.isDebugEnabled()) {
 						logger.debug("aquireLock() the Coordinator ("
 								+ this.getClass() + ") has a write lock: "
 								+ this.writeLock);
 					}
 					throw new TransactionLockException(this.writeLock);
 				}
 			}
 			if (write) {
 				// there are no reader allowed when one write is using the
 				// coordinator.
 				if (this.readLocks.size() != 0) {
 					Transaction readLock;
 					Iterator<Transaction> iter = this.readLocks.values()
 							.iterator();
 					while (iter.hasNext()) {
 						readLock = iter.next();
 						if (!readLock.isAncestorOf(tx)) {
 							throw new TransactionLockException(readLock);
 						}
 					}
 					this.readLocks.remove(tx.getId());
 				}
 				// everything is fine ... lock the coordinator.
 				this.writeLock = tx;
 
 			} else {
 				// if no write lock is set a read lock can always be
 				// granted.
 				if (tx != null && tx.getId() != null) {
 					this.readLocks.put(tx.getId(), tx);
 				}
 			}
 		}
 		if (logger.isDebugEnabled()) {
 			logger.debug("auireLock() lock aquired for coordinator "
 					+ this.getClass());
 		}
 	}
 
 	/***
 	 * Updates the locks of this coordinator.<br>
 	 * All locks which are set will be set to the father transaction or null if
 	 * there is no father.<br>
 	 * This method calls {@link ICoordinator#commitEntryLocks(Transaction)}.
 	 * 
 	 * @param tx
 	 *            the transaction to commit.
 	 * @throws TransactionLockException
 	 *             thrown if the lock can not be aquired.
 	 */
 	protected void commitLocks(Transaction tx) throws TransactionLockException {
 		if (logger.isDebugEnabled()) {
 			logger.debug("commitLocks(" + tx + ")");
 		}
 		synchronized (this.lockObject) {
 			if (this.readLocks.get(tx.getId()) != null) {
 				// remove the read lock.
 				this.readLocks.remove(tx.getId());
 				if (tx.getFather() != null) {
 					this.readLocks.put(tx.getFather().getId(), tx.getFather());
 				}
 			}
 			if (this.writeLock != null && this.writeLock.equals(tx)) {
 				// remove the write lock.
 				this.writeLock = tx.getFather();
 			}
 			// this.commitEntryLocks(tx);
 		}
 		if (logger.isDebugEnabled()) {
 			logger.debug("commitLocks() transaction commited) for coordinator "
 					+ this.getClass());
 		}
 	}
 
 	/***
 	 * Updates the locks of this coordinator.<br>
 	 * All locks will be set to <code>null</code>.<br>
 	 * This method calls {@link ICoordinator#rollbackEntryLocks(Transaction)}.
 	 * 
 	 * @param tx
 	 *            the transaction to rollback.
 	 * @throws TransactionLockException
 	 *             thrown if the lock can not be aquired.
 	 */
 	protected void rollbackLocks(Transaction tx)
 			throws TransactionLockException {
 		if (logger.isDebugEnabled()) {
 			logger.debug("rollbackLocks(" + tx + ")");
 		}
 		synchronized (this.lockObject) {
 			// remove the read lock.
 			this.readLocks.remove(tx.getId());
 			if (this.writeLock != null && this.writeLock.equals(tx)) {
 				// remove the write lock.
 				this.writeLock = null;
 			}
 			// this.rollbackEntryLocks(tx);
 		}
 		if (logger.isDebugEnabled()) {
 			logger.debug("rollbackLocks() locks released for coordinator "
 					+ this.getClass());
 		}
 	}
 
 	public Properties getProperties() {
 		return this.properties;
 	}
 
 	public void setProperties(Properties properties) {
 		this.properties = properties;
 	}
 }