package org.jlego.core.dao;

import java.util.List;

import javax.persistence.Query;

/**
 * Base interface for all DAO classes <br/>
 * Example:
 *
 * <code><br/>
 * public class AnotherDao extends BaseDaoImpl <Long, User> implements BaseDao {<br/>
 *        <br/>
 * }<br/>
 * </code>
 *
 * @author Ali Irawan
 * @version 1.0
 * @param <K>
 *            key type
 * @param <E>
 *            value/entity type
 */
public interface BaseDao<K, E> {

    /**
     * insert data to persistence
     *
     * @param entity
     *            object to be inserted
     * @throws CoreException
     */

    public void persist(E entity);

    /**
     * update data to persistence
     *
     * @param entity
     *            object to be updated
     * @throws CoreException
     */

    public E merge(K id, E entity);

    /**
     * delete data from persistence
     *
     * @param id
     *            primary key that uniquely identify the object to be deleted
     * @throws CoreException
     */

    public void remove(K id);

    /**
     * Search data from persistence using specified ID
     *
     * @param id
     *            primary key that uniquely identify the object
     * @return return the object defined by Key, if no data match the method
     *         returns null
     */
    public E findByPk(K id);

    /**
     * Query data with specified criteria
     *
     * @return list of data with specific entity type
     */

    public E find(Criteria criteria);

    /**
     * Query all data and return in a List
     *
     * @return list of data with specific entity type
     */

    public List<E> findAll();

    /**
     * Query data with specified criteria and return in a List
     *
     * @return list of data with specific entity type
     */
    public List<E> findAll(Criteria criteria);

    /**
     * Return number of data in table
     * @return count value
     */
    public long count();

    /**
     * Create a query with JPQL language
     * @param query JPQL language
     * @return an instance of javax.persistence.Query
     */
    public Query createQuery(String query);

    /**
     * Create a query with named query
     * @param queryName name of named query (JPQL)
     * @return an instance of javax.persistence.Query
     */
    public Query createNamedQuery(String queryName);

    /**
     * Create a query with using native SQL language. This is database specific. Using it will reduce portability between databases
     * @param sqlString SQL native language based on the database used
     * @return an instance of javax.persistence.Query
     */
    public Query createNativeQuery(String sqlString);

    /**
     * Flush cache
     *
     */
    public void flush();

}