KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > ofbiz > minerva > pool > 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 JavaDoc createObject(Object JavaDoc parameters) throws Exception JavaDoc;
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 JavaDoc source, Object JavaDoc 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 JavaDoc("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 JavaDoc prepareObject(Object JavaDoc 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 JavaDoc translateObject(Object JavaDoc 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 JavaDoc returnObject(Object JavaDoc 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 JavaDoc("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 JavaDoc 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 JavaDoc isUniqueRequest() {
130         return null;
131     }
132 }
133
Popular Tags