org.greenstone.gs3services
Class QBRSOAPServer

java.lang.Object
  extended by org.greenstone.gs3services.QBRSOAPServer

public class QBRSOAPServer
extends java.lang.Object

Class that provides the basic Query, Browse and Retrieve (QBR) web service operations for Greenstone 3. It contains a MessageRouter that carries out all the tasks by calling the appropriate Greenstone functionality for each request message passed to it, and returning a response message. All response messages are returned from the MessageRouter to clients invoking the web services. All return values are strings that represent XML messages. Method help() reads from the file QBRWebServicesHelp.properties to list the web service operations available. Method helpWithMethod(String methodName) reads from the same file to display a description of the requested operation. (These method descriptions are mostly the same as those in the Javadoc comments.) NOTE: to run this class, the folder containing this web service class' properties helpFile should be on the classpath.

Author:
ak19

Field Summary
protected static java.lang.String browseStructureOptions
           
protected  org.greenstone.gsdl3.util.XMLConverter converter
          A converter class to parse XML and create Docs
protected static java.lang.String csSubsetOptions
           
protected  org.w3c.dom.Document doc
          Container Document to create XML Nodes
protected static java.lang.String docStructureInfo
           
protected static java.lang.String docStructureOptions
           
protected static java.lang.String helpErrormessage
          Error message loading helpFile.
protected static java.lang.String helpFile
          The help properties file describing the web service operations
protected  org.greenstone.gsdl3.core.MessageRouter mr
          Message Router object to pass requests messages to and which will process them.
protected static java.lang.String mrSubsetOptions
           
protected static java.util.Properties properties
          Properties map with mappings from methodname to help description string.
protected static java.lang.String serviceSubsetOptions
           
protected  java.lang.String site_name
          site_name the MessageRouter works with, here set to "localsite"
 
Constructor Summary
QBRSOAPServer()
          Constructor that initializes the web services' MessageRouter object Reads from GlobalProperties to get gsdl3_home and set the sitename.
 
Method Summary
 java.lang.String basicQuery(java.lang.String collection, java.lang.String lang, java.lang.String query)
          This method is used to perform the most basic query: it assumes defaults for all other parameters and provides only the query string.
 java.lang.String browse(java.lang.String collection, java.lang.String browseService, java.lang.String lang, java.lang.String[] classifierNodeIDs, java.lang.String[] structureParams)
          To send a browse request for specific parts of a classifier node (children, ancestors, descendants).
 java.lang.String browseDescendants(java.lang.String collection, java.lang.String browseService, java.lang.String lang, java.lang.String[] classifierNodeIDs)
          To send a browse request for all the descendants of a classifier node.
 java.lang.String describe(java.lang.String lang, java.lang.String subsetOption)
          Sends a describe message to the MessageRouter.
protected  java.lang.String describe(java.lang.String to, java.lang.String lang, java.lang.String subsetOption, java.lang.String validSubsetOptions)
          For sending a describe message.
 java.lang.String describeCollection(java.lang.String collection, java.lang.String lang, java.lang.String subsetOption)
          For sending Describe messages to Collections.
 java.lang.String describeCollectionService(java.lang.String collection, java.lang.String service, java.lang.String lang, java.lang.String subsetOption)
          For sending a describe message to a Collection's Service.
 java.lang.String describeService(java.lang.String service, java.lang.String lang, java.lang.String subsetOption)
          For sending a describe message to a Service hosted by the Message Router (no collection).
 java.lang.String describeServiceCluster(java.lang.String serviceCluster, java.lang.String lang, java.lang.String subsetOption)
          For sending Describe messages to ServiceClusters.
protected  java.lang.String error(java.lang.String errorMessage)
          Creates a String response message to represent an XML error response message using the error specified in the message parameter.
static java.lang.String help()
           
static java.lang.String helpWithMethod(java.lang.String methodname)
           
static void main(java.lang.String[] args)
           
protected  java.lang.String metadataRetrieve(java.lang.String to, java.lang.String lang, java.lang.String[] nodeIDs, java.lang.String[] metaNames, java.lang.String NODE_ELEM)
          Performs a metadata retrieve for documents and (browse) classification hierarchies.
protected  java.lang.String processInternal(org.w3c.dom.Element message)
          Called by most other methods in order to send the constructed message to the Greenstone's MessageRouter, intercept the response and return it.
 java.lang.String query(java.lang.String collection, java.lang.String service, java.lang.String lang, java.util.Map nameToValsMap)
          For executing a (process-type message) query-type service.
 java.lang.String retrieveAllBrowseMetadata(java.lang.String collection, java.lang.String categoryName, java.lang.String lang, java.lang.String[] nodeIDs)
          Retrieve all classification Metadata for browsing (sent to the ClassifierBrowseMetadataRetrieve service).
 java.lang.String retrieveAllDocumentMetadata(java.lang.String collection, java.lang.String lang, java.lang.String[] docNodeIDs)
          DocumentMetadataRetrieve request sent to a collection's DocumentMetadataRetrieve service to retrieve all of a document's metadata.
 java.lang.String retrieveBrowseMetadata(java.lang.String collection, java.lang.String categoryName, java.lang.String lang, java.lang.String[] nodeIDs, java.lang.String[] metaNames)
          ClassifierBrowseMetadataRetrieve service to retrieve some specific metadata values of a document.
 java.lang.String retrieveDocumentContent(java.lang.String collection, java.lang.String lang, java.lang.String[] docNodeIDs)
          DocumentContentRetrieve request sent to a collection's DocumentContentRetrieve service (see manual, p.48)
 java.lang.String retrieveDocumentMetadata(java.lang.String collection, java.lang.String lang, java.lang.String[] docNodeIDs, java.lang.String[] metaNames)
          DocumentMetadataRetrieve service to retrieve some specific metadata values of a document.
 java.lang.String retrieveDocumentStructure(java.lang.String collection, java.lang.String lang, java.lang.String[] docNodeIDs, java.lang.String[] structure, java.lang.String[] info)
          DocumentStructureRetrieve request sent to a collection's DocumentStructureRetrieve service (manual pp.48, 49) to retrieve the specified part of the document's structure.
 java.lang.String retrieveEntireDocumentStructure(java.lang.String collection, java.lang.String lang, java.lang.String[] docNodeIDs)
          DocumentStructureRetrieve request sent to a collection's DocumentStructureRetrieve service (manual pp.48, 49) to retrieve the entire document structure.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

helpErrormessage

protected static java.lang.String helpErrormessage
Error message loading helpFile. Remains at "" if everything is fine


properties

protected static java.util.Properties properties
Properties map with mappings from methodname to help description string.


helpFile

protected static java.lang.String helpFile
The help properties file describing the web service operations


site_name

protected java.lang.String site_name
site_name the MessageRouter works with, here set to "localsite"


mr

protected org.greenstone.gsdl3.core.MessageRouter mr
Message Router object to pass requests messages to and which will process them.


doc

protected org.w3c.dom.Document doc
Container Document to create XML Nodes


converter

protected org.greenstone.gsdl3.util.XMLConverter converter
A converter class to parse XML and create Docs


mrSubsetOptions

protected static final java.lang.String mrSubsetOptions
See Also:
Constant Field Values

csSubsetOptions

protected static final java.lang.String csSubsetOptions
See Also:
Constant Field Values

serviceSubsetOptions

protected static final java.lang.String serviceSubsetOptions
See Also:
Constant Field Values

docStructureOptions

protected static final java.lang.String docStructureOptions
See Also:
Constant Field Values

docStructureInfo

protected static final java.lang.String docStructureInfo
See Also:
Constant Field Values

browseStructureOptions

protected static final java.lang.String browseStructureOptions
See Also:
Constant Field Values
Constructor Detail

QBRSOAPServer

public QBRSOAPServer()
Constructor that initializes the web services' MessageRouter object Reads from GlobalProperties to get gsdl3_home and set the sitename.

Method Detail

describe

public java.lang.String describe(java.lang.String lang,
                                 java.lang.String subsetOption)
Sends a describe message to the MessageRouter.

Parameters:
lang - is the language of the display content in the response.
subsetOption - are the requested list of items to return in the response. For the Message Router this can be collectionList, serviceClusterList, serviceList, siteList
See Also:
The Greenstone 3 Developer's Manual - pages 35-41

describeServiceCluster

public java.lang.String describeServiceCluster(java.lang.String serviceCluster,
                                               java.lang.String lang,
                                               java.lang.String subsetOption)
For sending Describe messages to ServiceClusters.

Parameters:
serviceCluster - is the name of the Service Cluster that this describe request is sent to.
lang - is the language of the display content in the response
subsetOption - is the requested list of items to return in the response For Service Clusters this can be metadataList, serviceList, displayItemList.
See Also:
The Greenstone 3 Developer's Manual - pages 35-41

describeCollection

public java.lang.String describeCollection(java.lang.String collection,
                                           java.lang.String lang,
                                           java.lang.String subsetOption)
For sending Describe messages to Collections.

Parameters:
collection - is the name of the Collection that this describe request is sent to.
lang - is the language of the display content in the response
subsetOption - is the requested list of items to return in the response For Collections this can be metadataList, serviceList and displayItemList.
See Also:
The Greenstone 3 Developer's Manual - pages 35-41

describeCollectionService

public java.lang.String describeCollectionService(java.lang.String collection,
                                                  java.lang.String service,
                                                  java.lang.String lang,
                                                  java.lang.String subsetOption)
For sending a describe message to a Collection's Service.

Parameters:
collection - is the name of the Collection whose service this describe request is sent to.
service - is the name of the Service (of that collection) to which this describe request is sent.
lang - is the language of the display content in the response
subsetOption - is the requested list of items to return in the response For Services this can be paramList, displayItemList
See Also:
The Greenstone 3 Developer's Manual - pages 35-41

describeService

public java.lang.String describeService(java.lang.String service,
                                        java.lang.String lang,
                                        java.lang.String subsetOption)
For sending a describe message to a Service hosted by the Message Router (no collection).

Parameters:
service - is the name of the MessageRouter's Service to which this describe request is sent.
lang - is the language of the display content in the response
subsetOption - is the requested list of items to return in the response For Services this can be paramList, displayItemList
See Also:
The Greenstone 3 Developer's Manual - pages 35-41

describe

protected java.lang.String describe(java.lang.String to,
                                    java.lang.String lang,
                                    java.lang.String subsetOption,
                                    java.lang.String validSubsetOptions)
For sending a describe message. If public, this method would give full access: a describe message that lets the user specify all the details of who the receiver is, and what details are requested.

Parameters:
to - - the Greenstone module (MessageRouter, Collection, ServiceCluster or (Collection-)Service to send this describe message to. (The module asked to describe itself.)
lang - - the language of the display content in the response.
subsetOption - - the set of elements of the describe response that are requested. These vary depending on the GS3 module asked to describe itself.
validSubsetOptions - - the list of subsetOptions that are allowed for the module this describe message is sent to. Parameter subsetOption has to be among the list of validSubsetOptions.
See Also:
The Greenstone 3 Developer's Manual - pages 35-41

query

public java.lang.String query(java.lang.String collection,
                              java.lang.String service,
                              java.lang.String lang,
                              java.util.Map nameToValsMap)
For executing a (process-type message) query-type service.

Parameters:
collection - is the name of the Collection whose query service this query-process request is sent to. If "", then the Message Router is assumed.
service - is the name of the Query Service (of that collection) to which this request is sent.
lang - is the language of the display content in the response
nameToValsMap - is a Map of the (fieldname, value) pairs for the parameters of the query. The field names should be those recognised by Greenstone 3. That is, the names must exist for the (Collection-)Service Query that this message is sent To (as given in 'to' argument). For names of Greenstone-accepted arguments,
See Also:
The Greenstone 3 Developer's Manual - page 45, Greenstone wiki - Actions and Arguments

basicQuery

public java.lang.String basicQuery(java.lang.String collection,
                                   java.lang.String lang,
                                   java.lang.String query)
This method is used to perform the most basic query: it assumes defaults for all other parameters and provides only the query string. It is built on top of a TextQuery.

Parameters:
collection - is the Greenstone collection to be searched
lang - is the preferred language of the display content in the response to be returned.
query - is the string to be sought in the Greenstone collection
Returns:
a Greenstone 3 XML response message for the query specifying the search results.

retrieveDocumentContent

public java.lang.String retrieveDocumentContent(java.lang.String collection,
                                                java.lang.String lang,
                                                java.lang.String[] docNodeIDs)
DocumentContentRetrieve request sent to a collection's DocumentContentRetrieve service (see manual, p.48)

Parameters:
collection - is the name of the Collection whose DocumentContentRetrieve is requested
lang - is the language of the display content in the response
docNodeIDs - is the list of documentNodeIDs for which the content ought to be retrieved.
See Also:
The Greenstone 3 Developer's Manual - page 48

retrieveEntireDocumentStructure

public java.lang.String retrieveEntireDocumentStructure(java.lang.String collection,
                                                        java.lang.String lang,
                                                        java.lang.String[] docNodeIDs)
DocumentStructureRetrieve request sent to a collection's DocumentStructureRetrieve service (manual pp.48, 49) to retrieve the entire document structure.

Parameters:
collection - is the name of the Collection whose DocumentStructureRetrieve is requested
lang - is the language of the display content in the response
docNodeIDs - is the list of documentNodeIDs for which the entire structure ought to be retrieved.
See Also:
The Greenstone 3 Developer's Manual - pages 48, 49

retrieveDocumentStructure

public java.lang.String retrieveDocumentStructure(java.lang.String collection,
                                                  java.lang.String lang,
                                                  java.lang.String[] docNodeIDs,
                                                  java.lang.String[] structure,
                                                  java.lang.String[] info)
DocumentStructureRetrieve request sent to a collection's DocumentStructureRetrieve service (manual pp.48, 49) to retrieve the specified part of the document's structure.

Parameters:
collection - is the name of the Collection whose DocumentStructureRetrieve is requested
lang - is the language of the display content in the response
docNodeIDs - is the list of documentNodeIDs for which the structure ought to be retrieved.
structure - specifies what structure information needs to be retrieved. The values can be one or more of ancestors, parent, siblings, children, descendants (note spelling), entire.
info - - for specifying extra information to be retrieved. Possible values for info parameters are numSiblings, siblingPosition, numChildren
See Also:
The Greenstone 3 Developer's Manual - pages 48, 49

retrieveAllDocumentMetadata

public java.lang.String retrieveAllDocumentMetadata(java.lang.String collection,
                                                    java.lang.String lang,
                                                    java.lang.String[] docNodeIDs)
DocumentMetadataRetrieve request sent to a collection's DocumentMetadataRetrieve service to retrieve all of a document's metadata.

Parameters:
collection - is the name of the Collection whose DocumentMetadataRetrieve is requested
lang - is the language of the display content in the response
docNodeIDs - is the list of documentNodeIDs for which the structure ought to be retrieved.
See Also:
The Greenstone 3 Developer's Manual - page 47

retrieveDocumentMetadata

public java.lang.String retrieveDocumentMetadata(java.lang.String collection,
                                                 java.lang.String lang,
                                                 java.lang.String[] docNodeIDs,
                                                 java.lang.String[] metaNames)
DocumentMetadataRetrieve service to retrieve some specific metadata values of a document. (Manual on page 47.)

Parameters:
collection - is the name of the Collection whose DocumentContentRetrieve is requested
lang - is the language of the display content in the response
docNodeIDs - is the list of documentNodeIDs for which the structure ought to be retrieved.
metaNames - is a list of metadata names which are requested to be fetched for the specified documents
See Also:
The Greenstone 3 Developer's Manual - page 47

retrieveAllBrowseMetadata

public java.lang.String retrieveAllBrowseMetadata(java.lang.String collection,
                                                  java.lang.String categoryName,
                                                  java.lang.String lang,
                                                  java.lang.String[] nodeIDs)
Retrieve all classification Metadata for browsing (sent to the ClassifierBrowseMetadataRetrieve service).

Parameters:
collection - is the name of the Collection whose ClassifierBrowseMetadataRetrieve service is called
categoryName - - name of the browsing category, usually ClassifierBrowse. (If left as "", then it defaults to ClassifierBrowse)
lang - is the language of the display content in the response
nodeIDs - is the list of document or classifier NodeIDs for which the metadata ought to be retrieved.
See Also:
The Greenstone 3 Developer's Manual - pages 47, 48

retrieveBrowseMetadata

public java.lang.String retrieveBrowseMetadata(java.lang.String collection,
                                               java.lang.String categoryName,
                                               java.lang.String lang,
                                               java.lang.String[] nodeIDs,
                                               java.lang.String[] metaNames)
ClassifierBrowseMetadataRetrieve service to retrieve some specific metadata values of a document.

Parameters:
collection - is the name of the Collection whose ClassifierBrowseMetadataRetrieve service is called
categoryName - - name of the browsing category, usually ClassifierBrowse. (If left as "", then it defaults to ClassifierBrowse)
lang - is the language of the display content in the response
nodeIDs - is the list of document or classifier NodeIDs for which the metadata ought to be retrieved.
metaNames - is a list of metadata names which are requested to be fetched for the specified documents or classifiers
See Also:
The Greenstone 3 Developer's Manual - pages 47, 48

metadataRetrieve

protected java.lang.String metadataRetrieve(java.lang.String to,
                                            java.lang.String lang,
                                            java.lang.String[] nodeIDs,
                                            java.lang.String[] metaNames,
                                            java.lang.String NODE_ELEM)
Performs a metadata retrieve for documents and (browse) classification hierarchies. Sends a Document- or ClassifierBrowse- MetadataRetrieve message to the Document- or ClassifierBrowse- MetadataRetrieve service.

Parameters:
to - - the Document- or ClassifierBrowse- MetadataRetrieve service to send this metadata retrieve message to.
lang - - the language of the display content in the response
nodeIDs - - the list of (document or classifier) nodeIDs for which to retrieve the metadata for
metaNames - - a list specifiying the names of the metadata items to be retrieved for each nodeID. E.g. "Title", but a list is allowed.
NODE_ELEM - - either of GSXML's names for the <documentNode> or <classifierNode> elements.

browseDescendants

public java.lang.String browseDescendants(java.lang.String collection,
                                          java.lang.String browseService,
                                          java.lang.String lang,
                                          java.lang.String[] classifierNodeIDs)
To send a browse request for all the descendants of a classifier node. Useful for getting the entire structure of a top-level <classificationNode>

Parameters:
collection - is the name of the Collection whose browse Classifier Browse Service is called
browseService - is the name of the (Classifier) Browse Service (of the given collection) to which this request message is sent.
lang - is the language of the display content in the response
classifierNodeIDs - is an array of classifierNodeIDs for which the structures ought to be retrieved.
See Also:
The Greenstone 3 Developer's Manual - page 46

browse

public java.lang.String browse(java.lang.String collection,
                               java.lang.String browseService,
                               java.lang.String lang,
                               java.lang.String[] classifierNodeIDs,
                               java.lang.String[] structureParams)
To send a browse request for specific parts of a classifier node (children, ancestors, descendants). Useful for getting specific parts of the structure of a top-level <classificationNode>.

Parameters:
collection - is the name of the Collection whose browse Classifier Browse Service is called
browseService - is the name of the (Classifier) Browse Service (of the given collection) to which this request message is sent.
lang - is the language of the display content in the response
classifierNodeIDs - is the list of classifierNodeIDs for which the structure ought to be retrieved.
structureParams - the list of parameters indicating what structure information is requested. Accepted values are ancestors, parent, siblings, children, descendants.
See Also:
The Greenstone 3 Developer's Manual - page 46

processInternal

protected java.lang.String processInternal(org.w3c.dom.Element message)
Called by most other methods in order to send the constructed message to the Greenstone's MessageRouter, intercept the response and return it.

Parameters:
message - is the XML message Element to send to GS3's MessageRouter.
Returns:
the XML response in String format.

error

protected java.lang.String error(java.lang.String errorMessage)
Creates a String response message to represent an XML error response message using the error specified in the message parameter. A String is created because this method ensures that a response message is reliably constructed (no exceptions are thrown) that can be sent to clients.

Parameters:
errorMessage - - the errormessage to be conveyed
Returns:
an XML response message containing an GS3 error element.

help

public static java.lang.String help()
Returns:
a help string for listing all the web service methods.

helpWithMethod

public static java.lang.String helpWithMethod(java.lang.String methodname)
Parameters:
methodname - is the name of the method to be described.
Returns:
a help string for the given method, explaining what the method does, what parameters it expects and their types and what it returns.

main

public static void main(java.lang.String[] args)