    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    }