1 package org.apache.turbine.services.pool;
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22 import org.apache.turbine.services.Service;
23 import org.apache.turbine.util.TurbineException;
24
25 /***
26 * The Pool Service extends the Factory Service by adding support
27 * for pooling instantiated objects. When a new instance is
28 * requested, the service first checks its pool if one is available.
29 * If the the pool is empty, a new object will be instantiated
30 * from the specified class. If only class name is given, the request
31 * to create an intance will be forwarded to the Factory Service.
32 *
33 * <p>For objects implementing the Recyclable interface, a recycle
34 * method will be called, when they are taken from the pool, and
35 * a dispose method, when they are returned to the pool.
36 *
37 * @author <a href="mailto:ilkka.priha@simsoft.fi">Ilkka Priha</a>
38 * @version $Id: PoolService.java 534527 2007-05-02 16:10:59Z tv $
39 */
40 public interface PoolService
41 extends Service
42 {
43 /*** The key under which this service is stored in TurbineServices. */
44 String SERVICE_NAME = "PoolService";
45
46 /*** The default pool capacity. */
47 int DEFAULT_POOL_CAPACITY = 128;
48
49 /*** The name of the pool capacity property */
50 String POOL_CAPACITY_KEY = "pool.capacity";
51
52 /*** Are we running in debug mode? */
53 String POOL_DEBUG_KEY = "pool.debug";
54
55 /*** Default Value for debug mode */
56 boolean POOL_DEBUG_DEFAULT = false;
57
58 /***
59 * Gets an instance of a named class.
60 *
61 * @param className the name of the class.
62 * @return the instance.
63 * @throws TurbineException if instantiation fails.
64 */
65 Object getInstance(String className)
66 throws TurbineException;
67
68 /***
69 * Gets an instance of a named class using a specified class loader.
70 *
71 * <p>Class loaders are supported only if the isLoaderSupported
72 * method returns true. Otherwise the loader parameter is ignored.
73 *
74 * @param className the name of the class.
75 * @param loader the class loader.
76 * @return the instance.
77 * @throws TurbineException if instantiation fails.
78 */
79 Object getInstance(String className,
80 ClassLoader loader)
81 throws TurbineException;
82
83 /***
84 * Gets an instance of a named class.
85 * Parameters for its constructor are given as an array of objects,
86 * primitive types must be wrapped with a corresponding class.
87 *
88 * @param className the name of the class.
89 * @param params an array containing the parameters of the constructor.
90 * @param signature an array containing the signature of the constructor.
91 * @return the instance.
92 * @throws TurbineException if instantiation fails.
93 */
94 Object getInstance(String className,
95 Object[] params,
96 String[] signature)
97 throws TurbineException;
98
99 /***
100 * Gets an instance of a named class using a specified class loader.
101 * Parameters for its constructor are given as an array of objects,
102 * primitive types must be wrapped with a corresponding class.
103 *
104 * <p>Class loaders are supported only if the isLoaderSupported
105 * method returns true. Otherwise the loader parameter is ignored.
106 *
107 * @param className the name of the class.
108 * @param loader the class loader.
109 * @param params an array containing the parameters of the constructor.
110 * @param signature an array containing the signature of the constructor.
111 * @return the instance.
112 * @throws TurbineException if instantiation fails.
113 */
114 Object getInstance(String className,
115 ClassLoader loader,
116 Object[] params,
117 String[] signature)
118 throws TurbineException;
119
120 /***
121 * Tests if specified class loaders are supported for a named class.
122 *
123 * @param className the name of the class.
124 * @return true if class loaders are supported, false otherwise.
125 * @throws TurbineException if test fails.
126 * @deprecated Use TurbineFactory.isLoaderSupported(className)
127 */
128 boolean isLoaderSupported(String className)
129 throws TurbineException;
130
131 /***
132 * Gets an instance of a specified class either from the pool
133 * or by instatiating from the class if the pool is empty.
134 *
135 * @param clazz the class.
136 * @return the instance.
137 * @throws TurbineException if recycling fails.
138 */
139 Object getInstance(Class clazz)
140 throws TurbineException;
141
142 /***
143 * Gets an instance of a specified class either from the pool
144 * or by instatiating from the class if the pool is empty.
145 *
146 * @param clazz the class.
147 * @param params an array containing the parameters of the constructor.
148 * @param signature an array containing the signature of the constructor.
149 * @return the instance.
150 * @throws TurbineException if recycling fails.
151 */
152 Object getInstance(Class clazz,
153 Object params[],
154 String signature[])
155 throws TurbineException;
156
157 /***
158 * Puts a used object back to the pool. Objects implementing
159 * the Recyclable interface can provide a recycle method to
160 * be called when they are reused and a dispose method to be
161 * called when they are returned to the pool.
162 *
163 * @param instance the object instance to recycle.
164 * @return true if the instance was accepted.
165 */
166 boolean putInstance(Object instance);
167
168 /***
169 * Gets the capacity of the pool for a named class.
170 *
171 * @param className the name of the class.
172 */
173 int getCapacity(String className);
174
175 /***
176 * Sets the capacity of the pool for a named class.
177 * Note that the pool will be cleared after the change.
178 *
179 * @param className the name of the class.
180 * @param capacity the new capacity.
181 */
182 void setCapacity(String className,
183 int capacity);
184
185 /***
186 * Gets the current size of the pool for a named class.
187 *
188 * @param className the name of the class.
189 */
190 int getSize(String className);
191
192 /***
193 * Clears instances of a named class from the pool.
194 *
195 * @param className the name of the class.
196 */
197 void clearPool(String className);
198
199 /***
200 * Clears all instances from the pool.
201 */
202 void clearPool();
203
204 }