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 <code>KeyedObjectPool</code>.
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: 1085933 $ $Date: 2011-03-27 06:40:20 -0700 (Sun, 27 Mar 2011) $
28 * @since Pool 1.0
29 */
30 public abstract class BaseKeyedObjectPool implements KeyedObjectPool {
31
32 /**
33 * {@inheritDoc}
34 */
35 public abstract Object borrowObject(Object key) throws Exception;
36
37 /**
38 * {@inheritDoc}
39 */
40 public abstract void returnObject(Object key, Object obj) throws Exception;
41
42 /**
43 * <p>Invalidates an object from the pool.</p>
44 *
45 * <p>By contract, <code>obj</code> <strong>must</strong> have been obtained
46 * using {@link #borrowObject borrowObject} using a <code>key</code> that is
47 * equivalent to the one used to borrow the <code>Object</code> in the first place.</p>
48 *
49 * <p>This method should be used when an object that has been borrowed
50 * is determined (due to an exception or other problem) to be invalid.</p>
51 *
52 * @param key the key used to obtain the object
53 * @param obj a {@link #borrowObject borrowed} instance to be returned.
54 * @throws Exception
55 */
56 public abstract void invalidateObject(Object key, Object obj) throws Exception;
57
58 /**
59 * Not supported in this base implementation.
60 * Always throws an {@link UnsupportedOperationException},
61 * subclasses should override this behavior.
62 * @param key ignored
63 * @throws UnsupportedOperationException
64 */
65 public void addObject(Object key) throws Exception, UnsupportedOperationException {
66 throw new UnsupportedOperationException();
67 }
68
69 /**
70 * Not supported in this base implementation.
71 * @return a negative value.
72 * @param key ignored
73 */
74 public int getNumIdle(Object key) throws UnsupportedOperationException {
75 return -1;
76 }
77
78 /**
79 * Not supported in this base implementation.
80 * @return a negative value.
81 * @param key ignored
82 */
83 public int getNumActive(Object key) throws UnsupportedOperationException {
84 return -1;
85 }
86
87 /**
88 * Not supported in this base implementation.
89 * @return a negative value.
90 */
91 public int getNumIdle() throws UnsupportedOperationException {
92 return -1;
93 }
94
95 /**
96 * Not supported in this base implementation.
97 * @return a negative value.
98 */
99 public int getNumActive() throws UnsupportedOperationException {
100 return -1;
101 }
102
103 /**
104 * Not supported in this base implementation.
105 * @throws UnsupportedOperationException
106 */
107 public void clear() throws Exception, UnsupportedOperationException {
108 throw new UnsupportedOperationException();
109 }
110
111 /**
112 * Not supported in this base implementation.
113 * @param key ignored
114 * @throws UnsupportedOperationException
115 */
116 public void clear(Object key) throws Exception, UnsupportedOperationException {
117 throw new UnsupportedOperationException();
118 }
119
120 /**
121 * Close this pool.
122 * This affects the behavior of <code>isClosed</code> and <code>assertOpen</code>.
123 */
124 public void close() throws Exception {
125 closed = true;
126 }
127
128 /**
129 * Not supported in this base implementation.
130 * Always throws an {@link UnsupportedOperationException},
131 * subclasses should override this behavior.
132 * @param factory the new KeyedPoolableObjectFactory
133 * @deprecated to be removed in pool 2.0
134 */
135 public void setFactory(KeyedPoolableObjectFactory factory) throws IllegalStateException, UnsupportedOperationException {
136 throw new UnsupportedOperationException();
137 }
138
139 /**
140 * Has this pool instance been closed.
141 * @return <code>true</code> when this pool has been closed.
142 * @since Pool 1.4
143 */
144 protected final boolean isClosed() {
145 return closed;
146 }
147
148 /**
149 * Throws an <code>IllegalStateException</code> when this pool has been closed.
150 * @throws IllegalStateException when this pool has been closed.
151 * @see #isClosed()
152 * @since Pool 1.4
153 */
154 protected final void assertOpen() throws IllegalStateException {
155 if(isClosed()) {
156 throw new IllegalStateException("Pool not open");
157 }
158 }
159
160 /** Whether or not the pool is close */
161 private volatile boolean closed = false;
162 }