head	1.1;
access;
symbols;
locks; strict;
comment	@# @;


1.1
date	2001.07.19.20.22.44;	author dlr;	state Exp;
branches;
next	;


desc
@@


1.1
log
@Ported Joist searching classes into Helm.
@
text
@/* ================================================================
 * Copyright (c) 2000 Collab.Net.  All rights reserved.
 * 
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are
 * met:
 * 
 * 1. Redistributions of source code must retain the above copyright
 * notice, this list of conditions and the following disclaimer.
 * 
 * 2. Redistributions in binary form must reproduce the above copyright
 * notice, this list of conditions and the following disclaimer in the
 * documentation and/or other materials provided with the distribution.
 * 
 * 3. The end-user documentation included with the redistribution, if
 * any, must include the following acknowlegement: "This product includes
 * software developed by Collab.Net (http://www.Collab.Net/)."
 * Alternately, this acknowlegement may appear in the software itself, if
 * and wherever such third-party acknowlegements normally appear.
 * 
 * 4. The hosted project names must not be used to endorse or promote
 * products derived from this software without prior written
 * permission. For written permission, please contact info@@collab.net.
 * 
 * 5. Products derived from this software may not use the "Tigris" name
 * nor may "Tigris" appear in their names without prior written
 * permission of Collab.Net.
 * 
 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
 * IN NO EVENT SHALL COLLAB.NET OR ITS CONTRIBUTORS BE LIABLE FOR ANY
 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
 * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
 * IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 * ====================================================================
 * 
 * This software consists of voluntary contributions made by many
 * individuals on behalf of Collab.Net.
 */
package org.tigris.helm.search; 
 
 
/** Class to pass query and query arguments to Search.
* <p>
* &laquo;Immutable -- Read-Only.&raquo;
* <p>
* Queries objects of this class go against one index only.  To 
* run a search against multiple indexes, run the query multiple 
* times specifying a different index each time.
* <p>
* Different search engines may have more facility to pass
* in a query -- just subclass or add to this class when 
* the time comes.  In particular, we'll need to support
* paging through returned results.
*
* @@author <a href="mailto:stack@@collab.net">St.Ack</a>
* @@version $Id: Query.java,v 1.4 2000/11/06 19:31:51 stack Exp $
*/
public class Query
{
    /** Number of search result items to return per query.
    */
    private int resultsPerQuery = -1;
    
    
    /** Query string to pass search.
    */
    private String queryString = null;
    
    
    /** Index we're to use.  
    * This is full-path or a index 'name'.  
    * For swishe, its full-path.  May be 
    * just a unique name when we use other
    * indexes.
    */
    private String searchIndex = null;
    
    
    /** Upper limit on how many queries results we'll return.
    * I want it to fail if search engine returns 50,000 pages.
    * I'd rather this than it hang whole website processing too
    * many results.
    */
    private final static int QUERY_RESULTS_UPPER_LIMIT = 10000;
    
    
    
    /** Constructor
    *
    * @@param inQuery Query object to run
    * @@param inResultsPerQuery How many results to return.  
    * Usually forms part of query.  Can be zero.  Then we 
    * return the default setting for results per page.  
    * Cannot be negative. 
    * @@param inSearchIndex Name of search index that this 
    * query is to go against. Can be name or full-path to 
    * index.  Depends on the search-engine.
    *
    * @@exception NullPointerException If passed in params 
    * are null or empty.
    * @@exception IndexOutOfBoundsException If passed in 
    * inResultsPerQuery is less than 0 or greater than 
    * QUERY_RESULTS_UPPER_LIMIT, our arbitrary upper-bound.
    * @@exception java.io.FileNotFoundException If search 
    * index does not exist.
    */
    public Query( String inQuery,  
                    String inSearchIndex,
                    int inResultsPerQuery )
        throws NullPointerException, 
                IndexOutOfBoundsException,
                java.io.FileNotFoundException
    {
        if( ( inQuery == null ) || ( inQuery.length( ) <= 0 ) )
            throw new NullPointerException("inQuery is null or empty");
        queryString = inQuery;
             
        // Test for non-null index and that it exists
        //
        if( ( inSearchIndex == null ) 
            || ( inSearchIndex.length( ) <= 0 ) )
            throw new NullPointerException( "inSearchIndex is null or empty" );
        java.io.File fileIndex = new java.io.File( inSearchIndex );
        if( !fileIndex.exists( ) )
            throw new java.io.FileNotFoundException( "Search index &lt;"
                + inSearchIndex 
                + "> does not exist" );
        searchIndex = inSearchIndex;
        
        // Test inResultsPerQuery is w/i bounds
        //
        if( ( inResultsPerQuery < 0 ) 
            || ( inResultsPerQuery > QUERY_RESULTS_UPPER_LIMIT ) )
            throw new IndexOutOfBoundsException( "Results-per-query <"
                + Integer.toString( inResultsPerQuery )
                + "> is negative or greater than our upper-bound limit, " 
                + Integer.toString( QUERY_RESULTS_UPPER_LIMIT ) );
        resultsPerQuery = inResultsPerQuery;
    }
    
    
    /** Constructor override.
    * Doesn't supply the inResultsPerQuery.  Rely on search-engine 
    * using its default for results per query.
    *
    * @@param inQuery Query to run
    * @@param inSearchIndex Name of search index that this query is 
    * to go against. Can be name or full-path to index.  Depends 
    * on the search-engine.
    *
    * @@exception NullPointerException If passed in params are null 
    * or empty.
    * @@exception IndexOutOfBoundsException If passed in 
    * inResultsPerQuery is less than 0 or greater than 
    * QUERY_RESULTS_UPPER_LIMIT, our arbitrary upper-bound.
    * @@exception java.io.FileNotFoundException If search 
    * index does not exist.
    */
    public Query( String inQuery,  
                    String inSearchIndex ) 
        throws NullPointerException, 
                IndexOutOfBoundsException,
                java.io.FileNotFoundException
    {
        this( inQuery, inSearchIndex, 0 );
    }
    
   
    /** Accessor for query String
    * @@result Returns query string.
    */
    public String getQueryString( )
    {
        return queryString;
    }
    
    
    /** Accessor for search index to use
    * @@result Returns search index to use this query against
    */
    public String getSearchIndex( )
    {
        return searchIndex;
    }
    
    
    /** Accessor for search index to use
    * @@result Returns results per query to return.
    */
    public int getResultsPerQuery( )
    {
        return resultsPerQuery;
    }    
}
@
