001: /*
002: * Licensed under the X license (see http://www.x.org/terms.htm)
003: */
004: package org.ofbiz.minerva.pool;
005:
006: /**
007: * Creates objects to be used in an object pool. This is a class instead of
008: * an interface so you can ignore any of the methods you don't need.
009: *
010: * @author Aaron Mulder (ammulder@alumni.princeton.edu)
011: */
012: public abstract class PoolObjectFactory {
013:
014: /**
015: * Creates a new object to be stored in an object pool. This is the
016: * instance that will actually be sotred in the pool and reused. If you
017: * want to wrap it somehow, or return instances of a different type that
018: * refers to these, you can implement prepareObject.
019: * @see #prepareObject
020: * @param parameters Any parameters specified for creating the object.
021: * This will frequently be null, so the factory must have some
022: * reasonable default. If the factory does not use parameters
023: * to create objects, feel free to ignore this.
024: */
025: public abstract Object createObject(Object parameters)
026: throws Exception;
027:
028: /**
029: * Tells whether a pooled object matches the specified parameters.
030: * This is only called if the client requested an object with
031: * specific parameters. Usually all objects are "the same" so this
032: * is not necessary.
033: */
034: public boolean checkValidObject(Object source, Object parameters) {
035: return true;
036: }
037:
038: /**
039: * Indicates to the factory that the pool has started up. This will be
040: * called before any other methods of the factory are called (on behalf of
041: * this pool).
042: * @param pool The pool that is starting. You may decide to allow
043: * multiple pools you use your factory, or to restrict it to a one-to-one
044: * relationship.
045: * @throws java.lang.IllegalArgumentException
046: * Occurs when the pool is null.
047: */
048: public void poolStarted(ObjectPool pool) {
049: if (pool == null)
050: throw new IllegalArgumentException(
051: "Cannot start factory with null pool!");
052: }
053:
054: /**
055: * Prepares an object to be returned to the client. This may be used to
056: * configure the object somehow, or actually return a completely different
057: * object (so long as the original can be recovered in translateObject or
058: * returnObject). This will be called whenever an object is returned to
059: * the client, whether a new object or a previously pooled object.
060: * @param pooledObject The object in the pool, as created by createObject.
061: * @return The object to return to the client. If different, the pooled
062: * object must be recoverable by translateObject and returnObject.
063: */
064: public Object prepareObject(Object pooledObject) {
065: return pooledObject;
066: }
067:
068: /**
069: * If the objects supplied to the client are different than the objects in
070: * the pool, extracts a pool object from a client object. This should only
071: * be called between prepareObject and returnObject for any given pool
072: * object (and associated client object). However, it may be called once
073: * after an object has been released if the garbage collector and a client
074: * attempt to release an object at the same time. In this case, this
075: * method may work, return null, or throw an exception and the pool will
076: * handle it gracefully. The default implementation returns the parameter
077: * object (assumes client and pooled objects are the same).
078: * @param clientObject The client object, as returned by prepareObject
079: * @return The pooled object, as originally returned by createObject
080: */
081: public Object translateObject(Object clientObject) {
082: return clientObject;
083: }
084:
085: /**
086: * Prepares an object to be returned to the pool. Any cleanup or reset
087: * actions should be performed here. This also has the same effect as
088: * translateObject (only relevant if the pooled objects are different than
089: * the objects supplied to the client).
090: * @param clientObject The client object, as returned by prepareObject
091: * @return The pooled object, as originally returned by createObject, ready
092: * to be put back in the pool and reused.
093: */
094: public Object returnObject(Object clientObject) {
095: return clientObject;
096: }
097:
098: /**
099: * Indicates to the factory that the pool is closing down. This will be
100: * called before all the instances are destroyed. There may be calls to
101: * returnObject or translateObject after this, but no calls to
102: * createObject or prepareObject (on behalf of this pool).
103: * @param pool The pool that is closing. You may decide to allow
104: * multiple pools you use your factory, or to restrict it to a one-to-one
105: * relationship.
106: * @throws java.lang.IllegalArgumentException
107: * Occurs when the pool is null.
108: */
109: public void poolClosing(ObjectPool pool) {
110: if (pool == null)
111: throw new IllegalArgumentException(
112: "Cannot close factory with a null pool!");
113: }
114:
115: /**
116: * Permanently closes an object, after it is removed from the pool. The
117: * object will not be returned to the pool - after this, it is gone. This
118: * is called when the pool shrinks, and when the pool is shut down.
119: */
120: public void deleteObject(Object pooledObject) {
121: }
122:
123: /**
124: * Decides whether a request for an object should be fulfilled by an
125: * object checked out of the pool previously, or a new object. In general,
126: * every request should generate a new object, so this should return null.
127: * @return An existing object, if this request is effectively the same as
128: * a previous request and the result should be shared. <B>null</B>
129: * if this is a unique request and should be fulfilled by a unique
130: * object.
131: */
132: public Object isUniqueRequest() {
133: return null;
134: }
135: }
|