001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements. See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License. You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018 package org.apache.commons.pool;
019
020 /**
021 * A simple base implementation of <code>KeyedObjectPool</code>.
022 * Optional operations are implemented to either do nothing, return a value
023 * indicating it is unsupported or throw {@link UnsupportedOperationException}.
024 *
025 * @param <K> the type of keys in this pool
026 * @param <V> the type of objects held in this pool
027 *
028 * @author Rodney Waldhoff
029 * @author Sandy McArthur
030 * @version $Revision: 1222396 $ $Date: 2011-12-22 14:02:25 -0500 (Thu, 22 Dec 2011) $
031 * @since Pool 1.0
032 */
033 public abstract class BaseKeyedObjectPool<K, V> implements KeyedObjectPool<K, V> {
034
035 /**
036 * {@inheritDoc}
037 */
038 public abstract V borrowObject(K key) throws Exception;
039
040 /**
041 * {@inheritDoc}
042 */
043 public abstract void returnObject(K key, V obj) throws Exception;
044
045 /**
046 * <p>Invalidates an object from the pool.</p>
047 *
048 * <p>By contract, <code>obj</code> <strong>must</strong> have been obtained
049 * using {@link #borrowObject borrowObject} using a <code>key</code> that is
050 * equivalent to the one used to borrow the <code>Object</code> in the first place.</p>
051 *
052 * <p>This method should be used when an object that has been borrowed
053 * is determined (due to an exception or other problem) to be invalid.</p>
054 *
055 * @param key the key used to obtain the object
056 * @param obj a {@link #borrowObject borrowed} instance to be returned.
057 * @throws Exception
058 */
059 public abstract void invalidateObject(K key, V obj) throws Exception;
060
061 /**
062 * Not supported in this base implementation.
063 * Always throws an {@link UnsupportedOperationException},
064 * subclasses should override this behavior.
065 * @param key ignored
066 * @throws UnsupportedOperationException
067 */
068 public void addObject(K key) throws Exception, UnsupportedOperationException {
069 throw new UnsupportedOperationException();
070 }
071
072 /**
073 * Not supported in this base implementation.
074 * @return a negative value.
075 * @param key ignored
076 */
077 public int getNumIdle(K key) throws UnsupportedOperationException {
078 return -1;
079 }
080
081 /**
082 * Not supported in this base implementation.
083 * @return a negative value.
084 * @param key ignored
085 */
086 public int getNumActive(K key) throws UnsupportedOperationException {
087 return -1;
088 }
089
090 /**
091 * Not supported in this base implementation.
092 * @return a negative value.
093 */
094 public int getNumIdle() throws UnsupportedOperationException {
095 return -1;
096 }
097
098 /**
099 * Not supported in this base implementation.
100 * @return a negative value.
101 */
102 public int getNumActive() throws UnsupportedOperationException {
103 return -1;
104 }
105
106 /**
107 * Not supported in this base implementation.
108 * @throws UnsupportedOperationException
109 */
110 public void clear() throws Exception, UnsupportedOperationException {
111 throw new UnsupportedOperationException();
112 }
113
114 /**
115 * Not supported in this base implementation.
116 * @param key ignored
117 * @throws UnsupportedOperationException
118 */
119 public void clear(K key) throws Exception, UnsupportedOperationException {
120 throw new UnsupportedOperationException();
121 }
122
123 /**
124 * Close this pool.
125 * This affects the behavior of <code>isClosed</code> and <code>assertOpen</code>.
126 */
127 public void close() throws Exception {
128 closed = true;
129 }
130
131 /**
132 * Not supported in this base implementation.
133 * Always throws an {@link UnsupportedOperationException},
134 * subclasses should override this behavior.
135 * @param factory the new KeyedPoolableObjectFactory
136 * @deprecated to be removed in pool 2.0
137 */
138 @Deprecated
139 public void setFactory(KeyedPoolableObjectFactory<K, V> factory) throws IllegalStateException, UnsupportedOperationException {
140 throw new UnsupportedOperationException();
141 }
142
143 /**
144 * Has this pool instance been closed.
145 * @return <code>true</code> when this pool has been closed.
146 * @since Pool 1.4
147 */
148 protected final boolean isClosed() {
149 return closed;
150 }
151
152 /**
153 * Throws an <code>IllegalStateException</code> when this pool has been closed.
154 * @throws IllegalStateException when this pool has been closed.
155 * @see #isClosed()
156 * @since Pool 1.4
157 */
158 protected final void assertOpen() throws IllegalStateException {
159 if(isClosed()) {
160 throw new IllegalStateException("Pool not open");
161 }
162 }
163
164 /** Whether or not the pool is close */
165 private volatile boolean closed = false;
166 }