package org.litesoft.orsup.base;

import java.util.*;

import org.litesoft.db.*;
import org.litesoft.orsup.nonpublic.*;
import org.litesoft.orsup.selection.*;
import org.litesoft.orsup.transact.*;

public interface Finder extends ORFacilitator, MetaDataStore
{
    public static final PersistentObject[] NO_PERSISTENT_OBJECTS = new PersistentObject[0];

    public boolean isIncludingImmortalInactives();

    public NonTransactionalFinder getNonTransactionalFinder();

    public Transaction createTransaction();

    /**
     * @param pPersistedObjectRegistrationName
     *                              - Persisted Object Class Name (getClass().getName())
     * @param pSelectionWhereClause - null means all
     * @param pOrderBy              - null means order immaterial
     * @param pOffset               - Rows to Skip (< 0 treated as 0)
     * @param pLimit                - Max Rows to return (< 1 treated as 1)
     *
     * @return !Null Mutable List
     *
     * @throws DBException - Exception regarding the OR layer
     */
    public List<PersistentObject<?>> findSubset( String pPersistedObjectRegistrationName,
                                                 WhereClause pSelectionWhereClause, //
                                                 OrderBy pOrderBy, long pOffset, int pLimit )
            throws DBException;

    /**
     * @param pPersistedObjectClass - Persisted Object Class (getClass())
     * @param pSelectionWhereClause - null means all
     * @param pOrderBy              - null means order immaterial
     * @param pOffset               - Rows to Skip (< 0 treated as 0)
     * @param pLimit                - Max Rows to return (< 1 treated as 1)
     *
     * @return !Null Mutable List
     *
     * @throws DBException - Exception regarding the OR layer
     */
    public <T extends PersistentObject> List<T> findSubset( Class<T> pPersistedObjectClass,
                                                            WhereClause pSelectionWhereClause, //
                                                            OrderBy pOrderBy, long pOffset, int pLimit )
            throws DBException;

    /**
     * @param pPersistedObjectRegistrationName
     *                              - Persisted Object Class Name (getClass().getName())
     * @param pSelectionWhereClause - null means all
     * @param pOrderBy              - null means order immaterial
     *
     * @return !Null Mutable List
     *
     * @throws DBException - Exception regarding the OR layer
     */
    public List<PersistentObject<?>> findAll( 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 !Null Mutable List
     *
     * @throws DBException - Exception regarding the OR layer
     */
    public <T extends PersistentObject> List<T> findAll( Class<T> pPersistedObjectClass,
                                                         WhereClause pSelectionWhereClause, OrderBy pOrderBy )
            throws DBException;

    /**
     * @param pPersistedObjectRegistrationName
     *                              - Persisted Object Class Name (getClass().getName())
     * @param pSelectionWhereClause - null means all
     *
     * @return !Null Mutable List, order indeterminate
     *
     * @throws DBException - Exception regarding the OR layer
     */
    public List<PersistentObject<?>> findAll( String pPersistedObjectRegistrationName,
                                              WhereClause pSelectionWhereClause )
            throws DBException;

    /**
     * @param pPersistedObjectClass - Persisted Object Class (getClass())
     * @param pSelectionWhereClause - null means all
     *
     * @return !Null Mutable List, order indeterminate
     *
     * @throws DBException - Exception regarding the OR layer
     */
    public <T extends PersistentObject> List<T> findAll( Class<T> pPersistedObjectClass,
                                                         WhereClause pSelectionWhereClause )
            throws DBException;

    /**
     * @param pPersistedObjectRegistrationName
     *                 - Persisted Object Class Name (getClass().getName())
     * @param pKeys    - null or empty means none
     * @param pOrderBy - null means order immaterial
     *
     * @return !Null Mutable List
     *
     * @throws UnsupportedOperationException - if the PO type does not have a "single" key
     * @throws DBException                   - other Exception regarding the OR layer
     */
    public List<PersistentObject<?>> findAllByKeys( String pPersistedObjectRegistrationName, Collection pKeys,
                                                    OrderBy pOrderBy )
            throws UnsupportedOperationException, DBException;

    /**
     * @param pPersistedObjectClass - Persisted Object Class (getClass())
     * @param pKeys                 - null or empty means none
     * @param pOrderBy              - null means order immaterial
     *
     * @return !Null Mutable List
     *
     * @throws UnsupportedOperationException - if the PO type does not have a "single" key
     * @throws DBException                   - other Exception regarding the OR layer
     */
    public <T extends PersistentObject> List<T> findAllByKeys( Class<T> pPersistedObjectClass,
                                                               Collection pKeys, OrderBy pOrderBy )
            throws UnsupportedOperationException, DBException;

    /**
     * @param pPersistedObjectRegistrationName
     *              - Persisted Object Class Name (getClass().getName())
     * @param pKeys - null or empty means none
     *
     * @return !Null Mutable List, order indeterminate
     *
     * @throws UnsupportedOperationException - if the PO type does not have a "single" key
     * @throws DBException                   - other Exception regarding the OR layer
     */
    public List<PersistentObject<?>> findAllByKeys( String pPersistedObjectRegistrationName,
                                                    Collection pKeys )
            throws UnsupportedOperationException, DBException;

    /**
     * @param pPersistedObjectClass - Persisted Object Class (getClass())
     * @param pKeys                 - null or empty means none
     *
     * @return !Null Mutable List, order indeterminate
     *
     * @throws UnsupportedOperationException - if the PO type does not have a "single" key
     * @throws DBException                   - other Exception regarding the OR layer
     */
    public <T extends PersistentObject> List<T> findAllByKeys( Class<T> pPersistedObjectClass,
                                                               Collection pKeys )
            throws UnsupportedOperationException, DBException;

    /**
     * @param pPersistedObjectRegistrationName
     *                              - Persisted Object Class Name (getClass().getName())
     * @param pSelectionWhereClause - null means all, which will only succeed if the table only has one entry
     *
     * @return Null if not Found
     *
     * @throws DBException - Exception regarding the OR layer
     */
    public PersistentObject<?> findOne( String pPersistedObjectRegistrationName,
                                        WhereClause pSelectionWhereClause )
            throws DBException;

    /**
     * @param pPersistedObjectClass - Persisted Object Class (getClass())
     * @param pSelectionWhereClause - null means all, which will only succeed if the table only has one entry
     *
     * @return Null if not Found
     *
     * @throws DBException - Exception regarding the OR layer
     */
    public <T extends PersistentObject> T findOne( Class<T> pPersistedObjectClass,
                                                   WhereClause pSelectionWhereClause )
            throws DBException;

    /**
     * @param pPersistedObjectRegistrationName
     *                                   - Persisted Object Class Name (getClass().getName())
     * @param pPersistentObjectUniqueKey - !Null
     *
     * @return Null if not Found
     *
     * @throws DBException - Exception regarding the OR layer
     */
    public PersistentObject<?> findOne( String pPersistedObjectRegistrationName,
                                        PersistentObjectUniqueKey pPersistentObjectUniqueKey )
            throws DBException;

    /**
     * @param pPersistedObjectClass      - Persisted Object Class (getClass())
     * @param pPersistentObjectUniqueKey - !Null
     *
     * @return Null if not Found
     *
     * @throws DBException - Exception regarding the OR layer
     */
    public <T extends PersistentObject> T findOne( Class<T> pPersistedObjectClass,
                                                   PersistentObjectUniqueKey pPersistentObjectUniqueKey )
            throws DBException;

    /**
     * @param pPersistentObjectURL - !Null
     *
     * @return Null if not Found
     *
     * @throws DBException - Exception regarding the OR layer
     */
    public PersistentObject<?> findOne( PersistentObjectURL pPersistentObjectURL )
            throws DBException;

    /**
     * Convenience alternative to findOne(PersistentObjectURL) as we will seem to need to do this
     * conversion more and more.
     *
     * @param pPersistentObjectURL - !Null - a string suitable for translation into a PersistentObjectURL
     *
     * @return Null if not Found
     *
     * @throws DBException              - Exception regarding the OR layer
     * @throws IllegalArgumentException - if the string cannot be parsed and the PO reference or the Key is invalid
     */
    public PersistentObject<?> findOne( String pPersistentObjectURL )
            throws DBException, IllegalArgumentException;

    /**
     * @param pObjectHandle - !Null
     *
     * @return Null if not Found
     *
     * @throws DBException - Exception regarding the OR layer
     */
    public PersistentObject<?> findOne( ObjectHandle pObjectHandle )
            throws DBException;

    public POQueryFilterFactory getPOQueryFilterFactory();

    /**
     * @param pPersistedObjectRegistrationName
     *                     - Persisted Object Class Name (getClass().getName())
     * @param pKeyToString - The String that was generated by the toString() method from a PersistentObjectUniqueKey
     *
     * @return A (!Null) PersistentObjectUniqueKey that can be used with the rest of the ORmapping layer
     *
     * @throws IllegalArgumentException - if either the PO reference is invalid or the Key can not be parsed
     */
    public PersistentObjectUniqueKey createPersistentObjectUniqueKeyFrom(
            String pPersistedObjectRegistrationName, String pKeyToString )
            throws IllegalArgumentException;

    /**
     * @param pPersistedObjectClass - Persisted Object Class (getClass())
     * @param pKeyToString          - The String that was generated by the toString() method from a PersistentObjectUniqueKey
     *
     * @return A (!Null) PersistentObjectUniqueKey that can be used with the rest of the ORmapping layer
     *
     * @throws IllegalArgumentException - if either the PO reference is invalid or the Key can not be parsed
     */
    public PersistentObjectUniqueKey createPersistentObjectUniqueKeyFrom(
            Class<? extends PersistentObject> pPersistedObjectClass, String pKeyToString )
            throws IllegalArgumentException;

    /**
     * @param pURLtoString - The String that was generated by the toString() method from a PersistentObjectURL
     *
     * @return A (!Null) PersistentObjectURL that can be used with the rest of the ORmapping layer
     *
     * @throws IllegalArgumentException - if the string can not be parsed and the PO reference or the Key is invalid
     */
    public PersistentObjectURL createPersistentObjectURLfrom( String pURLtoString )
            throws IllegalArgumentException;
}