// 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.core.simpletypes.*;
import org.litesoft.core.util.*;

public interface ServerVoPersister<T extends IViewObject>
{
    void initialize( ServerVoDataProviderMap pServerVoDataProviderMap );

    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!
     */
    T getVOby( ObjectURL pObjectURL )
            throws PersistenceException;

    /**
     * Get a single Matching VO by the supplied criteria.
     *
     * @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 single VO found (matches), or null if not found
     *
     * @throws MultipleMatchingPersistenceException
     *                              if the criteria results in more than one row
     * @throws PersistenceException if there was an underlying exception!
     */
    T getMatchingVO( SSMap... pORed_ANDFilters )
            throws MultipleMatchingPersistenceException, 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!
     */
    SizedIterator<T> getMatchingVOs( Integer pMaxToReturn, SSMap... pORed_ANDFilters )
            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!
     */
    SCresult commit( TransactionSet pTransactionSet, ObjectURL... pReturnOnSuccess )
            throws PersistenceException;
}