/*
    * ObjectPool.java
    *
    * This file is part of the creme library.
    * The creme library intends to ease the development effort of large
    * applications by providing easy to use support classes.
    *
    * Copyright (C) 2002 Denis Bregeon
    *
   *
   * This library is free software; you can redistribute it and/or
   * modify it under the terms of the GNU Lesser General Public
   * License as published by the Free Software Foundation; either
   * version 2.1 of the License, or (at your option) any later version.
   *
   * This library 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
   * Lesser General Public License for more details.
   *
   * You should have received a copy of the GNU Lesser General Public
   * License along with this library; if not, write to the Free Software
   * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
   *
   * contact information: dbregeon@sourceforge.net
   */
  
  package org.jcreme.pool;
  
  import java.util.ArrayList;
  import java.util.Collection;
  import java.util.Stack;
  
  /***
   * This class represents a pool of objects. That is a number of objects that are
   * shared in an application as a limited resource. This is a lazy
   * implementation, it builds the pooled objects as needed through the use of the
   * buildObject method. This class must be derived to provide an actual
   * implementation of the buildNew method.
   * 
   * @author $Author: dbregeon $
   * @version $Revision: 1.3 $
   */
  public abstract class ObjectPool {
  	/***
  	 * The initial size of the pool. It might be reused to reinitialize the
  	 * pool.
  	 */
  	private int minSize = 0;
  
  	/***
  	 * The maximum size of the pool.
  	 */
  	private int maxSize = 1;
  
  	/***
  	 * The pool objects that are not currently in use.
  	 */
  	private final Stack freeObjects = new Stack();
  
  	/***
  	 * The pool objects that are currently in use.
  	 */
  	private final ArrayList usedObjects = new ArrayList();
  
  	/***
  	 * Creates a new instance of ObjectPool If the minSize is greater than the
  	 * maxSize, it is reduced to the maxSize. The constructor builds as many
  	 * objects as minSize through the initPool method.
  	 * 
  	 * @param minSize
  	 *            the initial size of the pool.
  	 * @param maxSize
  	 *            the maximum size of the pool.
  	 */
  	protected ObjectPool(int minSize, int maxSize) {
  		if (minSize > maxSize) {
  			minSize = maxSize;
  		}
  		this.minSize = minSize;
  		this.maxSize = maxSize;
  		initPool();
  	}
  
  	/***
  	 * This method makes as many calls to buildNew as minSize. It is used to
  	 * populate the pool.
  	 */
  	protected final void initPool() {
  		Object current = null;
  		for (int i = 0; ((i < this.minSize) && (i < this.maxSize)); i++) {
  			current = buildNew();
  			if (current != null) {
  				this.freeObjects.add(current);
  			}
  		}
  	}
  
  	/***
 	 * This method enabled to build a new object when needed. Any parameters
 	 * needed should be provided by the actual ObjectPool implementation.
 	 * 
 	 * @return a newly constructed pool element.
 	 */
 	protected abstract Object buildNew();
 
 	/***
 	 * This method enabled to remove an old object when needed. It enables to
 	 * free resources when an object is permanently removed from the ObjectPool.
 	 * 
 	 * @param obj
 	 *            the object to remove.
 	 */
 	protected abstract void removeOld(final Object obj);
 
 	/***
 	 * This method enables to retrieve an object from the freeObjects stack. If
 	 * the stack is empty and the maxSize is not exceeded, it builds a new
 	 * object using the buildNew method. If the stack is empty and the maxSize
 	 * was reached, it waits for an object to be released. The call is then
 	 * blocked indefinitely.
 	 * 
 	 * @return an object freshly removed from the freeObjects stack.
 	 * @throws InterruptedException
 	 *             if the wait for a free object was interrupted.
 	 */
 	protected Object getObjectFromFree() throws InterruptedException {
 		Object result = null;
 		synchronized (this.freeObjects) {
 			if (this.freeObjects.isEmpty()) {
 				if (this.usedObjects.size() < this.maxSize) {
 					result = buildNew();
 				} else {
 					this.freeObjects.wait();
 				}
 			} else {
 				result = this.freeObjects.pop();
 			}
 		}
 		return result;
 	}
 
 	/***
 	 * This method enables to retrieve an object from the freeObjects stack. If
 	 * the stack is empty and the maxSize is not exceeded, it builds a new
 	 * object using the buildNew method. If the stack is empty and the maxSize
 	 * was reached, it waits for an object to be released for the given time.
 	 * 
 	 * @param waitingPeriod
 	 *            the time the method is allowed to wait for an object from the
 	 *            pool.
 	 * @return an object freshly removed from the freeObjects stack.
 	 * @throws InterruptedException
 	 *             if the wait for a free object was interrupted.
 	 */
 	protected Object getObjectFromFree(final int waitingPeriod)
 			throws InterruptedException {
 		Object result = null;
 		synchronized (this.freeObjects) {
 			if (this.freeObjects.isEmpty()) {
 				if (this.usedObjects.size() < this.maxSize) {
 					result = buildNew();
 				} else if (waitingPeriod > 0) {
 					this.freeObjects.wait(waitingPeriod);
 				}
 			} else {
 				result = this.freeObjects.pop();
 			}
 		}
 		return result;
 	}
 
 	/***
 	 * This method enables to remove an object from the usedObjects list.
 	 * 
 	 * @param o
 	 *            the object to remove from the usedObjects.
 	 * @return the object actually removed from the list. This is to prevent
 	 *         objects from being introduced in the ObjectPool while they may
 	 *         have been created outside.
 	 */
 	protected Object getObjectFromUsed(final Object o) {
 		synchronized (this.usedObjects) {
 			// Ensures that the object that is returned is really part
 			// of the ObjectPool.
 			return this.usedObjects.remove(this.usedObjects.indexOf(o));
 		}
 	}
 
 	/***
 	 * This method enabled to return an object to the freeObjects stack.
 	 * 
 	 * @param o
 	 *            the object to return to the stack.
 	 */
 	protected void putInFreeObjects(final Object o) {
 		if (o != null) {
 			synchronized (this.freeObjects) {
 				this.freeObjects.push(o);
 				this.freeObjects.notifyAll();
 			}
 		}
 	}
 
 	/***
 	 * This method enabled to register an object to the usedObjects list.
 	 * 
 	 * @param o
 	 *            the object to add to the usedObjects list.
 	 */
 	protected void putInUsedObjects(final Object o) {
 		if (o != null) {
 			synchronized (this.usedObjects) {
 				this.usedObjects.add(o);
 			}
 		}
 	}
 
 	/***
 	 * This method enables to get an object from the ObjectPool. It will block
 	 * indefinitely while waiting for a free object.
 	 * 
 	 * @return an object from the ObjectPool. Null if the method was
 	 *         interrupted.
 	 */
 	protected Object getObject() {
 		Object result = null;
 		try {
 			while (result == null) {
 				result = getObjectFromFree();
 			}
 			putInUsedObjects(result);
 		} catch (InterruptedException e) {
 			e.printStackTrace();
 		}
 		return result;
 	}
 
 	/***
 	 * This method enables to get an object from the ObjectPool. It will block
 	 * for the given time while waiting for a free object.
 	 * 
 	 * @param waitingPeriod
 	 *            the number of millisecond the method will wait for an object
 	 *            to be freed.
 	 * @return an object from the ObjectPool. Null if the method was
 	 *         interrupted.
 	 */
 	protected Object getObject(final int waitingPeriod) {
 		Object result = null;
 		int loopCount = 0;
 		int wait = waitingPeriod;
 		try {
 			while ((result == null) && (loopCount < 2)) {
 				if (loopCount > 0) {
 					wait = 0;
 				}
 				result = getObjectFromFree(wait);
 				loopCount++;
 			}
 			putInUsedObjects(result);
 		} catch (InterruptedException e) {
 			e.printStackTrace();
 		}
 		return result;
 	}
 
 	/***
 	 * This method enables to return an object to the ObjectPool.
 	 * 
 	 * @param obj
 	 *            the object to release.
 	 */
 	protected void releaseObject(final Object obj) {
 		final Object pooledObject = getObjectFromUsed(obj);
 		// return the object only if the max size is not exceeded.
 		// this is to accomodate a change in the maxSize.
 		if (this.usedObjects.size() + this.freeObjects.size() < this.maxSize) {
 			putInFreeObjects(pooledObject);
 		} else {
 			removeOld(obj);
 		}
 	}
 
 	/***
 	 * Gives access to the freeObjects Stack.
 	 * 
 	 * @return the freeObjects.
 	 */
 	protected Collection getFreeObjects() {
 		return this.freeObjects;
 	}
 
 	/***
 	 * Gives access to the usedObjects Vector.
 	 * 
 	 * @return the usedObjects.
 	 */
 	protected Collection getUsedObjects() {
 		return this.usedObjects;
 	}
 
 	/***
 	 * This method enables to change the minimum size of the ConnectionPool.
 	 * Sizes lesser than 0 will be ignored.
 	 * 
 	 * @param minSize
 	 *            the new minimum size to apply.
 	 * 
 	 */
 	public void setMinimumSize(final int minSize) {
 		if (minSize >= 0) {
 			this.minSize = minSize;
 			if (this.freeObjects.size() + this.usedObjects.size() < this.minSize) {
 				synchronized (this.freeObjects) {
 					Object current = null;
 					for (int i = this.freeObjects.size()
 							+ this.usedObjects.size(); ((i < this.minSize) && (i < this.maxSize)); i++) {
 						current = buildNew();
 
 						if (current != null) {
 							this.freeObjects.add(current);
 						}
 					}
 				}
 			}
 		}
 	}
 
 	/***
 	 * This method enables to change the maximum size of the ConnectionPool. If
 	 * the size is lower than the minimum size, it will be ignored.
 	 * 
 	 * @param maxSize
 	 *            the new maximum size to apply.
 	 * 
 	 */
 	public void setMaximumSize(final int maxSize) {
 		if (maxSize >= this.minSize) {
 			this.maxSize = maxSize;
 			synchronized (this.freeObjects) {
 				Object current = null;
 				while (this.usedObjects.size() + this.freeObjects.size() > this.maxSize) {
 					current = this.freeObjects.lastElement();
 					this.freeObjects.remove(current);
 					removeOld(current);
 				}
 			}
 		}
 	}
 }