org.greenstone.gs3client.dlservices
Interface DigitalLibraryServicesAPIA

All Known Implementing Classes:

FedoraServicesAPIA, GS3ServicesAPIA

public interface DigitalLibraryServicesAPIA

Interface that defines the digital library methods that need to be provided by a digital library that's going to be incorporated into the Greenstone Java-Client, so that the client may be able to use/access its functionality. Note that the Strings returned by all defined methods -- with the exception of getLanguage() -- represent Greenstone3 XML response messages, as defined in the Greenstone3 manual. These methods do not throw exceptions, but rather embed any error information in the XML Strings returned, as is done in Greenstone3 XML response messages. The final 'A' of DigitalLibraryServicesAPIA stands for Access, as the methods defined here are to give access to a digital library's repository.

Author:

ak19

Nested Class Summary

static class

DigitalLibraryServicesAPIA.CancelException If there's a dialog, then the CancelException can be used to indicate that the user cancelled out of it rather than having seen it through.

Field Summary

static java.io.File

propertiesFile The properties file containing the initial digital library connection settings which get displayed in the connection dialog fields

Method Summary

java.lang.String	describe()
java.lang.String	describeCollection(java.lang.String collection)
java.lang.String	describeCollectionService(java.lang.String collection, java.lang.String service)
java.lang.String	describeService(java.lang.String service)
java.lang.String	getAssocFileBaseURL()
java.lang.String	getAssocFileBaseURL(DocumentNodeData docNode)
java.lang.String	getDisplayName()
java.lang.String	getLanguage() Gets the language that's set as the preferred language.
java.lang.String	query(java.lang.String collection, java.lang.String service, java.util.Map nameValParamsMap)
java.lang.String	retrieveBrowseMetadata(java.lang.String collection, java.lang.String service, java.lang.String[] nodeIDs)
java.lang.String	retrieveBrowseStructure(java.lang.String collection, java.lang.String service, java.lang.String classifierID)
java.lang.String	retrieveDocumentChildren(java.lang.String collection, java.lang.String docID)
java.lang.String	retrieveDocumentChildren(java.lang.String collection, java.lang.String[] docIDs)
java.lang.String	retrieveDocumentContent(java.lang.String collection, java.lang.String docID)
java.lang.String	retrieveDocumentContent(java.lang.String collection, java.lang.String[] docIDs)
java.lang.String	retrieveDocumentMetadata(java.lang.String collection, java.lang.String docID)
java.lang.String	retrieveDocumentMetadata(java.lang.String collection, java.lang.String[] docIDs)
java.lang.String	retrieveDocumentStructure(java.lang.String collection, java.lang.String docID)
java.lang.String	retrieveDocumentStructure(java.lang.String collection, java.lang.String[] docIDs)
java.lang.String	retrieveTitleMetadata(java.lang.String collection, java.lang.String docID)
java.lang.String	retrieveTitleMetadata(java.lang.String collection, java.lang.String[] docIDs)
void	setLanguage(java.lang.String language) Sets the preferred language (code) for metadata and other content to be returned on request messages.

Field Detail

propertiesFile

static final java.io.File propertiesFile

The properties file containing the initial digital library connection settings which get displayed in the connection dialog fields

Method Detail

getDisplayName

java.lang.String getDisplayName()

Returns:

the name of this digital library for displaying in the client

getAssocFileBaseURL

java.lang.String getAssocFileBaseURL()

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

java.lang.String getAssocFileBaseURL(DocumentNodeData docNode)

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.

setLanguage

void setLanguage(java.lang.String language)

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.

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

java.lang.String getLanguage()

Gets the language that's set as the preferred language.

Returns:

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

describe

java.lang.String describe()

Returns:

Greenstone3 XML describe response message with information about collections contained and services (and any serviceRacks) supported by the Digital library.

describeCollection

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

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

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

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

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

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

retrieveDocumentMetadata

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

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

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

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

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

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

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

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

retrieveDocumentContent

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

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

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

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

retrieveDocumentStructure

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

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 descendents

retrieveDocumentStructure

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

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 descendents

retrieveDocumentChildren

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

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

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

Parameters:

collection - is the name of the collection

docID - is an 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

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

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 descendents of the classifier).

retrieveBrowseMetadata

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

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

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

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 This method is only ever called when any of the services in the digital library described themselves as type=query. Therefore any digital libraries that have no query services, can just return emtpy message strings (or even "") since this method will never be called on them anyway.

Returns:

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