PoolObjectFactory


1   /*
2    * Licensed under the X license (see http://www.x.org/terms.htm)
3    */
4   package org.ofbiz.minerva.pool;
5   
6   /**
7    * Creates objects to be used in an object pool.  This is a class instead of
8    * an interface so you can ignore any of the methods you don't need.
9    *
10   * @author Aaron Mulder (ammulder@alumni.princeton.edu)
11   */
12  public abstract class PoolObjectFactory {
13  
14      /**
15       * Creates a new object to be stored in an object pool.  This is the
16       * instance that will actually be sotred in the pool and reused.  If you
17       * want to wrap it somehow, or return instances of a different type that
18       * refers to these, you can implement prepareObject.
19       * @see #prepareObject
20       * @param parameters Any parameters specified for creating the object.
21       *        This will frequently be null, so the factory must have some
22       *        reasonable default.  If the factory does not use parameters
23       *        to create objects, feel free to ignore this.
24       */
25      public abstract Object   createObject(Object   parameters) throws Exception  ;
26  
27      /**
28       * Tells whether a pooled object matches the specified parameters.
29       * This is only called if the client requested an object with
30       * specific parameters.  Usually all objects are "the same" so this
31       * is not necessary.
32       */
33      public boolean checkValidObject(Object   source, Object   parameters) {
34          return true;
35      }
36  
37      /**
38       * Indicates to the factory that the pool has started up.  This will be
39       * called before any other methods of the factory are called (on behalf of
40       * this pool).
41       * @param pool The pool that is starting.  You may decide to allow
42       *    multiple pools you use your factory, or to restrict it to a one-to-one
43       *    relationship.
44       * @throws java.lang.IllegalArgumentException
45       *         Occurs when the pool is null.
46       */
47      public void poolStarted(ObjectPool pool) {
48          if (pool == null)
49              throw new IllegalArgumentException  ("Cannot start factory with null pool!");
50      }
51  
52      /**
53       * Prepares an object to be returned to the client.  This may be used to
54       * configure the object somehow, or actually return a completely different
55       * object (so long as the original can be recovered in translateObject or
56       * returnObject).  This will be called whenever an object is returned to
57       * the client, whether a new object or a previously pooled object.
58       * @param pooledObject The object in the pool, as created by createObject.
59       * @return The object to return to the client.  If different, the pooled
60       *    object must be recoverable by translateObject and returnObject.
61       */
62      public Object   prepareObject(Object   pooledObject) {
63          return pooledObject;
64      }
65  
66      /**
67       * If the objects supplied to the client are different than the objects in
68       * the pool, extracts a pool object from a client object.  This should only
69       * be called between prepareObject and returnObject for any given pool
70       * object (and associated client object).  However, it may be called once
71       * after an object has been released if the garbage collector and a client
72       * attempt to release an object at the same time.  In this case, this
73       * method may work, return null, or throw an exception and the pool will
74       * handle it gracefully.  The default implementation returns the parameter
75       * object (assumes client and pooled objects are the same).
76       * @param clientObject The client object, as returned by prepareObject
77       * @return The pooled object, as originally returned by createObject
78       */
79      public Object   translateObject(Object   clientObject) {
80          return clientObject;
81      }
82  
83      /**
84       * Prepares an object to be returned to the pool.  Any cleanup or reset
85       * actions should be performed here.  This also has the same effect as
86       * translateObject (only relevant if the pooled objects are different than
87       * the objects supplied to the client).
88       * @param clientObject The client object, as returned by prepareObject
89       * @return The pooled object, as originally returned by createObject, ready
90       *     to be put back in the pool and reused.
91       */
92      public Object   returnObject(Object   clientObject) {
93          return clientObject;
94      }
95  
96      /**
97       * Indicates to the factory that the pool is closing down.  This will be
98       * called before all the instances are destroyed.  There may be calls to
99       * returnObject or translateObject after this, but no calls to
100      * createObject or prepareObject (on behalf of this pool).
101      * @param pool The pool that is closing.  You may decide to allow
102      *    multiple pools you use your factory, or to restrict it to a one-to-one
103      *    relationship.
104      * @throws java.lang.IllegalArgumentException
105      *         Occurs when the pool is null.
106      */
107     public void poolClosing(ObjectPool pool) {
108         if (pool == null)
109             throw new IllegalArgumentException  ("Cannot close factory with a null pool!");
110     }
111 
112     /**
113      * Permanently closes an object, after it is removed from the pool.  The
114      * object will not be returned to the pool - after this, it is gone.  This
115      * is called when the pool shrinks, and when the pool is shut down.
116      */
117     public void deleteObject(Object   pooledObject) {
118     }
119 
120     /**
121      * Decides whether a request for an object should be fulfilled by an
122      * object checked out of the pool previously, or a new object.  In general,
123      * every request should generate a new object, so this should return null.
124      * @return An existing object, if this request is effectively the same as
125      *         a previous request and the result should be shared.  <B>null</B>
126      *         if this is a unique request and should be fulfilled by a unique
127      *         object.
128      */
129     public Object   isUniqueRequest() {
130         return null;
131     }
132 }
133
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags