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 {@link ObjectPool}.
022 * Optional operations are implemented to either do nothing, return a value
023 * indicating it is unsupported or throw {@link UnsupportedOperationException}.
024 *
025 * @param <T> the type of objects held in this pool
026 *
027 * @author Rodney Waldhoff
028 * @author Sandy McArthur
029 * @version $Revision: 1222396 $ $Date: 2011-12-22 14:02:25 -0500 (Thu, 22 Dec 2011) $
030 * @since Pool 1.0
031 */
032 public abstract class BaseObjectPool<T> implements ObjectPool<T> {
033 /**
034 * Obtains an instance from the pool.
035 *
036 * @return an instance from the pool
037 * @throws Exception if an instance cannot be obtained from the pool
038 */
039 public abstract T borrowObject() throws Exception;
040
041 /**
042 * Returns an instance to the pool.
043 *
044 * @param obj instance to return to the pool
045 */
046 public abstract void returnObject(T obj) throws Exception;
047
048 /**
049 * <p>Invalidates an object from the pool.</p>
050 *
051 * <p>By contract, <code>obj</code> <strong>must</strong> have been obtained
052 * using {@link #borrowObject borrowObject}.<p>
053 *
054 * <p>This method should be used when an object that has been borrowed
055 * is determined (due to an exception or other problem) to be invalid.</p>
056 *
057 * @param obj a {@link #borrowObject borrowed} instance to be disposed.
058 * @throws Exception
059 */
060 public abstract void invalidateObject(T obj) throws Exception;
061
062 /**
063 * Not supported in this base implementation.
064 * @return a negative value.
065 *
066 * @throws UnsupportedOperationException
067 */
068 public int getNumIdle() throws UnsupportedOperationException {
069 return -1;
070 }
071
072 /**
073 * Not supported in this base implementation.
074 * @return a negative value.
075 *
076 * @throws UnsupportedOperationException
077 */
078 public int getNumActive() throws UnsupportedOperationException {
079 return -1;
080 }
081
082 /**
083 * Not supported in this base implementation.
084 *
085 * @throws UnsupportedOperationException
086 */
087 public void clear() throws Exception, UnsupportedOperationException {
088 throw new UnsupportedOperationException();
089 }
090
091 /**
092 * Not supported in this base implementation.
093 * Always throws an {@link UnsupportedOperationException},
094 * subclasses should override this behavior.
095 *
096 * @throws UnsupportedOperationException
097 */
098 public void addObject() throws Exception, UnsupportedOperationException {
099 throw new UnsupportedOperationException();
100 }
101
102 /**
103 * Close this pool.
104 * This affects the behavior of <code>isClosed</code> and <code>assertOpen</code>.
105 */
106 public void close() throws Exception {
107 closed = true;
108 }
109
110 /**
111 * Not supported in this base implementation.
112 * Always throws an {@link UnsupportedOperationException},
113 * subclasses should override this behavior.
114 *
115 * @param factory the PoolableObjectFactory
116 * @throws UnsupportedOperationException
117 * @throws IllegalStateException
118 * @deprecated to be removed in pool 2.0
119 */
120 @Deprecated
121 public void setFactory(PoolableObjectFactory<T> factory) throws IllegalStateException, UnsupportedOperationException {
122 throw new UnsupportedOperationException();
123 }
124
125 /**
126 * Has this pool instance been closed.
127 * @return <code>true</code> when this pool has been closed.
128 */
129 public final boolean isClosed() {
130 return closed;
131 }
132
133 /**
134 * Throws an <code>IllegalStateException</code> when this pool has been closed.
135 * @throws IllegalStateException when this pool has been closed.
136 * @see #isClosed()
137 */
138 protected final void assertOpen() throws IllegalStateException {
139 if (isClosed()) {
140 throw new IllegalStateException("Pool not open");
141 }
142 }
143
144 /** Whether or not the pool is closed */
145 private volatile boolean closed = false;
146 }