// This Source Code is in the Public Domain per: http://litesoft.org/License.txt
package org.litesoft.orsup.base;

import org.litesoft.db.*;
import org.litesoft.logger.*;
import org.litesoft.orsup.selection.*;

public interface NonTransactionalFinder<FT extends NonTransactionalFinder> extends Finder
{
    public static final Logger LOGGER = LoggerFactory.getLogger( NonTransactionalFinder.class );

    FT includeImmortalInactives();

    FT excludeImmortalInactives();

    /**
     * @param pPersistedObjectRegistrationName
     *                              - Persisted Object Class Name (getClass().getName())
     * @param pSelectionWhereClause - null means all
     * @param pOrderBy              - null means order immaterial
     *
     * @return An Iterator (!Null) that will manage the underlying ResultSet (& DBConnection) creating PO Keys as it goes
     *
     * @throws IllegalStateException         - if the underlying 'set' POQueryFilter is not an POKeyQueryFilter
     * @throws UnsupportedOperationException - if the PO type does not have a "single" key
     * @throws DBException                   - other Exception regarding the OR layer
     */
    public POKeyIterator findAllKeysCursored( String pPersistedObjectRegistrationName, WhereClause pSelectionWhereClause, OrderBy pOrderBy )
            throws IllegalStateException, UnsupportedOperationException, DBException;

    /**
     * @param pPersistedObjectClass - Persisted Object Class (getClass())
     * @param pSelectionWhereClause - null means all
     * @param pOrderBy              - null means order immaterial
     *
     * @return An Iterator (!Null) that will manage the underlying ResultSet (& DBConnection) creating PO Keys as it goes
     *
     * @throws IllegalStateException         - if the underlying 'set' POQueryFilter is not an POKeyQueryFilter
     * @throws UnsupportedOperationException - if the PO type does not have a "single" key
     * @throws DBException                   - other Exception regarding the OR layer
     */
    public POKeyIterator findAllKeysCursored( Class<? extends PersistentObject> pPersistedObjectClass, WhereClause pSelectionWhereClause, OrderBy pOrderBy )
            throws IllegalStateException, UnsupportedOperationException, DBException;

    /**
     * @param pPersistedObjectRegistrationName
     *                              - Persisted Object Class Name (getClass().getName())
     * @param pSelectionWhereClause - null means all
     *
     * @return An Iterator (!Null) that will manage the underlying ResultSet (& DBConnection) creating PO Keys as it goes
     *
     * @throws IllegalStateException         - if the underlying 'set' POQueryFilter is not an POKeyQueryFilter
     * @throws UnsupportedOperationException - if the PO type does not have a "single" key
     * @throws DBException                   - other Exception regarding the OR layer
     */
    public POKeyIterator findAllKeysCursored( String pPersistedObjectRegistrationName, WhereClause pSelectionWhereClause )
            throws IllegalStateException, UnsupportedOperationException, DBException;

    /**
     * @param pPersistedObjectClass - Persisted Object Class (getClass())
     * @param pSelectionWhereClause - null means all
     *
     * @return An Iterator (!Null) that will manage the underlying ResultSet (& DBConnection) creating PO Keys as it goes
     *
     * @throws IllegalStateException         - if the underlying 'set' POQueryFilter is not an POKeyQueryFilter
     * @throws UnsupportedOperationException - if the PO type does not have a "single" key
     * @throws DBException                   - other Exception regarding the OR layer
     */
    public POKeyIterator findAllKeysCursored( Class<? extends PersistentObject> pPersistedObjectClass, WhereClause pSelectionWhereClause )
            throws IllegalStateException, UnsupportedOperationException, DBException;

    /**
     * @param pPersistedObjectRegistrationName
     *                              - Persisted Object Class Name (getClass().getName())
     * @param pSelectionWhereClause - null means all
     * @param pOrderBy              - null means order immaterial
     *
     * @return An Iterator (!Null) that will manage the underlying ResultSet (& DBConnection) creating POs as it goes
     *
     * @throws DBException - Exception regarding the OR layer
     */
    public POQueryIterator findAllCursored( String pPersistedObjectRegistrationName, WhereClause pSelectionWhereClause, OrderBy pOrderBy )
            throws DBException;

    /**
     * @param pPersistedObjectClass - Persisted Object Class (getClass())
     * @param pSelectionWhereClause - null means all
     * @param pOrderBy              - null means order immaterial
     *
     * @return An Iterator (!Null) that will manage the underlying ResultSet (& DBConnection) creating POs as it goes
     *
     * @throws DBException - Exception regarding the OR layer
     */
    public <T extends PersistentObject> POQueryIterator<T> findAllCursored( Class<T> pPersistedObjectClass, WhereClause pSelectionWhereClause, OrderBy pOrderBy )
            throws DBException;

    /**
     * @param pPersistedObjectRegistrationName
     *                              - Persisted Object Class Name (getClass().getName())
     * @param pSelectionWhereClause - null means all
     *
     * @return An Iterator (!Null) that will manage the underlying ResultSet (& DBConnection) creating POs as it goes
     *
     * @throws DBException - Exception regarding the OR layer
     */
    public POQueryIterator findAllCursored( String pPersistedObjectRegistrationName, WhereClause pSelectionWhereClause )
            throws DBException;

    /**
     * @param pPersistedObjectClass - Persisted Object Class (getClass())
     * @param pSelectionWhereClause - null means all
     *
     * @return An Iterator (!Null) that will manage the underlying ResultSet (& DBConnection) creating POs as it goes
     *
     * @throws DBException - Exception regarding the OR layer
     */
    public <T extends PersistentObject> POQueryIterator<T> findAllCursored( Class<T> pPersistedObjectClass, WhereClause pSelectionWhereClause )
            throws DBException;

    /**
     * @param pPersistedObject - Persisted Object to be freshly read
     *
     * @return latest version of pPersistedObject, or Null if pPersistedObject is null OR has been deleted
     *
     * @throws DBException - Exception regarding the OR layer
     */
    public <T extends PersistentObject> T refresh( PersistentObject<T> pPersistedObject )
            throws DBException;
}