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 hold search results.
* <p>
* &laquo;Immutable -- Read-Only.&raquo;
* <p>
* Holds a search query return. A query result will have
* general header information such as a count of results
* items, the name of search collection we searched over, 
* etc., as well as a SearchResultItem per result returned.
*
* @@author <a href="mailto:stack@@collab.net">St.Ack</a>
* @@version $Id: SearchResult.java,v 1.4 2000/11/06 00:08:21 stack Exp $
*/
public class SearchResult
{
    /** Class version string
    */
    public static final String versionID 
        = "$Id: SearchResult.java,v 1.4 2000/11/06 00:08:21 stack Exp $";
    
    
    /** Array of search results.
    * Keep the order returned by the search-engine.
    * Item 0 should be highest ranked.  Later we can
    * come along and do sorts on other than ranking.
    * Maybe this should be a set.  Then we're guaranteed
    * uniqueness.  Or SortedSet might help when it comes
    * to sorting time.
    */
    private java.util.List resultItems = null;
    
    
    /** Name of index results came from.
    */
    private String indexName = null;
    
    
    /** Number of hits.
    * How many result items.  Can be bigger than the
    * results per page.  Showing this number then will
    * help the user when there are more results than
    * results-per-page will allow them see.
    */
    private int numberOfHits = 0;
    
    
    /** The Query object that was responsible for these results.
    */
    private Query query = null;
    
    
    /** When index was last updated.
    * A date as a string (conversion to Date ain't worth the bother).
    */
    private String indexModDate = null;
    
    
    /** Search result index statistics.
    * Some stats returned by the search-engine describing the index..
    * For example, a Swish-e string would be '19 words, 2 files'.  
    */
    private String indexStats = null;
    
    
    /** Search words.
    * This is a list of words that the search engine
    * reports it searched on.  Often different from
    * what is in the Query object.
    */
    private String searchengineSearchWords = null;
    
    
    /** Pointer to the index used.
    * This is path or url to index.  May be null.
    */
    private String indexPointer = null;
    
    
    /** Index description. May be null
    */
    private String description = null;
    
    
    /** Constructor
    *
    * @@param inQuery        Query that generated this result set.
    * @@param inResultsItem  An array of result items.  Can be null
    * @@param inIndexName    Name of our index. Can be a path or just 
    *                       a handle.  Can be null.
    * @@param inNumberOfHits Number of items returned.  Can be zero.
    * @@param inIndexModDate A date as string telling when index 
    *                       was last modified.  Can be null.
    * @@param inIndexStats   A string of stats on the index.
    *                       Can be null.
    * @@param inIndexPointer Url or path to index. May be null.
    * @@param inDescription  Index description.  May be null.
    * @@param inSearchengineSearchWords Search words used according to search engine.
    * May be null for not all search engines will provide this info.
    *
    * @@exception NullPointerException If passed in Query object is empty.
    * @@exception IndexOutOfBoundsException If passed in inNumberOfHits 
    * doesn't match the inResultItems or is negative.
    */
    public SearchResult( Query inQuery,
                            java.util.List inResultItems,
                            String inIndexName,
                            int inNumberOfHits, 
                            String inIndexModDate, 
                            String inIndexStats, 
                            String inIndexPointer, 
                            String inDescription, 
                            String inSearchengineSearchWords )
        throws NullPointerException,
                IndexOutOfBoundsException
    {
        if( inQuery == null )
            throw new NullPointerException( "inQuery is null" );
        query = inQuery;
        
        resultItems = inResultItems;
         
        if( inNumberOfHits < 0 )
            throw new IndexOutOfBoundsException( "inNumberOfHits <"
                + Integer.toString( inNumberOfHits )
                + "> negative or not equal to size of resultItems" );
        numberOfHits = inNumberOfHits;
        
        indexName = inIndexName;
        indexModDate = inIndexModDate;
        indexStats = inIndexStats;
        indexPointer = inIndexPointer;
        description = inDescription;
        searchengineSearchWords = inSearchengineSearchWords;
    }
    
    
    /** Return search result index stats description string.
    * For example, a Swish-e string would be '19 words, 2 files'.  
    * This string seems to say that the index has 19 words in it
    * and two files.  Returned as part of every search.
    * @@return A description string
    */
    public String getIndexStats( )
    {
        return indexStats;
    }
    
    
    /** Return the query that was responsible for making these
    * results.
    * @@return Query object.
    */
    public Query getQuery( )
    {
        return query;
    }
    
    
    /** Return the date the search index was last updated.
    * @@return A modification date as a string to display
    */
    public String getIndexModDate( )
    {
        return indexModDate;
    }
    
    
    /** Get name of index that these search results came from.
    * @@return Name of search index.  Can be path to search index or 
    * an index 'name'. May be null.
    */
    public String getIndexName( )
    {
        return indexName;
    }
    
    /** Get number of result items in this search result.
    * @@return Number of hits.  May be zero.
    */
    public int getNumberOfHits( )
    {
        return numberOfHits;
    }
    
    
    /** Accessor for search result items.
    * @@return Array of SearchResultItems.  May be null if no results returned
    */
    public java.util.List getSearchResultItems( )
    {
        return resultItems;
    }
    
    
    /** Get the search words that the search-engine reports it used searching.
    * Differs from what is passed as the query.  Shows how the search-engine
    * preprocesses the passed in query before it goes about it's work.  This
    * list may help debugging search results.
    * @@return The search words string as reported by the search engine.
    */
    public String getSearchengineSearchWords( )
    {
        return searchengineSearchWords;
    }
    
    
    /** Return the path or url to index
    * @@return Pointer to index
    */
    public String getIndexPointer( )
    {
        return indexPointer;
    }
    

    /** Return index description.
    * @@return Description string about index
    */
    public String getDescription( )
    {
        return description;
    }
    
    
    /** Print out contents as a string
    * @@return Contents of this object as a string
    */
    public String toString( )
    {
        StringBuffer strBuffer = new StringBuffer( );
        strBuffer.append( super.toString( ) );
        strBuffer.append( ": indexName " );
        strBuffer.append( ( getIndexName( ) != null )
                            ? getIndexName( )
                            : "null" );
        strBuffer.append( ", numberOfHits " );
        strBuffer.append( Integer.toString( getNumberOfHits( ) ) );     
        strBuffer.append(", indexModDate ");
        strBuffer.append( ( getIndexModDate( ) != null )
                            ? getIndexModDate( )
                            : "null" );
        strBuffer.append( ", indexStats " );
        strBuffer.append( ( getIndexStats( ) != null )
                            ? getIndexStats( )
                            : "null" );
        strBuffer.append( ", searchengineSearchWords " );
        strBuffer.append( ( getSearchengineSearchWords( ) != null )
                            ? getSearchengineSearchWords( )
                            : "null" );
        strBuffer.append( ", indexPointer " );
        strBuffer.append( ( getIndexPointer( ) != null )
                            ? getIndexPointer( )
                            : "null" );   
        strBuffer.append( ", description " );
        strBuffer.append( ( getDescription( ) != null )
                            ? getDescription( )
                            : "null" );  
        strBuffer.append( "\n" );
        
        
        // Now do each of the result items, a line to themselves
        //
        SearchResultItem item = null;
        label_searchresults_not_null: if( resultItems != null )
        {
            for( int i = 0; i < resultItems.size( ); i++ )
            {
                item = ( SearchResultItem )resultItems.get( i );
                strBuffer.append( Integer.toString( i ) );
                strBuffer.append( ": ranking " );
                strBuffer.append( Integer.toString( item.getRanking( ) ) );
                strBuffer.append(", size ");
                strBuffer.append( Integer.toString( item.getSize( ) ) );
                strBuffer.append( ", url " );
                strBuffer.append( item.getUrl( ).toString( ) );
                strBuffer.append( ", title " );
                strBuffer.append( ( item.getTitle( ) != null )
                                    ? item.getTitle( )
                                    : "null" ); 
                strBuffer.append( "\n\t" );  
            }
        } // label_searchresults_not_null
        
        return strBuffer.toString( );
    }
}
@
