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

import org.litesoft.bo.views.server.*;
import org.litesoft.commonfoundation.exceptions.*;
import org.litesoft.commonfoundation.interators.*;
import org.litesoft.core.simpletypes.*;
import org.litesoft.logger.*;

@SuppressWarnings({"DuplicateThrows"})
public interface ServerVoDataProvider<T extends IViewObject>
{
    public static final Logger LOGGER = LoggerFactory.getLogger( ServerVoDataProvider.class );

    public VoMetaData<T> getVOMetaData();

    public void initialize( ServerVoDataProviderMap pServerVoDataProviderMap );

    public ServerVoDataProviderMap getServerVoDataProviderMap();

    /**
     * Get a single VO based on an ObejctURL
     *
     * @param pObjectURL if null, null will be return
     *
     * @return single VO found (matches), or null if not found (or pObjectURL is null)
     *
     * @throws PersistenceException if there was an underlying exception!
     */
    public T getVOby( ObjectURL pObjectURL )
            throws PersistenceException;

    /**
     * Get all Matching VO(s) with the supplied URLs.
     *
     * @param pObjectURLs the URLs for the VOs to fetch.
     *
     * @return a SizedIterator, if the rows found are <= pMaxToReturn then the size indicated will match the rows returned by iterating, otherwise, the state of the iterator is unspecified.
     *
     * @throws PersistenceException if there was an underlying exception!
     */
    public SizedIterator<T> getMatchingVOs( ObjectURL... pObjectURLs )
            throws PersistenceException;

    /**
     * Get all Matching VO(s) by the supplied criteria (Not to exceed the pMaxToReturn).
     *
     * @param pMaxToReturn     if ! null, then if there are more then the pMaxToReturn that match, return none, but indicate how many would have been returned.
     * @param pORed_ANDFilters - OR the criteria of each map, where each map is the ANDing of the attribute values (Note: if No Maps are given then return ALL)
     *
     * @return a SizedIterator, if the rows found are <= pMaxToReturn then the size indicated will match the rows returned by iterating, otherwise, the state of the iterator is unspecified.
     *
     * @throws PersistenceException if there was an underlying exception!
     */
    public SizedIterator<T> getMatchingVOs( Integer pMaxToReturn, SSMap... pORed_ANDFilters )
            throws PersistenceException;

    public SCresult requestFunctionSimple( String pFunction, IViewObject... pVOs )
            throws PersistenceException;

    public SCresult requestFunctionFetchRow( String pFunction, IViewObject... pVOs )
            throws MultipleMatchingPersistenceException, PersistenceException;

    public SCresult requestFunctionFetchRows( String pFunction, Integer pMaxToReturn, IViewObject... pVOs )
            throws PersistenceException;

    public SCresult requestRowByObjectURL( ObjectURL pObjectURL )
            throws MultipleMatchingPersistenceException, PersistenceException;

    public SCresult requestRowsByObjectURLs( ObjectURL... pObjectURLs )
            throws PersistenceException;

    public SCresult requestRowsByFilters( BoAccessorFilters pFilters, Integer pMaxToReturn )
            throws PersistenceException;

    /**
     * ACIDly update the Backing Persistence Engine (DB?) with rows from the pTransactionSet.
     *
     * @param pTransactionSet  !null
     * @param pReturnOnSuccess the SCresult will contain a VO (which may be null) entry for each VO originally in the pTransactionSet whose original ObjectURL matches the entry in this array (dups allowed).
     *
     * @return a Relatively complex object that is used to manage Caches.
     *
     * @throws PersistenceException if there was an underlying exception!
     */
    public SCresult requestCommit( TransactionSet pTransactionSet, ObjectURL... pReturnOnSuccess )
            throws PersistenceException;
}