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