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    }