    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: 1084645 $ $Date: 2011-03-23 10:11:19 -0700 (Wed, 23 Mar 2011) $
    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    }