CVS: Tapestry/framework/src/net/sf/tapestry/util/pool Pool.java,1.7.2.2,1.7.2.3

Update of /cvsroot/tapestry/Tapestry/framework/src/net/sf/tapestry/util/pool
In directory sc8-pr-cvs1:/tmp/cvs-serv4609/framework/src/net/sf/tapestry/util/pool

Modified Files:
      Tag: hship-2-3
	Pool.java 
Log Message:
Add warnings to Pool about misuse.

Index: Pool.java
===================================================================
RCS file: /cvsroot/tapestry/Tapestry/framework/src/net/sf/tapestry/util/pool/Pool.java,v
retrieving revision 1.7.2.2
retrieving revision 1.7.2.3
diff -C2 -d -r1.7.2.2 -r1.7.2.3
*** Pool.java	3 Jan 2003 20:54:18 -0000	1.7.2.2
--- Pool.java	4 Jan 2003 19:31:13 -0000	1.7.2.3
***************
*** 21,25 ****
   *  keys, much like a {@link Map}, to identify a list of pooled objects.
   *  Retrieving an object from the Pool atomically removes it from the
!  *  pool.  It can then be stored again later.
   *
   *  <p>The implementation of Pool is threadsafe.
--- 21,33 ----
   *  keys, much like a {@link Map}, to identify a list of pooled objects.
   *  Retrieving an object from the Pool atomically removes it from the
!  *  pool.  It can then be stored again later.  In this way, a single
!  *  Pool instance can manage many different types of pooled objects,
!  *  filed under different keys.
!  * 
!  *  <p>
!  *  Unlike traditional Pools, this class does not create new instances of
!  *  the objects it stores (with the exception of simple Java Beans,
!  *  via {@link #retrieve(Class)}.  The usage pattern is to retrieve an instance
!  *  from the Pool, and if the instance is null, create a new instance.
   *
   *  <p>The implementation of Pool is threadsafe.
***************
*** 29,33 ****
   *  a recent time frame.  A generational system is used, where each
   *  pooled object is assigned a generation count.  {@link #executeCleanup}
!  *  culls objects whose generation count is too old (outside of a
   *  {@link #getWindow() window}).
   * 
--- 37,41 ----
   *  a recent time frame.  A generational system is used, where each
   *  pooled object is assigned a generation count.  {@link #executeCleanup}
!  *  discards objects whose generation count is too old (outside of a
   *  {@link #getWindow() window}).
   * 
***************
*** 35,39 ****
   *  Objects in the pool can receive two notifications: one notification
   *  when they are {@link #store(Object, Object) stored} into the pool,
!  *  and one when they are discarded form the pool.
   * 
   *  <p>
--- 43,47 ----
   *  Objects in the pool can receive two notifications: one notification
   *  when they are {@link #store(Object, Object) stored} into the pool,
!  *  and one when they are discarded from the pool.
   * 
   *  <p>
***************
*** 45,50 ****
   *  Alternately, an adaptor for the other classes can be
   *  registerered (using {@link #registerAdaptor(Class, IPoolableAdaptor)}.
!  *  The adaptor will be invoked to perform the desred cleanup
!  *  of the object instead.
   *
   *  @author Howard Lewis Ship
--- 53,58 ----
   *  Alternately, an adaptor for the other classes can be
   *  registerered (using {@link #registerAdaptor(Class, IPoolableAdaptor)}.
!  *  The adaptor will be invoked to handle the notification when a 
!  *  pooled object is stored or discarded.
   *
   *  @author Howard Lewis Ship
***************
*** 104,107 ****
--- 112,117 ----
       *  Creates a new Pool using the specified map size.  The map is created immediately.
       *
+      *  @deprecated Use {@link #Pool()} instead.
+      * 
       **/
  
***************
*** 135,138 ****
--- 145,150 ----
       *
       *  @since 1.0.5
+      *  @deprecated Use {@link #Pool(boolean) instead.
+      * 
       **/
  
***************
*** 184,188 ****
      public synchronized Object retrieve(Object key)
      {
-         PoolList list;
          Object result = null;
  
--- 196,199 ----
***************
*** 190,194 ****
              _map = new HashMap();
  
!         list = (PoolList) _map.get(key);
  
          if (list != null)
--- 201,205 ----
              _map = new HashMap();
  
!         PoolList list = (PoolList) _map.get(key);
  
          if (list != null)
***************
*** 209,212 ****
--- 220,233 ----
       *  (using the no arguments constructor).  Objects are
       *  pooled using their actual class as a key.
+      * 
+      *  <p>
+      *  However, don't be fooled by false economies.  Unless
+      *  an object is very expensive to create, pooling is 
+      *  <em>more</em> expensive than simply instantiating temporary
+      *  instances and letting the garbage collector deal with it
+      *  (this is counter intuitive, but true).  For example,
+      *  this method was originally created to allow pooling
+      *  of {@link StringBuffer}, but testing showed that it
+      *  was a net defecit.
       * 
       **/



-------------------------------------------------------
This sf.net email is sponsored by:ThinkGeek
Welcome to geek heaven.
http://thinkgeek.com/sf