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    }