KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > excalibur > mpool > ManagablePool


1 /*
2  * Copyright 1999-2004 The Apache Software Foundation
3  * Licensed under the Apache License, Version 2.0 (the "License");
4  * you may not use this file except in compliance with the License.
5  * You may obtain a copy of the License at
6  *
7  * http://www.apache.org/licenses/LICENSE-2.0
8  *
9  * Unless required by applicable law or agreed to in writing, software
10  * distributed under the License is distributed on an "AS IS" BASIS,
11  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
12  * implied.
13  *
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  */
17 package org.apache.excalibur.mpool;
18
19 /**
20  * This is the interface for Pools that are not a fixed size. This interface
21  * exposes enough explicit state so that an external asynchronous Controller
22  * can do it's job. A secondary purpose of this interface is to supply a
23  * simple authentication mechanism so that the Pool only responds to method
24  * invocations by the legitimate controller.
25  *
26  * <p>
27  * The key is a randomly generated number greater than one assigned by the
28  * PoolManager and given to the Pool and the PoolController. The mechanism
29  * to generate the number is up to the PoolManager's policy. Keep in mind
30  * that should the key be made publicly available, the Pool is susceptible
31  * to a replay attack. Therefore, it is suggested that the key be created
32  * at the same time the Pool is created.
33  * </p>
34  *
35  * @author <a HREF="mailto:dev@avalon.apache.org">Avalon Development Team</a>
36  * @version CVS $Revision: 1.4 $ $Date: 2004/02/28 11:47:33 $
37  * @since 4.1
38  */
39 public interface ManagablePool extends Pool
40 {
41     /**
42      * Grow by the specified amount. The pool should trust the Controller
43      * for the Grow size.
44      *
45      * @param amount an integer amount to increase the pool size by.
46      * @param key an integer number supplied by the PoolManager to
47      * validate that the method is called legitimately
48      *
49      * @throws IllegalAccessException if the key does not match the
50      * controller's key.
51      */
52     void grow( int amount, long key )
53         throws IllegalAccessException JavaDoc;
54
55     /**
56      * Shrink the pool by the specified amount. The pool should trust the
57      * Controller, but be smart enough not to achieve a negative pool size.
58      * In other words, you should clip the shrink amount so that the pool
59      * does not go below 0.
60      *
61      * @param amount an integer amount to decrease the pool size by.
62      * @param key an integer number supplied by the PoolManager to
63      * validate that the method is called legitimately
64      *
65      * @throws IllegalAccessException if the key does not match the
66      * controller's key.
67      */
68     void shrink( int amount, long key )
69         throws IllegalAccessException JavaDoc;
70
71     /**
72      * Determine the pool's current size. The size is defined as the number
73      * of Poolable objects in reserve.
74      *
75      * @param key an integer number supplied by the PoolManager to
76      * validate that the method is called legitimately
77      *
78      * @return size of pool's reserve.
79      *
80      * @throws IllegalAccessException if the key does not match the
81      * controller's key.
82      */
83     int size( long key )
84         throws IllegalAccessException JavaDoc;
85 }
86
Popular Tags