Changeset 2107

Timestamp:

2001-03-03T09:22:55+13:00 (23 years ago)

Author:

bas6

Message:

add comments to NzdlQuery

File:

• trunk/java-client/org/nzdl/gsdl/service/NzdlQuery.java (modified) (4 diffs)

trunk/java-client/org/nzdl/gsdl/service/NzdlQuery.java

@@ -1 @@
-
+/*
+ *    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.*;
-
 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])
+ * @version $Revision$
+ */
+
 public class NzdlQuery extends java.lang.Object {
 
-  /** */
+
   private Map m_Options = null;
 
-  /** */
-
+  /**      
+   * Creates an instance of NzdlQuery with an empty query string.
+   *  Default values are: maxDocs 200, startResults= 1, endResults= 10,
+   *  queryType= "ranked", caseFolding= true, stemming= false, queryTerm= "".
+   */
   public NzdlQuery() {
     m_Options = new HashMap();
@@ -24 +55 @@
   }
 
+  /**
+   * 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();
@@ -35 +72 @@
   }
 
-  /** */
-
+  /** 
+   * 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));
   }
 
-  public void setMaxDocs(int _max) {
-    m_Options.put("Maxdocs", new Integer(_max));
-  }
-
-  /** */
-
+  /**
+  * 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();
   }
 
-  public int getMaxDocs() {
-    return ((Integer) m_Options.get("Maxdocs")).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();
@@ -106 +227 @@
 
 }
+