Coverage Report

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

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 pooling interface.
  * <p>
  * <code>ObjectPool</code> defines a trivially simple pooling interface. The only
  * required methods are {@link #borrowObject borrowObject}, {@link #returnObject returnObject}
  * and {@link #invalidateObject invalidateObject}.
  * </p>
  * <p>
  * Example of use:
  * <pre style="border:solid thin; padding: 1ex;"
  * > Object obj = <code style="color:#00C">null</code>;
  *
  * <code style="color:#00C">try</code> {
  *     obj = pool.borrowObject();
  *     <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(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(obj);
  *    }
  * }</pre>
  * </p>
  *
  * <p>See {@link BaseObjectPool} for a simple base implementation.</p>
  *
  * @author Rodney Waldhoff
  * @author Sandy McArthur
  * @version $Revision: 778007 $ $Date: 2009-05-23 15:57:11 -0400 (Sat, 23 May 2009) $
  * @see PoolableObjectFactory
  * @see ObjectPoolFactory
  * @see KeyedObjectPool
  * @see BaseObjectPool
  * @since Pool 1.0
  */
 public interface ObjectPool {
     /**
      * Obtains an instance from this pool.
      * <p>
      * Instances returned from this method will have been either newly created with
      * {@link PoolableObjectFactory#makeObject makeObject} or will be a previously idle object and
      * have been activated with {@link PoolableObjectFactory#activateObject activateObject} and
      * then validated with {@link PoolableObjectFactory#validateObject validateObject}.
      * </p>
      * <p>
      * By contract, clients <strong>must</strong> return the borrowed instance using
      * {@link #returnObject returnObject}, {@link #invalidateObject invalidateObject}, or a related method
      * as defined in an implementation or sub-interface.
      * </p>
      * <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}.
      * </p>
      *
      * @return an instance from this pool.
      * @throws IllegalStateException after {@link #close close} has been called on this pool.
      * @throws Exception when {@link PoolableObjectFactory#makeObject makeObject} throws an exception.
      * @throws NoSuchElementException when the pool is exhausted and cannot or will not return another instance.
      */
     Object borrowObject() 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.
      *
      * @param obj a {@link #borrowObject borrowed} instance to be returned.
      * @throws Exception 
      */
     void returnObject(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.
      * <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 obj a {@link #borrowObject borrowed} instance to be disposed.
      * @throws Exception
      */
     void invalidateObject(Object obj) throws Exception;
 
     /**
      * Create an object using the {@link PoolableObjectFactory 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).
      *
      * @throws Exception when {@link PoolableObjectFactory#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() throws Exception, IllegalStateException, UnsupportedOperationException;
 
     /**
      * Return the number of instances
      * currently idle in this pool (optional operation).
      * This may be considered an approximation of the number
      * of objects that can be {@link #borrowObject borrowed}
      * without creating any new instances.
      * Returns a negative value if this information is not available.
      *
      * @return the number of instances currently idle in this pool or a negative value if unsupported
      * @throws UnsupportedOperationException <strong>deprecated</strong>: if this implementation does not support the operation
      */
     int getNumIdle() throws UnsupportedOperationException;
 
     /**
      * Return the number of instances
      * currently borrowed from this pool
      * (optional operation).
      * Returns a negative value if this information is not available.
      *
      * @return the number of instances currently borrowed from this pool or a negative value if unsupported
      * @throws UnsupportedOperationException <strong>deprecated</strong>: if this implementation does not support the operation
      */
     int getNumActive() throws UnsupportedOperationException;
 
     /**
      * Clears any objects sitting idle in the pool, releasing any
      * associated resources (optional operation).
      * Idle objects cleared must be {@link PoolableObjectFactory#destroyObject(Object) destroyed}.
      *
      * @throws UnsupportedOperationException if this implementation does not support the operation
      */
     void clear() throws Exception, UnsupportedOperationException;
 
     /**
      * Close this pool, and free any resources associated with it.
      * <p>
      * Calling {@link #addObject} or {@link #borrowObject} after invoking
      * this method on a pool will cause them to throw an
      * {@link IllegalStateException}.
      * </p>
      *
      * @throws Exception <strong>deprecated</strong>: implementations should silently fail if not all resources can be freed.
      */
     void close() throws Exception;
 
     /**
      * Sets the {@link PoolableObjectFactory factory} this 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 PoolableObjectFactory} used to create new instances.
      * @throws IllegalStateException when the factory cannot be set at this time
      * @throws UnsupportedOperationException if this implementation does not support the operation
      */
     void setFactory(PoolableObjectFactory 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 pooling interface.
24		* <p>
25		* <code>ObjectPool</code> defines a trivially simple pooling interface. The only
26		* required methods are {@link #borrowObject borrowObject}, {@link #returnObject returnObject}
27		* and {@link #invalidateObject invalidateObject}.
28		* </p>
29		* <p>
30		* Example of use:
31		* <pre style="border:solid thin; padding: 1ex;"
32		* > Object obj = <code style="color:#00C">null</code>;
33		*
34		* <code style="color:#00C">try</code> {
35		* obj = pool.borrowObject();
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(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(obj);
46		* }
47		* }</pre>
48		* </p>
49		*
50		* <p>See {@link BaseObjectPool} for a simple base implementation.</p>
51		*
52		* @author Rodney Waldhoff
53		* @author Sandy McArthur
54		* @version $Revision: 778007 $ $Date: 2009-05-23 15:57:11 -0400 (Sat, 23 May 2009) $
55		* @see PoolableObjectFactory
56		* @see ObjectPoolFactory
57		* @see KeyedObjectPool
58		* @see BaseObjectPool
59		* @since Pool 1.0
60		*/
61		public interface ObjectPool {
62		/**
63		* Obtains an instance from this pool.
64		* <p>
65		* Instances returned from this method will have been either newly created with
66		* {@link PoolableObjectFactory#makeObject makeObject} or will be a previously idle object and
67		* have been activated with {@link PoolableObjectFactory#activateObject activateObject} and
68		* then validated with {@link PoolableObjectFactory#validateObject validateObject}.
69		* </p>
70		* <p>
71		* By contract, clients <strong>must</strong> return the borrowed instance using
72		* {@link #returnObject returnObject}, {@link #invalidateObject invalidateObject}, or a related method
73		* as defined in an implementation or sub-interface.
74		* </p>
75		* <p>
76		* The behaviour of this method when the pool has been exhausted
77		* is not strictly specified (although it may be specified by implementations).
78		* Older versions of this method would return <code>null</code> to indicate exhaustion,
79		* newer versions are encouraged to throw a {@link NoSuchElementException}.
80		* </p>
81		*
82		* @return an instance from this pool.
83		* @throws IllegalStateException after {@link #close close} has been called on this pool.
84		* @throws Exception when {@link PoolableObjectFactory#makeObject makeObject} throws an exception.
85		* @throws NoSuchElementException when the pool is exhausted and cannot or will not return another instance.
86		*/
87		Object borrowObject() throws Exception, NoSuchElementException, IllegalStateException;
88
89		/**
90		* Return an instance to the pool.
91		* By contract, <code>obj</code> <strong>must</strong> have been obtained
92		* using {@link #borrowObject() borrowObject}
93		* or a related method as defined in an implementation
94		* or sub-interface.
95		*
96		* @param obj a {@link #borrowObject borrowed} instance to be returned.
97		* @throws Exception
98		*/
99		void returnObject(Object obj) throws Exception;
100
101		/**
102		* Invalidates an object from the pool.
103		* By contract, <code>obj</code> <strong>must</strong> have been obtained
104		* using {@link #borrowObject borrowObject}
105		* or a related method as defined in an implementation
106		* or sub-interface.
107		* <p>
108		* This method should be used when an object that has been borrowed
109		* is determined (due to an exception or other problem) to be invalid.
110		* </p>
111		*
112		* @param obj a {@link #borrowObject borrowed} instance to be disposed.
113		* @throws Exception
114		*/
115		void invalidateObject(Object obj) throws Exception;
116
117		/**
118		* Create an object using the {@link PoolableObjectFactory factory} or other
119		* implementation dependent mechanism, passivate it, and then place it in the idle object pool.
120		* <code>addObject</code> is useful for "pre-loading" a pool with idle objects.
121		* (Optional operation).
122		*
123		* @throws Exception when {@link PoolableObjectFactory#makeObject} fails.
124		* @throws IllegalStateException after {@link #close} has been called on this pool.
125		* @throws UnsupportedOperationException when this pool cannot add new idle objects.
126		*/
127		void addObject() throws Exception, IllegalStateException, UnsupportedOperationException;
128
129		/**
130		* Return the number of instances
131		* currently idle in this pool (optional operation).
132		* This may be considered an approximation of the number
133		* of objects that can be {@link #borrowObject borrowed}
134		* without creating any new instances.
135		* Returns a negative value if this information is not available.
136		*
137		* @return the number of instances currently idle in this pool or a negative value if unsupported
138		* @throws UnsupportedOperationException <strong>deprecated</strong>: if this implementation does not support the operation
139		*/
140		int getNumIdle() throws UnsupportedOperationException;
141
142		/**
143		* Return the number of instances
144		* currently borrowed from this pool
145		* (optional operation).
146		* Returns a negative value if this information is not available.
147		*
148		* @return the number of instances currently borrowed from this pool or a negative value if unsupported
149		* @throws UnsupportedOperationException <strong>deprecated</strong>: if this implementation does not support the operation
150		*/
151		int getNumActive() throws UnsupportedOperationException;
152
153		/**
154		* Clears any objects sitting idle in the pool, releasing any
155		* associated resources (optional operation).
156		* Idle objects cleared must be {@link PoolableObjectFactory#destroyObject(Object) destroyed}.
157		*
158		* @throws UnsupportedOperationException if this implementation does not support the operation
159		*/
160		void clear() throws Exception, UnsupportedOperationException;
161
162		/**
163		* Close this pool, and free any resources associated with it.
164		* <p>
165		* Calling {@link #addObject} or {@link #borrowObject} after invoking
166		* this method on a pool will cause them to throw an
167		* {@link IllegalStateException}.
168		* </p>
169		*
170		* @throws Exception <strong>deprecated</strong>: implementations should silently fail if not all resources can be freed.
171		*/
172		void close() throws Exception;
173
174		/**
175		* Sets the {@link PoolableObjectFactory factory} this pool uses
176		* to create new instances (optional operation). Trying to change
177		* the <code>factory</code> after a pool has been used will frequently
178		* throw an {@link UnsupportedOperationException}. It is up to the pool
179		* implementation to determine when it is acceptable to call this method.
180		*
181		* @param factory the {@link PoolableObjectFactory} used to create new instances.
182		* @throws IllegalStateException when the factory cannot be set at this time
183		* @throws UnsupportedOperationException if this implementation does not support the operation
184		*/
185		void setFactory(PoolableObjectFactory factory) throws IllegalStateException, UnsupportedOperationException;
186		}