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 * @author Rodney Waldhoff
026 * @author Sandy McArthur
027 * @version $Revision: 1085933 $ $Date: 2011-03-27 06:40:20 -0700 (Sun, 27 Mar 2011) $
028 * @since Pool 1.0
029 */
030 public abstract class BaseKeyedObjectPool implements KeyedObjectPool {
031
032 /**
033 * {@inheritDoc}
034 */
035 public abstract Object borrowObject(Object key) throws Exception;
036
037 /**
038 * {@inheritDoc}
039 */
040 public abstract void returnObject(Object key, Object obj) throws Exception;
041
042 /**
043 * <p>Invalidates an object from the pool.</p>
044 *
045 * <p>By contract, <code>obj</code> <strong>must</strong> have been obtained
046 * using {@link #borrowObject borrowObject} using a <code>key</code> that is
047 * equivalent to the one used to borrow the <code>Object</code> in the first place.</p>
048 *
049 * <p>This method should be used when an object that has been borrowed
050 * is determined (due to an exception or other problem) to be invalid.</p>
051 *
052 * @param key the key used to obtain the object
053 * @param obj a {@link #borrowObject borrowed} instance to be returned.
054 * @throws Exception
055 */
056 public abstract void invalidateObject(Object key, Object obj) throws Exception;
057
058 /**
059 * Not supported in this base implementation.
060 * Always throws an {@link UnsupportedOperationException},
061 * subclasses should override this behavior.
062 * @param key ignored
063 * @throws UnsupportedOperationException
064 */
065 public void addObject(Object key) throws Exception, UnsupportedOperationException {
066 throw new UnsupportedOperationException();
067 }
068
069 /**
070 * Not supported in this base implementation.
071 * @return a negative value.
072 * @param key ignored
073 */
074 public int getNumIdle(Object key) throws UnsupportedOperationException {
075 return -1;
076 }
077
078 /**
079 * Not supported in this base implementation.
080 * @return a negative value.
081 * @param key ignored
082 */
083 public int getNumActive(Object key) throws UnsupportedOperationException {
084 return -1;
085 }
086
087 /**
088 * Not supported in this base implementation.
089 * @return a negative value.
090 */
091 public int getNumIdle() throws UnsupportedOperationException {
092 return -1;
093 }
094
095 /**
096 * Not supported in this base implementation.
097 * @return a negative value.
098 */
099 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 }