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 }