001: /*
002: * Licensed under the X license (see http://www.x.org/terms.htm)
003: */
004: package org.ofbiz.minerva.pool.cache;
005:
006: import java.io.PrintWriter;
007:
008: /**
009: * Creates objects for a cache. The cache is essentially a map,
010: * so this factory is given a "key" and creates the appropriate "value"
011: * which will be cached. There are a number of other functions that
012: * can be overridden for more specific control, but createObject is
013: * the only one that's required.
014: *
015: * @author Aaron Mulder ammulder@alumni.princeton.edu
016: */
017: public abstract class CachedObjectFactory {
018:
019: public CachedObjectFactory() {
020: }
021:
022: /**
023: * Creates a new object to be stored in an object cache. This is the
024: * instance that will actually be stored in the cache and reused. If you
025: * want to wrap it somehow, or return instances of a different type that
026: * refers to these, you can implement prepareObject.
027: * @see #prepareObject
028: */
029: public abstract Object createObject(Object identifier);
030:
031: /*
032: * Indicates to the factory that the cache has started up. This will be
033: * called before any other methods of the factory are called (on behalf of
034: * this cache).
035: * @param cache The cache that is starting. You may decide to allow
036: * multiple cached you use your factory, or to restrict it to a one-to-one
037: * relationship.
038: * @param log A writer you can use to log messages. Use this in preference
039: * to System.xxx.println.
040: * @throws java.lang.IllegalArgumentException
041: * Occurs when the cache is null.
042: */
043: public void cacheStarted(ObjectCache cache, PrintWriter log) {
044: if (cache == null)
045: throw new IllegalArgumentException(
046: "Cannot start factory with null cache!");
047: }
048:
049: /**
050: * Prepares an object to be returned to the client. This may be used to
051: * configure the object somehow, or actually return a completely different
052: * object (so long as the original can be recovered in translateObject.
053: * This will be called whenever an object is returned to the client, whether
054: * a new object or a cached object.
055: * @param cachedObject The object in the cache, as created by createObject.
056: * @return The object to return to the client. If different, the cached
057: * object must be recoverable by translateObject.
058: */
059: public Object prepareObject(Object cachedObject) {
060: return cachedObject;
061: }
062:
063: /**
064: * If the objects supplied to the client are different than the objects in
065: * the cache, extracts a cache object from a client object. This may be
066: * called once after an object has been released if the garbage collector
067: * and a client attempt to release an object at the same time. In this
068: * case, this method may work, return null, or throw an exception and the
069: * cache will handle it gracefully. The default implementation returns the
070: * parameter object (assumes client and cached objects are the same).
071: * @param clientObject The client object, as returned by prepareObject
072: * @return The cached object, as originally returned by createObject
073: */
074: public Object translateObject(Object clientObject) {
075: return clientObject;
076: }
077:
078: /**
079: * Indicates to the factory that the cache is closing down. This will be
080: * called before all the instances are destroyed. There may be calls to
081: * returnObject or translateObject after this, but no calls to
082: * createObject or prepareObject (on behalf of this cache).
083: * @param cache The cache that is closing. You may decide to allow
084: * multiple caches you use your factory, or to restrict it to a one-to-one
085: * relationship.
086: * @throws java.lang.IllegalArgumentException
087: * Occurs when the pool is null.
088: */
089: public void cacheClosing(ObjectCache cache) {
090: if (cache == null)
091: throw new IllegalArgumentException(
092: "Cannot close factory with a null cache!");
093: }
094:
095: /**
096: * Permanently closes an object, after it is removed from the cache. The
097: * object will not be returned to the cache - after this, it is gone. This
098: * is called when the cache is full and new objects are added, and when
099: * the cache is closed.
100: */
101: public void deleteObject(Object pooledObject) {
102: }
103: }
|