Changeset 2108 for trunk/java-client/org/nzdl/gsdl/service/NzdlResultSet.java

Timestamp:

2001-03-05T08:44:51+13:00 (23 years ago)

Author:

bas6

Message:

Documenting NzdlQuery, NzdlResponse, NzdlResultSet & NzdlServiceServer (removed some extraneous @see comments)

File:

• trunk/java-client/org/nzdl/gsdl/service/NzdlResultSet.java (modified) (10 diffs)

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

@@ -1 @@
-
+/*
+ *    NzdlResultSet.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.*;
 
+/**
+ * An object that holds results extracted from a response by
+ * {@link NzdlResponse#getResultSet() NzdlResponse.getResultSet()}.
+ * Easily interrogated by a user.
+ */
 public class NzdlResultSet extends java.lang.Object {
 
@@ -11 +35 @@
   private List m_queryTerms  = null;
   private List m_docIDs = null;
-  /** the key is the query term, the value its frequency */
+
+  /* The key is the query term, the value its frequency */
   private Map m_frequencies = null;
-  /** 
-   * the key is the docID, the value is the doc corresponding 
+
+  /*
+   * The key is the docID, the value is the doc corresponding
    * meta data which is also a Map where the key is the meta tag
    * and the value is a set of values for that tag
@@ -20 +46 @@
   private Map m_docToMetaDataMap = null;
 
-  /** */
-  
+  /**
+   * Creates an empty instance of NzdlResultSet.
+   */
   public NzdlResultSet() {
     m_resultSet = new ArrayList();
@@ -28 +55 @@
   }
 
-  /** */
-
+  /**
+   * Adds a {@link NzdlQueryHit NzdlQueryHit} to a result set.
+   * @param hit - is an instance of NzdlQueryHit.
+   */
   public void add( NzdlQueryHit _hit ) {
     m_resultSet.add( _hit ) ;
@@ -37 +66 @@
   }
 
+    /**
+   * Sets the number of documents in a NzdlResultSet.
+   * @param num the number of documents in the result set
+   */
   public void setNumOfDocs( int _num ) {
     m_numDocs = _num;
   }
 
+
+  /**
+   * Sets the result type.
+   * @param type an integer representing the result type.
+   */
   public void setResultType( int _type ) {
     m_resultType = _type;
   }
 
+  /**
+   * Sets the Query terms of a NzdlResultSet.
+   * @param terms a list of words within the query string.
+   */
   public void setQueryTerms( List _terms ) {
     m_queryTerms = _terms;
@@ -53 +95 @@
 //    }
 
+  /**
+   * Sets the term frequencies within a NzdlResultSet.
+   * @param freqs a map of the term frequencies. The map key is the query term.
+   */
   public void setTermFrequencies( Map _freqs ) {
     m_frequencies = _freqs;
   }
 
-  /** */
-
+  /**
+   * Returns the number of documents that matched a query. <br>
+   * Pre: A {@link NzdlResponse NzdlResponse} object has been created. A
+   * {@link NzdlService NzdlService} object has filled the NzdlResponse
+   * object with results from servicing a {@link NzdlRequest NzdlRequest}.<br>
+   * @return The number of documents that matched a query. This is limited
+   * by the maxDocs set in {@link NzdlQuery NzdlQuery}
+   */
   public int getNumOfDocs() {
     return m_numDocs;
   }
 
+  /**
+   * Returns the result type for the NzdlResultSet. <br>
+   * Pre: A {@link NzdlResponse NzdlResponse} object has been created. A
+   * {@link NzdlService NzdlService} object has filled the NzdlResponse
+   * object with results from servicing a {@link NzdlRequest NzdlRequest}.<br>
+   * @return result type as an integer.
+   */
   public int getResultType() {
     return m_resultType;
   }
 
+  /**
+   * Returns a list of the words within the query string. <br>
+   * Pre: A {@link NzdlResponse NzdlResponse} object has been created. A
+   * {@link NzdlService NzdlService} object has filled the NzdlResponse
+   * object with results from servicing a {@link NzdlRequest NzdlRequest}.<br>
+   * @return A list of words within the query string.
+   */
   public List getQueryTerms() {
     return m_queryTerms;
   }
-  
+
+   /**
+   * Returns the number of hits for each word within the query string. <br>
+   * Pre: A {@link NzdlResponse NzdlResponse} object has been created. A
+   * {@link NzdlService NzdlService} object has filled the NzdlResponse
+   * object with results from servicing a {@link NzdlRequest NzdlRequest}.<br>
+   * @return A map of the frequency of each query word. The map key is the query term..
+   */
   public Map getTermFrequencies() {
     return m_frequencies;
@@ -90 +163 @@
 //    }
 
+  /**
+   * Returns a list of Document ID's in the NzdlResultSet. <br>
+   * Pre: A {@link NzdlResponse NzdlResponse} object has been created. A
+   * {@link NzdlService NzdlService} object has filled the NzdlResponse
+   * object with results from servicing a {@link NzdlRequest NzdlRequest}.<br>
+   * @return A list of Document ID's in the NzdlResultSet.
+   */
     public List getDocumentIDs() {
       return m_docIDs;
@@ -105 +185 @@
 //    }
 
+  /**
+   * Returns metatag values for a document. <br>
+   * Pre: A {@link NzdlResponse NzdlResponse} object has been created. A
+   * {@link NzdlService NzdlService} object has filled the NzdlResponse
+   * object with results from servicing a {@link NzdlRequest NzdlRequest}.<br>
+   * @return A map of metatag values in the specified document. The key
+   * of the map is the metatag field such as Author or Title.
+   */
   public Set getMetaData( String _docID, String _metaTag ) {
     Map metaData = (Map) m_docToMetaDataMap.get( _docID );
@@ -110 +198 @@
   }
 
+  /**
+   * Returns all values for a particular metatag in the result set. <br>
+   * Pre: A {@link NzdlResponse NzdlResponse} object has been created. A
+   * {@link NzdlService NzdlService} object has filled the NzdlResponse
+   * object with results from servicing a {@link NzdlRequest NzdlRequest}.<br>
+   * @param metaTag Descriptive data such as Author, Title or Date.
+   * @return A map of all values for a particular metatag in all documents
+   * in the NzdlResultSet. The map key is document ID.
+   */
   public Map getMetaData( String _metaTag ) {
     Map metaData = new HashMap();
@@ -119 +216 @@
   }
 
+  /**
+   * Returns all values for all metatags in the result set. <br>
+   * Pre: A {@link NzdlResponse NzdlResponse} object has been created. A
+   * {@link NzdlService NzdlService} object has filled the NzdlResponse
+   * object with results from servicing a {@link NzdlRequest NzdlRequest}.<br>
+   * @return The metatag values for all metatags in all documents
+   * in the NzdlResultSet. The map key is document ID.
+   */
   public Map getAllMetaData( ) {
     return m_docToMetaDataMap;