View Javadoc

1   package org.apache.turbine.services.pool;
2   
3   /*
4    * Licensed to the Apache Software Foundation (ASF) under one
5    * or more contributor license agreements.  See the NOTICE file
6    * distributed with this work for additional information
7    * regarding copyright ownership.  The ASF licenses this file
8    * to you under the Apache License, Version 2.0 (the
9    * "License"); you may not use this file except in compliance
10   * with the License.  You may obtain a copy of the License at
11   *
12   *   http://www.apache.org/licenses/LICENSE-2.0
13   *
14   * Unless required by applicable law or agreed to in writing,
15   * software distributed under the License is distributed on an
16   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17   * KIND, either express or implied.  See the License for the
18   * specific language governing permissions and limitations
19   * under the License.
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 }