org.greenstone.gs3client.dlservices
Class GS3WebServicesQBRAPI

java.lang.Object
  org.greenstone.gs3client.dlservices.GS3WebServicesQBRAPI

Direct Known Subclasses:

GS3ServicesAPIA

public class GS3WebServicesQBRAPI
extends java.lang.Object

GS3WebServicesQBRAPI deals with invoking the Greenstone 3 web services functionality through use of Apache Axis' Service and Call objects. Each Greenstone 3 web service operation has an equivalent method here that invokes it, even if some of these web service operations are never called by the Java-client and therefore not prescribed by the DigitalLibraryServicesAPIA interface.

Author:

ak19

Field Summary

protected org.apache.axis.client.Call	call Axis Call object for invoking Greenstone 3's WebServices using its WSDL file
static java.lang.String	defaultWsdlURL The value that the input dialog's field wsdlURL will default to if there is (no properties file and) no wsdlURL property
(package private) static org.apache.log4j.Logger	LOG The Logger for this class
protected java.lang.String	namespace namespace of Greenstone 3's WebServices, as given in the WSDL file
protected java.lang.String	portName port Name of Greenstone 3's WebServices, as given in the WSDL file
protected org.apache.axis.client.Service	service Axis Service object for connecting to invoking Greenstone 3's WebServices using its WSDL file
protected java.lang.String	serviceName service Name of Greenstone 3's WebServices, as given in the WSDL file
protected java.lang.String	wsdlURLName Url of the Greenstone 3 WebServices' WSDL

Constructor Summary

GS3WebServicesQBRAPI(java.lang.String wsdlURLName)
GS3ServicesAPIA constructor, that given the url to the wsdl file, finds either service and port or the service's endpoint of the GS3 Web Services and instantiates the associated Service and Call objects.

Method Summary

protected void	addArrayParam(java.lang.String arrayParamName) Helper method.
protected void	addStringParam(java.lang.String paramName) Helper method.
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) Describe request message sent to the Message Router.
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 static java.util.Vector	getElementsByTagNameNS(org.w3c.dom.Element parentElement, java.lang.String namespacePrefix, java.lang.String localName) Static method that gets all the descendant elements of a portion of XMl within the same namespace as indicated by parameters namespacePrefix and localName.
protected static void	getElementsByTagNameNS(org.w3c.dom.Element parentElement, java.lang.String namespacePrefix, java.lang.String localName, java.util.Vector v) At method's end, Vector v will contain those descendent elements of parentElement where the element's name is prefixed by namespacePrefix and suffixed by localName.
protected static void	getElementsByTagNameSuffix(org.w3c.dom.Element parentElement, java.lang.String localName, java.util.Vector v) Recursive method.
java.lang.String	getNamespace()
java.lang.String	getPort()
java.lang.String	getService()
java.lang.String	getWsdl()
java.lang.String	help()
java.lang.String	helpWithMethod(java.lang.String methodname)
protected java.lang.String	invokeWith(java.lang.Object[] params) Helper method.
static void	main(java.lang.String[] args)
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) (c) 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) (a) DocumentContentRetrieve request sent to a collection's DocumentContentRetrieve service (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) (b) 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

LOG

static org.apache.log4j.Logger LOG

The Logger for this class

defaultWsdlURL

public static final java.lang.String defaultWsdlURL

The value that the input dialog's field wsdlURL will default to if there is (no properties file and) no wsdlURL property

See Also:

Constant Field Values

service

protected org.apache.axis.client.Service service

Axis Service object for connecting to invoking Greenstone 3's WebServices using its WSDL file

call

protected org.apache.axis.client.Call call

Axis Call object for invoking Greenstone 3's WebServices using its WSDL file

portName

protected java.lang.String portName

port Name of Greenstone 3's WebServices, as given in the WSDL file

namespace

protected java.lang.String namespace

namespace of Greenstone 3's WebServices, as given in the WSDL file

serviceName

protected java.lang.String serviceName

service Name of Greenstone 3's WebServices, as given in the WSDL file

wsdlURLName

protected java.lang.String wsdlURLName

Url of the Greenstone 3 WebServices' WSDL

Constructor Detail

GS3WebServicesQBRAPI

public GS3WebServicesQBRAPI(java.lang.String wsdlURLName)
                     throws javax.xml.rpc.ServiceException,
                            java.net.MalformedURLException,
                            javax.xml.parsers.ParserConfigurationException,
                            java.io.IOException,
                            org.xml.sax.SAXException

GS3ServicesAPIA constructor, that given the url to the wsdl file, finds either service and port or the service's endpoint of the GS3 Web Services and instantiates the associated Service and Call objects.

Parameters:

wsdlURLName - - location of the WSDL URL for Greenstone 3's web services

Throws:

javax.xml.rpc.ServiceException

java.net.MalformedURLException

javax.xml.parsers.ParserConfigurationException

java.io.IOException

org.xml.sax.SAXException

Method Detail

getElementsByTagNameNS

protected static java.util.Vector getElementsByTagNameNS(org.w3c.dom.Element parentElement,
                                                         java.lang.String namespacePrefix,
                                                         java.lang.String localName)

Static method that gets all the descendant elements of a portion of XMl within the same namespace as indicated by parameters namespacePrefix and localName.

Parameters:

namespacePrefix - - a String for the namespacePrefix to search for. This can be the wildcard * for any/allnamespaces.

localName - - the suffix of the namespaceprefix. For instance, localName "soap" will return elements that have the tag wsdlsoap.

parentElement - - the XML element whose descendants will be returned if their element names conform to the specified namespacePrefix and localName parameters.

Returns:

a Vector of all descendant elements whose namespace-qualfied tag names are as specified by the parameters namespacePrefix and localName. Had to implement my own getElementsByTagNameNS() method since the original Element.getElementsByTagNameNS() does not work for Elements created using DOM level 1 (such as with document.createElement()). See the API for Element. This method is slightly more generic, as it returns all descendent elements in a vector where the element name is prefixed by "namespacePrefix" (which need not be a namespace uri at all) and is suffixed by an equally arbitrary String called localName. If "*" is passed instead of namespacePrefix, this method will ignore any prefixes and check only for element names that end on the suffix localName. Old versions of this method had all the same functionality in one method, but it was not so optimised (several if-statement checks would have been executed an unnecessary number of times. This (current) version is split into 3 methods: this one and two helper functions that deal with the case where namespacePrefix can be anything and where it is particularly specified.

getElementsByTagNameSuffix

protected static void getElementsByTagNameSuffix(org.w3c.dom.Element parentElement,
                                                 java.lang.String localName,
                                                 java.util.Vector v)

Recursive method. At method's end, Vector v will contain those descendent elements of parentElement where the element's name is suffixed by/ends with parameter localName. Related to local method getElementsByTagNameNS(). Deals with the case where any and all (namespace)Prefix of an element is accepted, but where an element name's suffix should match with the given localName.

Parameters:

parentElement - us the XML element whose descendants are to be retrieved by the given TagNameSuffix.

localName - is the tagName suffix to retrieve the descendants of parentElement by.

v - is a Vector of all the previously retrieved elements whose tag names are suffixed by localName. This Vector is appended to by recursive calls to this method.

getElementsByTagNameNS

protected static void getElementsByTagNameNS(org.w3c.dom.Element parentElement,
                                             java.lang.String namespacePrefix,
                                             java.lang.String localName,
                                             java.util.Vector v)

At method's end, Vector v will contain those descendent elements of parentElement where the element's name is prefixed by namespacePrefix and suffixed by localName. Related to local method getElementsByTagNameNS(). Deals with the case where a particular (namespace)Prefix of an element and suffix (localname) are given and an element's name should match both prefix and suffix.

Parameters:

parentElement - is the XML element whose descendants are to be retrieved by the given TagNameSuffix.

namespacePrefix - is the namespace prefix to look for in the descendants of parentElement that will be collected in Vector v.

localName - is the tagName suffix to look for in the descendants of parentElement that will be collected in Vector v.

v - is a Vector of all the previously retrieved elements whose tag names are prefixed by namespacePrefix and suffixed by localName. This Vector is appended to by recursive calls to this method.

getNamespace

public java.lang.String getNamespace()

Returns:

the namespace of the wsdl file.

getService

public java.lang.String getService()

Returns:

the web service's serviceName without the namespace

getPort

public java.lang.String getPort()

Returns:

the web service's portName without the namespace

getWsdl

public java.lang.String getWsdl()

Returns:

the the URL of the wsdl file.

invokeWith

protected java.lang.String invokeWith(java.lang.Object[] params)

Helper method. Uses the Call object to invoke the operation (already set prior to calling invokeWith()) with the given parameters.

addStringParam

protected void addStringParam(java.lang.String paramName)

Helper method. Adds a string parameter by the name of paramName to the Call object.

Parameters:

paramName - - the name of the String parameter to add to the call object

addArrayParam

protected void addArrayParam(java.lang.String arrayParamName)

Helper method. Adds an array parameter by the name of arrayParamName to the Call object.

Parameters:

arrayParamName - - the name of the Array parameter to add to the Call object

describe

public java.lang.String describe(java.lang.String lang,
                                 java.lang.String subsetOption)

Describe request message sent to the Message Router.

Parameters:

lang - is the language of the display content in the response

subsetOption - is 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

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 arguments,

See Also:

The Greenstone 3 Developer's Manual - page 45, Greenstone wiki - Actions and Arguments, How to use XMLType.SOAP_MAP

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)

(a) DocumentContentRetrieve request sent to a collection's DocumentContentRetrieve service (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)

(b) 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, descendents (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)

(c) 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

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

help

public java.lang.String help()

Returns:

a help string for listing all the web service methods.

helpWithMethod

public 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)