source: trunk/java-client/org/nzdl/gsdl/service/NzdlQuery.java@ 2163

/*
 *    NzdlQuery.java
 *    Copyright (C) 2001 New Zealand Digital Library Project
 *
 *    This program is free software; you can redistribute it and/or modify
 *    it under the terms of the GNU General Public License as published by
 *    the Free Software Foundation; either version 2 of the License, or
 *    (at your option) any later version.
 *
 *    This program is distributed in the hope that it will be useful,
 *    but WITHOUT ANY WARRANTY; without even the implied warranty of
 *    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *    GNU General Public License for more details.
 *
 *    You should have received a copy of the GNU General Public License
 *    along with this program; if not, write to the Free Software
 *    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 */

//the package we're in
package org.nzdl.gsdl.service;

import java.util.HashMap;
import java.util.Map;
import java.util.Set;
import java.util.Collection;

import org.nzdl.gsdl.util.NzdlConstants;

/**
 * NzdlQuery is an object that holds the options for a query and is
 * easily configured by the user.
 *
 * @author Stuart Yeates  ([email protected])
 * @author Aziz Mahoui    ([email protected])
 * @author Gordon Paynter ([email protected])
 * @author Brett Sheeran ([email protected]) (comments)
 * @version $Revision: 2163 $
 */

public class NzdlQuery extends java.lang.Object {


  private Map m_Options = null;

  /**      
   * Creates an instance of NzdlQuery with an empty query string.
   * This can then be used as a constructor parameter when creating a
   * {@link NzdlRequest NzdlRequest} object for servicing by a
   * {@link NzdlService NzdlService} object.
   * Default values for a NzdlQuery object are: maxDocs 200, startResults= 1,
   *  endResults= 10, queryType= "ranked", caseFolding= true, stemming= false,
   * queryTerm= "".
   */
  public NzdlQuery() {
    m_Options = new HashMap();
    setQueryTerm   ( NzdlConstants.DEFAULT_QUERY_TERM );
    setQueryType   ( NzdlConstants.DEFAULT_QUERY_TYPE );
    setCaseFolding ( NzdlConstants.DEFAULT_CASE_FOLDING );
    setStemming    ( NzdlConstants.DEFAULT_STEMMING );
    setStartResults( NzdlConstants.DEFAULT_START_RESULTS );
    setEndResults  ( NzdlConstants.DEFAULT_END_RESULTS );
    setMaxDocs     ( NzdlConstants.DEFAULT_MAX_DOCS );
  }

  /**
   * Creates an instance of NzdlQuery with a value for query string. Has the
   * same default values as NzdlQuery(), with the exception of term which is
   * loaded into the query string field.
   * @param term the query string
   */
  public NzdlQuery( String _term ) {
    m_Options = new HashMap();
    setQueryTerm   ( _term );
    setQueryType   ( NzdlConstants.DEFAULT_QUERY_TYPE );
    setCaseFolding ( NzdlConstants.DEFAULT_CASE_FOLDING );
    setStemming    ( NzdlConstants.DEFAULT_STEMMING );
    setStartResults( NzdlConstants.DEFAULT_START_RESULTS );
    setEndResults  ( NzdlConstants.DEFAULT_END_RESULTS );
    setMaxDocs     ( NzdlConstants.DEFAULT_MAX_DOCS );
  }

  /** 
   * Sets the expression to be queried. Note: this can also be done using the
   * constructor.
   * @param term the query expression string
   */
  public void setQueryTerm(String _term) {
    m_Options.put("Term", _term);
  }

  /**
  * Sets the query type as either "ranked" or "boolean". "ranked"
  * orders results by suitability. "boolean" allows use of operators such as
  * !, &, |. Default is "ranked"
  * @param type "ranked" or "boolean"
  */
  public void setQueryType(String _type) {
    m_Options.put("QueryType", _type);
  }

  /**
  * Sets query to ignore case. Default is true.
  * @param case if false then sets query to be case sensitive. If true
  * then sets query to be case insenstive.
  */
  public void setCaseFolding(String _case) {
    m_Options.put("CaseFold", _case);
  }

  /**
  * Sets query to ignore word endings. Default is "false."
  * @param stem if "true", sets query to strip endings such as "...ing",
  * "...ed". If "false", sets query to only match whole words.
  */
  public void setStemming(String _stem) {
    m_Options.put("Stem", _stem);
  }

  /**
  * Sets the maximum number of documents that can be found by a query.
  * Default is 200.
  * @param max The maximum permitted number of documents to be found
  * by the query
  */
  public void setMaxDocs(int _max) {
    m_Options.put("Maxdocs", new Integer(_max));
  }

  /**
  * Sets the start number of the result set. The result set is a subset
  * of the maximum number of documents that will be found by the query.
  * Default is 1.
  * @param start the number of the first document, relative to the found
  * documents
  */
  public void setStartResults(int _start) {
    m_Options.put("StartResults", new Integer(_start));
  }

  /**
  * Sets the end number of the result set. The result set is a subset of the
  * maximum number documents that could be found by that query.
  * Default is 10.
  * @param end the number of the last document relative to the found
  * documents
  */
  public void setEndResults(int _end) {
    m_Options.put("EndResults", new Integer(_end));
  }

  /**
  * Returns whether query is "ranked" or "boolean". "ranked" orders results by
  * suitability. "boolean" allows use of operators such as !, &, |. Default is
  * "ranked"
  * @return Either "ranked" or "boolean"
  */
  public String getQueryType() {
    return (String)m_Options.get("QueryType");
  }

  /**
  * Returns the query string expression.
  * @return the query string
  */
  public String getQueryTerm() {
    return (String)m_Options.get("Term");
  }

  /**
  * Returns "true" if query is case insenstive. Default is "true"
  * @return "true" if query is case insenstive, "false" if the query is case
  * senstive.
  */
  public String getCaseFolding() {
    return (String)m_Options.get("CaseFold");
  }

  /**
  * Returns "true" if query ignores word endings. Default is "false".
  * @return "true" if query strips endings such as "...ing" or "...ed" , false
  * if query only matches whole words.
  */
  public String getStemming() {
    return (String)m_Options.get("Stem");
  }

    /**
   * Returns the current setting for the maximum number of documents that
   * may be found by a query. Default is 200.
   * @return The maximum number of documents to be found
   */
  public int getMaxDocs() {
    return ((Integer) m_Options.get("Maxdocs")).intValue();
  }

  /**
  * Returns the start number of the result set. The result set is a subset of
  * the maximum number of documents that could be found by the query.
  * Default is 1.
  * @return The number of the first document relative to the documents that
  * were found to match the query
  */
  public int getStartResults() {
    return ((Integer) m_Options.get("StartResults")).intValue();
  }

  /**
  * Returns the end number of the result set. The result set is a subset of
  * the maximum number documents that could be found by the query.
  * Default is 10.
  * @return The number of the last document relative to the documents that
  * were found to match the query.
  */
  public int getEndResults() {
    return ((Integer) m_Options.get("EndResults")).intValue();
  }

  /**
  * Returns the set of query terms.
  * @return This set: "EndResults", "QueryType", "Term", "MaxDocs",
  * "StartResults", "Stem", "CaseFold"
  */
  public Set queryKeySet() {
    return m_Options.keySet();
  }

  /**
  * Returns a collection of the current query values.
  * @return For a default query this collection: 10, "ranked", "", 200, 1
  * , false, true
  */
  public Collection queryValues() {
    return m_Options.values();
  }

}