public interface CacheableAhead {
/**
* Resets the object to the "initial" state. That is the state the object
* was in right after it was created (via <code>new</code>).
*/
void activate();
 
/**
* Prepares the object to be returned to the pool. Needs to free up any
* resources at any point. Similar to {@link #destroy()} but potentially
* less "destructive".
*/
void passivate();
 
/**
* "Destroys" the object. That is, frees up any resources that the object is
* taking and prepares it to be released into the great void of garbage
* collection :D
*/
void destroy();
 
/**
* Used by the caches/pools to verify whether this object is valid to be
* re-pooled or it needs to be destroyed and chucked away.
*
* @return true if the object is valid and can be returned to the pool
*         (passivated first) or false if this object needs to be thrown
*         away (after it's been destroyed)
*/
boolean isValid();
}

/**
* Factory class which delegates all the methods to {@link CacheableAhead} for
* creating instances of classes.
*
* @author Liviu Tudor http://about.me/liviutudor
* @param <V>
*            Type of class it operates on.
*/
public class CreateInstanceFactory<V extends CacheableAhead> implements KeyedPoolableObjectFactory<Class<V>, V> {
@Override
public V makeObject(Class<V> key) throws InstantiationException, IllegalAccessException {
return key.newInstance();
}
 
@Override
public void destroyObject(Class<V> key, V obj) throws Exception {
obj.destroy();
}
 
@Override
public boolean validateObject(Class<V> key, V obj) {
return obj.isValid();
}
 
@Override
public void activateObject(Class<V> key, V obj) throws Exception {
obj.activate();
}
 
@Override
public void passivateObject(Class<V> key, V obj) throws Exception {
obj.passivate();
}
}

/**
* This is a type of cache which creates ahead a certain number of instances for
* a given key in order to prevent creation on demand and also has a background
* thread which ensure there are at least a certain number of pre-created items
* in the pool when it runs (and creates more as necessary). Since we don't know
* upfront the keys to this pool, the pool will start empty, however, once an
* object is requested for a certain key, soon after, the background thread will
* kick in and pre-populate the pool for that key. Users can also force
* pre-population by calling <code>preparePool(key,true)</code>.
*
* @param T
*            Object type produced (and pooled) by this cache/pool
* @author Liviu Tudor http://about.me/liviutudor
*/
public class CreateInstanceAheadCache<T extends CacheableAhead> extends GenericKeyedObjectPool<Class<T>, T> {
/** Debug logging. */
private static final Logger      LOG = LoggerFactory.getLogger(CreateInstanceAheadCache.class);
/**
* This is the background thread which is responsible for creating instances
* when needed.
*/
private ScheduledExecutorService backgroundTask;
 
/**
* Stores all the keys that were requested via <code>borrowObject</code>,
* <code>preparePool</code>, <code>clear(key)</code>. This is being
* traversed in {@link #prepopulate()} to prepopulate the pool.
*/
private Set<Class<T>>            keys;
 
/**
* Creates a cache which will use the given factory to create new instances
* and will maintain a certain number of idle instances in the cache. It
* also initiates a background thread which will "wake up" regularly and
* ensure there are at least certain number of instances for each key in the
* pool.
*
* @param factory
*            Factory used to create new instances in the pool
* @param minIdle
*            Minimum instances to create in the pool for a key
* @param wakeUpInterval
*            Interval in miliseconds for the background thread to wakeup
*            and perform creation of additional instances if needed
*/
public CreateInstanceAheadCache(KeyedPoolableObjectFactory<Class<T>, T> factory, int minIdle,
long wakeUpInterval) {
super(factory);
LOG.debug("Creating cache ahead with minIdle={}, wakeUpInterval={}", minIdle, wakeUpInterval);
if (minIdle <= 0) {
throw new IllegalArgumentException("minIdle (" + minIdle + ") cannot be <= 0 !");
}
setMinIdle(minIdle);
if (wakeUpInterval <= 0) {
throw new IllegalArgumentException("wakeUpInterval (" + wakeUpInterval + ") cannot be <= 0 !");
}
this.keys = Collections.synchronizedSet(new HashSet<Class<T>>());
LOG.debug("Created keySet {}", this.keys);
 
LOG.debug("Parameters correct, creating background thread");
backgroundTask = Executors.newSingleThreadScheduledExecutor();
LOG.debug("Schedulling background thread");
backgroundTask.scheduleAtFixedRate(new Runnable() {
@Override
public void run() {
LOG.debug("Running prepopulate on timer");
prepopulate();
}
}, wakeUpInterval, wakeUpInterval, TimeUnit.MILLISECONDS);
LOG.debug("Cache ahead created.");
}
 
@Override
public final void close() throws Exception {
LOG.debug("Closing parent cache");
super.close();
LOG.debug("Emptying key set");
keys.clear();
LOG.debug("Shutting down thread");
backgroundTask.shutdownNow();
LOG.debug("Calling close hook");
closeHook();
LOG.debug("Cache closed");
}
 
/**
* Used as a "hook" for subclasses to get notifications when this cache is
* being closed. Called by {@link #close()} right at the end.
*
* @throws Exception
*             if any errors occur during releasing resources etc.
*/
protected void closeHook() throws Exception {
}
 
@Override
public final T borrowObject(Class<T> key) throws Exception {
LOG.debug("Borrowing object for {}", key);
if (!keys.contains(key)) {
keys.add(key);
}
LOG.debug("Set of keys so far {}", keys);
borrowObjectHook(key);
LOG.debug("Called borrowObjectHook, now forwarding call to superclass");
return super.borrowObject(key);
}
 
/**
* Used by {@link #borrowObject(Class)} as a "hook" to notify subclasses of
* the call received.
*
* @param key
*            Key that was just used in the call to
*            {@link #borrowObject(Class)}.
* @throws Exception
*             Thrown to prevent the call to
*             <code>super.borrowObject(key)</code> from completing.
*/
protected void borrowObjectHook(Class<T> key) throws Exception {
}
 
@Override
public final void clear(Class<T> key) {
LOG.debug("Clearing key {}", key);
keys.remove(key);
LOG.debug("Set of keys so far {}", keys);
clearHook(key);
LOG.debug("Called clearHook, now forwarding call to superclass");
super.clear(key);
}
 
/**
* Used by {@link #clear(Class)} as a "hook" to notify subclasses of the
* call received.
*
* @param key
*            Key received in the call to {@link #clear(Class)} for which
*            we're clearing the cache
*/
protected void clearHook(Class<T> key) {
}
 
@Override
public final void clear() {
LOG.debug("Clearing whole cache.");
keys.clear();
LOG.debug("Set of keys after clear: {}", keys);
clearHook();
LOG.debug("Called clearHook(void), now forwarding call to superclass");
super.clear();
}
 
/**
* Used by {@link #clear()} as a "hook" to notify subclasses of the calls
* received.
*/
protected void clearHook() {
}
 
@Override
public final synchronized void preparePool(Class<T> key, boolean populateImmediately) {
if (!keys.contains(key)) {
keys.add(key);
}
super.preparePool(key, populateImmediately);
}
 
/**
* Used internally to go through all the keys in the cache and
*/
protected final void prepopulate() {
LOG.debug("Running prepopulate");
for (Class<T> t : keys) {
LOG.debug("Prepopulating {}", t);
prepopulateHook(t);
LOG.debug("Called hook, prepopulating");
preparePool(t, true);
}
LOG.debug("Finished prepopulating");
}
 
/**
* Used as a hook when {@link #prepopulate()} kicks in, for each key, it
* will call this function and pass in this key prior to creating the
* required number of instances.
*
* @param key
*            Key for which we are about to prepopulate the cache.
*/
protected void prepopulateHook(Class<T> key) {
}
}