1 package org.apache.fulcrum.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 /**
23 * The Pool Service extends the Factory Service by adding support for pooling
24 * instantiated objects. When a new instance is requested, the service first
25 * checks its pool if one is available. If the the pool is empty, a new object
26 * will be instantiated from the specified class. If only class name is given,
27 * the request to create an instance will be forwarded to the Factory Service.
28 *
29 * <p>
30 * For objects implementing the Recyclable interface, a recycle method will be
31 * called, when they are taken from the pool, and a dispose method, when they
32 * are returned to the pool.
33 * </p>
34 *
35 * @author <a href="mailto:ilkka.priha@simsoft.fi">Ilkka Priha</a>
36 * @author <a href="mailto:mcconnell@apache.org">Stephen McConnell</a>
37 * @version $Id$
38 */
39 public interface PoolService
40 {
41 /** Avalon role - used to id the component within the manager */
42 String ROLE = PoolService.class.getName();
43
44 /**
45 * The default pool capacity.
46 */
47 public static final int DEFAULT_POOL_CAPACITY = 128;
48
49 /**
50 * Gets an instance of a specified class either from the pool or by
51 * instantiating from the class if the pool is empty.
52 *
53 * @param <T> type of the instance
54 * @param clazz the class.
55 * @return the instance.
56 * @throws PoolException if recycling fails.
57 */
58 public <T> T getInstance(Class<?> clazz) throws PoolException;
59
60 /**
61 * Gets an instance of a specified class either from the pool or by
62 * instantiating from the class if the pool is empty.
63 *
64 * @param <T> type of the instance class
65 * @param clazz the class.
66 * @param params an array containing the parameters of the constructor.
67 * @param signature an array containing the signature of the constructor.
68 * @return the instance.
69 * @throws PoolException if recycling fails.
70 */
71 public <T> T getInstance(Class<?> clazz, Object params[], String signature[]) throws PoolException;
72
73 /**
74 * Puts a used object back to the pool. Objects implementing the Recyclable
75 * interface can provide a recycle method to be called when they are reused and
76 * a dispose method to be called when they are returned to the pool.
77 *
78 * @param instance the object instance to recycle.
79 * @return true if the instance was accepted.
80 */
81 public boolean putInstance(Object instance);
82
83 /**
84 * Gets the capacity of the pool for a named class.
85 *
86 * @param className the name of the class.
87 * @return total capacity
88 */
89 public int getCapacity(String className);
90
91 /**
92 * Sets the capacity of the pool for a named class. Note that the pool will be
93 * cleared after the change.
94 *
95 * @param className the name of the class.
96 * @param capacity the new capacity.
97 */
98 public void setCapacity(String className, int capacity);
99
100 /**
101 * Gets the current size of the pool for a named class.
102 *
103 * @param className the name of the class
104 * @return the size of the pool for the class
105 */
106 public int getSize(String className);
107
108 /**
109 * Clears instances of a named class from the pool.
110 *
111 * @param className the name of the class.
112 */
113 public void clearPool(String className);
114
115 /**
116 * Clears all instances from the pool.
117 */
118 void clearPool();
119
120 }