/**
 * Defines a generic DAO interface.
 * 
 * @author javier
 * 
 * @param <T>
 *            The type this DAO handles.
 * @param <ID>
 *            The type of the id of the handled entity.
 */
public interface DAOInterface<T, ID extends Serializable>
{

    /**
     * Makes the given entity persistent.
     *
     * @param entity The entity to persist.
     * @throws When the quota of instances for that entity was exceeded.
     */
    void makePersistent(T entity) throws QuotaExceededException;

    /**
     * Makes the given entity transient.
     *
     * @param entity The entity to make transient.
     */
    void makeTransient(T entity);

    /**
     * @return the number of matching entities.
     */
    int count(Filter filter);

    /**
     * Returns a single entity which has the given ID or throws an
     * <code>EntityNotFoundException</code> if no matching entity is found.
     * 
     * @param id
     *            The ID of the entity to return.
     * @return The entity.
     */
    T findById(ID id) throws EntityNotFoundException;

    /**
     * Returns all matching entities of type <code>T</code>.
     * 
     * @param filter
     *            The <code>Filter</code> to use.
     *
     * @return An ordered <code>List</code> with the entities.
     */
    List<T> find(Filter filter);

    /**
     * Returns all entities of type <code>T</code>.
     * 
     * @return An ordered <code>List</code> with the entities.
     */
    List<T> findAll();

    /**
     * Returns a page of entities.
     * 
     * @param filter
     *            The <code>Filter</code> to use.
     * @param startRow
     *            The offset.
     * @param pageSize
     *            The number of entities to return.
     *
     * @return A <code>Pair</code> of values. The first value is the
     *         <code>List</code> of entities and the second one if the total
     *         number of existing entities.
     */
    Pair<List<T>, Integer> findPaged(Filter filter, int startRow, int pageSize);

    /**
     * Flushing is the process of synchronising the underlying persistent
     * store with persistable state held in memory. 
     */
    void flush();
}