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     * @param <K> the type of keys in this pool
026     * @param <V> the type of objects held in this pool
027     * 
028     * @author Rodney Waldhoff
029     * @author Sandy McArthur
030     * @version $Revision: 1222396 $ $Date: 2011-12-22 14:02:25 -0500 (Thu, 22 Dec 2011) $
031     * @since Pool 1.0
032     */
033    public abstract class BaseKeyedObjectPool<K, V> implements KeyedObjectPool<K, V> {
034        
035        /**
036         * {@inheritDoc}
037         */
038        public abstract V borrowObject(K key) throws Exception;
039        
040        /**
041         * {@inheritDoc}
042         */
043        public abstract void returnObject(K key, V obj) throws Exception;
044        
045        /**
046         * <p>Invalidates an object from the pool.</p>
047         * 
048         * <p>By contract, <code>obj</code> <strong>must</strong> have been obtained
049         * using {@link #borrowObject borrowObject} using a <code>key</code> that is
050         * equivalent to the one used to borrow the <code>Object</code> in the first place.</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 key the key used to obtain the object
056         * @param obj a {@link #borrowObject borrowed} instance to be returned.
057         * @throws Exception 
058         */
059        public abstract void invalidateObject(K key, V obj) throws Exception;
060    
061        /**
062         * Not supported in this base implementation.
063         * Always throws an {@link UnsupportedOperationException},
064         * subclasses should override this behavior.
065         * @param key ignored
066         * @throws UnsupportedOperationException
067         */
068        public void addObject(K key) throws Exception, UnsupportedOperationException {
069            throw new UnsupportedOperationException();
070        }
071    
072        /**
073         * Not supported in this base implementation.
074         * @return a negative value.
075         * @param key ignored
076         */
077        public int getNumIdle(K key) throws UnsupportedOperationException {
078            return -1;
079        }
080    
081        /**
082         * Not supported in this base implementation.
083         * @return a negative value.
084         * @param key ignored
085         */
086        public int getNumActive(K key) throws UnsupportedOperationException {
087            return -1;
088        }
089    
090        /**
091         * Not supported in this base implementation.
092         * @return a negative value.
093         */
094        public int getNumIdle() throws UnsupportedOperationException {
095            return -1;
096        }
097    
098        /**
099         * Not supported in this base implementation.
100         * @return a negative value.
101         */
102        public int getNumActive() throws UnsupportedOperationException {
103            return -1;
104        }
105    
106        /**
107         * Not supported in this base implementation.
108         * @throws UnsupportedOperationException
109         */
110        public void clear() throws Exception, UnsupportedOperationException {
111            throw new UnsupportedOperationException();
112        }
113    
114        /**
115         * Not supported in this base implementation.
116         * @param key ignored
117         * @throws UnsupportedOperationException
118         */
119        public void clear(K key) throws Exception, UnsupportedOperationException {
120            throw new UnsupportedOperationException();
121        }
122    
123        /**
124         * Close this pool.
125         * This affects the behavior of <code>isClosed</code> and <code>assertOpen</code>.
126         */
127        public void close() throws Exception {
128            closed = true;
129        }
130    
131        /**
132         * Not supported in this base implementation.
133         * Always throws an {@link UnsupportedOperationException},
134         * subclasses should override this behavior.
135         * @param factory the new KeyedPoolableObjectFactory
136         * @deprecated to be removed in pool 2.0
137         */
138        @Deprecated
139        public void setFactory(KeyedPoolableObjectFactory<K, V> factory) throws IllegalStateException, UnsupportedOperationException {
140            throw new UnsupportedOperationException();
141        }
142    
143        /**
144         * Has this pool instance been closed.
145         * @return <code>true</code> when this pool has been closed.
146         * @since Pool 1.4
147         */
148        protected final boolean isClosed() {
149            return closed;
150        }
151    
152        /**
153         * Throws an <code>IllegalStateException</code> when this pool has been closed.
154         * @throws IllegalStateException when this pool has been closed.
155         * @see #isClosed()
156         * @since Pool 1.4
157         */
158        protected final void assertOpen() throws IllegalStateException {
159            if(isClosed()) {
160                throw new IllegalStateException("Pool not open");
161            }
162        }
163    
164        /** Whether or not the pool is close */
165        private volatile boolean closed = false;
166    }