org.greenstone.gs3client.dlservices
Class GS3ServicesAPIA

java.lang.Object
  extended by org.greenstone.gs3client.dlservices.GS3WebServicesQBRAPI
      extended by 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.