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