Coverage Report

Coverage Report - org.apache.commons.pool.KeyedObjectPool

Classes in this File

 /*
  * Licensed to the Apache Software Foundation (ASF) under one or more
  * contributor license agreements.  See the NOTICE file distributed with
  * this work for additional information regarding copyright ownership.
  * The ASF licenses this file to You under the Apache License, Version 2.0
  * (the "License"); you may not use this file except in compliance with
  * the License.  You may obtain a copy of the License at
  *
  *      http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
 
 package org.apache.commons.pool;
 
 import java.util.NoSuchElementException;
 
 /**
  * A "keyed" pooling interface.
  * <p>
  * A keyed pool pools instances of multiple types. Each
  * type may be accessed using an arbitrary key.
  * </p>
  * <p>
  * Example of use:
  * <pre style="border:solid thin; padding: 1ex;"
  * > Object obj = <code style="color:#00C">null</code>;
  * Object key = <code style="color:#C00">"Key"</code>;
  *
  * <code style="color:#00C">try</code> {
  *     obj = pool.borrowObject(key);
  *     <code style="color:#0C0">//...use the object...</code>
  * } <code style="color:#00C">catch</code>(Exception e) {
  *     <code style="color:#0C0">// invalidate the object</code>
  *     pool.invalidateObject(key, obj);
  *     <code style="color:#0C0">// do not return the object to the pool twice</code>
  *     obj = <code style="color:#00C">null</code>;
  * } <code style="color:#00C">finally</code> {
  *     <code style="color:#0C0">// make sure the object is returned to the pool</code>
  *     <code style="color:#00C">if</code>(<code style="color:#00C">null</code> != obj) {
  *         pool.returnObject(key, obj);
  *     }
  * }</pre>
  * </p>
  * <p>
  * {@link KeyedObjectPool} implementations <i>may</i> choose to store at most
  * one instance per key value, or may choose to maintain a pool of instances
  * for each key (essentially creating a {@link java.util.Map Map} of
  * {@link ObjectPool pools}).
  * </p>
  *
  * <p>See {@link BaseKeyedObjectPool} for a simple base implementation.</p>
  *
  * @author Rodney Waldhoff
  * @author Sandy McArthur
  * @version $Revision: 778480 $ $Date: 2009-05-25 15:34:55 -0400 (Mon, 25 May 2009) $
  * @see KeyedPoolableObjectFactory
  * @see KeyedObjectPoolFactory
  * @see ObjectPool
  * @see BaseKeyedObjectPool
  * @since Pool 1.0
  */
 public interface KeyedObjectPool {
     /**
      * Obtains an instance from this pool for the specified <code>key</code>.
      * <p>
      * Instances returned from this method will have been either newly created with
      * {@link KeyedPoolableObjectFactory#makeObject makeObject} or will be a previously idle object and
      * have been activated with {@link KeyedPoolableObjectFactory#activateObject activateObject} and
      * then validated with {@link KeyedPoolableObjectFactory#validateObject validateObject}.
      * <p>
      * By contract, clients <strong>must</strong> return the borrowed object using
      * {@link #returnObject returnObject}, {@link #invalidateObject invalidateObject}, or a related method
      * as defined in an implementation or sub-interface,
      * using a <code>key</code> that is {@link Object#equals equivalent} to the one used to
      * borrow the instance in the first place.
      * <p>
      * The behaviour of this method when the pool has been exhausted
      * is not strictly specified (although it may be specified by implementations).
      * Older versions of this method would return <code>null</code> to indicate exhaustion,
      * newer versions are encouraged to throw a {@link NoSuchElementException}.
      *
      * @param key the key used to obtain the object
      * @return an instance from this pool.
      * @throws IllegalStateException after {@link #close close} has been called on this pool
      * @throws Exception when {@link KeyedPoolableObjectFactory#makeObject makeObject} throws an exception
      * @throws NoSuchElementException when the pool is exhausted and cannot or will not return another instance
      */
     Object borrowObject(Object key) throws Exception, NoSuchElementException, IllegalStateException;
 
     /**
      * Return an instance to the pool.
      * By contract, <code>obj</code> <strong>must</strong> have been obtained
      * using {@link #borrowObject borrowObject}
      * or a related method as defined in an implementation
      * or sub-interface
      * using a <code>key</code> that is equivalent to the one used to
      * borrow the instance in the first place.
      *
      * @param key the key used to obtain the object
      * @param obj a {@link #borrowObject borrowed} instance to be returned.
      * @throws Exception 
      */
     void returnObject(Object key, Object obj) throws Exception;
 
     /**
      * Invalidates an object from the pool
      * By contract, <code>obj</code> <strong>must</strong> have been obtained
      * using {@link #borrowObject borrowObject}
      * or a related method as defined in an implementation
      * or sub-interface
      * using a <code>key</code> that is equivalent to the one used to
      * borrow the <code>Object</code> in the first place.
      * <p>
      * This method should be used when an object that has been borrowed
      * is determined (due to an exception or other problem) to be invalid.
      * </p>
      *
      * @param key the key used to obtain the object
      * @param obj a {@link #borrowObject borrowed} instance to be returned.
      * @throws Exception 
      */
     void invalidateObject(Object key, Object obj) throws Exception;
 
     /**
      * Create an object using the {@link KeyedPoolableObjectFactory factory} or other
      * implementation dependent mechanism, passivate it, and then place it in the idle object pool.
      * <code>addObject</code> is useful for "pre-loading" a pool with idle objects
      * (Optional operation).
      *
      * @param key the key a new instance should be added to
      * @throws Exception when {@link KeyedPoolableObjectFactory#makeObject} fails.
      * @throws IllegalStateException after {@link #close} has been called on this pool.
      * @throws UnsupportedOperationException when this pool cannot add new idle objects.
      */
     void addObject(Object key) throws Exception, IllegalStateException, UnsupportedOperationException;
 
     /**
      * Returns the number of instances
      * corresponding to the given <code>key</code>
      * currently idle in this pool (optional operation).
      * Returns a negative value if this information is not available.
      *
      * @param key the key to query
      * @return the number of instances corresponding to the given <code>key</code> currently idle in this pool or a negative value if unsupported
      * @throws UnsupportedOperationException <strong>deprecated</strong>: when this implementation doesn't support the operation
      */
     int getNumIdle(Object key) throws UnsupportedOperationException;
 
     /**
      * Returns the number of instances
      * currently borrowed from but not yet returned
      * to the pool corresponding to the
      * given <code>key</code> (optional operation).
      * Returns a negative value if this information is not available.
      *
      * @param key the key to query
      * @return the number of instances corresponding to the given <code>key</code> currently borrowed in this pool or a negative value if unsupported
      * @throws UnsupportedOperationException <strong>deprecated</strong>: when this implementation doesn't support the operation
      */
     int getNumActive(Object key) throws UnsupportedOperationException;
 
     /**
      * Returns the total number of instances
      * currently idle in this pool (optional operation).
      * Returns a negative value if this information is not available.
      *
      * @return the total number of instances currently idle in this pool or a negative value if unsupported
      * @throws UnsupportedOperationException <strong>deprecated</strong>: when this implementation doesn't support the operation
      */
     int getNumIdle() throws UnsupportedOperationException;
 
     /**
      * Returns the total number of instances
      * current borrowed from this pool but not
      * yet returned (optional operation).
      * Returns a negative value if this information is not available.
      *
      * @return the total number of instances currently borrowed from this pool or a negative value if unsupported
      * @throws UnsupportedOperationException <strong>deprecated</strong>: when this implementation doesn't support the operation
      */
     int getNumActive() throws UnsupportedOperationException;
 
     /**
      * Clears the pool, removing all pooled instances (optional operation).
      * Throws {@link UnsupportedOperationException} if the pool cannot be cleared.
      *
      * @throws UnsupportedOperationException when this implementation doesn't support the operation
      */
     void clear() throws Exception, UnsupportedOperationException;
 
     /**
      * Clears the specified pool, removing all
      * pooled instances corresponding to
      * the given <code>key</code> (optional operation).
      * Throws {@link UnsupportedOperationException} if the pool cannot be cleared.
      *
      * @param key the key to clear
      * @throws UnsupportedOperationException when this implementation doesn't support the operation
      */
     void clear(Object key) throws Exception, UnsupportedOperationException;
 
     /**
      * Close this pool, and free any resources associated with it.
      * <p>
      * Calling {@link #addObject addObject} or {@link #borrowObject borrowObject} after invoking
      * this method on a pool will cause them to throw an {@link IllegalStateException}.
      * </p>
      *
      * @throws Exception
      */
     void close() throws Exception;
 
     /**
      * Sets the {@link KeyedPoolableObjectFactory factory} the pool uses
      * to create new instances (optional operation).
      * Trying to change the <code>factory</code> after a pool has been used will frequently
      * throw an {@link UnsupportedOperationException}. It is up to the pool
      * implementation to determine when it is acceptable to call this method.
      *
      * @param factory the {@link KeyedPoolableObjectFactory} used to create new instances.
      * @throws IllegalStateException when the factory cannot be set at this time
      * @throws UnsupportedOperationException when this implementation doesn't support the operation
      */
     void setFactory(KeyedPoolableObjectFactory factory) throws IllegalStateException, UnsupportedOperationException;
 }

1		/*
2		* Licensed to the Apache Software Foundation (ASF) under one or more
3		* contributor license agreements. See the NOTICE file distributed with
4		* this work for additional information regarding copyright ownership.
5		* The ASF licenses this file to You under the Apache License, Version 2.0
6		* (the "License"); you may not use this file except in compliance with
7		* the License. You may obtain a copy of the License at
8		*
9		* http://www.apache.org/licenses/LICENSE-2.0
10		*
11		* Unless required by applicable law or agreed to in writing, software
12		* distributed under the License is distributed on an "AS IS" BASIS,
13		* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14		* See the License for the specific language governing permissions and
15		* limitations under the License.
16		*/
17
18		package org.apache.commons.pool;
19
20		import java.util.NoSuchElementException;
21
22		/**
23		* A "keyed" pooling interface.
24		* <p>
25		* A keyed pool pools instances of multiple types. Each
26		* type may be accessed using an arbitrary key.
27		* </p>
28		* <p>
29		* Example of use:
30		* <pre style="border:solid thin; padding: 1ex;"
31		* > Object obj = <code style="color:#00C">null</code>;
32		* Object key = <code style="color:#C00">"Key"</code>;
33		*
34		* <code style="color:#00C">try</code> {
35		* obj = pool.borrowObject(key);
36		* <code style="color:#0C0">//...use the object...</code>
37		* } <code style="color:#00C">catch</code>(Exception e) {
38		* <code style="color:#0C0">// invalidate the object</code>
39		* pool.invalidateObject(key, obj);
40		* <code style="color:#0C0">// do not return the object to the pool twice</code>
41		* obj = <code style="color:#00C">null</code>;
42		* } <code style="color:#00C">finally</code> {
43		* <code style="color:#0C0">// make sure the object is returned to the pool</code>
44		* <code style="color:#00C">if</code>(<code style="color:#00C">null</code> != obj) {
45		* pool.returnObject(key, obj);
46		* }
47		* }</pre>
48		* </p>
49		* <p>
50		* {@link KeyedObjectPool} implementations <i>may</i> choose to store at most
51		* one instance per key value, or may choose to maintain a pool of instances
52		* for each key (essentially creating a {@link java.util.Map Map} of
53		* {@link ObjectPool pools}).
54		* </p>
55		*
56		* <p>See {@link BaseKeyedObjectPool} for a simple base implementation.</p>
57		*
58		* @author Rodney Waldhoff
59		* @author Sandy McArthur
60		* @version $Revision: 778480 $ $Date: 2009-05-25 15:34:55 -0400 (Mon, 25 May 2009) $
61		* @see KeyedPoolableObjectFactory
62		* @see KeyedObjectPoolFactory
63		* @see ObjectPool
64		* @see BaseKeyedObjectPool
65		* @since Pool 1.0
66		*/
67		public interface KeyedObjectPool {
68		/**
69		* Obtains an instance from this pool for the specified <code>key</code>.
70		* <p>
71		* Instances returned from this method will have been either newly created with
72		* {@link KeyedPoolableObjectFactory#makeObject makeObject} or will be a previously idle object and
73		* have been activated with {@link KeyedPoolableObjectFactory#activateObject activateObject} and
74		* then validated with {@link KeyedPoolableObjectFactory#validateObject validateObject}.
75		* <p>
76		* By contract, clients <strong>must</strong> return the borrowed object using
77		* {@link #returnObject returnObject}, {@link #invalidateObject invalidateObject}, or a related method
78		* as defined in an implementation or sub-interface,
79		* using a <code>key</code> that is {@link Object#equals equivalent} to the one used to
80		* borrow the instance in the first place.
81		* <p>
82		* The behaviour of this method when the pool has been exhausted
83		* is not strictly specified (although it may be specified by implementations).
84		* Older versions of this method would return <code>null</code> to indicate exhaustion,
85		* newer versions are encouraged to throw a {@link NoSuchElementException}.
86		*
87		* @param key the key used to obtain the object
88		* @return an instance from this pool.
89		* @throws IllegalStateException after {@link #close close} has been called on this pool
90		* @throws Exception when {@link KeyedPoolableObjectFactory#makeObject makeObject} throws an exception
91		* @throws NoSuchElementException when the pool is exhausted and cannot or will not return another instance
92		*/
93		Object borrowObject(Object key) throws Exception, NoSuchElementException, IllegalStateException;
94
95		/**
96		* Return an instance to the pool.
97		* By contract, <code>obj</code> <strong>must</strong> have been obtained
98		* using {@link #borrowObject borrowObject}
99		* or a related method as defined in an implementation
100		* or sub-interface
101		* using a <code>key</code> that is equivalent to the one used to
102		* borrow the instance in the first place.
103		*
104		* @param key the key used to obtain the object
105		* @param obj a {@link #borrowObject borrowed} instance to be returned.
106		* @throws Exception
107		*/
108		void returnObject(Object key, Object obj) throws Exception;
109
110		/**
111		* Invalidates an object from the pool
112		* By contract, <code>obj</code> <strong>must</strong> have been obtained
113		* using {@link #borrowObject borrowObject}
114		* or a related method as defined in an implementation
115		* or sub-interface
116		* using a <code>key</code> that is equivalent to the one used to
117		* borrow the <code>Object</code> in the first place.
118		* <p>
119		* This method should be used when an object that has been borrowed
120		* is determined (due to an exception or other problem) to be invalid.
121		* </p>
122		*
123		* @param key the key used to obtain the object
124		* @param obj a {@link #borrowObject borrowed} instance to be returned.
125		* @throws Exception
126		*/
127		void invalidateObject(Object key, Object obj) throws Exception;
128
129		/**
130		* Create an object using the {@link KeyedPoolableObjectFactory factory} or other
131		* implementation dependent mechanism, passivate it, and then place it in the idle object pool.
132		* <code>addObject</code> is useful for "pre-loading" a pool with idle objects
133		* (Optional operation).
134		*
135		* @param key the key a new instance should be added to
136		* @throws Exception when {@link KeyedPoolableObjectFactory#makeObject} fails.
137		* @throws IllegalStateException after {@link #close} has been called on this pool.
138		* @throws UnsupportedOperationException when this pool cannot add new idle objects.
139		*/
140		void addObject(Object key) throws Exception, IllegalStateException, UnsupportedOperationException;
141
142		/**
143		* Returns the number of instances
144		* corresponding to the given <code>key</code>
145		* currently idle in this pool (optional operation).
146		* Returns a negative value if this information is not available.
147		*
148		* @param key the key to query
149		* @return the number of instances corresponding to the given <code>key</code> currently idle in this pool or a negative value if unsupported
150		* @throws UnsupportedOperationException <strong>deprecated</strong>: when this implementation doesn't support the operation
151		*/
152		int getNumIdle(Object key) throws UnsupportedOperationException;
153
154		/**
155		* Returns the number of instances
156		* currently borrowed from but not yet returned
157		* to the pool corresponding to the
158		* given <code>key</code> (optional operation).
159		* Returns a negative value if this information is not available.
160		*
161		* @param key the key to query
162		* @return the number of instances corresponding to the given <code>key</code> currently borrowed in this pool or a negative value if unsupported
163		* @throws UnsupportedOperationException <strong>deprecated</strong>: when this implementation doesn't support the operation
164		*/
165		int getNumActive(Object key) throws UnsupportedOperationException;
166
167		/**
168		* Returns the total number of instances
169		* currently idle in this pool (optional operation).
170		* Returns a negative value if this information is not available.
171		*
172		* @return the total number of instances currently idle in this pool or a negative value if unsupported
173		* @throws UnsupportedOperationException <strong>deprecated</strong>: when this implementation doesn't support the operation
174		*/
175		int getNumIdle() throws UnsupportedOperationException;
176
177		/**
178		* Returns the total number of instances
179		* current borrowed from this pool but not
180		* yet returned (optional operation).
181		* Returns a negative value if this information is not available.
182		*
183		* @return the total number of instances currently borrowed from this pool or a negative value if unsupported
184		* @throws UnsupportedOperationException <strong>deprecated</strong>: when this implementation doesn't support the operation
185		*/
186		int getNumActive() throws UnsupportedOperationException;
187
188		/**
189		* Clears the pool, removing all pooled instances (optional operation).
190		* Throws {@link UnsupportedOperationException} if the pool cannot be cleared.
191		*
192		* @throws UnsupportedOperationException when this implementation doesn't support the operation
193		*/
194		void clear() throws Exception, UnsupportedOperationException;
195
196		/**
197		* Clears the specified pool, removing all
198		* pooled instances corresponding to
199		* the given <code>key</code> (optional operation).
200		* Throws {@link UnsupportedOperationException} if the pool cannot be cleared.
201		*
202		* @param key the key to clear
203		* @throws UnsupportedOperationException when this implementation doesn't support the operation
204		*/
205		void clear(Object key) throws Exception, UnsupportedOperationException;
206
207		/**
208		* Close this pool, and free any resources associated with it.
209		* <p>
210		* Calling {@link #addObject addObject} or {@link #borrowObject borrowObject} after invoking
211		* this method on a pool will cause them to throw an {@link IllegalStateException}.
212		* </p>
213		*
214		* @throws Exception
215		*/
216		void close() throws Exception;
217
218		/**
219		* Sets the {@link KeyedPoolableObjectFactory factory} the pool uses
220		* to create new instances (optional operation).
221		* Trying to change the <code>factory</code> after a pool has been used will frequently
222		* throw an {@link UnsupportedOperationException}. It is up to the pool
223		* implementation to determine when it is acceptable to call this method.
224		*
225		* @param factory the {@link KeyedPoolableObjectFactory} used to create new instances.
226		* @throws IllegalStateException when the factory cannot be set at this time
227		* @throws UnsupportedOperationException when this implementation doesn't support the operation
228		*/
229		void setFactory(KeyedPoolableObjectFactory factory) throws IllegalStateException, UnsupportedOperationException;
230		}