org.greenstone.fedora.services
Class FedoraGS3Connection

java.lang.Object
  org.greenstone.fedora.services.FedoraConnection
      org.greenstone.fedora.services.FedoraGS3Connection

All Implemented Interfaces:

FedoraGS3DL, FedoraToGS3Interface, FedoraToGS3Interface.Constants

public class FedoraGS3Connection
extends FedoraConnection
implements FedoraToGS3Interface, FedoraToGS3Interface.Constants

Class that extends FedoraConnection in order to be able to use Fedora's web services to retrieve the specific datastreams of Greenstone documents stored in Fedora's repository. This class provides methods that convert those datastreams into Greenstone3 XML response messages which are returned.

Author:

ak19

Nested Class Summary

Nested classes/interfaces inherited from interface org.greenstone.fedora.services.FedoraToGS3Interface

FedoraToGS3Interface.Constants

Field Summary

protected static int	CHILDREN constant CHILDREN indicates that a DocumentStructureRetrieve is to return only the child nodes of a section, not any further descendants
protected static int	DESCENDANTS constant DESCENDANTS indicates that a DocumentStructureRetrieve is to return all descendants of a section
protected GSearchConnection	fedoraGSearch The object used to connect to FedoraGenericSearch, which is used for doing full-text searching
protected static java.lang.String	gSearchWSDLSuffix The last part of the gSearchWSDL URL.
protected java.lang.String	gSearchWSDLURL The url for the wsdl file of FedoraGSearch's web services by default this will be the Fedora server's base URL concatenated to "gsearch/services/FgsOperations?wsdl"
protected java.lang.String[]	serviceNames List of services actually supported by our FedoraGS3 repository after construction.
protected static java.lang.String[]	SERVICES Complete list of services that are supported our FedoraGS3 would support if everything goes well.

Fields inherited from class org.greenstone.fedora.services.FedoraConnection

APIA, baseURL, builder, defaultPortAddressSuffix, fedoraVersion, GET, INTERNAL_NODE, lang, maxresults, portAddressSuffix, SUPPORTED_VERSION, TYPE

Fields inherited from interface org.greenstone.fedora.services.FedoraToGS3Interface.Constants

ALL_FIELDS, ALL_TITLES, ASSOCFILEPREFIX, COMMA, DOC_TITLES, FIELDNAME_ATT, FULLTEXT, GS3FilePathMacro, MAXDOCS, NUM_DOCS_MATCHED, OCCURS_ATT, QUERY, SIMPLEFIELD_ATT

Fields inherited from interface org.greenstone.fedora.services.FedoraGS3DL

_COLLECTION, COLLECTION, COLLECTIONNAME, COLON, DC, DLS, ENGLISH, EX, FEDORA_GS3, GREENSTONE, GREENSTONE_, HYPHEN, ID, METADATA, NAME, PERIOD, QUALIFIER, SECTION, SECTION_ELEMENT, TITLE, TOC, UTF8, WILDCARD

Constructor Summary

FedoraGS3Connection()
No-argument constructor which is the same as that of superclass FedoraConnection: it displays a small dialog requesting input for the host, port, administrative password and username of the fedora server.

FedoraGS3Connection(java.io.File propertiesFilename)
Single-argument constructor which is the same as that of superclass FedoraConnection: it takes the name of the properties file where connection initialisation values may already be provided and then displays a small dialog requesting input for the host, port, administrative password and username of the fedora server showing the values in the properties file as default.

FedoraGS3Connection(java.lang.String protocol, java.lang.String host, int port, java.lang.String fedoraServerUsername, java.lang.String fedoraServerPassword)
5 argument constructor is the same as that of superclass FedoraConnection:

Method Summary

protected void	addMetadataWithFixedTagName(org.w3c.dom.Document doc, org.w3c.dom.Element metadataList, java.lang.String metaDatastream, java.lang.String metadataSet) This method retrieves all the metadata elements in the metaDataStream of the form <"namespace:"metadata name="metadataName">value</metadata> where "namespace" is the namespace prefix of each tag, and metadataName is the name of the metadata (like author, title).
protected void	addMetadataWithNamespacedTagNames(org.w3c.dom.Document doc, org.w3c.dom.Element metadataList, java.lang.String metaDatastream, java.lang.String metadataSet) This method retrieves all the metadata elements in the metaDataStream parameter of the form <"metadataSetNS:metadata">"value"</metadata> where metadataSetNS is the namespace of each tag, and creates a new element of the form <metadata name="metadataSetNS:metadata">"value"</metadata> for each.
java.lang.String	browse(java.lang.String collectionName, java.lang.String classifierID) This method performs the implemented browse operation: allowing the user to browse the titles of documents in the given collection by letter and returning the results.
java.lang.String	browseMetadataRetrieve(java.lang.String[] classNodeIDs) This method performs something equivalent to a greenstone3 ClassifierBrowseMetadataRetrieve on the classifierNodeIDs
protected boolean	containsSectionNumber(java.lang.String docID) For finding out if the sectionNumber is given as part of the docID.
protected org.w3c.dom.Element	createClassifierElement(org.w3c.dom.Document doc, java.lang.String content, int classifierNum, java.lang.String displayNameVal, java.lang.String displayDescrVal)
protected org.w3c.dom.Element	createDocNodeFromSubsection(org.w3c.dom.Document doc, org.w3c.dom.Element subSection, java.lang.String docID) Given a particular subsection element, this method creates a Greenstone3 DocumentNode element that mirrors it.
protected void	createDocStructure(org.w3c.dom.Document doc, org.w3c.dom.Element section, org.w3c.dom.Element parent, java.lang.String docPID) Recursive method that creates a documentStructure mirroring parameter section, starting from parameter parent down to all descendants
protected org.w3c.dom.Element	createNameValuePairElement(org.w3c.dom.Document doc, java.lang.String elementName, java.lang.String name, java.lang.String value)
protected org.w3c.dom.Element	createResponseMessage(org.w3c.dom.Document doc, org.w3c.dom.Element content, java.lang.Exception ex, java.lang.String responseType, java.lang.String originator) Here we create the greenstone's response message element: <message≶<response><content></response></message>
protected org.w3c.dom.Element	createServiceList(org.w3c.dom.Document doc)
java.lang.String	describeCollection(java.lang.String collectionName)
java.lang.String	describeCollectionService(java.lang.String collectionName, java.lang.String serviceName) All collections in this Digital Library (Fedora Repository) share the same services, so this method returns the same as describeService(serviceName).
java.lang.String	describeCollectionServices(java.lang.String collectionName)
protected void	describeFieldQueryService(org.w3c.dom.Element service) Appends children to the parameter service Element that make the final service Element into a describe response XML for FedoraGS3's FieldQuery service.
java.lang.String	describeService(java.lang.String serviceName) All collections in this Digital Library (Fedora Repository) share the same services, so this method returns the same as describeCollectionService(collName, serviceName).
protected void	describeTextQueryService(org.w3c.dom.Element service) Appends children to the parameter service Element that make the final service Element into a describe response XML for FedoraGS3's TextQuery service.
java.lang.String[]	fieldQuery(java.lang.String collection, java.util.Map nameValParamsMap, int maxDocs) This method performs a fieldquery, searching for x number of phrases in each of the 4 indexed fields.
java.lang.String	getChildren(java.lang.String docID)
java.lang.String	getChildren(java.lang.String[] docIDs)
java.lang.String	getCollectionList()
java.lang.String	getCollectionMetadata(java.lang.String collID) Given a collectionID, returns a GS3 DocumentMetadataRetrieve response message that gives the metadata for the collection identified
java.lang.String	getCollectionMetadata(java.lang.String[] collIDs) Given a list of collectionIDs, returns a GS3 DocumentMetadataRetrieve response message that gives the metadata for each collection identified
java.lang.String	getContent(java.lang.String docID) Given an identifier that is either a docPID or a concatenation of docPID+sectionID, this method works out the fedora assigned docPID and sectionID and then calls getContentBody(docPID, sectionID) with those.
java.lang.String	getContent(java.lang.String[] docIDs) Given an identifier that is a concatenation of docID+sectionID, this method works out the fedora assigned docPID and sectionID and then calls getContentBody(docPID, sectionID) with those.
protected java.lang.String	getContentBody(java.lang.String docPID, java.lang.String sectionID) Gets the contents of a textNode from a section.
protected java.lang.String	getDocPIDFromDocID(java.lang.String docID) This method will extract the docPID from docID and return it.
java.lang.String	getDocumentMetadata(java.lang.String docID) Given a document identifier, returns a GS3 DocumentMetadataRetrieve response message containing the metadata for the document.
java.lang.String	getDocumentMetadata(java.lang.String[] docIDs) Given a list of document identifiers, a GS3 DocumentMetadataRetrieve response message is returned containing the metadata for each document.
java.lang.String	getDocumentStructure(java.lang.String docID)
java.lang.String	getDocumentStructure(java.lang.String[] docIDs)
java.lang.String	getGSearchWSDLURL()
protected org.w3c.dom.Element	getMetadata(org.w3c.dom.Document doc, java.lang.String id) Method that takes a new DOM document, as well as an identifier of either a collection or document (which may be a fedora pid for the collection or document, or may be the documentPid-sectionNumber for a document) and returns a documentNode element for it: <documentNode><metadataList> <metadata name="">value</metadata> ...
java.lang.String	getMetadata(java.lang.String[] docIDsOrCollIDs)
protected java.lang.String	getSectionIDFromDocID(java.lang.String docID) This method will return the section Number, if there's any suffixed to the docID.
java.lang.String	getServiceList()
protected java.lang.String[]	getServiceNames()
protected org.w3c.dom.Element	getStructure(org.w3c.dom.Document doc, java.lang.String requestingDocID, java.lang.String docID, org.w3c.dom.Element section) Takes the portion of the XML document outlining the structure of the document (section)--in the format this is stored in Fedora--and returns Greenstone 3 DOM XML format for outlining document structure.
protected java.lang.String	getStructure(java.lang.String[] docIDs, int levels) Returns a greenstone3 DocumentStructureRetrieve XML response message containing the document structures for the given docIDs.
protected void	getStructureElement(org.w3c.dom.Element docNodeList, java.lang.String[] docIDs, int levels) Given a <documentNodeList> portion of a greenstone3 DocumentStructureRetrieve XML response message, this method will populate it with the <documentNodes> that represent the structure of the given docIDs.
protected org.w3c.dom.Element	getTitleMetadata(org.w3c.dom.Document doc, java.lang.String docID) Method that takes a new DOM document, as well as an identifier of either a document or document section and returns a documentNode element containing the title metadata for it: <documentNode nodeID="docID"><metadataList> <metadata name="Title">sometitle</metadata> </metadataList></documentNode>
java.lang.String	getTitleMetadata(java.lang.String docID) Given a document identifier, returns a GS3 DocumentMetadataRetrieve response message containing ONLY the Title metadata for the document.
java.lang.String	getTitleMetadata(java.lang.String[] docIDs) Given a document identifier, returns a GS3 DocumentMetadataRetrieve response message containing ONLY the Title metadata for the documents.
protected void	initSearchFunctionality() Init method that instantiates a GSearchConnection object used to work with the separate FedoraGSearch web services.
static void	main(java.lang.String[] args)
java.lang.String	query(java.lang.String collection, java.lang.String service, java.util.Map nameValParamsMap)
void	setGSearchWSDLURL(java.lang.String url) Sets the member variable gSearchWSDLURL that specify the location of the WSDL file of FedoraGSearch's web services.
protected void	setInitialisationProperties(java.util.Properties properties) The superclass constructor calls this method passing any preset properties loaded from a propertiesFile.
java.lang.String[]	textQuery(java.lang.String collection, java.lang.String query, int maxDocs)

Methods inherited from class org.greenstone.fedora.services.FedoraConnection

browseTitlesByLetter, convertToMetaNumber, createAPIA, findObjectsWithTitlesContaining, getAssocFileBaseURL, getBaseURL, getChildrenOfSection, getChildrenOfSectionXML, getCollectionDocs, getCollectionName, getCollectionNames, getCollectionPID, getCollectionPIDs, getCollections, getCollectionTitle, getCollectionTitles, getDC, getDLS, getDocName, getDocTitle, getDocTitles, getEX, getFedoraVersion, getItem, getLanguage, getMaxResults, getPortAddressURL, getSection, getSectionDCMetadata, getSectionEXMetadata, getSectionNames, getSectionNumbers, getSectionTitle, getSectionTitles, getSubsection, getSubsectionXML, getSubstructure, getSupportedVersion, getTitle, getTitle, getTitles, getTOC, init, removePrefix, searchDocumentTitles, setLanguage, setMaxResults, showAuthenticationPopup

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

gSearchWSDLSuffix

protected static final java.lang.String gSearchWSDLSuffix

The last part of the gSearchWSDL URL. The first part is the same as the fedora server's base url.

See Also:

Constant Field Values

SERVICES

protected static final java.lang.String[] SERVICES

Complete list of services that are supported our FedoraGS3 would support if everything goes well. If a connection to FedoraGSearch cannot be established, the query services will no longer be available. The actual services supported are given by member variable serviceNames.

serviceNames

protected java.lang.String[] serviceNames

List of services actually supported by our FedoraGS3 repository after construction. If FedoraGenericSearch can't be connected to, then query services will not be offered

CHILDREN

protected static final int CHILDREN

constant CHILDREN indicates that a DocumentStructureRetrieve is to return only the child nodes of a section, not any further descendants

See Also:

Constant Field Values

DESCENDANTS

protected static final int DESCENDANTS

constant DESCENDANTS indicates that a DocumentStructureRetrieve is to return all descendants of a section

See Also:

Constant Field Values

fedoraGSearch

protected GSearchConnection fedoraGSearch

The object used to connect to FedoraGenericSearch, which is used for doing full-text searching

gSearchWSDLURL

protected java.lang.String gSearchWSDLURL

The url for the wsdl file of FedoraGSearch's web services by default this will be the Fedora server's base URL concatenated to "gsearch/services/FgsOperations?wsdl"

Constructor Detail

FedoraGS3Connection

public FedoraGS3Connection(java.lang.String protocol,
                           java.lang.String host,
                           int port,
                           java.lang.String fedoraServerUsername,
                           java.lang.String fedoraServerPassword)
                    throws javax.xml.parsers.ParserConfigurationException,
                           java.net.MalformedURLException,
                           javax.net.ssl.SSLHandshakeException,
                           java.rmi.RemoteException,
                           FedoraGS3Exception.AuthenticationFailedException,
                           FedoraGS3Exception.NotAFedoraServerException,
                           java.net.ConnectException,
                           java.lang.Exception

5 argument constructor is the same as that of superclass FedoraConnection:

Parameters:

protocol - can be either http or https

host - is the host where the fedora server is listening

port - is the port where the fedora server is listening

fedoraServerUsername - is the username for administrative authentication required to access the fedora server.

fedoraServerPassword - is the password for administrative authentication required to access the fedora server. If no password was set when installing Fedora, leave the field "". Instantiates a FedoraGS3Connection object which connects to Fedora's web services through stub classes and tries to connect to FedoraGSearch's web services through the default WSDL location for it ("gsearch/services/FgsOperations?wsdl"). If another url is to be used, call setGSearchWSDLURL(url) after the constructor instead.

Throws:

javax.xml.parsers.ParserConfigurationException

java.net.MalformedURLException

javax.net.ssl.SSLHandshakeException

java.rmi.RemoteException

FedoraGS3Exception.AuthenticationFailedException

FedoraGS3Exception.NotAFedoraServerException

java.net.ConnectException

java.lang.Exception

FedoraGS3Connection

public FedoraGS3Connection()
                    throws javax.xml.parsers.ParserConfigurationException,
                           java.net.MalformedURLException,
                           FedoraGS3Exception.CancelledException,
                           java.net.ConnectException,
                           java.rmi.RemoteException,
                           javax.net.ssl.SSLHandshakeException,
                           java.lang.Exception

No-argument constructor which is the same as that of superclass FedoraConnection: it displays a small dialog requesting input for the host, port, administrative password and username of the fedora server. If no password was set on the fedora repository when installing it, the user can leave the password field blank.

Throws:

javax.xml.parsers.ParserConfigurationException

java.net.MalformedURLException

FedoraGS3Exception.CancelledException

java.net.ConnectException

java.rmi.RemoteException

javax.net.ssl.SSLHandshakeException

java.lang.Exception

FedoraGS3Connection

public FedoraGS3Connection(java.io.File propertiesFilename)
                    throws javax.xml.parsers.ParserConfigurationException,
                           java.net.MalformedURLException,
                           FedoraGS3Exception.CancelledException,
                           java.net.ConnectException,
                           java.rmi.RemoteException,
                           javax.net.ssl.SSLHandshakeException,
                           java.lang.Exception

Single-argument constructor which is the same as that of superclass FedoraConnection: it takes the name of the properties file where connection initialisation values may already be provided and then displays a small dialog requesting input for the host, port, administrative password and username of the fedora server showing the values in the properties file as default. If the necessary initialisation are not present in the file, they corresponding fields in the dialog will be blank. If no password was set on the fedora repository when installing it, the user can leave the password field blank.

Throws:

javax.xml.parsers.ParserConfigurationException

java.net.MalformedURLException

FedoraGS3Exception.CancelledException

java.net.ConnectException

java.rmi.RemoteException

javax.net.ssl.SSLHandshakeException

java.lang.Exception

Method Detail

setInitialisationProperties

protected void setInitialisationProperties(java.util.Properties properties)
                                    throws javax.xml.parsers.ParserConfigurationException,
                                           java.net.MalformedURLException,
                                           FedoraGS3Exception.CancelledException,
                                           java.net.ConnectException,
                                           java.rmi.RemoteException,
                                           javax.net.ssl.SSLHandshakeException,
                                           java.lang.Exception

The superclass constructor calls this method passing any preset properties loaded from a propertiesFile. This method is overridden here in order to instantiate the gSearchConnection based on the gSearchWSDLURL. (If one was not provided in the properties file, gSearchWSDLURL defaults to something of the form "http://localhost:8080/fedoragsearch/services/FgsOperations?wsdl" where http://localhost:8080/fedora is the baseURL of fedora and "gsearch/services/FgsOperations?wsdl" is the default gSearchWSDLSuffix.)

Overrides:

setInitialisationProperties in class FedoraConnection

Parameters:

properties - is the Properties Map loaded from a properties file (if there was any) which specifies such things as host and port of the FedoraServer, but can also specify the property "gSearchWsdlURL". At the end of this method, properties' "gSearchWsdlURL" will be set to whatever the final value of this.gSearchWSDLURL is.

Throws:

javax.xml.parsers.ParserConfigurationException

java.net.MalformedURLException

FedoraGS3Exception.CancelledException

java.net.ConnectException

java.rmi.RemoteException

javax.net.ssl.SSLHandshakeException

java.lang.Exception

initSearchFunctionality

protected void initSearchFunctionality()

Init method that instantiates a GSearchConnection object used to work with the separate FedoraGSearch web services. The url of the WSDL for FedoraGSearch's web services is worked out from the baseURL of the Fedora server.

getGSearchWSDLURL

public java.lang.String getGSearchWSDLURL()

Returns:

the gSearchWSDLURL, the url of the WSDL for the FedoraGSearch web services

setGSearchWSDLURL

public void setGSearchWSDLURL(java.lang.String url)

Sets the member variable gSearchWSDLURL that specify the location of the WSDL file of FedoraGSearch's web services. Then it attempts to instantiate a connection to those web services.

Parameters:

url - is the new url of the GSearch web services WSDL file

getServiceNames

protected java.lang.String[] getServiceNames()

Returns:

the array of the services actually supported by FedoraGS3

containsSectionNumber

protected boolean containsSectionNumber(java.lang.String docID)

For finding out if the sectionNumber is given as part of the docID.

Parameters:

docID - is the String that contains the docPID and may also contain the section number.

Returns:

true if the document identifier docID contains a section- number, and false if it consists solely of the docPID. That is, true is returned if

docID = "greenstone:colName-<docPID>-<sectionNum>"

and false is returned if

docID = "greenstone:colName-<docPID>"

getDocPIDFromDocID

protected java.lang.String getDocPIDFromDocID(java.lang.String docID)

This method will extract the docPID from docID and return it. (If a sectionNumber is suffixed to the docID, the docPID which is the prefix is returned; otherwise the docID is the docPID and is returned)

Parameters:

docID - is the String that contains the docPID and may also contain the section number.

Returns:

only the docPID portion of the docID.

getSectionIDFromDocID

protected java.lang.String getSectionIDFromDocID(java.lang.String docID)

This method will return the section Number, if there's any suffixed to the docID. Otherwise it will return the empty string

Parameters:

docID - is the String that contains the docPID and may also contain the section number.

Returns:

only the sectionID portion of the docID - if any, else "".

getCollectionMetadata

public java.lang.String getCollectionMetadata(java.lang.String[] collIDs)

Given a list of collectionIDs, returns a GS3 DocumentMetadataRetrieve response message that gives the metadata for each collection identified

Specified by:

getCollectionMetadata in interface FedoraToGS3Interface

Parameters:

collIDs - is an array of fedora pids identifying collections in the fedora repository

Returns:

a GS3 DocumentMetadataRetrieve response message containing the EX metadata for all the requested collections

getDocumentMetadata

public java.lang.String getDocumentMetadata(java.lang.String[] docIDs)

Given a list of document identifiers, a GS3 DocumentMetadataRetrieve response message is returned containing the metadata for each document.

Specified by:

getDocumentMetadata in interface FedoraToGS3Interface

Parameters:

docIDs - is an array of document identifiers (docID can either be <pid>s items (documents) in the fedora repository, or "<pid>-sectionNumber".

Returns:

a GS3 DocumentMetadataRetrieve response message containing the EX, DC, DLS metadata for all the requested documents

getCollectionMetadata

public java.lang.String getCollectionMetadata(java.lang.String collID)

Given a collectionID, returns a GS3 DocumentMetadataRetrieve response message that gives the metadata for the collection identified

Specified by:

getCollectionMetadata in interface FedoraToGS3Interface

Parameters:

collID - is a fedora pid identifying a collection in its repository

Returns:

a GS3 DocumentMetadataRetrieve response message containing the EX metadata for the requested collection

getDocumentMetadata

public java.lang.String getDocumentMetadata(java.lang.String docID)

Given a document identifier, returns a GS3 DocumentMetadataRetrieve response message containing the metadata for the document.

Specified by:

getDocumentMetadata in interface FedoraToGS3Interface

Parameters:

docID - is a document identifier (docID can either be a <pid> of an item (document) in the fedora repository, or it can be "<pid>-sectionNumber".

Returns:

a GS3 DocumentMetadataRetrieve response message containing the EX, DC, DLS metadata for the requested document

getMetadata

public java.lang.String getMetadata(java.lang.String[] docIDsOrCollIDs)

Specified by:

getMetadata in interface FedoraToGS3Interface

Parameters:

docIDsOrCollIDs - is an array of identifiers which may be either the fedora pids for collections, or otherwise may be a document identifier. In the last case, the document ID may consist of either "documentPID-sectionNumber" or may just be just fedora documentPID

Returns:

a greenstone DocumentMetadataRetrieve response for the documents or collections indicated by the docIDsOrCollIDs.

getMetadata

protected org.w3c.dom.Element getMetadata(org.w3c.dom.Document doc,
                                          java.lang.String id)
                                   throws java.rmi.RemoteException,
                                          java.io.UnsupportedEncodingException,
                                          org.xml.sax.SAXException,
                                          java.io.IOException

Method that takes a new DOM document, as well as an identifier of either a collection or document (which may be a fedora pid for the collection or document, or may be the documentPid-sectionNumber for a document) and returns a documentNode element for it: <documentNode><metadataList> <metadata name="">value</metadata> ... </metadataList></documentNode>

Parameters:

id - denotes a collection pid, a document pid or a docID of the form "documentpid-sectionNumber"

Returns:

documentNode containing the metadata for the collection or document given by parameter ID

Throws:

java.rmi.RemoteException

java.io.UnsupportedEncodingException

org.xml.sax.SAXException

java.io.IOException

addMetadataWithNamespacedTagNames

protected void addMetadataWithNamespacedTagNames(org.w3c.dom.Document doc,
                                                 org.w3c.dom.Element metadataList,
                                                 java.lang.String metaDatastream,
                                                 java.lang.String metadataSet)
                                          throws org.xml.sax.SAXException,
                                                 java.io.IOException

This method retrieves all the metadata elements in the metaDataStream parameter of the form <"metadataSetNS:metadata">"value"</metadata> where metadataSetNS is the namespace of each tag, and creates a new element of the form <metadata name="metadataSetNS:metadata">"value"</metadata> for each. Each of these are then appended to the metadataList parameter.

Parameters:

doc - is the Document object using which the new metadata Elements are to be constructed

metadataList - is the <metadataList> Element to which the new metadata Elements are to be appended as children.

metaDatastream - the metadata datastream in string form (e.g. the Dublin Core metadata stored in the Fedora repository).

metadataSet - is the constant datastream identifier, e.g. "DC". At present this method only applies to the DC metadata as that's the only one where each tagname is different except for the constant dc: namespace.

Throws:

org.xml.sax.SAXException

java.io.IOException

addMetadataWithFixedTagName

protected void addMetadataWithFixedTagName(org.w3c.dom.Document doc,
                                           org.w3c.dom.Element metadataList,
                                           java.lang.String metaDatastream,
                                           java.lang.String metadataSet)
                                    throws org.xml.sax.SAXException,
                                           java.io.IOException

This method retrieves all the metadata elements in the metaDataStream of the form <"namespace:"metadata name="metadataName">value</metadata> where "namespace" is the namespace prefix of each tag, and metadataName is the name of the metadata (like author, title). For each element it creates a corresponding new element of the form <metadata name="namespace:metadataName">value</metadata>. Each of these are then appended to the metadataList parameter.

Parameters:

doc - is the Document object using which the new metadata Elements are to be constructed

metadataList - is the <metadataList> Element to which the new metadata Elements are to be appended as children.

metaDatastream - the metadata datastream in string form (e.g. the EX/Greenstone extracted metadata or DLS metadata stored in the Fedora repository).

metadataSet - is the constant datastream identifier, e.g. "DLS" or "EX". At present this method applies to the DLS and EX metadata as they have constant tagnames throughout.

Throws:

org.xml.sax.SAXException

java.io.IOException

getTitleMetadata

public java.lang.String getTitleMetadata(java.lang.String docID)

Given a document identifier, returns a GS3 DocumentMetadataRetrieve response message containing ONLY the Title metadata for the document.

Specified by:

getTitleMetadata in interface FedoraToGS3Interface

Parameters:

docID - is a document identifier (docID can either be a <pid> of an item (document) in the fedora repository, or it can be "<pid>-sectionNumber".

Returns:

a GS3 DocumentMetadataRetrieve response message containing the Title metadata for the requested document

getTitleMetadata

public java.lang.String getTitleMetadata(java.lang.String[] docIDs)

Given a document identifier, returns a GS3 DocumentMetadataRetrieve response message containing ONLY the Title metadata for the documents.

Specified by:

getTitleMetadata in interface FedoraToGS3Interface

Parameters:

docIDs - is a list of document identifiers (where docID can either be a <pid> of an item (document) in the fedora repository, or it can be "<pid>-sectionNumber".

Returns:

a GS3 DocumentMetadataRetrieve response message containing the Title metadata for all the requested documents

getTitleMetadata

protected org.w3c.dom.Element getTitleMetadata(org.w3c.dom.Document doc,
                                               java.lang.String docID)
                                        throws java.rmi.RemoteException,
                                               java.io.UnsupportedEncodingException,
                                               org.xml.sax.SAXException,
                                               java.io.IOException

Method that takes a new DOM document, as well as an identifier of either a document or document section and returns a documentNode element containing the title metadata for it: <documentNode nodeID="docID"><metadataList> <metadata name="Title">sometitle</metadata> </metadataList></documentNode>

Parameters:

docID - denotes the id of a document or a document section, so id is either a document-pid or it's of the form documentpid-sectionNumber

Returns:

documentNode containing the metadata for the collection or document given by parameter ID

Throws:

java.rmi.RemoteException

java.io.UnsupportedEncodingException

org.xml.sax.SAXException

java.io.IOException

getDocumentStructure

public java.lang.String getDocumentStructure(java.lang.String docID)

Specified by:

getDocumentStructure in interface FedoraToGS3Interface

Parameters:

docID - the identifier for the document whose structure is required. This is of the format "greenstone:<collectionName>-<docPID>" OR "greenstone:<collectionName>-<docPID>-<sectioNumber>" where "greenstone:<collectionName>-<docPID>-1" is the same as "greenstone:<collectionName>-<docPID>" and will return the same response

Returns:

the documentStructure of the document or section given by docID. The structure is returned in the XML format of a Greenstone3 DocumentStructureRetrieve response message. This method returns the entire subSection of the docID (that is, all descendants included).

getChildren

public java.lang.String getChildren(java.lang.String docID)

Specified by:

getChildren in interface FedoraToGS3Interface

Parameters:

docID - the identifier for the document whose structure is required. This is of the format "greenstone:<collectionName>-<docPID>" OR "greenstone:<collectionName>-<docPID>-<sectioNumber>" where "greenstone:<collectionName>-<docPID>-1" is the same as "greenstone:<collectionName>-<docPID>" and will return the same response

Returns:

a view of the structure of the document or section given by docID which contains only the section and its direct children. This structure is returned in the XML format of a Greenstone3 DocumentStructureRetrieve response message.

getDocumentStructure

public java.lang.String getDocumentStructure(java.lang.String[] docIDs)

Specified by:

getDocumentStructure in interface FedoraToGS3Interface

Parameters:

docIDs - is an array of identifiers for the documents whose structures are required. This is of the format "greenstone:<collectionName>-<docPID>" OR "greenstone:<collectionName>-<docPID>-<sectioNumber>" where "greenstone:<collectionName>-<docPID>-1" is the same as "greenstone:<collectionName>-<docPID>" and will return the same response

Returns:

the documentStructure of the documents or sections given by docIDs. The structure is returned in the XML format of a Greenstone3 DocumentStructureRetrieve response message. This method returns the entire subSection of each docID (that is, all descendants included).

getChildren

public java.lang.String getChildren(java.lang.String[] docIDs)

Specified by:

getChildren in interface FedoraToGS3Interface

Parameters:

docIDs - the identifiers for the documents whose structures are required. The docids are of the format "greenstone:<collectionName>-<docPID>" OR "greenstone:<collectionName>-<docPID>-<sectioNumber>" where "greenstone:<collectionName>-<docPID>-1" is the same as "greenstone:<collectionName>-<docPID>" and will return the same response

Returns:

the documentStructure of the documents or sections given by docIDs but only the sections and their children (not any further descendants). The structure is returned in the XML format of a Greenstone3 DocumentStructureRetrieve response message.

getStructure

protected java.lang.String getStructure(java.lang.String[] docIDs,
                                        int levels)

Returns a greenstone3 DocumentStructureRetrieve XML response message containing the document structures for the given docIDs. Similar to FedoraConnection.getTOC(), but instead of fedora formatted XML, greenstone formatted XML is returned. The requested section of the table of contents (TOC) for a document is converted into the greenstone3 xml format that is returned upon DocumentStructureRetrieve requests.

Parameters:

docIDs - the documentIDs for which the section's structure is returned; where a docID is either a fedora pid <docPID> or <docPID>-<sectionNumber>.

levels - - either CHILDREN or DESCENDANTS. CHILDREN returns only the first-level descendants (children) of the requested document sections indicated by docIDs. DESCENDANTS returns all descendants of all the document-sections denoted by docIDs.

Returns:

a greenstone3 DocumentStructureRetrieve XML response message in String format with the structure of the docIDs requested.

getStructureElement

protected void getStructureElement(org.w3c.dom.Element docNodeList,
                                   java.lang.String[] docIDs,
                                   int levels)
                            throws java.rmi.RemoteException,
                                   java.io.UnsupportedEncodingException,
                                   org.xml.sax.SAXException,
                                   java.io.IOException

Given a <documentNodeList> portion of a greenstone3 DocumentStructureRetrieve XML response message, this method will populate it with the <documentNodes> that represent the structure of the given docIDs.

Parameters:

docNodeList - is a <documentNodeList> to which <documentNodes> of the doc structures are appended.

docIDs - the documentIDs for which the section's structure is returned; where a docID is either a fedora pid <docPID> or <docPID>-<sectionNumber>.

levels - - either CHILDREN or DESCENDANTS. CHILDREN returns only the first-level descendants (children) of the requested document sections indicated by docIDs. DESCENDANTS returns all descendants of all the document-sections denoted by docIDs.

Throws:

java.rmi.RemoteException

java.io.UnsupportedEncodingException

org.xml.sax.SAXException

java.io.IOException

getStructure

protected org.w3c.dom.Element getStructure(org.w3c.dom.Document doc,
                                           java.lang.String requestingDocID,
                                           java.lang.String docID,
                                           org.w3c.dom.Element section)

Takes the portion of the XML document outlining the structure of the document (section)--in the format this is stored in Fedora--and returns Greenstone 3 DOM XML format for outlining document structure.

Parameters:

requestingDocID - is the identifier of the document for which the structure was requested. It's this document's children or descendants that will be returned. Note that this is not always the same as (clear from) parameter docID.

docID - is the documentID for which the section's structure is returned where docID = "docPID-sectionNumber".

section - - the fedora section XML that is being mirrored in greenstone3 format.

Returns:

a <documentNode> element that contains a greenstone3 DocumentStructureRetrieve XML corresponding to the parameter Element section (which is in fedora XML), for the document indicated by docID.

createDocStructure

protected void createDocStructure(org.w3c.dom.Document doc,
                                  org.w3c.dom.Element section,
                                  org.w3c.dom.Element parent,
                                  java.lang.String docPID)

Recursive method that creates a documentStructure mirroring parameter section, starting from parameter parent down to all descendants

Parameters:

section - is the XML <Section> in the fedora repository's TOC for the docPID whose substructure is to be mirrored

parent - is the XML documentNode in the greenstone repository whose descendants created by this method will correspond to the descendants of parameter section.

doc - is the document containing the parent;

docPID - is the prefix of all nodeIDs in the parent's structure

createDocNodeFromSubsection

protected org.w3c.dom.Element createDocNodeFromSubsection(org.w3c.dom.Document doc,
                                                          org.w3c.dom.Element subSection,
                                                          java.lang.String docID)

Given a particular subsection element, this method creates a Greenstone3 DocumentNode element that mirrors it.

Parameters:

doc - is the document that will contain the created DocumentNode

docID - is the prefix of all nodeIDs in the parent's structure

subSection - is the XML <Section> in the fedora repository's TOC for the docPID which will be mirrored in the greenstone XML documentNode that will be returned.

Returns:

a greenstone <documentNode> that represents the fedora TOC's <Section> element passed as parameter subSection.

getContent

public java.lang.String getContent(java.lang.String docID)

Given an identifier that is either a docPID or a concatenation of docPID+sectionID, this method works out the fedora assigned docPID and sectionID and then calls getContentBody(docPID, sectionID) with those.

Specified by:

getContent in interface FedoraToGS3Interface

Parameters:

docID - is expected to be of the form "greenstone:<collectionName>-<docPID>-<sectionNumber>" or "greenstone:<collectionName>-<docPID>" If it is "greenstone:<collectionName>-<docPID>", then the content for "greenstone:<collectionName>-1" ("greenstone:<collectionName>-Section1") is returned!

getContent

public java.lang.String getContent(java.lang.String[] docIDs)

Given an identifier that is a concatenation of docID+sectionID, this method works out the fedora assigned docPID and sectionID and then calls getContentBody(docPID, sectionID) with those.

Specified by:

getContent in interface FedoraToGS3Interface

Parameters:

docIDs - is an array of document identifiers of the form "greenstone:<collectionName>-<docPID>-<sectionNumber>" If it is "greenstone:<collectionName>-<docPID>", then the content for "greenstone:<collectionName>-Section1" is returned!

getContentBody

protected java.lang.String getContentBody(java.lang.String docPID,
                                          java.lang.String sectionID)
                                   throws java.rmi.RemoteException,
                                          java.io.UnsupportedEncodingException,
                                          org.xml.sax.SAXException,
                                          java.io.IOException

Gets the contents of a textNode from a section.

Parameters:

docPID - the pid of the document from which a section's text is to be retrieved.

sectionID - is the section identifier of the document denoted by docPID whose text is to be returned.

Returns:

the text content of a section.

Throws:

java.rmi.RemoteException

java.io.UnsupportedEncodingException

org.xml.sax.SAXException

java.io.IOException

createResponseMessage

protected org.w3c.dom.Element createResponseMessage(org.w3c.dom.Document doc,
                                                    org.w3c.dom.Element content,
                                                    java.lang.Exception ex,
                                                    java.lang.String responseType,
                                                    java.lang.String originator)

Here we create the greenstone's response message element: <message≶<response><content></response></message>

Parameters:

doc - - the Document object which should me used to create the <message> and <response> elements

content - - the element that is to be nested inside <response>

ex - - any exception that occurred when trying to create the content parameter

responseType - - the value for the type attribute of <response>, such as "describe", "retrieve", "browse", "query"...

originator - - indiates the collectionName or service (like DocumentContentRetrieve) from where this response message originates

Returns:

a greenstone response-message element.

createServiceList

protected org.w3c.dom.Element createServiceList(org.w3c.dom.Document doc)

Parameters:

doc - - the Document object which should me used to create the <serviceList> element

Returns:

a <serviceList> Element as defined by GS3: containing all the services (denoted by <service> elements) that are supported by FedoraGS3. At present these are: DocumentContentRetrieve, DocumentMetadataRetrieve, DocumentStructureRetrieve, TextQuery, FieldQuery, ClassifierBrowse, ClassifierBrowseMetadataRetrieve (as indicated by member var serviceNames).

getServiceList

public java.lang.String getServiceList()

Specified by:

getServiceList in interface FedoraToGS3Interface

Returns:

a GS3 response message for a describe services request: indicating the list of services supported by the Fedora-Greenstone interface. These are DocumentContentRetrieve, DocumentMetadataRetrieve, DocumentStructureRetrieve, ClassifierBrowse, TextQuery, FieldQuery, ClassifierBrowseMetadataRetrieve - as indicated by member variable serviceNames.

getCollectionList

public java.lang.String getCollectionList()

Specified by:

getCollectionList in interface FedoraToGS3Interface

Returns:

a GS3 describe response message listing the collections and collection-specific metadata stored in the Fedora-Greenstone repository.

describeCollection

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

Specified by:

describeCollection in interface FedoraToGS3Interface

Parameters:

collectionName - - the name of the collection that is to be described. It will be converted to a fedora collection pid, which is of the form "greenstone:<collectionName>-collection".

Returns:

a GS3 describe response message for a collection in the Fedora-Greenstone repository.

describeCollectionServices

public java.lang.String describeCollectionServices(java.lang.String collectionName)

Specified by:

describeCollectionServices in interface FedoraToGS3Interface

Parameters:

collectionName - - the name of the collection whose services are to be described. It will be converted to a fedora collection pid, which is of the form "greenstone:<collectionName>-collection".

Returns:

a GS3 describe response message for the services of a collection in the Fedora-Greenstone repository. So far, these services are the same for all fedora collections: they are the services given in member variable serviceNames: DocumentContent/Metadata/StructureRetrieve, ClassifierBrowse, ClassifierBrowseMetadataRetrieve.

describeService

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

All collections in this Digital Library (Fedora Repository) share the same services, so this method returns the same as describeCollectionService(collName, serviceName).

Specified by:

describeService in interface FedoraToGS3Interface

Parameters:

serviceName - - the name of the service in the collection which is to be described.

Returns:

a GS3 describe response message for the requested service of the given collection. DocumentContent/Metadata/StructureRetrieve return nothing special except their names; browse (and any query) return more complex XML responses. All collections in this Digital Library (Fedora Repository) share the same services, so this method returns the same as describeService(serviceName).

describeTextQueryService

protected void describeTextQueryService(org.w3c.dom.Element service)

Appends children to the parameter service Element that make the final service Element into a describe response XML for FedoraGS3's TextQuery service.

Parameters:

service - is the service Element that is being filled out.

describeFieldQueryService

protected void describeFieldQueryService(org.w3c.dom.Element service)

Appends children to the parameter service Element that make the final service Element into a describe response XML for FedoraGS3's FieldQuery service.

Parameters:

service - is the service Element that is being filled out.

describeCollectionService

public java.lang.String describeCollectionService(java.lang.String collectionName,
                                                  java.lang.String serviceName)

Description copied from interface: FedoraToGS3Interface

All collections in this Digital Library (Fedora Repository) share the same services, so this method returns the same as describeService(serviceName).

Specified by:

describeCollectionService in interface FedoraToGS3Interface

Parameters:

collectionName - - the name of the collection whose service is to be described. It will be converted to a fedora collection pid, which is of the form "greenstone:<collectionName>-collection".

serviceName - - the name of the service in the collection which is to be described.

Returns:

a GS3 describe response message for the requested service of the given collection. DocumentContent/Metadata/StructureRetrieve return nothing special except their names; browse (and any query) return more complex XML responses. All collections in this Digital Library (Fedora Repository) share the same services, so this method returns the same as describeService(serviceName).

browse

public java.lang.String browse(java.lang.String collectionName,
                               java.lang.String classifierID)

This method performs the implemented browse operation: allowing the user to browse the titles of documents in the given collection by letter and returning the results.

Specified by:

browse in interface FedoraToGS3Interface

Parameters:

classifierID - is the id of the classifier on which to browse. In this case, the classifier indicates whether we browse titles by letter, or browse (documents) by collection; and it is of the form <CL(letter)>.

collectionName - is the name of the collection whose documents starting with the given letter will be returned.

Returns:

a GS3 DocumentStructureRetrieve response message which lists all the documents that start with the letter indicated by parameter classifier.

browseMetadataRetrieve

public java.lang.String browseMetadataRetrieve(java.lang.String[] classNodeIDs)

This method performs something equivalent to a greenstone3 ClassifierBrowseMetadataRetrieve on the classifierNodeIDs

Specified by:

browseMetadataRetrieve in interface FedoraToGS3Interface

Parameters:

classNodeIDs - array of classifierNode IDs of for which the metadata needs to be returned.

Returns:

a GS3 ClassifierBrowseMetadataRetrieve response message which lists the metadata for all the classifierNodes passed as parameter.

createClassifierElement

protected org.w3c.dom.Element createClassifierElement(org.w3c.dom.Document doc,
                                                      java.lang.String content,
                                                      int classifierNum,
                                                      java.lang.String displayNameVal,
                                                      java.lang.String displayDescrVal)

Parameters:

doc - - the document used to create the element

content - - value of the content attribute

classifierNum - - the number suffixed to the CL, together forming the classifier Node's ID

displayNameVal - is the bodytext of a named displayItem element

displayDescrVal - is the bodytext of a displayItem element with description

Returns:

a newly created element of the following format: <classifier content="somecontent" name="CL+num"> <displayItem name="name">someClassifierName</displayItem> <displayItem name="description">Browse by classifier name</displayItem> </classifier>

createNameValuePairElement

protected org.w3c.dom.Element createNameValuePairElement(org.w3c.dom.Document doc,
                                                         java.lang.String elementName,
                                                         java.lang.String name,
                                                         java.lang.String value)

Parameters:

doc - - the document used to create the element

elementName - - the tag name

name - - value of attribute name

value - - the body text of the element

Returns:

a newly created element of the following format: <elementName name="somename">"some display value"</elementName>

textQuery

public java.lang.String[] textQuery(java.lang.String collection,
                                    java.lang.String query,
                                    int maxDocs)
                             throws java.lang.Exception

Parameters:

collection - is the collection to search in

query - is the query term to search for. It won't specify the indexed field to search in, which will mean that GSearch will search all default indexed fields.

maxDocs - is the maximum number of results to return (which at present we consider equivalent to FedoraGSearch's hitpageSize).

Throws:

java.lang.Exception

fieldQuery

public java.lang.String[] fieldQuery(java.lang.String collection,
                                     java.util.Map nameValParamsMap,
                                     int maxDocs)
                              throws java.lang.Exception

This method performs a fieldquery, searching for x number of phrases in each of the 4 indexed fields.

Parameters:

collection - is the collection to search in

nameValParamsMap - is a Map of several(key, value) entries, 4 of which we're concerned with here: - the keys are ALL_FIELDS, DOC_TITLES, ALL_TITLES, FULLTEXT - the values are a comma separated list of terms (phrases or single words) to search that field in. There may be more than 1 or there may be none (in which case there may be N empty values or spaces separated by commas).

maxDocs - is the maximum number of results to return (which at present we consider equivalent to FedoraGSearch's hitpageSize).

Throws:

java.lang.Exception

query

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

Specified by:

query in interface FedoraToGS3Interface

Parameters:

nameValParamsMap - is a Hashmap 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.

main

public static void main(java.lang.String[] args)