View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  
18  package org.apache.commons.pool;
19  
20  /**
21   * A simple base implementation of {@link ObjectPool}.
22   * Optional operations are implemented to either do nothing, return a value
23   * indicating it is unsupported or throw {@link UnsupportedOperationException}.
24   *
25   * @author Rodney Waldhoff
26   * @author Sandy McArthur
27   * @version $Revision: 1084645 $ $Date: 2011-03-23 10:11:19 -0700 (Wed, 23 Mar 2011) $
28   * @since Pool 1.0
29   */
30  public abstract class BaseObjectPool implements ObjectPool {
31      /**
32       * Obtains an instance from the pool.
33       * 
34       * @return an instance from the pool
35       * @throws Exception if an instance cannot be obtained from the pool
36       */
37      public abstract Object borrowObject() throws Exception;
38      
39      /**
40       * Returns an instance to the pool.
41       * 
42       * @param obj instance to return to the pool
43       */
44      public abstract void returnObject(Object obj) throws Exception;
45      
46      /**
47       * <p>Invalidates an object from the pool.</p>
48       * 
49       * <p>By contract, <code>obj</code> <strong>must</strong> have been obtained
50       * using {@link #borrowObject borrowObject}.<p>
51       * 
52       * <p>This method should be used when an object that has been borrowed
53       * is determined (due to an exception or other problem) to be invalid.</p>
54       *
55       * @param obj a {@link #borrowObject borrowed} instance to be disposed.
56       * @throws Exception 
57       */
58      public abstract void invalidateObject(Object obj) throws Exception;
59  
60      /**
61       * Not supported in this base implementation.
62       * @return a negative value.
63       * 
64       * @throws UnsupportedOperationException
65       */
66      public int getNumIdle() throws UnsupportedOperationException {
67          return -1;
68      }
69  
70      /**
71       * Not supported in this base implementation.
72       * @return a negative value.
73       * 
74       * @throws UnsupportedOperationException
75       */
76      public int getNumActive() throws UnsupportedOperationException {
77          return -1;
78      }
79  
80      /**
81       * Not supported in this base implementation.
82       * 
83       * @throws UnsupportedOperationException
84       */
85      public void clear() throws Exception, UnsupportedOperationException {
86          throw new UnsupportedOperationException();
87      }
88  
89      /**
90       * Not supported in this base implementation.
91       * Always throws an {@link UnsupportedOperationException},
92       * subclasses should override this behavior.
93       * 
94       * @throws UnsupportedOperationException
95       */
96      public void addObject() throws Exception, UnsupportedOperationException {
97          throw new UnsupportedOperationException();
98      }
99  
100     /**
101      * Close this pool.
102      * This affects the behavior of <code>isClosed</code> and <code>assertOpen</code>.
103      */
104     public void close() throws Exception {
105         closed = true;
106     }
107 
108     /**
109      * Not supported in this base implementation.
110      * Always throws an {@link UnsupportedOperationException},
111      * subclasses should override this behavior.
112      * 
113      * @param factory the PoolableObjectFactory
114      * @throws UnsupportedOperationException
115      * @throws IllegalStateException
116      * @deprecated to be removed in pool 2.0
117      */
118     public void setFactory(PoolableObjectFactory factory) throws IllegalStateException, UnsupportedOperationException {
119         throw new UnsupportedOperationException();
120     }
121 
122     /**
123      * Has this pool instance been closed.
124      * @return <code>true</code> when this pool has been closed.
125      */
126     public final boolean isClosed() {
127         return closed;
128     }
129 
130     /**
131      * Throws an <code>IllegalStateException</code> when this pool has been closed.
132      * @throws IllegalStateException when this pool has been closed.
133      * @see #isClosed()
134      */
135     protected final void assertOpen() throws IllegalStateException {
136         if (isClosed()) {
137             throw new IllegalStateException("Pool not open");
138         }
139     }
140 
141     /** Whether or not the pool is closed */
142     private volatile boolean closed = false;
143 }