org.greenstone.gs3client.dlservices
Class GS3ServicesAPIA

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

All Implemented Interfaces:

DigitalLibraryServicesAPIA

public class GS3ServicesAPIA
extends GS3WebServicesQBRAPI
implements DigitalLibraryServicesAPIA

GS3ServicesAPIA does two things: - it implements DigitalLibraryServicesAPIA for enabling the Java-client to access Greenstone's repository of collections and documents. It makes this possible through use of Greenstone 3's web services. - it inherits from GS3WebServicesQBRAPI, which means it inherits all the methods that deal with invoking the Greenstone 3 web services functionality (through use of Apache Axis' Service and Call objects). It therefore provides an equivalent method to each Greenstone 3 web service operation, 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

Nested Class Summary

Nested classes/interfaces inherited from interface org.greenstone.gs3client.dlservices.DigitalLibraryServicesAPIA

DigitalLibraryServicesAPIA.CancelException

Field Summary

protected java.lang.String	language Storing language settings for requests and responses
(package private) static org.apache.log4j.Logger	LOG The Logger for this class

Fields inherited from class org.greenstone.gs3client.dlservices.GS3WebServicesQBRAPI

call, defaultWsdlURL, namespace, portName, service, serviceName, wsdlURLName

Fields inherited from interface org.greenstone.gs3client.dlservices.DigitalLibraryServicesAPIA

propertiesFile

Constructor Summary

GS3ServicesAPIA()
Displays a dialog to get user input for the location of the Greenstone 3 web services' WSDL file

GS3ServicesAPIA(java.lang.String wsdlURLName)
GS3ServicesAPIA constructor, which, 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

java.lang.String	describe() Part of the GS3 Java-Client's DigitalLibraryServicesAPIA interface contract
java.lang.String	describeCollection(java.lang.String collection) Part of the GS3 Java-Client's DigitalLibraryServicesAPIA interface contract.
java.lang.String	describeCollectionService(java.lang.String collection, java.lang.String service) Part of the GS3 Java-Client's DigitalLibraryServicesAPIA interface contract.
java.lang.String	describeService(java.lang.String service) Part of the GS3 Java-Client's DigitalLibraryServicesAPIA interface contract.
java.lang.String	getAssocFileBaseURL() Part of the GS3 Java-Client's DigitalLibraryServicesAPIA interface contract.
java.lang.String	getAssocFileBaseURL(DocumentNodeData docNode) Part of the GS3 Java-Client's DigitalLibraryServicesAPIA interface contract.
java.lang.String	getDisplayName()
java.lang.String	getLanguage() Part of the GS3 Java-Client's DigitalLibraryServicesAPIA interface contract.
java.lang.String	query(java.lang.String collection, java.lang.String service, java.util.Map nameValParamsMap) Part of the GS3 Java-Client's DigitalLibraryServicesAPIA interface contract.
java.lang.String	retrieveBrowseMetadata(java.lang.String collection, java.lang.String service, java.lang.String[] nodeIDs) Part of the GS3 Java-Client's DigitalLibraryServicesAPIA interface contract.
java.lang.String	retrieveBrowseStructure(java.lang.String collection, java.lang.String service, java.lang.String classifierID) Part of the GS3 Java-Client's DigitalLibraryServicesAPIA interface contract.
java.lang.String	retrieveDocumentChildren(java.lang.String collection, java.lang.String docID) Part of the GS3 Java-Client's DigitalLibraryServicesAPIA interface contract.
java.lang.String	retrieveDocumentChildren(java.lang.String collection, java.lang.String[] docIDs) Part of the GS3 Java-Client's DigitalLibraryServicesAPIA interface contract.
java.lang.String	retrieveDocumentContent(java.lang.String collection, java.lang.String docID) Part of the GS3 Java-Client's DigitalLibraryServicesAPIA interface contract.
java.lang.String	retrieveDocumentContent(java.lang.String collection, java.lang.String[] docIDs) Part of the GS3 Java-Client's DigitalLibraryServicesAPIA interface contract.
java.lang.String	retrieveDocumentMetadata(java.lang.String collection, java.lang.String docID) Part of the GS3 Java-Client's DigitalLibraryServicesAPIA interface contract.
java.lang.String	retrieveDocumentMetadata(java.lang.String collection, java.lang.String[] docIDs) Part of the GS3 Java-Client's DigitalLibraryServicesAPIA interface contract.
java.lang.String	retrieveDocumentStructure(java.lang.String collection, java.lang.String docID) Part of the GS3 Java-Client's DigitalLibraryServicesAPIA interface contract.
java.lang.String	retrieveDocumentStructure(java.lang.String collection, java.lang.String[] docIDs) Part of the GS3 Java-Client's DigitalLibraryServicesAPIA interface contract.
java.lang.String	retrieveTitleMetadata(java.lang.String collection, java.lang.String docID) Part of the GS3 Java-Client's DigitalLibraryServicesAPIA interface contract.
java.lang.String	retrieveTitleMetadata(java.lang.String collection, java.lang.String[] docIDs) Part of the GS3 Java-Client's DigitalLibraryServicesAPIA interface contract.
void	setLanguage(java.lang.String language) Part of the GS3 Java-Client's DigitalLibraryServicesAPIA interface contract.
static java.lang.String	showWsdlInputDialog() Static method that displays a dialog requesting the user to input the location of Greenstone 3 web services' WSDL file.

Methods inherited from class org.greenstone.gs3client.dlservices.GS3WebServicesQBRAPI

addArrayParam, addStringParam, basicQuery, browse, browseDescendants, describe, describeCollection, describeCollectionService, describeService, describeServiceCluster, getElementsByTagNameNS, getElementsByTagNameNS, getElementsByTagNameSuffix, getNamespace, getPort, getService, getWsdl, help, helpWithMethod, invokeWith, main, query, retrieveAllBrowseMetadata, retrieveAllDocumentMetadata, retrieveBrowseMetadata, retrieveDocumentContent, retrieveDocumentMetadata, retrieveDocumentStructure, retrieveEntireDocumentStructure

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

language

protected java.lang.String language

Storing language settings for requests and responses

Constructor Detail

GS3ServicesAPIA

public GS3ServicesAPIA()
                throws javax.xml.rpc.ServiceException,
                       java.net.MalformedURLException,
                       javax.xml.parsers.ParserConfigurationException,
                       java.io.IOException,
                       java.lang.Exception

Displays a dialog to get user input for the location of the Greenstone 3 web services' WSDL file

Throws:

javax.xml.rpc.ServiceException

java.net.MalformedURLException

javax.xml.parsers.ParserConfigurationException

java.io.IOException

java.lang.Exception

GS3ServicesAPIA

public GS3ServicesAPIA(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, which, 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 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

showWsdlInputDialog

public static java.lang.String showWsdlInputDialog()
                                            throws java.lang.Exception

Static method that displays a dialog requesting the user to input the location of Greenstone 3 web services' WSDL file.

Returns:

a String representing the URL location of Greenstone 3 web services' WSDL file

Throws:

java.lang.Exception

getDisplayName

public java.lang.String getDisplayName()

Specified by:

getDisplayName in interface DigitalLibraryServicesAPIA

Returns:

the name of this digital library for displaying in the client

setLanguage

public void setLanguage(java.lang.String language)

Part of the GS3 Java-Client's DigitalLibraryServicesAPIA interface contract. Sets the preferred language (code) for metadata and other content to be returned on request messages. If the preferred language is not available, the implementation may choose to send English back instead, or failing that, send the data in any other available language.

Specified by:

setLanguage in interface DigitalLibraryServicesAPIA

Parameters:

language - has to be a language code as recognised by Greenstone3 (the language codes used by W3C probably). E.g. "en" for English.

getLanguage

public java.lang.String getLanguage()

Part of the GS3 Java-Client's DigitalLibraryServicesAPIA interface contract. Gets the language that's set as the preferred language.

Specified by:

getLanguage in interface DigitalLibraryServicesAPIA

Returns:

the language code as recognised by Greenstone3 (which are the language codes used by W3C probably). E.g. "en" for English.

getAssocFileBaseURL

public java.lang.String getAssocFileBaseURL()

Part of the GS3 Java-Client's DigitalLibraryServicesAPIA interface contract.

Specified by:

getAssocFileBaseURL in interface DigitalLibraryServicesAPIA

Returns:

the overall directory path for associated files (not including the document's nodeID/pid). This can be used to *formulate* the base url of JEditorPane's HTML documents. If the documents from any digital library do not contain relative paths, or otherwise deal with the resolution of relative urls themselves, then return "" from here.

getAssocFileBaseURL

public java.lang.String getAssocFileBaseURL(DocumentNodeData docNode)

Part of the GS3 Java-Client's DigitalLibraryServicesAPIA interface contract.

Specified by:

getAssocFileBaseURL in interface DigitalLibraryServicesAPIA

Returns:

the directory path to the associated files of the given document node. For instance, the base url of a JEditorPane's HTML documents can be set to this.

describe

public java.lang.String describe()

Part of the GS3 Java-Client's DigitalLibraryServicesAPIA interface contract

Specified by:

describe in interface DigitalLibraryServicesAPIA

Returns:

Greenstone3 XML describe response message originating from the Message Router, describing the Collections, ServiceRacks and Services supported by the Message Router for all collections.

describeCollection

public java.lang.String describeCollection(java.lang.String collection)

Part of the GS3 Java-Client's DigitalLibraryServicesAPIA interface contract.

Specified by:

describeCollection in interface DigitalLibraryServicesAPIA

Parameters:

collection - is the name of the collection to be described.

Returns:

Greenstone3 XML describe response message originating from a collection, describing the collection (display items) as well as listing any services supported specifically by the collection.

describeCollectionService

public java.lang.String describeCollectionService(java.lang.String collection,
                                                  java.lang.String service)

Part of the GS3 Java-Client's DigitalLibraryServicesAPIA interface contract.

Specified by:

describeCollectionService in interface DigitalLibraryServicesAPIA

Parameters:

collection - is the name of the collection to be described.

service - is the name of the collection's service to be described.

Returns:

Greenstone3 XML describe response message originating from a collection's service, describing the service (display items).

describeService

public java.lang.String describeService(java.lang.String service)

Part of the GS3 Java-Client's DigitalLibraryServicesAPIA interface contract.

Specified by:

describeService in interface DigitalLibraryServicesAPIA

Parameters:

service - is the name of the collection's service to be described.

Returns:

Greenstone3 XML describe response message originating from a general (non-collection specific) service, describing the requested service (for example with GS3 display items).

retrieveDocumentContent

public java.lang.String retrieveDocumentContent(java.lang.String collection,
                                                java.lang.String[] docIDs)

Part of the GS3 Java-Client's DigitalLibraryServicesAPIA interface contract.

Specified by:

retrieveDocumentContent in interface DigitalLibraryServicesAPIA

Parameters:

collection - is the name of the collection.

docIDs - is an array of document identifiers of documents whose (text) contents are requested.

Returns:

a String representing Greenstone3 DocumentContentRetrieve XML containing the document contents of the documents indicated by docIDs

retrieveDocumentContent

public java.lang.String retrieveDocumentContent(java.lang.String collection,
                                                java.lang.String docID)

Part of the GS3 Java-Client's DigitalLibraryServicesAPIA interface contract.

Specified by:

retrieveDocumentContent in interface DigitalLibraryServicesAPIA

Parameters:

collection - is the name of the collection.

docID - is the document identifier of the document whose (text) content is requested.

Returns:

a String representing Greenstone3 DocumentContentRetrieve XML containing the document contents of the document indicated by docID

retrieveDocumentMetadata

public java.lang.String retrieveDocumentMetadata(java.lang.String collection,
                                                 java.lang.String[] docIDs)

Part of the GS3 Java-Client's DigitalLibraryServicesAPIA interface contract.

Specified by:

retrieveDocumentMetadata in interface DigitalLibraryServicesAPIA

Parameters:

collection - is the name of the collection.

docIDs - is an array of document identifiers of documents whose metadata is requested.

Returns:

a String representing Greenstone3 DocumentMetadataRetrieve XML containing all the metadata of all the documents indicated by docIDs

retrieveDocumentMetadata

public java.lang.String retrieveDocumentMetadata(java.lang.String collection,
                                                 java.lang.String docID)

Part of the GS3 Java-Client's DigitalLibraryServicesAPIA interface contract.

Specified by:

retrieveDocumentMetadata in interface DigitalLibraryServicesAPIA

Parameters:

collection - is the name of the collection.

docID - is the document identifier of the document whose metadata is requested.

Returns:

a String representing Greenstone3 DocumentMetadataRetrieve XML containing all the metadata of the document denoted by docID

retrieveTitleMetadata

public java.lang.String retrieveTitleMetadata(java.lang.String collection,
                                              java.lang.String[] docIDs)

Part of the GS3 Java-Client's DigitalLibraryServicesAPIA interface contract.

Specified by:

retrieveTitleMetadata in interface DigitalLibraryServicesAPIA

Parameters:

collection - is the name of the collection.

docIDs - is an array of document identifiers of documents whose titles are requested

Returns:

a String representing Greenstone3 DocumentMetadataRetrieve XML containing only the title metadata of the documents denoted by docIDs

retrieveTitleMetadata

public java.lang.String retrieveTitleMetadata(java.lang.String collection,
                                              java.lang.String docID)

Part of the GS3 Java-Client's DigitalLibraryServicesAPIA interface contract.

Specified by:

retrieveTitleMetadata in interface DigitalLibraryServicesAPIA

Parameters:

collection - is the name of the collection

docID - is the document identifier of the document whose titles is requested

Returns:

a String representing Greenstone3 DocumentMetadataRetrieve XML containing only the title metadata of the document denoted by docID

retrieveDocumentStructure

public java.lang.String retrieveDocumentStructure(java.lang.String collection,
                                                  java.lang.String[] docIDs)

Part of the GS3 Java-Client's DigitalLibraryServicesAPIA interface contract.

Specified by:

retrieveDocumentStructure in interface DigitalLibraryServicesAPIA

Parameters:

collection - is the name of the collection

docIDs - is an array of document identifiers of documents whose hierarchical structures are requested

Returns:

a String representing Greenstone3 DocumentMetadataRetrieve XML containing the document structure of the documents indicated by docIDs: this means all their descendants

retrieveDocumentStructure

public java.lang.String retrieveDocumentStructure(java.lang.String collection,
                                                  java.lang.String docID)

Part of the GS3 Java-Client's DigitalLibraryServicesAPIA interface contract.

Specified by:

retrieveDocumentStructure in interface DigitalLibraryServicesAPIA

Parameters:

collection - is the name of the collection

docID - is the document identifier of the document whose hierarchical structure is requested

Returns:

a String representing Greenstone3 DocumentMetadataRetrieve XML containing the document structure of the document indicated by docID: this means all its descendants

retrieveDocumentChildren

public java.lang.String retrieveDocumentChildren(java.lang.String collection,
                                                 java.lang.String[] docIDs)

Part of the GS3 Java-Client's DigitalLibraryServicesAPIA interface contract.

Specified by:

retrieveDocumentChildren in interface DigitalLibraryServicesAPIA

Parameters:

collection - is the name of the collection

docIDs - is an array of document identifiers of documents whose hierarchical structures are requested

Returns:

a String representing Greenstone3 DocumentMetadataRetrieve XML containing a view of the document structure of the documents denoted by docs where only the requested documents and their direct children are returned.

retrieveDocumentChildren

public java.lang.String retrieveDocumentChildren(java.lang.String collection,
                                                 java.lang.String docID)

Part of the GS3 Java-Client's DigitalLibraryServicesAPIA interface contract.

Specified by:

retrieveDocumentChildren in interface DigitalLibraryServicesAPIA

Parameters:

collection - is the name of the collection

docID - is the document identifier of the document whose hierarchical structure is requested

Returns:

a String representing Greenstone3 DocumentMetadataRetrieve XML containing a view of the document structure of the document denoted by docID where only the document and its direct children are returned.

retrieveBrowseStructure

public java.lang.String retrieveBrowseStructure(java.lang.String collection,
                                                java.lang.String service,
                                                java.lang.String classifierID)

Part of the GS3 Java-Client's DigitalLibraryServicesAPIA interface contract.

Specified by:

retrieveBrowseStructure in interface DigitalLibraryServicesAPIA

Parameters:

classifierID - is of the form CL# where the number (#) marks out structured sections like CL1.1.3 or CL2

collection - is the name of the collection

service - is the name of the browse service (=ClassifierBrowse usually)

Returns:

a String representing Greenstone3 ClassifierBrowse XML giving the entire *structure* of the classification denoted by classifierID (including the structures of document descendants of the classifier).

retrieveBrowseMetadata

public java.lang.String retrieveBrowseMetadata(java.lang.String collection,
                                               java.lang.String service,
                                               java.lang.String[] nodeIDs)

Part of the GS3 Java-Client's DigitalLibraryServicesAPIA interface contract.

Specified by:

retrieveBrowseMetadata in interface DigitalLibraryServicesAPIA

Parameters:

nodeIDs - is of the form CL#.# where the number (#) marks out structured sections like CL2.1.3. NodeIDs are generally subsections of top-level classifierNodes (CL#, e.g. CL3).

collection - is the name of the collection

service - is the name of the Browse's MetadataRetrieve service (usually the browse service is ClassifierBrowse, in which case it always has a retrieve service called ClassifierBrowseMetadataRetrieve)

Returns:

a String representing Greenstone3 ClassifierBrowseMetadataRetrieve XML giving all the metadata for all the subclassifiers denoted by nodeIDs.

query

public java.lang.String query(java.lang.String collection,
                              java.lang.String service,
                              java.util.Map nameValParamsMap)

Part of the GS3 Java-Client's DigitalLibraryServicesAPIA interface contract.

Specified by:

query in interface DigitalLibraryServicesAPIA

Parameters:

nameValParamsMap - is a Map of name and value pairs for all the query field data values. The names match the field names that describeCollectionService() would have returned for the query service.

collection - is the name of the collection

service - is the name of the query service

Returns:

a String representing Greenstone3 XML for a query process response returning the results for the query denoted by parameter nameValParamsMap.