org.greenstone.gs3services
Class QBRSOAPServer

java.lang.Object
  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)