1b5840353SAdam Hornáček /* 2b5840353SAdam Hornáček * The contents of this file are Copyright (c) 2012, Swaranga Sarma, DZone MVB 3b5840353SAdam Hornáček * made available under free license, 4b5840353SAdam Hornáček * http://javawithswaranga.blogspot.com/2011/10/generic-and-concurrent-object-pool.html 5b5840353SAdam Hornáček * https://dzone.com/articles/generic-and-concurrent-object : "Feel free to use 6b5840353SAdam Hornáček * it, change it, add more implementations. Happy coding!" 7b5840353SAdam Hornáček * Copyright (c) 2017, Chris Fraire <cfraire@me.com>. 8b5840353SAdam Hornáček */ 9b5840353SAdam Hornáček 10*9805b761SAdam Hornáček package org.opengrok.indexer.util; 11b5840353SAdam Hornáček 12b5840353SAdam Hornáček /** 13b5840353SAdam Hornáček * Represents an API for a cached pool of objects. 14b5840353SAdam Hornáček * @author Swaranga 15b5840353SAdam Hornáček * @param <T> the type of object to pool. 16b5840353SAdam Hornáček */ 17b5840353SAdam Hornáček public interface ObjectPool<T> { 18b5840353SAdam Hornáček 19b5840353SAdam Hornáček /** 20b5840353SAdam Hornáček * Gets an instance from the pool. 21b5840353SAdam Hornáček * The call may be a blocking one or a non-blocking one 22b5840353SAdam Hornáček * and that is determined by the implementation. 23b5840353SAdam Hornáček * <p> 24b5840353SAdam Hornáček * If the call is a blocking call, 25b5840353SAdam Hornáček * the call returns immediately with a valid object 26b5840353SAdam Hornáček * if available, else the thread is made to wait 27b5840353SAdam Hornáček * until an object becomes available. 28b5840353SAdam Hornáček * In case of a blocking call, 29b5840353SAdam Hornáček * it is advised that clients react 30b5840353SAdam Hornáček * to {@link InterruptedException} which might be thrown 31b5840353SAdam Hornáček * when the thread waits for an object to become available. 32b5840353SAdam Hornáček * <p> 33b5840353SAdam Hornáček * If the call is a non-blocking one, 34b5840353SAdam Hornáček * the call returns immediately irrespective of 35b5840353SAdam Hornáček * whether an object is available or not. 36b5840353SAdam Hornáček * If any object is available the call returns it 37b5840353SAdam Hornáček * else the call returns <code>null</code>. 38b5840353SAdam Hornáček * <p> 39b5840353SAdam Hornáček * The validity of the objects are determined using the 40b5840353SAdam Hornáček * {@link ObjectValidator} interface, such that 41b5840353SAdam Hornáček * an object <code>o</code> is valid if 42b5840353SAdam Hornáček * <code> ObjectValidator.isValid(o) == true </code>. 43b5840353SAdam Hornáček * @return T one of the pooled objects. 44b5840353SAdam Hornáček */ get()45b5840353SAdam Hornáček T get(); 46b5840353SAdam Hornáček 47b5840353SAdam Hornáček /** 48b5840353SAdam Hornáček * Releases the object and puts it back to the pool. 49b5840353SAdam Hornáček * The mechanism of putting the object back to the pool is 50b5840353SAdam Hornáček * generally asynchronous, 51b5840353SAdam Hornáček * however future implementations might differ. 52b5840353SAdam Hornáček * @param t the object to return to the pool 53b5840353SAdam Hornáček */ release(T t)54b5840353SAdam Hornáček void release(T t); 55b5840353SAdam Hornáček 56b5840353SAdam Hornáček /** 57b5840353SAdam Hornáček * Shuts down the pool. In essence this call will not 58b5840353SAdam Hornáček * accept any more requests 59b5840353SAdam Hornáček * and will release all resources. 60b5840353SAdam Hornáček * Releasing resources are done 61b5840353SAdam Hornáček * via the {@link ObjectValidator#invalidate(java.lang.Object)} 62b5840353SAdam Hornáček * method. 63b5840353SAdam Hornáček */ shutdown()64b5840353SAdam Hornáček void shutdown(); 65b5840353SAdam Hornáček } 66