commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <>
Subject [Jakarta-commons Wiki] Update of "PoolRoadMap" by SandyMcArthur
Date Mon, 13 Mar 2006 08:06:44 GMT
Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Jakarta-commons Wiki" for change notification.

The following page has been changed by SandyMcArthur:

The comment on the change is:
Expanded on the motivation for Pool 2 changes

  === Pool 1.3 ===
- There are a number of important fixes which have been committed. Therefore, cutting a 1.3
release makes sense.
+ There are a number of important fixes which have been committed. A 1.3 release is pending
peer review.
  === Pool 2 ===
  This will not fully compatible with the Pool 1.x releases. This has been necessitated by
some recent changes to semantics. Areas with the code contracts defined in interfaces is loosely
defined or unnecessary allows methods to return a variety of responses with the same meaning
will be changed to more user friendly behavior. This release will take advantage of Java 1.4
+ The planned changes of behavior are based on the intent of the client code using the pool.
+ Acquiring idle objects:
+  * addObject: client code calling this method wants to add another object to the list of
idle objects. If this fails then the client code should know about it with an exception.
+  * borrowObject: client code calling this method wants a valid object. Implementations should
try to return an idle object first. If this idle object fails to be activated or validated
then it should be destroyed and the pool should try again. When there are no more idle objects
then a new object should be created. If this fails then an exception should be propagate to
the client code. Also, null should never be returned.
+ Returning idle objects:
+  * returnObject: when client code is done with an object and still thinks the object is
valid it passes it back to the pool with returnObject. returnObject passivates the instance
and adds it to the idle object pool. If the passivation fails then the object is not added
to the idle object pool and it an attempt to destroy the object is made. In no situation should
an exception be allowed to propagate to client code. The client code is returning the object
and doesn't care about it anymore. If the client code need information about objects that
fail to be returned it should handle that in the PoolableObjectFactory implementation.
+  * invalidateObject: when client code is done with an object and thinks it's invalid for
future reuse. The object should be destroyed and never should an exception be propagated to
the calling code.
+ Pool maintenance methods:
+  * clear: like addObject the client code is requesting a specific behavior and should be
notified of problems clearing the pool. This does not include exceptions from destroying objects.
(That said, I personally cannot think of a situation where a clear would fail.)
+  * close: the client code calling this method is done with the pool. Resources that it makes
sense to free should be freed. (That does not mean null-ing all private fields as the factory
will still be needed to destroyObjects returned to the pool after it has been closed.) Unlike
the close method, problems while freeing those resources should be swallowed. After calling
the close method addObject and borrowObject method should throw an IllegalStateException and
the other methods like returnObject or invalidateObject should accept objects but immediately
destroy and discard them. This is important in a multi-threaded enviroment, such as a webapp,
where it is difficult or impossible to be sure when any object borrowed before the call to
close will be returned and threads that happen to return objects after the pool has been closed
should be allowed to complete normally until they can be shutdown.
+  * getNumActive and getNumIdle: previously these were declared to throw exceptions when
they were unsupported. Instead they should return a negative value because it would never
make sense for the active or idle count of a pool to go negative. By not throwing an exception
code like: if (pool.getNumActive() > 3) ... is safer and less error prone.
+  * setFactory: I think it's a gross misuse of a pool to change it's factory after it's been
created, especially after the first object has been borrowed.
+ Other points:
+  * a pool implementation should never allow a null PoolableObjectFactry. A pool with no
factory is called a java.util.List or a keyed pool a java.util.Map of java.util.Lists. 
+  * any object borrowed from the pool must be returned to the pool. Client code should be
careful to only return a borrowed object once. The same borrowed instance should never be
returned to both returnObject and invalidateObject in one borrow cycle.
+  * an object that fails to fails activation, validation, passivation, or is passed to invalidateObject
must be destroyed. Much like the finalize method isn't guarenteed to be called in a deterministic
manner, neither is when the call to destroyObject is to be made strictly specified. For example
a pool could queue objects to be destroyed with a java.util.Timer to help improve the perceived
performance of the pool.
  === Pool 3 ===
  This may break API compatibility for implementations of pools but shouldn't affect client
code using pools. Mostly the exceptions declared in the interfaces that is no longer needed
because of behavior changes in Pool 2 will be removed. This release probably will take advantage
of Java 5 (aka: 1.5) features.
+ Probable changes:
+  * Generification
+  * JMX monitoring: to be able to answer questions like: how many DB connects are currently
in use?
+  * java.util.concurrent: improved parallelism
  == Performant Implementations ==

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message