001    package com.sptci.prevayler.query;
002    
003    import com.sptci.prevayler.PrevalentException;
004    import com.sptci.prevayler.PrevalentObject;
005    import com.sptci.prevayler.PrevalentSystem;
006    import org.apache.lucene.search.Filter;
007    import org.apache.lucene.search.Query;
008    import org.apache.lucene.search.Sort;
009    
010    import java.util.Collection;
011    import java.util.Date;
012    
013    /**
014     * The query for retrieving a collection of prevalent objects that match
015     * the specified query and optional filter.  This query uses the full-text
016     * indices to retrieve the matching prevalent objects.
017     *
018     * @see com.sptci.prevayler.PrevalentManager#search(org.apache.lucene.search.Query,
019     *   org.apache.lucene.search.Filter, int, org.apache.lucene.search.Sort)
020     * <p>&copy; Copyright 2008 <a href='http://sptci.com/' target='_top'>Sans Pareil
021     *   Technologies, Inc.</a></p>
022     * @author Rakesh Vidyadharan 2008-05-27
023     * @version $Id: Search.java 22 2008-11-24 19:04:25Z sptrakesh $
024     */
025    public class Search<P extends Collection<PrevalentObject>, S extends PrevalentSystem>
026        extends AbstractQuery<P,S>
027    {
028      /** The query that is to be executed. */
029      private final Query query;
030    
031      /** The optional filter clause to apply for the search results. */
032      private final Filter filter;
033    
034      /** The maximum number of search results to return. */
035      private final int count;
036    
037      /** The sort criteria to apply to the search results. */
038      private final Sort sort;
039    
040      /**
041       * Create a new instance of the query with the specified parameters.
042       *
043       * @param query The lucene query to execute.
044       * @param count The maximum number of results.
045       */
046      public Search( final Query query, final int count )
047      {
048        this( query, null, count, null );
049      }
050    
051      /**
052       * Create a new instance of the query with the specified parameters.
053       *
054       * @param query The lucene query to execute.
055       * @param filter The filter to apply to the results.
056       * @param count The maximum number of results.
057       */
058      public Search( final Query query, final Filter filter, final int count )
059      {
060        this( query, filter, count, null );
061      }
062    
063      /**
064       * Create a new instance of the query with the specified parameters.  This
065       * is the designated initialiser.
066       *
067       * @param query The lucene query to execute.
068       * @param filter The filter to apply to the results.
069       * @param count The maximum number of results.
070       * @param sort The sort criteria for the results.
071       */
072      public Search( final Query query, final Filter filter, final int count,
073          final Sort sort )
074      {
075        this.query = query;
076        this.filter = filter;
077        this.count = count;
078        this.sort = sort;
079      }
080    
081      /**
082       * Execute the query on the prevalent system and return the prevalent
083       *  object instances that match the specified query.
084       *
085       * @param system The prevalent system that is to be acted upon.
086       * @param timestamp The timestamp for the query.
087       * @return The collection of prevalent objects or an empty collection.
088       * @throws com.sptci.prevayler.PrevalentException If errors are encountered
089       *   while fetching the required prevalent object.
090       */
091      @SuppressWarnings( {"unchecked"} )
092      protected P query( final S system, final Date timestamp )
093          throws PrevalentException
094      {
095        return (P) system.search( query, filter, count, sort );
096      }
097    }