package com.gamepatriot.androidframework.framework;

import java.util.Collection;

/**
 * An AndroidPool implementation should allow the storage and retrieval of an object to avoid re-instantiation.
 * 
 * @author Pete Schmitz, May 9, 2013
 *
 * @param <T>		The typecast of the objects to be pooled.
 */
public interface AndroidPool<T> {
	
	/** 
	 * Get an object of the casted type associated with this pool. If an old one doesn't exist in the pool a new object of that type will be instantiated.
	 * @return		A usable object of the pool's specificed typecast. Should never be null.
	 */
	public T get();
	
	/**
	 * Store an object of the typecasted class associated with this pool. A limit should be enforced to prevent unnecessary pool sizes.
	 * @param $t	A non-null and instantiated object of the typecast associated with this pool. It will be stored until it's returned by a {@link #get()} call.
	 * @return		Whether or not this object was added to the pool (Limit was hit or add request was null).
	 */
	public boolean add(T $t);
	
	/**
	 * Release the objects referenced in this pool and empty the pool.
	 * @return		The collection of objects that were contained in this pool.
	 */
	public Collection<T> release();
	
	/**
	 * Return the number of objects in this pool.
	 */
	public int size();
	
}
