Index: /trunk/java-client/org/nzdl/gsdl/service/NzdlQuery.java
===================================================================
--- /trunk/java-client/org/nzdl/gsdl/service/NzdlQuery.java (revision 2107)
+++ /trunk/java-client/org/nzdl/gsdl/service/NzdlQuery.java (revision 2108)
@@ -41,6 +41,10 @@
/**
* 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= "".
+ * 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() {
@@ -101,7 +105,7 @@
/**
- * 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.
+ * 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) {
Index: /trunk/java-client/org/nzdl/gsdl/service/NzdlRequest.java
===================================================================
--- /trunk/java-client/org/nzdl/gsdl/service/NzdlRequest.java (revision 2107)
+++ /trunk/java-client/org/nzdl/gsdl/service/NzdlRequest.java (revision 2108)
@@ -1,3 +1,22 @@
+/*
+ * NzdlRequest.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;
@@ -6,30 +25,78 @@
import java.util.*;
+/**
+ * An object that holds CORBA request data ready for by servicing by
+ * {@link NzdlService NzdlService}. NzdlRequest can receive data from:
+ * - a {@link NzdlQuery NzdlQuery} object
+ * - a document ID
+ * - document ID's and a metatag.
+ *
+ * @author Stuart Yeates (say1@cs.waikato.ac.nz)
+ * @author Aziz Mahoui (amahoui@yahoo.com)
+ * @author Gordon Paynter (paynter@cs.waikato.ac.nz)
+ * @version $Revision$
+ */
public class NzdlRequest extends java.lang.Object {
-
- /** */
private corbaFilterRequest m_Filter = null;
- /** */
-
+ /**
+ * Creates an instance of NzdlRequest based on a search string inside a
+ * {@link NzdlQuery NzdlQuery} object. When serviced by
+ * {@link NzdlService NzdlService}, this type of request will return
+ * references to zero or more documents.
+ * Pre: Have already created instance of NzdlQuery object containing a
+ * search string.
+ * Post: Created a query filter request that is ready for servicing.
+ * @param query a {@link NzdlQuery NzdlQuery} object containing a string
+ * search and options.
+ */
public NzdlRequest( NzdlQuery _query ) {
m_Filter = NzdlCorbaFactory.createQueryFilterRequest( _query );
}
+ /**
+ * Creates an instance of NzdlRequest based on a document ID. When serviced
+ * by {@link NzdlService NzdlService} this type of request will return
+ * exactly one document refernce.
+ * Pre: Have obtained a valid document ID.
+ * Post: Created a browse filter request
+ * @param docID a string containing a valid GSDL document identifier.
+ */
public NzdlRequest( String _docID ) {
m_Filter = NzdlCorbaFactory.createBrowseFilterRequest( _docID );
}
+ /**
+ * Creates an instance of NzdlRequest based on a document ID and
+ * a metatag.
+ * Pre: Have obtained a valid document ID and a metatag field.
+ * Post: Created a metadata filter request.
+ * @param docID a string containing a valid GSDL document identifier.
+ * @param metatag a string containing a valid GSDL metadata such as Title
+ * or Author.
+ */
public NzdlRequest( String _docID, String _metaTag ) {
m_Filter = NzdlCorbaFactory.createMetaDataFilterRequest( _docID, _metaTag );
}
+ /**
+ * Creates an instance of NzdlRequest based on a list of document ID's and
+ * a metatag.
+ * Pre: Have obtained a list of valid document ID's and a metatag field.
+ * Post: Created a metadata filter request.
+ * @param docIDs a list of strings containing a valid GSDL document
+ * identifiers.
+ * @param metatag a string containing a valid GSDL metadata type such as
+ * Title Author.
+ */
public NzdlRequest( List _docIDs, String _metaTag ) {
m_Filter = NzdlCorbaFactory.createMetaDataFilterRequest( _docIDs, _metaTag );
}
- /** */
-
+ /**
+ * Returns the corbaFilterRequest for the NzdlRequest object.
+ * @return The corbaFilterRequest Object.
+ */
public corbaFilterRequest getFilter() {
return m_Filter;
Index: /trunk/java-client/org/nzdl/gsdl/service/NzdlResponse.java
===================================================================
--- /trunk/java-client/org/nzdl/gsdl/service/NzdlResponse.java (revision 2107)
+++ /trunk/java-client/org/nzdl/gsdl/service/NzdlResponse.java (revision 2108)
@@ -1,3 +1,22 @@
+/*
+ * NzdlResponse.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;
@@ -8,7 +27,16 @@
import org.nzdl.gsdl.util.*;
+/**
+ * An object that holds data from a response after a
+ * {@link NzdlRequest NzdlRequest} has been serviced by
+ * {@link NzdlService NzdlService}.
+ *
+ * @author Stuart Yeates (say1@cs.waikato.ac.nz)
+ * @author Aziz Mahoui (amahoui@yahoo.com)
+ * @author Gordon Paynter (paynter@cs.waikato.ac.nz)
+ * @version $Revision$
+ */
+
public class NzdlResponse extends java.lang.Object {
-
- /** */
private corbaFilterResponseHolder m_responseHolder = null;
@@ -18,14 +46,39 @@
private List m_queryTerms = null;
- /** */
-
+ /**
+ * Create an empty instance of a NzdlResponse object.
+ */
public NzdlResponse( ) {
m_responseHolder = NzdlCorbaFactory.createFilterResponseHolder();
}
+ /**
+ * Get the corbaFilterReponse holder.
+ */
public corbaFilterResponseHolder getHolder() {
return m_responseHolder;
}
+ /**
+ * Get the result of {@link NzdlService NzdlService} servicing a
+ * {@link NzdlRequest NzdlRequest}.
+ * Pre:
+ * - Created instances of: NzdlRequest, NzdlService and
+ * {@link NzdlResponse NzdlResponse}.
+ * - NzdlService has serviced NzdlRequest.
+ * - Created instance of {@link NzdlResultSet NzdlResultSet}.
+ * Post: Copied result data from a NzdlResponse object into a NzdlResult
+ * set object
+ *
+ * Example Code
+ * NzdlQuery query = new NzdlQuery( "snail farming" );
+ * NzdlRequest request = new NzdlRequest( query );
+ * NzdlResponse response = new NzdlResponse( );
+ * // use service to get response from request to "demo" collection
+ * NzdlService myService = new NzdlServiceClient( _args );
+ * myService.service( "demo", request, response );
+ * // use getResultSet to get "results" from "response"
+ * NzdlResultSet results = response.getResultSet();
+ */
public NzdlResultSet getResultSet() {
if ( m_resultSet == null ) {
@@ -67,4 +120,8 @@
*/
+
+ /**
+ * Parse the CORBA filter response object
+ */
private void parseResponse () {
m_response = m_responseHolder.value;
@@ -134,3 +191,2 @@
}
-
Index: /trunk/java-client/org/nzdl/gsdl/service/NzdlResultSet.java
===================================================================
--- /trunk/java-client/org/nzdl/gsdl/service/NzdlResultSet.java (revision 2107)
+++ /trunk/java-client/org/nzdl/gsdl/service/NzdlResultSet.java (revision 2108)
@@ -1,7 +1,31 @@
-
+/*
+ * 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,8 +35,10 @@
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,6 +46,7 @@
private Map m_docToMetaDataMap = null;
- /** */
-
+ /**
+ * Creates an empty instance of NzdlResultSet.
+ */
public NzdlResultSet() {
m_resultSet = new ArrayList();
@@ -28,6 +55,8 @@
}
- /** */
-
+ /**
+ * 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,12 +66,25 @@
}
+ /**
+ * 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,22 +95,53 @@
// }
+ /**
+ * 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.
+ * 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}.
+ * @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.
+ * 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}.
+ * @return result type as an integer.
+ */
public int getResultType() {
return m_resultType;
}
+ /**
+ * Returns a list of the words within the query string.
+ * 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}.
+ * @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.
+ * 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}.
+ * @return A map of the frequency of each query word. The map key is the query term..
+ */
public Map getTermFrequencies() {
return m_frequencies;
@@ -90,4 +163,11 @@
// }
+ /**
+ * Returns a list of Document ID's in the NzdlResultSet.
+ * 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}.
+ * @return A list of Document ID's in the NzdlResultSet.
+ */
public List getDocumentIDs() {
return m_docIDs;
@@ -105,4 +185,12 @@
// }
+ /**
+ * Returns metatag values for a document.
+ * 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}.
+ * @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,4 +198,13 @@
}
+ /**
+ * Returns all values for a particular metatag in the result set.
+ * 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}.
+ * @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,4 +216,12 @@
}
+ /**
+ * Returns all values for all metatags in the result set.
+ * 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}.
+ * @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;
Index: /trunk/java-client/org/nzdl/gsdl/service/NzdlServiceServer.java
===================================================================
--- /trunk/java-client/org/nzdl/gsdl/service/NzdlServiceServer.java (revision 2107)
+++ /trunk/java-client/org/nzdl/gsdl/service/NzdlServiceServer.java (revision 2108)
@@ -52,7 +52,5 @@
* @author stuart yeates (say1@cs.waikato.ac.nz)
* @version $Revision$
- * @see
- * @see
- * @see
+
*
*/