001    package com.sptci.prevayler;
002    
003    import org.apache.lucene.search.Filter;
004    import org.apache.lucene.search.Query;
005    
006    import java.util.Collection;
007    
008    /**
009     * An interface that defines the transactional features exposed by the
010     * higher level database API.
011     *
012     * <p>&copy; Copyright 2008 <a href='http://sptci.com/' target='_top'>Sans
013     * Pareil Technologies, Inc.</a></p>
014     *
015     * @author Rakesh 2008-11-23
016     * @version $Id: Database.java 22 2008-11-24 19:04:25Z sptrakesh $
017     */
018    public interface Database<P extends PrevalentObject> extends AbstractDatabase<P>
019    {
020      /**
021       * Save the specified prevalent object to the prevalent system.  Objects
022       * not already persistent are added to the system, while already persistent
023       * objects are updated.
024       *
025       * @param object The prevalent object to be saved in the system.
026       * @return The potentially modified prevalent object.
027       * @throws PrevalentException If errors are encountered while
028       *   adding/updating the object.  Errors thrown could indicate constraint
029       *   violations.
030       */
031      P save( final P object ) throws PrevalentException;
032    
033      /**
034       * Delete the specified prevalent object from the prevalent system.
035       * Processes cascading delete rules if so configured.
036       *
037       * @param object The prevalent object to delete.
038       * @return The deleted object with potential modifications.
039       * @throws com.sptci.prevayler.PrevalentException If errors are encountered
040       *   while deleting the prevalent object.
041       */
042      P delete( P object ) throws PrevalentException;
043    
044      /**
045       * Execute the specified lucene query and return the collection of matching
046       * prevalent objects.
047       * @param query The lucene query that is to be executed to find matching
048       *   prevalent object instances.
049       * @param count The maximum number to top hits for the search to return.
050       * @return The collection of matching instances or an empty collection.
051       * @throws com.sptci.prevayler.PrevalentException If errors are encountered
052       *   while reconstituting the prevalent objects being returned.
053       */
054      Collection<P> search( Query query, int count ) throws PrevalentException;
055    
056      /**
057       * Execute the specified lucene query and return the collection of matching
058       * prevalent objects.
059       * @param query The lucene query that is to be executed to find matching
060       *   prevalent object instances.
061       * @param filter The filter to apply to restrict the query results.
062       * @param count The maximum number to top hits for the search to return.
063       * @return The collection of matching instances or an empty collection.
064       * @throws com.sptci.prevayler.PrevalentException If errors are encountered
065       *   while reconstituting the prevalent objects being returned.
066       */
067      Collection<P> search( Query query, Filter filter, int count )
068          throws PrevalentException;
069    }