KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > avalon > excalibur > pool > ManagablePool


1 /*
2  * Copyright (C) The Apache Software Foundation. All rights reserved.
3  *
4  * This software is published under the terms of the Apache Software License
5  * version 1.1, a copy of which has been included with this distribution in
6  * the LICENSE.txt file.
7  */
8 package org.apache.avalon.excalibur.pool;
9
10 /**
11  * This is the interface for Pools that are not a fixed size. This interface
12  * exposes enough explicit state so that an external asynchronous Controller can
13  * do it's job. A secondary purpose of this interface is to supply a simple
14  * authentication mechanism so that the Pool only responds to method invocations
15  * by the legitimate controller.
16  *
17  * <p>
18  * The key is a randomly generated number greater than one assigned by the
19  * PoolManager and given to the Pool and the PoolController. The mechanism to
20  * generate the number is up to the PoolManager's policy. Keep in mind that
21  * should the key be made publicly available, the Pool is susceptible to a
22  * replay attack. Therefore, it is suggested that the key be created at the
23  * same time the Pool is created.
24  * </p>
25  *
26  * @author <a HREF="mailto:bloritsch@apache.org">Berin Loritsch</a>
27  * @version CVS $Revision: 1.3 $ $Date: 2002/01/28 19:29:47 $
28  * @since 4.1
29  */
30 public interface ManagablePool extends Pool
31 {
32     /**
33      * Grow by the specified amount. The pool should trust the Controller for
34      * the Grow size.
35      *
36      * @param amount an integer amount to increase the pool size by.
37      * @param key an integer number supplied by the PoolManager to validate
38      * that the method is called legitimately
39      *
40      * @throws IllegalAccessException if the key does not match the controller's
41      * key.
42      */
43     void grow( int amount, long key )
44         throws IllegalAccessException JavaDoc;
45
46     /**
47      * Shrink the pool by the specified amount. The pool should trust the
48      * Controller, but be smart enough not to achieve a negative pool size.
49      * In other words, you should clip the shrink amount so that the pool does
50      * not go below 0.
51      *
52      * @param amount an integer amount to decrease the pool size by.
53      * @param key an integer number supplied by the PoolManager to validate
54      * that the method is called legitimately
55      *
56      * @throws IllegalAccessException if the key does not match the controller's
57      * key.
58      */
59     void shrink( int amount, long key )
60         throws IllegalAccessException JavaDoc;
61
62     /**
63      * Determine the pool's current size. The size is defined as the number of
64      * Poolable objects in reserve.
65      *
66      * @param key an integer number supplied by the PoolManager to validate
67      * that the method is called legitimately
68      *
69      * @return size of pool's reserve.
70      *
71      * @throws IllegalAccessException if the key does not match the controller's
72      * key.
73      */
74     int size( long key )
75         throws IllegalAccessException JavaDoc;
76 }
77
Popular Tags