Coverage Report

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

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;
 
 /**
  * An interface defining life-cycle methods for
  * instances to be served by an {@link ObjectPool}.
  * <p>
  * By contract, when an {@link ObjectPool}
  * delegates to a {@link PoolableObjectFactory},
  * <ol>
  *  <li>
  *   {@link #makeObject makeObject}
  *   is called whenever a new instance is needed.
  *  </li>
  *  <li>
  *   {@link #activateObject activateObject}
  *   is invoked on every instance that has been
  *   {@link #passivateObject passivated} before it is
  *   {@link ObjectPool#borrowObject borrowed} from the pool.
  *  </li>
  *  <li>
  *   {@link #validateObject validateObject}
  *   is invoked on {@link #activateObject activated} instances to make sure
  *   they can be {@link ObjectPool#borrowObject borrowed} from the pool.
  *   <code>validateObject</code> <strong>may</strong> also be used to test an
  *   instance being {@link ObjectPool#returnObject returned} to the pool
  *   before it is {@link #passivateObject passivated}. It will only be invoked
  *   on an activated instance.
  *  </li>
  *  <li>
  *   {@link #passivateObject passivateObject}
  *   is invoked on every instance when it is returned to the pool.
  *  </li>
  *  <li>
  *   {@link #destroyObject destroyObject}
  *   is invoked on every instance when it is being "dropped" from the
  *   pool (whether due to the response from <code>validateObject</code>,
  *   or for reasons specific to the pool implementation.) There is no
  *   guarantee that the instance being destroyed will
  *   be considered active, passive or in a generally consistent state.
  *  </li>
  * </ol>
  * </p>
  * <p>
  * {@link PoolableObjectFactory} must be thread-safe. The only promise
  * an {@link ObjectPool} makes is that the same instance of an object will not
  * be passed to more than one method of a <code>PoolableObjectFactory</code>
  * at a time.
  * </p>
  *
  * @see ObjectPool
  *
  * @author Rodney Waldhoff
  * @author Sandy McArthur
  * @version $Revision: 777748 $ $Date: 2009-05-22 20:00:44 -0400 (Fri, 22 May 2009) $
  * @since Pool 1.0
  */
 public interface PoolableObjectFactory {
   /**
    * Creates an instance that can be served by the pool.
    * Instances returned from this method should be in the
    * same state as if they had been
    * {@link #activateObject activated}. They will not be
    * activated before being served by the pool.
    *
    * @return an instance that can be served by the pool.
    * @throws Exception if there is a problem creating a new instance,
    *    this will be propagated to the code requesting an object.
    */
   Object makeObject() throws Exception;
 
   /**
    * Destroys an instance no longer needed by the pool.
    * <p>
    * It is important for implementations of this method to be aware
    * that there is no guarantee about what state <code>obj</code>
    * will be in and the implementation should be prepared to handle
    * unexpected errors.
    * </p>
    * <p>
    * Also, an implementation must take in to consideration that
    * instances lost to the garbage collector may never be destroyed.
    * </p>
    *
    * @param obj the instance to be destroyed
    * @throws Exception should be avoided as it may be swallowed by
    *    the pool implementation.
    * @see #validateObject
    * @see ObjectPool#invalidateObject
    */
   void destroyObject(Object obj) throws Exception;
 
   /**
    * Ensures that the instance is safe to be returned by the pool.
    * Returns <code>false</code> if <code>obj</code> should be destroyed.
    *
    * @param obj the instance to be validated
    * @return <code>false</code> if <code>obj</code> is not valid and should
    *         be dropped from the pool, <code>true</code> otherwise.
    */
   boolean validateObject(Object obj);
 
   /**
    * Reinitialize an instance to be returned by the pool.
    *
    * @param obj the instance to be activated
    * @throws Exception if there is a problem activating <code>obj</code>,
    *    this exception may be swallowed by the pool.
    * @see #destroyObject
    */
   void activateObject(Object obj) throws Exception;
 
   /**
    * Uninitialize an instance to be returned to the idle object pool.
    *
    * @param obj the instance to be passivated
    * @throws Exception if there is a problem passivating <code>obj</code>,
    *    this exception may be swallowed by the pool.
    * @see #destroyObject
    */
   void passivateObject(Object obj) throws Exception;
 }

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		/**
21		* An interface defining life-cycle methods for
22		* instances to be served by an {@link ObjectPool}.
23		* <p>
24		* By contract, when an {@link ObjectPool}
25		* delegates to a {@link PoolableObjectFactory},
26		* <ol>
27		* <li>
28		* {@link #makeObject makeObject}
29		* is called whenever a new instance is needed.
30		* </li>
31		* <li>
32		* {@link #activateObject activateObject}
33		* is invoked on every instance that has been
34		* {@link #passivateObject passivated} before it is
35		* {@link ObjectPool#borrowObject borrowed} from the pool.
36		* </li>
37		* <li>
38		* {@link #validateObject validateObject}
39		* is invoked on {@link #activateObject activated} instances to make sure
40		* they can be {@link ObjectPool#borrowObject borrowed} from the pool.
41		* <code>validateObject</code> <strong>may</strong> also be used to test an
42		* instance being {@link ObjectPool#returnObject returned} to the pool
43		* before it is {@link #passivateObject passivated}. It will only be invoked
44		* on an activated instance.
45		* </li>
46		* <li>
47		* {@link #passivateObject passivateObject}
48		* is invoked on every instance when it is returned to the pool.
49		* </li>
50		* <li>
51		* {@link #destroyObject destroyObject}
52		* is invoked on every instance when it is being "dropped" from the
53		* pool (whether due to the response from <code>validateObject</code>,
54		* or for reasons specific to the pool implementation.) There is no
55		* guarantee that the instance being destroyed will
56		* be considered active, passive or in a generally consistent state.
57		* </li>
58		* </ol>
59		* </p>
60		* <p>
61		* {@link PoolableObjectFactory} must be thread-safe. The only promise
62		* an {@link ObjectPool} makes is that the same instance of an object will not
63		* be passed to more than one method of a <code>PoolableObjectFactory</code>
64		* at a time.
65		* </p>
66		*
67		* @see ObjectPool
68		*
69		* @author Rodney Waldhoff
70		* @author Sandy McArthur
71		* @version $Revision: 777748 $ $Date: 2009-05-22 20:00:44 -0400 (Fri, 22 May 2009) $
72		* @since Pool 1.0
73		*/
74		public interface PoolableObjectFactory {
75		/**
76		* Creates an instance that can be served by the pool.
77		* Instances returned from this method should be in the
78		* same state as if they had been
79		* {@link #activateObject activated}. They will not be
80		* activated before being served by the pool.
81		*
82		* @return an instance that can be served by the pool.
83		* @throws Exception if there is a problem creating a new instance,
84		* this will be propagated to the code requesting an object.
85		*/
86		Object makeObject() throws Exception;
87
88		/**
89		* Destroys an instance no longer needed by the pool.
90		* <p>
91		* It is important for implementations of this method to be aware
92		* that there is no guarantee about what state <code>obj</code>
93		* will be in and the implementation should be prepared to handle
94		* unexpected errors.
95		* </p>
96		* <p>
97		* Also, an implementation must take in to consideration that
98		* instances lost to the garbage collector may never be destroyed.
99		* </p>
100		*
101		* @param obj the instance to be destroyed
102		* @throws Exception should be avoided as it may be swallowed by
103		* the pool implementation.
104		* @see #validateObject
105		* @see ObjectPool#invalidateObject
106		*/
107		void destroyObject(Object obj) throws Exception;
108
109		/**
110		* Ensures that the instance is safe to be returned by the pool.
111		* Returns <code>false</code> if <code>obj</code> should be destroyed.
112		*
113		* @param obj the instance to be validated
114		* @return <code>false</code> if <code>obj</code> is not valid and should
115		* be dropped from the pool, <code>true</code> otherwise.
116		*/
117		boolean validateObject(Object obj);
118
119		/**
120		* Reinitialize an instance to be returned by the pool.
121		*
122		* @param obj the instance to be activated
123		* @throws Exception if there is a problem activating <code>obj</code>,
124		* this exception may be swallowed by the pool.
125		* @see #destroyObject
126		*/
127		void activateObject(Object obj) throws Exception;
128
129		/**
130		* Uninitialize an instance to be returned to the idle object pool.
131		*
132		* @param obj the instance to be passivated
133		* @throws Exception if there is a problem passivating <code>obj</code>,
134		* this exception may be swallowed by the pool.
135		* @see #destroyObject
136		*/
137		void passivateObject(Object obj) throws Exception;
138		}