001: package org.apache.turbine.services.pool;
002:
003: /*
004: * Copyright 2001-2005 The Apache Software Foundation.
005: *
006: * Licensed under the Apache License, Version 2.0 (the "License")
007: * you may not use this file except in compliance with the License.
008: * You may obtain a copy of the License at
009: *
010: * http://www.apache.org/licenses/LICENSE-2.0
011: *
012: * Unless required by applicable law or agreed to in writing, software
013: * distributed under the License is distributed on an "AS IS" BASIS,
014: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015: * See the License for the specific language governing permissions and
016: * limitations under the License.
017: */
018:
019: import org.apache.turbine.services.Service;
020: import org.apache.turbine.util.TurbineException;
021:
022: /**
023: * The Pool Service extends the Factory Service by adding support
024: * for pooling instantiated objects. When a new instance is
025: * requested, the service first checks its pool if one is available.
026: * If the the pool is empty, a new object will be instantiated
027: * from the specified class. If only class name is given, the request
028: * to create an intance will be forwarded to the Factory Service.
029: *
030: * <p>For objects implementing the Recyclable interface, a recycle
031: * method will be called, when they are taken from the pool, and
032: * a dispose method, when they are returned to the pool.
033: *
034: * @author <a href="mailto:ilkka.priha@simsoft.fi">Ilkka Priha</a>
035: * @version $Id: PoolService.java 264148 2005-08-29 14:21:04Z henning $
036: */
037: public interface PoolService extends Service {
038: /** The key under which this service is stored in TurbineServices. */
039: String SERVICE_NAME = "PoolService";
040:
041: /** The default pool capacity. */
042: int DEFAULT_POOL_CAPACITY = 128;
043:
044: /** The name of the pool capacity property */
045: String POOL_CAPACITY_KEY = "pool.capacity";
046:
047: /** Are we running in debug mode? */
048: String POOL_DEBUG_KEY = "pool.debug";
049:
050: /** Default Value for debug mode */
051: boolean POOL_DEBUG_DEFAULT = false;
052:
053: /**
054: * Gets an instance of a named class.
055: *
056: * @param className the name of the class.
057: * @return the instance.
058: * @throws TurbineException if instantiation fails.
059: */
060: Object getInstance(String className) throws TurbineException;
061:
062: /**
063: * Gets an instance of a named class using a specified class loader.
064: *
065: * <p>Class loaders are supported only if the isLoaderSupported
066: * method returns true. Otherwise the loader parameter is ignored.
067: *
068: * @param className the name of the class.
069: * @param loader the class loader.
070: * @return the instance.
071: * @throws TurbineException if instantiation fails.
072: */
073: Object getInstance(String className, ClassLoader loader)
074: throws TurbineException;
075:
076: /**
077: * Gets an instance of a named class.
078: * Parameters for its constructor are given as an array of objects,
079: * primitive types must be wrapped with a corresponding class.
080: *
081: * @param className the name of the class.
082: * @param params an array containing the parameters of the constructor.
083: * @param signature an array containing the signature of the constructor.
084: * @return the instance.
085: * @throws TurbineException if instantiation fails.
086: */
087: Object getInstance(String className, Object[] params,
088: String[] signature) throws TurbineException;
089:
090: /**
091: * Gets an instance of a named class using a specified class loader.
092: * Parameters for its constructor are given as an array of objects,
093: * primitive types must be wrapped with a corresponding class.
094: *
095: * <p>Class loaders are supported only if the isLoaderSupported
096: * method returns true. Otherwise the loader parameter is ignored.
097: *
098: * @param className the name of the class.
099: * @param loader the class loader.
100: * @param params an array containing the parameters of the constructor.
101: * @param signature an array containing the signature of the constructor.
102: * @return the instance.
103: * @throws TurbineException if instantiation fails.
104: */
105: Object getInstance(String className, ClassLoader loader,
106: Object[] params, String[] signature)
107: throws TurbineException;
108:
109: /**
110: * Tests if specified class loaders are supported for a named class.
111: *
112: * @param className the name of the class.
113: * @return true if class loaders are supported, false otherwise.
114: * @throws TurbineException if test fails.
115: * @deprecated Use TurbineFactory.isLoaderSupported(className)
116: */
117: boolean isLoaderSupported(String className) throws TurbineException;
118:
119: /**
120: * Gets an instance of a specified class either from the pool
121: * or by instatiating from the class if the pool is empty.
122: *
123: * @param clazz the class.
124: * @return the instance.
125: * @throws TurbineException if recycling fails.
126: */
127: Object getInstance(Class clazz) throws TurbineException;
128:
129: /**
130: * Gets an instance of a specified class either from the pool
131: * or by instatiating from the class if the pool is empty.
132: *
133: * @param clazz the class.
134: * @param params an array containing the parameters of the constructor.
135: * @param signature an array containing the signature of the constructor.
136: * @return the instance.
137: * @throws TurbineException if recycling fails.
138: */
139: Object getInstance(Class clazz, Object params[], String signature[])
140: throws TurbineException;
141:
142: /**
143: * Puts a used object back to the pool. Objects implementing
144: * the Recyclable interface can provide a recycle method to
145: * be called when they are reused and a dispose method to be
146: * called when they are returned to the pool.
147: *
148: * @param instance the object instance to recycle.
149: * @return true if the instance was accepted.
150: */
151: boolean putInstance(Object instance);
152:
153: /**
154: * Gets the capacity of the pool for a named class.
155: *
156: * @param className the name of the class.
157: */
158: int getCapacity(String className);
159:
160: /**
161: * Sets the capacity of the pool for a named class.
162: * Note that the pool will be cleared after the change.
163: *
164: * @param className the name of the class.
165: * @param capacity the new capacity.
166: */
167: void setCapacity(String className, int capacity);
168:
169: /**
170: * Gets the current size of the pool for a named class.
171: *
172: * @param className the name of the class.
173: */
174: int getSize(String className);
175:
176: /**
177: * Clears instances of a named class from the pool.
178: *
179: * @param className the name of the class.
180: */
181: void clearPool(String className);
182:
183: /**
184: * Clears all instances from the pool.
185: */
186: void clearPool();
187:
188: }
|