Changeset 2108

Show
Ignore:
Timestamp:
05.03.2001 08:44:51 (19 years ago)
Author:
bas6
Message:

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

Location:
trunk/java-client/org/nzdl/gsdl/service
Files:
5 modified

Legend:

Unmodified
Added
Removed
  • trunk/java-client/org/nzdl/gsdl/service/NzdlQuery.java

    r2107 r2108  
    4141  /**       
    4242   * Creates an instance of NzdlQuery with an empty query string. 
    43    *  Default values are: maxDocs 200, startResults= 1, endResults= 10, 
    44    *  queryType= "ranked", caseFolding= true, stemming= false, queryTerm= "". 
     43   * This can then be used as a constructor parameter when creating a 
     44   * {@link NzdlRequest NzdlRequest} object for servicing by a 
     45   * {@link NzdlService NzdlService} object. 
     46   * Default values for a NzdlQuery object are: maxDocs 200, startResults= 1, 
     47   *  endResults= 10, queryType= "ranked", caseFolding= true, stemming= false, 
     48   * queryTerm= "". 
    4549   */ 
    4650  public NzdlQuery() { 
     
    101105 
    102106  /** 
    103   * Sets query to ignore word endings. Default is false. 
    104   * @param stem if true, sets query to strip endings such as "...ing", 
    105   * "...ed". If false, sets query to only match whole words. 
     107  * Sets query to ignore word endings. Default is "false." 
     108  * @param stem if "true", sets query to strip endings such as "...ing", 
     109  * "...ed". If "false", sets query to only match whole words. 
    106110  */ 
    107111  public void setStemming(String _stem) { 
  • trunk/java-client/org/nzdl/gsdl/service/NzdlRequest.java

    r2098 r2108  
     1/* 
     2 *    NzdlRequest.java 
     3 *    Copyright (C) 2001 New Zealand Digital Library Project 
     4 * 
     5 *    This program is free software; you can redistribute it and/or modify 
     6 *    it under the terms of the GNU General Public License as published by 
     7 *    the Free Software Foundation; either version 2 of the License, or 
     8 *    (at your option) any later version. 
     9 * 
     10 *    This program is distributed in the hope that it will be useful, 
     11 *    but WITHOUT ANY WARRANTY; without even the implied warranty of 
     12 *    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the 
     13 *    GNU General Public License for more details. 
     14 * 
     15 *    You should have received a copy of the GNU General Public License 
     16 *    along with this program; if not, write to the Free Software 
     17 *    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. 
     18 */ 
    119 
     20//the package we're in 
    221package org.nzdl.gsdl.service; 
    322 
     
    625import java.util.*; 
    726 
     27/** 
     28 * An object that holds CORBA request data ready for by servicing by 
     29 * {@link NzdlService NzdlService}. NzdlRequest can receive data from: <br> 
     30 * - a {@link NzdlQuery NzdlQuery} object <br> 
     31 * - a document ID <br> 
     32 * - document ID's and a metatag. 
     33 * 
     34 * @author Stuart Yeates  (say1@cs.waikato.ac.nz) 
     35 * @author Aziz Mahoui    (amahoui@yahoo.com) 
     36 * @author Gordon Paynter (paynter@cs.waikato.ac.nz) 
     37 * @version $Revision$ 
     38 */ 
    839public class NzdlRequest extends java.lang.Object { 
    9  
    10   /** */ 
    1140 
    1241  private corbaFilterRequest m_Filter = null; 
    1342 
    14   /** */ 
    15  
     43  /** 
     44   * Creates an instance of NzdlRequest based on a search string inside a 
     45   * {@link NzdlQuery NzdlQuery} object. When serviced by 
     46   * {@link NzdlService NzdlService}, this type of request will return 
     47   * references to zero or more documents. <br> 
     48   * Pre:  Have already created instance of NzdlQuery object containing a 
     49   * search string.<br> 
     50   * Post: Created a query filter request that is ready for servicing. 
     51   * @param query a {@link NzdlQuery NzdlQuery} object containing a string 
     52   * search and options. 
     53   */ 
    1654  public NzdlRequest( NzdlQuery _query ) { 
    1755    m_Filter = NzdlCorbaFactory.createQueryFilterRequest( _query ); 
    1856  } 
    1957 
     58  /** 
     59   * Creates an instance of NzdlRequest based on a document ID. When serviced 
     60   * by {@link NzdlService NzdlService} this type of request will return 
     61   * exactly one document refernce. <br> 
     62   * Pre:  Have obtained a valid document ID.<br> 
     63   * Post: Created a browse filter request 
     64   * @param docID a string containing a valid GSDL document identifier. 
     65   */ 
    2066  public NzdlRequest( String _docID ) { 
    2167    m_Filter = NzdlCorbaFactory.createBrowseFilterRequest( _docID ); 
    2268  } 
    2369 
     70  /** 
     71   * Creates an instance of NzdlRequest based on a document ID and 
     72   * a metatag. <br> 
     73   * Pre:  Have obtained a valid document ID and a metatag field.<br> 
     74   * Post: Created a metadata filter request. 
     75   * @param docID a string containing a valid GSDL document identifier. 
     76   * @param metatag a string containing a valid GSDL metadata such as Title 
     77   * or Author. 
     78   */ 
    2479  public NzdlRequest( String _docID, String _metaTag ) { 
    2580    m_Filter = NzdlCorbaFactory.createMetaDataFilterRequest( _docID, _metaTag ); 
    2681  } 
    2782 
     83  /** 
     84   * Creates an instance of NzdlRequest based on a list of document ID's and 
     85   * a metatag. <br> 
     86   * Pre:  Have obtained a list of valid document ID's and a metatag field.<br> 
     87   * Post: Created a metadata filter request. 
     88   * @param docIDs a list of strings containing a valid GSDL document 
     89   * identifiers. 
     90   * @param metatag a string containing a valid GSDL metadata type such as 
     91   * Title Author. 
     92   */ 
    2893  public NzdlRequest( List _docIDs, String _metaTag ) { 
    2994    m_Filter = NzdlCorbaFactory.createMetaDataFilterRequest( _docIDs, _metaTag ); 
    3095  } 
    3196 
    32   /** */ 
    33  
     97  /** 
     98   * Returns the corbaFilterRequest for the NzdlRequest object. 
     99   * @return The corbaFilterRequest Object. 
     100   */ 
    34101  public corbaFilterRequest getFilter() { 
    35102    return m_Filter; 
  • trunk/java-client/org/nzdl/gsdl/service/NzdlResponse.java

    r2098 r2108  
     1/* 
     2 *    NzdlResponse.java 
     3 *    Copyright (C) 2001 New Zealand Digital Library Project 
     4 * 
     5 *    This program is free software; you can redistribute it and/or modify 
     6 *    it under the terms of the GNU General Public License as published by 
     7 *    the Free Software Foundation; either version 2 of the License, or 
     8 *    (at your option) any later version. 
     9 * 
     10 *    This program is distributed in the hope that it will be useful, 
     11 *    but WITHOUT ANY WARRANTY; without even the implied warranty of 
     12 *    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the 
     13 *    GNU General Public License for more details. 
     14 * 
     15 *    You should have received a copy of the GNU General Public License 
     16 *    along with this program; if not, write to the Free Software 
     17 *    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. 
     18 */ 
    119 
     20//the package we're in 
    221package org.nzdl.gsdl.service; 
    322 
     
    827import org.nzdl.gsdl.util.*; 
    928 
     29/** 
     30 * An object that holds data from a response after a 
     31 * {@link NzdlRequest NzdlRequest} has been serviced by 
     32 * {@link NzdlService NzdlService}. 
     33 * 
     34 * @author Stuart Yeates  (say1@cs.waikato.ac.nz) 
     35 * @author Aziz Mahoui    (amahoui@yahoo.com) 
     36 * @author Gordon Paynter (paynter@cs.waikato.ac.nz) 
     37 * @version $Revision$ 
     38 */ 
     39 
    1040public class NzdlResponse extends java.lang.Object { 
    11  
    12   /** */ 
    1341 
    1442  private corbaFilterResponseHolder m_responseHolder = null; 
     
    1846  private List m_queryTerms = null; 
    1947 
    20   /** */ 
    21  
     48  /** 
     49   * Create an empty instance of a NzdlResponse object. 
     50   */ 
    2251  public NzdlResponse( ) { 
    2352    m_responseHolder = NzdlCorbaFactory.createFilterResponseHolder(); 
    2453  } 
    2554 
     55  /** 
     56   * Get the corbaFilterReponse holder. 
     57   */ 
    2658  public corbaFilterResponseHolder getHolder() { 
    2759    return m_responseHolder; 
    2860  } 
    2961 
     62  /** 
     63   * Get the result of {@link NzdlService NzdlService} servicing a 
     64   * {@link NzdlRequest NzdlRequest}. <br> 
     65   * Pre: <br> 
     66   * - Created instances of: NzdlRequest, NzdlService and 
     67   * {@link NzdlResponse NzdlResponse}. <br> 
     68   * - NzdlService has serviced NzdlRequest. <br> 
     69   * - Created instance of {@link NzdlResultSet NzdlResultSet}. <br> 
     70   * Post: Copied result data from a NzdlResponse object into a NzdlResult 
     71   * set object <br><br> 
     72   * 
     73   * <B>Example Code</B> <br> 
     74   * <TT>NzdlQuery query = new NzdlQuery( "snail farming" );          <br> 
     75   * NzdlRequest request = new NzdlRequest( query );                  <br> 
     76   * NzdlResponse response = new NzdlResponse( );                     <br><br> 
     77   * // use service to get response from request to "demo" collection <br> 
     78   * NzdlService myService = new NzdlServiceClient( _args );          <br> 
     79   * myService.service( "demo", request, response );                  <br><br> 
     80   * // use getResultSet to get "results" from "response"             <br> 
     81   * NzdlResultSet results = <B>response.getResultSet();</B> </TT> 
     82   */ 
    3083  public NzdlResultSet getResultSet() { 
    3184    if ( m_resultSet == null ) { 
     
    67120  */ 
    68121 
     122 
     123  /** 
     124   * Parse the CORBA filter response object 
     125   */ 
    69126  private void parseResponse () { 
    70127    m_response = m_responseHolder.value; 
     
    134191} 
    135192 
    136  
  • trunk/java-client/org/nzdl/gsdl/service/NzdlResultSet.java

    r2098 r2108  
    1  
     1/* 
     2 *    NzdlResultSet.java 
     3 *    Copyright (C) 2001 New Zealand Digital Library Project 
     4 * 
     5 *    This program is free software; you can redistribute it and/or modify 
     6 *    it under the terms of the GNU General Public License as published by 
     7 *    the Free Software Foundation; either version 2 of the License, or 
     8 *    (at your option) any later version. 
     9 * 
     10 *    This program is distributed in the hope that it will be useful, 
     11 *    but WITHOUT ANY WARRANTY; without even the implied warranty of 
     12 *    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the 
     13 *    GNU General Public License for more details. 
     14 * 
     15 *    You should have received a copy of the GNU General Public License 
     16 *    along with this program; if not, write to the Free Software 
     17 *    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. 
     18 */ 
     19 
     20//the package we're in 
    221package org.nzdl.gsdl.service; 
    322 
    423import java.util.*; 
    524 
     25/** 
     26 * An object that holds results extracted from a response by 
     27 * {@link NzdlResponse#getResultSet() NzdlResponse.getResultSet()}. 
     28 * Easily interrogated by a user. 
     29 */ 
    630public class NzdlResultSet extends java.lang.Object { 
    731 
     
    1135  private List m_queryTerms  = null; 
    1236  private List m_docIDs = null; 
    13   /** the key is the query term, the value its frequency */ 
     37 
     38  /* The key is the query term, the value its frequency */ 
    1439  private Map m_frequencies = null; 
    15   /**  
    16    * the key is the docID, the value is the doc corresponding  
     40 
     41  /* 
     42   * The key is the docID, the value is the doc corresponding 
    1743   * meta data which is also a Map where the key is the meta tag 
    1844   * and the value is a set of values for that tag 
     
    2046  private Map m_docToMetaDataMap = null; 
    2147 
    22   /** */ 
    23    
     48  /** 
     49   * Creates an empty instance of NzdlResultSet. 
     50   */ 
    2451  public NzdlResultSet() { 
    2552    m_resultSet = new ArrayList(); 
     
    2855  } 
    2956 
    30   /** */ 
    31  
     57  /** 
     58   * Adds a {@link NzdlQueryHit NzdlQueryHit} to a result set. 
     59   * @param hit - is an instance of NzdlQueryHit. 
     60   */ 
    3261  public void add( NzdlQueryHit _hit ) { 
    3362    m_resultSet.add( _hit ) ; 
     
    3766  } 
    3867 
     68    /** 
     69   * Sets the number of documents in a NzdlResultSet. 
     70   * @param num the number of documents in the result set 
     71   */ 
    3972  public void setNumOfDocs( int _num ) { 
    4073    m_numDocs = _num; 
    4174  } 
    4275 
     76 
     77  /** 
     78   * Sets the result type. 
     79   * @param type an integer representing the result type. 
     80   */ 
    4381  public void setResultType( int _type ) { 
    4482    m_resultType = _type; 
    4583  } 
    4684 
     85  /** 
     86   * Sets the Query terms of a NzdlResultSet. 
     87   * @param terms a list of words within the query string. 
     88   */ 
    4789  public void setQueryTerms( List _terms ) { 
    4890    m_queryTerms = _terms; 
     
    5395//    } 
    5496 
     97  /** 
     98   * Sets the term frequencies within a NzdlResultSet. 
     99   * @param freqs a map of the term frequencies. The map key is the query term. 
     100   */ 
    55101  public void setTermFrequencies( Map _freqs ) { 
    56102    m_frequencies = _freqs; 
    57103  } 
    58104 
    59   /** */ 
    60  
     105  /** 
     106   * Returns the number of documents that matched a query. <br> 
     107   * Pre: A {@link NzdlResponse NzdlResponse} object has been created. A 
     108   * {@link NzdlService NzdlService} object has filled the NzdlResponse 
     109   * object with results from servicing a {@link NzdlRequest NzdlRequest}.<br> 
     110   * @return The number of documents that matched a query. This is limited 
     111   * by the maxDocs set in {@link NzdlQuery NzdlQuery} 
     112   */ 
    61113  public int getNumOfDocs() { 
    62114    return m_numDocs; 
    63115  } 
    64116 
     117  /** 
     118   * Returns the result type for the NzdlResultSet. <br> 
     119   * Pre: A {@link NzdlResponse NzdlResponse} object has been created. A 
     120   * {@link NzdlService NzdlService} object has filled the NzdlResponse 
     121   * object with results from servicing a {@link NzdlRequest NzdlRequest}.<br> 
     122   * @return result type as an integer. 
     123   */ 
    65124  public int getResultType() { 
    66125    return m_resultType; 
    67126  } 
    68127 
     128  /** 
     129   * Returns a list of the words within the query string. <br> 
     130   * Pre: A {@link NzdlResponse NzdlResponse} object has been created. A 
     131   * {@link NzdlService NzdlService} object has filled the NzdlResponse 
     132   * object with results from servicing a {@link NzdlRequest NzdlRequest}.<br> 
     133   * @return A list of words within the query string. 
     134   */ 
    69135  public List getQueryTerms() { 
    70136    return m_queryTerms; 
    71137  } 
    72    
     138 
     139   /** 
     140   * Returns the number of hits for each word within the query string. <br> 
     141   * Pre: A {@link NzdlResponse NzdlResponse} object has been created. A 
     142   * {@link NzdlService NzdlService} object has filled the NzdlResponse 
     143   * object with results from servicing a {@link NzdlRequest NzdlRequest}.<br> 
     144   * @return A map of the frequency of each query word. The map key is the query term.. 
     145   */ 
    73146  public Map getTermFrequencies() { 
    74147    return m_frequencies; 
     
    90163//    } 
    91164 
     165  /** 
     166   * Returns a list of Document ID's in the NzdlResultSet. <br> 
     167   * Pre: A {@link NzdlResponse NzdlResponse} object has been created. A 
     168   * {@link NzdlService NzdlService} object has filled the NzdlResponse 
     169   * object with results from servicing a {@link NzdlRequest NzdlRequest}.<br> 
     170   * @return A list of Document ID's in the NzdlResultSet. 
     171   */ 
    92172    public List getDocumentIDs() { 
    93173      return m_docIDs; 
     
    105185//    } 
    106186 
     187  /** 
     188   * Returns metatag values for a document. <br> 
     189   * Pre: A {@link NzdlResponse NzdlResponse} object has been created. A 
     190   * {@link NzdlService NzdlService} object has filled the NzdlResponse 
     191   * object with results from servicing a {@link NzdlRequest NzdlRequest}.<br> 
     192   * @return A map of metatag values in the specified document. The key 
     193   * of the map is the metatag field such as Author or Title. 
     194   */ 
    107195  public Set getMetaData( String _docID, String _metaTag ) { 
    108196    Map metaData = (Map) m_docToMetaDataMap.get( _docID ); 
     
    110198  } 
    111199 
     200  /** 
     201   * Returns all values for a particular metatag in the result set. <br> 
     202   * Pre: A {@link NzdlResponse NzdlResponse} object has been created. A 
     203   * {@link NzdlService NzdlService} object has filled the NzdlResponse 
     204   * object with results from servicing a {@link NzdlRequest NzdlRequest}.<br> 
     205   * @param metaTag Descriptive data such as Author, Title or Date. 
     206   * @return A map of all values for a particular metatag in all documents 
     207   * in the NzdlResultSet. The map key is document ID. 
     208   */ 
    112209  public Map getMetaData( String _metaTag ) { 
    113210    Map metaData = new HashMap(); 
     
    119216  } 
    120217 
     218  /** 
     219   * Returns all values for all metatags in the result set. <br> 
     220   * Pre: A {@link NzdlResponse NzdlResponse} object has been created. A 
     221   * {@link NzdlService NzdlService} object has filled the NzdlResponse 
     222   * object with results from servicing a {@link NzdlRequest NzdlRequest}.<br> 
     223   * @return The metatag values for all metatags in all documents 
     224   * in the NzdlResultSet. The map key is document ID. 
     225   */ 
    121226  public Map getAllMetaData( ) { 
    122227    return m_docToMetaDataMap; 
  • trunk/java-client/org/nzdl/gsdl/service/NzdlServiceServer.java

    r2098 r2108  
    5252 * @author stuart yeates (say1@cs.waikato.ac.nz) 
    5353 * @version $Revision$ 
    54  * @see 
    55  * @see 
    56  * @see 
     54 
    5755 *  
    5856 */