Changeset 2108


Ignore:
Timestamp:
2001-03-05T08:44:51+13:00 (23 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 edited

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  ([email protected])
     35 * @author Aziz Mahoui    ([email protected])
     36 * @author Gordon Paynter ([email protected])
     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  ([email protected])
     35 * @author Aziz Mahoui    ([email protected])
     36 * @author Gordon Paynter ([email protected])
     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 ([email protected])
    5353 * @version $Revision$
    54  * @see
    55  * @see
    56  * @see
     54
    5755 *
    5856 */
Note: See TracChangeset for help on using the changeset viewer.