src/java/org/apache/turbine/services/pool/PoolService.java - turbine-core - Git at Google

 package org.apache.turbine.services.pool;

 /* ====================================================================
  * The Apache Software License, Version 1.1
  *
  * Copyright (c) 2001-2003 The Apache Software Foundation.  All rights
  * reserved.
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions
  * are met:
  *
  * 1. Redistributions of source code must retain the above copyright
  *    notice, this list of conditions and the following disclaimer.
  *
  * 2. Redistributions in binary form must reproduce the above copyright
  *    notice, this list of conditions and the following disclaimer in
  *    the documentation and/or other materials provided with the
  *    distribution.
  *
  * 3. The end-user documentation included with the redistribution,
  *    if any, must include the following acknowledgment:
  *       "This product includes software developed by the
  *        Apache Software Foundation (http://www.apache.org/)."
  *    Alternately, this acknowledgment may appear in the software itself,
  *    if and wherever such third-party acknowledgments normally appear.
  *
  * 4. The names "Apache" and "Apache Software Foundation" and
  *    "Apache Turbine" must not be used to endorse or promote products
  *    derived from this software without prior written permission. For
  *    written permission, please contact apache@apache.org.
  *
  * 5. Products derived from this software may not be called "Apache",
  *    "Apache Turbine", nor may "Apache" appear in their name, without
  *    prior written permission of the Apache Software Foundation.
  *
  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  * SUCH DAMAGE.
  * ====================================================================
  *
  * This software consists of voluntary contributions made by many
  * individuals on behalf of the Apache Software Foundation.  For more
  * information on the Apache Software Foundation, please see
  * <http://www.apache.org/>.
  */

 import org.apache.turbine.services.Service;
 import org.apache.turbine.util.TurbineException;

 /**
  * The Pool Service extends the Factory Service by adding support
  * for pooling instantiated objects. When a new instance is
  * requested, the service first checks its pool if one is available.
  * If the the pool is empty, a new object will be instantiated
  * from the specified class. If only class name is given, the request
  * to create an intance will be forwarded to the Factory Service.
  *
  * <p>For objects implementing the Recyclable interface, a recycle
  * method will be called, when they are taken from the pool, and
  * a dispose method, when they are returned to the pool.
  *
  * @author <a href="mailto:ilkka.priha@simsoft.fi">Ilkka Priha</a>
  * @version $Id$
  */
 public interface PoolService
         extends Service
 {
     /** The key under which this service is stored in TurbineServices. */
     String SERVICE_NAME = "PoolService";

     /** The default pool capacity. */
     int DEFAULT_POOL_CAPACITY = 128;

     /** The name of the pool capacity property */
     String POOL_CAPACITY_KEY = "pool.capacity";

     /** Are we running in debug mode? */
     String POOL_DEBUG_KEY = "pool.debug";

     /** Default Value for debug mode */
     boolean POOL_DEBUG_DEFAULT = false;

     /**
      * Gets an instance of a named class.
      *
      * @param className the name of the class.
      * @return the instance.
      * @throws TurbineException if instantiation fails.
      */
     Object getInstance(String className)
             throws TurbineException;

     /**
      * Gets an instance of a named class using a specified class loader.
      *
      * <p>Class loaders are supported only if the isLoaderSupported
      * method returns true. Otherwise the loader parameter is ignored.
      *
      * @param className the name of the class.
      * @param loader the class loader.
      * @return the instance.
      * @throws TurbineException if instantiation fails.
      */
     Object getInstance(String className,
             ClassLoader loader)
             throws TurbineException;

     /**
      * Gets an instance of a named class.
      * Parameters for its constructor are given as an array of objects,
      * primitive types must be wrapped with a corresponding class.
      *
      * @param className the name of the class.
      * @param params an array containing the parameters of the constructor.
      * @param signature an array containing the signature of the constructor.
      * @return the instance.
      * @throws TurbineException if instantiation fails.
      */
     Object getInstance(String className,
             Object[] params,
             String[] signature)
             throws TurbineException;

     /**
      * Gets an instance of a named class using a specified class loader.
      * Parameters for its constructor are given as an array of objects,
      * primitive types must be wrapped with a corresponding class.
      *
      * <p>Class loaders are supported only if the isLoaderSupported
      * method returns true. Otherwise the loader parameter is ignored.
      *
      * @param className the name of the class.
      * @param loader the class loader.
      * @param params an array containing the parameters of the constructor.
      * @param signature an array containing the signature of the constructor.
      * @return the instance.
      * @throws TurbineException if instantiation fails.
      */
     Object getInstance(String className,
             ClassLoader loader,
             Object[] params,
             String[] signature)
             throws TurbineException;

     /**
      * Tests if specified class loaders are supported for a named class.
      *
      * @param className the name of the class.
      * @return true if class loaders are supported, false otherwise.
      * @throws TurbineException if test fails.
      * @deprecated Use TurbineFactory.isLoaderSupported(className)
      */
     boolean isLoaderSupported(String className)
             throws TurbineException;

     /**
      * Gets an instance of a specified class either from the pool
      * or by instatiating from the class if the pool is empty.
      *
      * @param clazz the class.
      * @return the instance.
      * @throws TurbineException if recycling fails.
      */
     Object getInstance(Class clazz)
             throws TurbineException;

     /**
      * Gets an instance of a specified class either from the pool
      * or by instatiating from the class if the pool is empty.
      *
      * @param clazz the class.
      * @param params an array containing the parameters of the constructor.
      * @param signature an array containing the signature of the constructor.
      * @return the instance.
      * @throws TurbineException if recycling fails.
      */
     Object getInstance(Class clazz,
             Object params[],
             String signature[])
             throws TurbineException;

     /**
      * Puts a used object back to the pool. Objects implementing
      * the Recyclable interface can provide a recycle method to
      * be called when they are reused and a dispose method to be
      * called when they are returned to the pool.
      *
      * @param instance the object instance to recycle.
      * @return true if the instance was accepted.
      */
     boolean putInstance(Object instance);

     /**
      * Gets the capacity of the pool for a named class.
      *
      * @param className the name of the class.
      */
     int getCapacity(String className);

     /**
      * Sets the capacity of the pool for a named class.
      * Note that the pool will be cleared after the change.
      *
      * @param className the name of the class.
      * @param capacity the new capacity.
      */
     void setCapacity(String className,
                      int capacity);

     /**
      * Gets the current size of the pool for a named class.
      *
      * @param className the name of the class.
      */
     int getSize(String className);

     /**
      * Clears instances of a named class from the pool.
      *
      * @param className the name of the class.
      */
     void clearPool(String className);

     /**
      * Clears all instances from the pool.
      */
     void clearPool();

 }
	package org.apache.turbine.services.pool;

	/* ====================================================================
	* The Apache Software License, Version 1.1
	*
	* Copyright (c) 2001-2003 The Apache Software Foundation. All rights
	* reserved.
	*
	* Redistribution and use in source and binary forms, with or without
	* modification, are permitted provided that the following conditions
	* are met:
	*
	* 1. Redistributions of source code must retain the above copyright
	* notice, this list of conditions and the following disclaimer.
	*
	* 2. Redistributions in binary form must reproduce the above copyright
	* notice, this list of conditions and the following disclaimer in
	* the documentation and/or other materials provided with the
	* distribution.
	*
	* 3. The end-user documentation included with the redistribution,
	* if any, must include the following acknowledgment:
	* "This product includes software developed by the
	* Apache Software Foundation (http://www.apache.org/)."
	* Alternately, this acknowledgment may appear in the software itself,
	* if and wherever such third-party acknowledgments normally appear.
	*
	* 4. The names "Apache" and "Apache Software Foundation" and
	* "Apache Turbine" must not be used to endorse or promote products
	* derived from this software without prior written permission. For
	* written permission, please contact apache@apache.org.
	*
	* 5. Products derived from this software may not be called "Apache",
	* "Apache Turbine", nor may "Apache" appear in their name, without
	* prior written permission of the Apache Software Foundation.
	*
	* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
	* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
	* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
	* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
	* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
	* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
	* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
	* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
	* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
	* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
	* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	* SUCH DAMAGE.
	* ====================================================================
	*
	* This software consists of voluntary contributions made by many
	* individuals on behalf of the Apache Software Foundation. For more
	* information on the Apache Software Foundation, please see
	* <http://www.apache.org/>.
	*/

	import org.apache.turbine.services.Service;
	import org.apache.turbine.util.TurbineException;

	/**
	* The Pool Service extends the Factory Service by adding support
	* for pooling instantiated objects. When a new instance is
	* requested, the service first checks its pool if one is available.
	* If the the pool is empty, a new object will be instantiated
	* from the specified class. If only class name is given, the request
	* to create an intance will be forwarded to the Factory Service.
	*
	* <p>For objects implementing the Recyclable interface, a recycle
	* method will be called, when they are taken from the pool, and
	* a dispose method, when they are returned to the pool.
	*
	* @author <a href="mailto:ilkka.priha@simsoft.fi">Ilkka Priha</a>
	* @version $Id$
	*/
	public interface PoolService
	extends Service
	{
	/** The key under which this service is stored in TurbineServices. */
	String SERVICE_NAME = "PoolService";

	/** The default pool capacity. */
	int DEFAULT_POOL_CAPACITY = 128;

	/** The name of the pool capacity property */
	String POOL_CAPACITY_KEY = "pool.capacity";

	/** Are we running in debug mode? */
	String POOL_DEBUG_KEY = "pool.debug";

	/** Default Value for debug mode */
	boolean POOL_DEBUG_DEFAULT = false;

	/**
	* Gets an instance of a named class.
	*
	* @param className the name of the class.
	* @return the instance.
	* @throws TurbineException if instantiation fails.
	*/
	Object getInstance(String className)
	throws TurbineException;

	/**
	* Gets an instance of a named class using a specified class loader.
	*
	* <p>Class loaders are supported only if the isLoaderSupported
	* method returns true. Otherwise the loader parameter is ignored.
	*
	* @param className the name of the class.
	* @param loader the class loader.
	* @return the instance.
	* @throws TurbineException if instantiation fails.
	*/
	Object getInstance(String className,
	ClassLoader loader)
	throws TurbineException;

	/**
	* Gets an instance of a named class.
	* Parameters for its constructor are given as an array of objects,
	* primitive types must be wrapped with a corresponding class.
	*
	* @param className the name of the class.
	* @param params an array containing the parameters of the constructor.
	* @param signature an array containing the signature of the constructor.
	* @return the instance.
	* @throws TurbineException if instantiation fails.
	*/
	Object getInstance(String className,
	Object[] params,
	String[] signature)
	throws TurbineException;

	/**
	* Gets an instance of a named class using a specified class loader.
	* Parameters for its constructor are given as an array of objects,
	* primitive types must be wrapped with a corresponding class.
	*
	* <p>Class loaders are supported only if the isLoaderSupported
	* method returns true. Otherwise the loader parameter is ignored.
	*
	* @param className the name of the class.
	* @param loader the class loader.
	* @param params an array containing the parameters of the constructor.
	* @param signature an array containing the signature of the constructor.
	* @return the instance.
	* @throws TurbineException if instantiation fails.
	*/
	Object getInstance(String className,
	ClassLoader loader,
	Object[] params,
	String[] signature)
	throws TurbineException;

	/**
	* Tests if specified class loaders are supported for a named class.
	*
	* @param className the name of the class.
	* @return true if class loaders are supported, false otherwise.
	* @throws TurbineException if test fails.
	* @deprecated Use TurbineFactory.isLoaderSupported(className)
	*/
	boolean isLoaderSupported(String className)
	throws TurbineException;

	/**
	* Gets an instance of a specified class either from the pool
	* or by instatiating from the class if the pool is empty.
	*
	* @param clazz the class.
	* @return the instance.
	* @throws TurbineException if recycling fails.
	*/
	Object getInstance(Class clazz)
	throws TurbineException;

	/**
	* Gets an instance of a specified class either from the pool
	* or by instatiating from the class if the pool is empty.
	*
	* @param clazz the class.
	* @param params an array containing the parameters of the constructor.
	* @param signature an array containing the signature of the constructor.
	* @return the instance.
	* @throws TurbineException if recycling fails.
	*/
	Object getInstance(Class clazz,
	Object params[],
	String signature[])
	throws TurbineException;

	/**
	* Puts a used object back to the pool. Objects implementing
	* the Recyclable interface can provide a recycle method to
	* be called when they are reused and a dispose method to be
	* called when they are returned to the pool.
	*
	* @param instance the object instance to recycle.
	* @return true if the instance was accepted.
	*/
	boolean putInstance(Object instance);

	/**
	* Gets the capacity of the pool for a named class.
	*
	* @param className the name of the class.
	*/
	int getCapacity(String className);

	/**
	* Sets the capacity of the pool for a named class.
	* Note that the pool will be cleared after the change.
	*
	* @param className the name of the class.
	* @param capacity the new capacity.
	*/
	void setCapacity(String className,
	int capacity);

	/**
	* Gets the current size of the pool for a named class.
	*
	* @param className the name of the class.
	*/
	int getSize(String className);

	/**
	* Clears instances of a named class from the pool.
	*
	* @param className the name of the class.
	*/
	void clearPool(String className);

	/**
	* Clears all instances from the pool.
	*/
	void clearPool();

	}