KickJava   Java API By Example, From Geeks To Geeks.

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


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 interface is to define how a Pool is used. We have determined by
21  * using the previous Pool implementations that the Pool marker interface
22  * is considered harmful. When generics are introduced in JDK 1.5, this
23  * interface will be a prime candidate for those improvements.
24  *
25  * <p>
26  * It is important to realize that some objects are cheaper to simply allow
27  * the garbage collector to take care of them. Therefore, only pool objects
28  * that are computationally expensive to create. Prime candidates would be
29  * Components, JDBC Connection objects, Socket connections, etc.
30  * </p>
31  * <p>
32  * The interface is inspired by both the Mutex acquire/release and the
33  * structure of the ThreadLocal object. In fact, it would be trivial
34  * to implement a "ThreadLocal" pool.
35  * </p>
36  *
37  * @author <a HREF="mailto:dev@avalon.apache.org">Avalon Development Team</a>
38  * @version CVS $Revision: 1.4 $ $Date: 2004/02/28 11:47:33 $
39  * @since 4.1.2
40  */

41 public interface Pool
42 {
43     /**
44      * Acquire an instance of the pooled object.
45      *
46      * @return the pooled Object instance
47      *
48      * @throws Exception if the Pool is not able to return an object.
49      */

50     Object JavaDoc acquire() throws Exception JavaDoc;
51
52     /**
53      * Release the instance of the pooled object.
54      *
55      * @param pooledObject The pooled object to release to the pool.
56      */

57     void release( Object JavaDoc pooledObject );
58
59     /**
60      * Create a new instance of the object being pooled.
61      *
62      * @return the pooled Object instance
63      *
64      * @throws Exception if the instance cannot be created
65      */

66     Object JavaDoc newInstance() throws Exception JavaDoc;
67 }
68
Popular Tags