org.greenstone.fedora.services
Class FedoraConnection

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

All Implemented Interfaces:

FedoraGS3DL

Direct Known Subclasses:

FedoraGS3Connection

public class FedoraConnection
extends java.lang.Object
implements FedoraGS3DL

Class that establishes a connection with Fedora's web services (via Java stub classes for the same) and then provides methods to retrieve Greenstone-specific data, such as the TOC, EX, DC,and Section datastreams of the Greenstone documents stored in Fedora's repository. These datastreams are returned as Strings without any changes being made to them.

Author:

ak19

Field Summary

protected static fedora.server.access.FedoraAPIA	APIA The object used to access the Fedora API-A web service methods
protected java.lang.String	baseURL The location of the fedora server, usually of the form http://localhost:8080/fedora
protected javax.xml.parsers.DocumentBuilder	builder DocumentBuilder used to create and parse XML documents
protected static java.lang.String	defaultPortAddressSuffix The part of the portAddress that comes after the baseURL.
protected java.lang.String	fedoraVersion Version of the running fedora server
protected static java.lang.String	GET
protected static java.lang.String	INTERNAL_NODE
protected java.lang.String	lang The preferred language of the displat content
protected int	maxresults The maximum number of collections to retrieve
protected java.lang.String	portAddressSuffix The user-specified portAddressSuffix of the Fedora Access web services (endpoint URL in the WSDL), usually of the form http://localhost:8080/fedora/services/access Users can tell FedoraGS3 to try accessing that first by setting the "port.address.suffix" property in the properties file.
protected static java.lang.String	SUPPORTED_VERSION The version of fedora that is supported by class FedoraConnection
protected static java.lang.String	TYPE

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

FedoraConnection()
Default constructor which takes input from the user to get host, port, fedora username and password.

FedoraConnection(java.io.File propertyFile)
Single argument constructor that takes the name of the properties file defining the values of the initialisation parameters required to instantiate a FedoraConnection.

FedoraConnection(java.lang.String protocol, java.lang.String host, int port, java.lang.String fedoraServerUsername, java.lang.String fedoraServerPassword)
Code for this constructor is from DemoSOAPClient.java.

Method Summary

java.lang.String[]	browseTitlesByLetter(java.lang.String collName, java.lang.String letter) Implements browsing document titles of a greenstone collection stored in the fedora repository by letter.
protected java.lang.String	convertToMetaNumber(java.lang.String number) Given a number of the form x(.y.z), this method returns this number as is, except when x = 1, in which case, it would return .y.z That is, given number=3.2.1, this method would return 3.2.1 But, given number=1.2.3, this method would return .2.3.
protected void	createAPIA(fedora.server.access.FedoraAPIAServiceLocator serviceLocator, java.lang.String portSuffix, java.lang.String messageInsert, boolean isUserSpecifiedPortAddressSuffix) Tries to create the FedoraAPIA instance using the serviceLocator and the given portSuffix.
protected fedora.server.types.gen.FieldSearchResult	findObjectsWithTitlesContaining(java.lang.String collName, java.lang.String titleWord)
java.lang.String	getAssocFileBaseURL()
java.lang.String	getBaseURL()
java.lang.String	getChildrenOfSection(java.lang.String docPID, java.lang.String sectionID)
org.w3c.dom.Element	getChildrenOfSectionXML(java.lang.String docPID, java.lang.String sectionID)
java.lang.String[]	getCollectionDocs(java.lang.String colPID) Searches the fedora repository for all greenstone:<colPID>* and returns the PIDs of the data objects found, with the exception of greenstone:<colPID>-collection, which is not a document but a collection PID.
java.lang.String	getCollectionName(java.lang.String collPID)
java.lang.String[]	getCollectionNames(java.lang.String[] collPIDs)
java.lang.String	getCollectionPID(java.lang.String collName)
java.lang.String[]	getCollectionPIDs(java.lang.String[] collNames)
java.lang.String[]	getCollections() Gets all greenstone collections.
java.lang.String	getCollectionTitle(java.lang.String collPID) Gets the title of the collection denoted by the given collection's pid by retrieving the title metadata for it from the collection's EX datastream.
java.lang.String[]	getCollectionTitles(java.lang.String[] collPIDs)
java.lang.String	getDC(java.lang.String pid) All objects (incl "greenstone:*" objects) in fedora - be they collections, top-level documents or document sections - have a DC datastream.
java.lang.String	getDLS(java.lang.String pid) Some "greenstone:*" top-level documents in the fedora repository (but not greenstone collections or document sections) have a DLS metadata datastream.
java.lang.String	getDocName(java.lang.String docPID)
java.lang.String	getDocTitle(java.lang.String docPID) Gets the title metadata for a particular doc object in a collection denoted by docPID.
java.lang.String[]	getDocTitles(java.lang.String[] docPIDs)
java.lang.String	getEX(java.lang.String pid) All "greenstone:*" objects in fedora (be they collections be they collections, top-level documents or document sections) have an EX datastream.
java.lang.String	getFedoraVersion() The version of the running Fedora server, which may or may not match the supported version.
protected java.lang.String	getItem(java.lang.String docPID, java.lang.String itemID) Return a datastream of a document, given the document's id and the item id of the datastream which is to be retrieved.
java.lang.String	getLanguage()
int	getMaxResults() The default maximum number of search results returned for a search.
java.lang.String	getPortAddressURL()
java.lang.String	getSection(java.lang.String docPID, java.lang.String sectionID)
java.lang.String	getSectionDCMetadata(java.lang.String docPID, java.lang.String sectionID)
java.lang.String	getSectionEXMetadata(java.lang.String docPID, java.lang.String sectionID) Returns the section EX metadata XML datastream for SectionID which may be a section name or number.
java.lang.String[]	getSectionNames(java.lang.String docPID) Given the pid of a document fedora data object, this method will return all itemIDs that are part of that data object and are Sections.
java.lang.String[]	getSectionNumbers(java.lang.String docPID) Given the pid of a document fedora data object, this method will return all itemIDs that are part of that data object and are Sections, but just the Section numbers are returned.
java.lang.String	getSectionTitle(java.lang.String docPID, java.lang.String sectionID)
java.lang.String[]	getSectionTitles(java.lang.String[] docPIDs, java.lang.String[] sectionIDs)
java.lang.String	getSubsection(java.lang.String docPID, java.lang.String sectionID)
org.w3c.dom.Element	getSubsectionXML(java.lang.String docPID, java.lang.String sectionID)
protected org.w3c.dom.Element	getSubstructure(org.w3c.dom.Element e, boolean descendents) Convert the given Element to a String representing the same XML.
static java.lang.String	getSupportedVersion() Static method that returns the version of Fedora supported by this class FedoraConnection.
protected java.lang.String	getTitle(java.lang.String exStream) Given a string representation of a document's or document section's EX datastream -- which is a greenstone extracted metadata XML file -- of the form: <ex> <ex:metadata name="Title">sometitle</ex:metadata> <ex:metadata name="...">....</ex:metadata> ...
java.lang.String	getTitle(java.lang.String docPID, java.lang.String sectionID)
java.lang.String[]	getTitles(java.lang.String docPID, java.lang.String[] sectionIDs)
java.lang.String	getTOC(java.lang.String pid) All "greenstone:*" objects in fedora (be they collections or documents) have a TOC datastream.
protected void	init(java.lang.String protocol, java.lang.String host, java.lang.String port, java.lang.String fedoraServerUsername, java.lang.String fedoraServerPassword) Init method that is called by the constructor to set some important member variables including instantiating the APIA object used to invoke the Fedora APIA web service operations.
static void	main(java.lang.String[] args)
protected java.lang.String	removePrefix(java.lang.String str, java.lang.String prefix) Given something like str="SECTION1.2.1" and prefix="SECTION" this method returns "1.2.1".
java.lang.String[]	searchDocumentTitles(java.lang.String collName, java.lang.String titleContents, boolean startsWith) Implements querying document DC titles of a greenstone collection stored in the fedora repository for a term that may occur anywhere in their titles.
protected void	setInitialisationProperties(java.util.Properties properties) Method that loops to display the dialog that retrieves the fedora server initialisation properties from the user.
void	setLanguage(java.lang.String lang) Sets the the default language used to query for titles (and anything else where there are multiple language options).
void	setMaxResults(int maxresults) Set the default maximum number of search results returned for a search.
protected static java.util.Properties	showAuthenticationPopup(java.util.Properties properties) Static method that displays a popup to allow the user to provide Fedora authentication (username, pwd) and connection (protocol+host, port) details.

Methods inherited from class java.lang.Object

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

Field Detail

SUPPORTED_VERSION

protected static final java.lang.String SUPPORTED_VERSION

The version of fedora that is supported by class FedoraConnection

See Also:

Constant Field Values

TYPE

protected static final java.lang.String TYPE

See Also:

Constant Field Values

INTERNAL_NODE

protected static final java.lang.String INTERNAL_NODE

See Also:

Constant Field Values

GET

protected static final java.lang.String GET

See Also:

Constant Field Values

APIA

protected static fedora.server.access.FedoraAPIA APIA

The object used to access the Fedora API-A web service methods

fedoraVersion

protected java.lang.String fedoraVersion

Version of the running fedora server

baseURL

protected java.lang.String baseURL

The location of the fedora server, usually of the form http://localhost:8080/fedora

portAddressSuffix

protected java.lang.String portAddressSuffix

The user-specified portAddressSuffix of the Fedora Access web services (endpoint URL in the WSDL), usually of the form http://localhost:8080/fedora/services/access Users can tell FedoraGS3 to try accessing that first by setting the "port.address.suffix" property in the properties file. FedoraGS3 itself will not write the portAddressSuffix currently used in the file for next time, but leave whatever value was entered in the properties file. The portAddress--not just suffix--currently in use (once the FedoraAPIA handle has been instantiated) can be obtained through getPortAddressURL() method.

defaultPortAddressSuffix

protected static final java.lang.String defaultPortAddressSuffix

The part of the portAddress that comes after the baseURL. It is usually: "/services/access"

See Also:

Constant Field Values

lang

protected java.lang.String lang

The preferred language of the displat content

maxresults

protected int maxresults

The maximum number of collections to retrieve

builder

protected javax.xml.parsers.DocumentBuilder builder

DocumentBuilder used to create and parse XML documents

Constructor Detail

FedoraConnection

public FedoraConnection(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

Code for this constructor is from DemoSOAPClient.java. Instantiates the APIA handle using the protocol, host, port, fedora server repository username and password.

Parameters:

host - - the fedora server host (may be prefixed with http:// or https:// if parameter protocol is empty). If there's no protocol, and no protocol prefixed to the host, then the protocol defaults to http.

protocol - - either http or https (or empty "")

port - - the port on which fedora is running.

fedoraServerUsername - - the administrator username required to access the fedora server's repository. ("fedoraAdmin" unless changed).

fedoraServerPassword - - the fedora server repository's administrator password. If none was set on fedora installation, this can be empty ("").

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

FedoraConnection

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

Default constructor which takes input from the user to get host, port, fedora username and password. It keeps looping to display authentication popup, until valid values are entered: (a) if password is wrong, a RemoteException is thrown and popup reappears; This popup keeps appearing until the password and username are correct (as long as there's indeed a fedora server listening at the given host and port). (b) SSLHandshakeException occurs: this happens EITHER when the user prefixed the 'https' protocol to the host string when it should have been 'http'; OR the ssl connection failed for some other reason. Allowing for the 1st case, the authentication popup is displayed just once more. On the second (consec) attempt, the SSLHandshakeException is rethrown. NOTE: if a fedora server at the protocol (https or http) isn't accessible, it takes a long time for the SSLHandshakeException to be thrown. (c) if the connection is refused, then a ConnectException is thrown. In that case, it's EITHER because the host and port values that were entered are wrong (and the authentication popup dialog is redisplayed just once more allowing the user to correct host/port values) OR the entered host and part were right but the fedora server at this host and port is not running. On the second consecutive attempt where a ConnectionException is thrown, it's no longer processed but rethrown, as there's no use in redisplaying the authentication popup when the problem is not an authentication issue. (d) Another IOException (other than the SSLHandshakeException of (b)) occurs when there is indeed a server listening at the host and port entered, but it's not a Fedora server, because it is unable to process Fedora requests. If the expected message is found in the exception, than the authentication popup is displayed. However, other causes for an IOException are not handled. In such cases, the IOException is rethrown. (Note that IOException is not in the throws clause - other causes for it being unknown, it can be be considered as the more generic Exception.

Throws:

javax.xml.parsers.ParserConfigurationException

java.net.MalformedURLException

FedoraGS3Exception.CancelledException

java.net.ConnectException

java.rmi.RemoteException

javax.net.ssl.SSLHandshakeException

java.lang.Exception

FedoraConnection

public FedoraConnection(java.io.File propertyFile)
                 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 that takes the name of the properties file defining the values of the initialisation parameters required to instantiate a FedoraConnection. These are fedora server username, password, host and port. If these values are not present in the file, they are set to "" before showing the initialisation input dialog.

Parameters:

propertyFile - is the name of the properties file specifying the values for Fedora server username, password, host and port.

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

getSupportedVersion

public static java.lang.String getSupportedVersion()

Static method that returns the version of Fedora supported by this class FedoraConnection.

getFedoraVersion

public java.lang.String getFedoraVersion()

The version of the running Fedora server, which may or may not match the supported version.

getLanguage

public java.lang.String getLanguage()

Specified by:

getLanguage in interface FedoraGS3DL

Returns:

the default language used to query for titles (and anything else where there are multiple language options). Upon initialisation, this defaults to English.

setLanguage

public void setLanguage(java.lang.String lang)

Sets the the default language used to query for titles (and anything else where there are multiple language options). If the default language for any query is not available, then English ("en") is used. If that's not available then the first other available language is used.

Specified by:

setLanguage in interface FedoraGS3DL

Parameters:

lang - - the two-letter language code to set the default language to.

getMaxResults

public int getMaxResults()

The default maximum number of search results returned for a search. Upon initialisation, this defaults to Java's Integer.MAX_VALUE.

Specified by:

getMaxResults in interface FedoraGS3DL

setMaxResults

public void setMaxResults(int maxresults)

Set the default maximum number of search results returned for a search.

Specified by:

setMaxResults in interface FedoraGS3DL

Parameters:

maxresults - - the new default maximum number of search results to be returned.

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

Method that loops to display the dialog that retrieves the fedora server initialisation properties from the user. If there is a property file with values set already, it will display the previously entered values by loading them from that file. Otherwise, input fields in the dialog are empty.

Parameters:

properties - the Properties Hashmap storing values for username, password, host and port (and any errormessage).

Throws:

javax.xml.parsers.ParserConfigurationException

java.net.MalformedURLException

FedoraGS3Exception.CancelledException

java.net.ConnectException

java.rmi.RemoteException

javax.net.ssl.SSLHandshakeException

java.lang.Exception

showAuthenticationPopup

protected static java.util.Properties showAuthenticationPopup(java.util.Properties properties)
                                                       throws FedoraGS3Exception.CancelledException

Static method that displays a popup to allow the user to provide Fedora authentication (username, pwd) and connection (protocol+host, port) details.

Parameters:

properties - is a Properties HashMap where the property Keys which must have been put in here in advance (even with "" Values if appropriate) are:

 - username
 - password
 - host (may - but need not - be prefixed with either of the protocols 
   "http://" and "https://"
 - port
 - errorMessage (displayed near the top of the popup dialog). Can be "".
 

The values stored in the properties HashMap for the above property are initially displayed in the fields and the user can overwrite them. This is useful in such cases where invalid values were entered and this popup must be redisplayed to allow the user to correct their previous input.

Returns:

the same HashMap Properties which was passed as parameter.

Throws:

FedoraGS3Exception.CancelledException

init

protected void init(java.lang.String protocol,
                    java.lang.String host,
                    java.lang.String port,
                    java.lang.String fedoraServerUsername,
                    java.lang.String fedoraServerPassword)
             throws javax.xml.parsers.ParserConfigurationException,
                    java.net.MalformedURLException,
                    FedoraGS3Exception.AuthenticationFailedException,
                    java.rmi.RemoteException,
                    java.lang.Exception

Init method that is called by the constructor to set some important member variables including instantiating the APIA object used to invoke the Fedora APIA web service operations.

Parameters:

protocol - can be http or https

host - is the name of the Fedora server host

port - is the port number (String form) of the Fedora server

fedoraServerUsername - is the user name to access the Fedora Server

fedoraServerPassword - is the password needed to access the Fedora Server

Throws:

javax.xml.parsers.ParserConfigurationException

java.net.MalformedURLException

FedoraGS3Exception.AuthenticationFailedException

java.rmi.RemoteException

java.lang.Exception

createAPIA

protected void createAPIA(fedora.server.access.FedoraAPIAServiceLocator serviceLocator,
                          java.lang.String portSuffix,
                          java.lang.String messageInsert,
                          boolean isUserSpecifiedPortAddressSuffix)
                   throws java.lang.Exception

Tries to create the FedoraAPIA instance using the serviceLocator and the given portSuffix. The APIA instance is obtained for the baseURL+portSuffix. Any exceptions are (processed and) rethrown or, if the flag isUserSpecifiedPortAddressSuffix is true, then the Remote Exception from AXIS that it can't find the target service to invoke is ignored so that the caller can retry with the default port- address suffix first before giving up.

Throws:

java.lang.Exception

getCollections

public java.lang.String[] getCollections()
                                  throws java.rmi.RemoteException

Gets all greenstone collections. Searches for greenstone:*-collection. Method getCollections() defaults to getting only those objects in fedora's repository whose pids are of the format greenstone:*-collection. The use of AutoFinder and findObjects is shown in fedora-2.2.1-src/src/java/fedora/client/search/ResultFrame.java The Fedora-APIA's method definition of findObjects is:

 fedora-types:FieldSearchResult findObjects(
                                fedora-types:ArrayOfString resultFields,
                                xsd:nonNegativeInteger maxResults,
                                fedora-types:FieldSearchQuery query )
 

Specified by:

getCollections in interface FedoraGS3DL

Returns:

an array of Strings containing the pids of all collections matching the format greenstone:*-collection.

Throws:

java.rmi.RemoteException

See Also:

The local fedora search page for how the search works, Fedora access API, API-A for method findObjects, XML type definition of FieldSearchQuery, does not apply: type definition of 2.1.1 FieldSearchQuery, BrowseController.java for an example

getDC

public java.lang.String getDC(java.lang.String pid)
                       throws java.rmi.RemoteException,
                              java.io.UnsupportedEncodingException

All objects (incl "greenstone:*" objects) in fedora - be they collections, top-level documents or document sections - have a DC datastream. This method returns the content (XML) of the DC datastream as it is stored in fedora's repository. (The pid/DC call is one of the default fedora-system 3 disseminations.) Try an example of the form: http://localhost:8080/fedora/get/<pid>/DC To obtain the DC/any datastream, we use method getDatastreamDissemination() of the interface FedoraAPIA. This method returns a MIMETypedStream. The method signature is: MIMETypedStream getDatastreamDissemination(String pid, String dsID, String asOfDateTime) where dsID = itemID (look at datastreams page of running fedora instance) To access the XML content of the MIMETypedObject returned, we use its method bytes[] getStream(), but when instantiating a String from this, we have to use the String() contructor where we can specify the charset encoding (in this case, it must be UTF-8). Else getStream() returns gobbledygook.

Specified by:

getDC in interface FedoraGS3DL

Parameters:

pid - - the fedora persistent identifier for an item in the fedora repository.

Returns:

a String version of the XML in the DC datastream for the fedora object denoted by pid.

Throws:

java.rmi.RemoteException

java.io.UnsupportedEncodingException

See Also:

FedoraAPIABindingSOAPHTTPSkeleton.java, the API-A web service stub class, TestAPIA.java, which contains an example of MIMETypedObject.getStream() usage., constructor String(byte[], java.lang.String), Charset.java, for character sets and encoding

getEX

public java.lang.String getEX(java.lang.String pid)
                       throws java.rmi.RemoteException,
                              java.io.UnsupportedEncodingException

All "greenstone:*" objects in fedora (be they collections be they collections, top-level documents or document sections) have an EX datastream. This method returns the content (XML) of the EX datastream as is. (It calls the default fedora-system 3 dissemination <pid>/EX.)

Specified by:

getEX in interface FedoraGS3DL

Parameters:

pid - - the fedora persistent identifier for an item in the fedora repository. Use MIMETypedStream APIA.getDatastreamDissemination(pid, itemID, asOfDateTime). Use String(bytes[], charset="UTF-8") to convert MIMETypedStream.getStream().

Returns:

a String version of the XML in the EX datastream for the fedora object denoted by pid.

Throws:

java.rmi.RemoteException

java.io.UnsupportedEncodingException

See Also:

getDC(String pid) throws Exception

getDLS

public java.lang.String getDLS(java.lang.String pid)
                        throws java.rmi.RemoteException,
                               java.io.UnsupportedEncodingException

Some "greenstone:*" top-level documents in the fedora repository (but not greenstone collections or document sections) have a DLS metadata datastream. This method returns the content (XML) of the DLS datastream as is. (It calls the default fedora-system 3 dissemination <pid>/DLS.)

Specified by:

getDLS in interface FedoraGS3DL

Parameters:

pid - - the fedora persistent identifier for an item in the fedora repository. Use MIMETypedStream APIA.getDatastreamDissemination(pid, itemID, asOfDateTime). Use String(bytes[], charset="UTF-8") to convert MIMETypedStream.getStream().

Returns:

a String version of the XML in the DLS datastream for the fedora object denoted by pid, or "" if the document given by pid has no DLS datastream.

Throws:

java.rmi.RemoteException

java.io.UnsupportedEncodingException

See Also:

getDC(String pid) throws Exception

getTOC

public java.lang.String getTOC(java.lang.String pid)
                        throws java.rmi.RemoteException,
                               java.io.UnsupportedEncodingException

All "greenstone:*" objects in fedora (be they collections or documents) have a TOC datastream. This method returns the content (XML) of the TOC datastream as is. (Calls default fedora-system 3 dissemination <pid>/TOC.)

Specified by:

getTOC in interface FedoraGS3DL

Parameters:

pid - - the fedora persistent identifier for an item in the fedora repository. Use MIMETypedStream APIA.getDatastreamDissemination(pid, itemID, asOfDateTime) Use String(bytes[], charset="UTF-8") to convert MIMETypedStream.getStream()

Returns:

a String version of the XML in the TOC datastream for the fedora object denoted by pid.

Throws:

java.rmi.RemoteException

java.io.UnsupportedEncodingException

See Also:

getDC(String pid) throws Exception

getCollectionNames

public java.lang.String[] getCollectionNames(java.lang.String[] collPIDs)

Specified by:

getCollectionNames in interface FedoraGS3DL

Parameters:

collPIDs - - an array of Strings denoting the pids for greenstone collections stored in the fedora repositoryl. These should be of the format "greenstone:<collectionName>-collection".

Returns:

the <name>s (in greenstone:<name>-collection) for the collections indicated by collPIDs.

getCollectionPIDs

public java.lang.String[] getCollectionPIDs(java.lang.String[] collNames)

Specified by:

getCollectionPIDs in interface FedoraGS3DL

Parameters:

collNames - - a list of names of greenstone collections stored in the fedora repository.

Returns:

"greenstone:<name>-collection" for all <name>s in the parameter collNames.

getCollectionPID

public java.lang.String getCollectionPID(java.lang.String collName)

Specified by:

getCollectionPID in interface FedoraGS3DL

Parameters:

collName - - the name of a greenstone collection stored stored in the fedora repository.

Returns:

greenstone:<name>-collection for the<name> denoted by parameter collName.

getCollectionTitle

public java.lang.String getCollectionTitle(java.lang.String collPID)
                                    throws java.rmi.RemoteException,
                                           java.io.UnsupportedEncodingException,
                                           org.xml.sax.SAXException,
                                           java.io.IOException

Gets the title of the collection denoted by the given collection's pid by retrieving the title metadata for it from the collection's EX datastream.

Specified by:

getCollectionTitle in interface FedoraGS3DL

Parameters:

collPID - is the pid of a greenstone collection in the fedora repository.

Returns:

the title (in the default language, else English, else the first title found) for the particular collection denoted by its PID.

Throws:

java.rmi.RemoteException

java.io.UnsupportedEncodingException

org.xml.sax.SAXException

java.io.IOException

getCollectionTitles

public java.lang.String[] getCollectionTitles(java.lang.String[] collPIDs)
                                       throws java.rmi.RemoteException,
                                              java.io.UnsupportedEncodingException,
                                              org.xml.sax.SAXException,
                                              java.io.IOException

Specified by:

getCollectionTitles in interface FedoraGS3DL

Parameters:

collPIDs - - a list of pids identifying greenstone collections stored in the fedora repository.

Returns:

the collection titles for all the collections indicated by collPIDs.

Throws:

java.rmi.RemoteException

java.io.UnsupportedEncodingException

org.xml.sax.SAXException

java.io.IOException

getDocTitles

public java.lang.String[] getDocTitles(java.lang.String[] docPIDs)
                                throws java.rmi.RemoteException,
                                       java.io.UnsupportedEncodingException,
                                       org.xml.sax.SAXException,
                                       java.io.IOException

Specified by:

getDocTitles in interface FedoraGS3DL

Parameters:

docPIDs - - a list of pids identifying documents stored in the fedora repository.

Returns:

the title metadata for the given doc objects of a collection. These titles are returned in the same order as the given docIDs. (The docPIDs already contain the collection name anyway.)

Throws:

java.rmi.RemoteException

java.io.UnsupportedEncodingException

org.xml.sax.SAXException

java.io.IOException

getDocTitle

public java.lang.String getDocTitle(java.lang.String docPID)
                             throws java.rmi.RemoteException,
                                    java.io.UnsupportedEncodingException,
                                    org.xml.sax.SAXException,
                                    java.io.IOException

Gets the title metadata for a particular doc object in a collection denoted by docPID. The docPID already contains the collection name.

Specified by:

getDocTitle in interface FedoraGS3DL

Parameters:

docPID - is the pid of the document in the fedora repository (docPID is of the form greenstone:<colName>-<doc-identifier>

Returns:

the title for the fedora document item denoted by docPID

Throws:

java.rmi.RemoteException

java.io.UnsupportedEncodingException

org.xml.sax.SAXException

java.io.IOException

getTitle

protected java.lang.String getTitle(java.lang.String exStream)
                             throws org.xml.sax.SAXException,
                                    java.io.IOException

Given a string representation of a document's or document section's EX datastream -- which is a greenstone extracted metadata XML file -- of the form: <ex> <ex:metadata name="Title">sometitle</ex:metadata> <ex:metadata name="...">....</ex:metadata> ... </ex> This method finds the <ex:metadata> where the name="Title" and returns the value embedded in that element ('sometitle' in the example above).

Parameters:

exStream - the EX datastream in String form of the document or document section.

Returns:

the title metadata of the document/document section whose EX datastream is passed as parameter

Throws:

org.xml.sax.SAXException

java.io.IOException

getSectionTitles

public java.lang.String[] getSectionTitles(java.lang.String[] docPIDs,
                                           java.lang.String[] sectionIDs)
                                    throws java.rmi.RemoteException,
                                           java.io.UnsupportedEncodingException,
                                           org.xml.sax.SAXException,
                                           java.io.IOException

Specified by:

getSectionTitles in interface FedoraGS3DL

Parameters:

docPIDs - - a list of pids identifying documents stored in the fedora repository.

sectionIDs - - a list of sectionIDs identifying individual sections of documents stored in the fedora repository whose titles are requested.

Returns:

the title metadata for the given document sections. These titles are returned in the same order as the given docPIDs and associated sectionIDs. (The docPIDs already contain the collection name anyway.)

Throws:

java.rmi.RemoteException

java.io.UnsupportedEncodingException

org.xml.sax.SAXException

java.io.IOException

getSectionTitle

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

Specified by:

getSectionTitle in interface FedoraGS3DL

Parameters:

docPID - - a pid identifying a document in the fedora repository.

sectionID - - the sectionID of the section of the document whose title is requested.

Returns:

the title metadata for the given document section. (The docPID already contain the collection name anyway.)

Throws:

java.io.UnsupportedEncodingException

java.rmi.RemoteException

org.xml.sax.SAXException

java.io.IOException

getCollectionDocs

public java.lang.String[] getCollectionDocs(java.lang.String colPID)
                                     throws java.rmi.RemoteException

Searches the fedora repository for all greenstone:<colPID>* and returns the PIDs of the data objects found, with the exception of greenstone:<colPID>-collection, which is not a document but a collection PID. That is, pids of objects whose pid is greenstone:<colName>* (but not greenstone:<colName>-collection itself, because that represents the collection and not an object of the same collection) are returned. All pids that do not map to a collection are assumed to be documents!

Specified by:

getCollectionDocs in interface FedoraGS3DL

Parameters:

colPID - is the pid of the greenstone collection stored in the fedora repository.

Returns:

a list of the pids of all the (doc) objects in a collection.

Throws:

java.rmi.RemoteException

getSectionNames

public java.lang.String[] getSectionNames(java.lang.String docPID)
                                   throws java.rmi.RemoteException

Given the pid of a document fedora data object, this method will return all itemIDs that are part of that data object and are Sections. For further information see interface Comparable (implemented by String), SortedSet and TreeSet.

Specified by:

getSectionNames in interface FedoraGS3DL

Parameters:

docPID - is a fedora pid identifying a greenstone document object.

Returns:

an array of itemIDs of the Sections of the document, indicated by docPID, in ascending order. These are of the form: "SECTION1.*"

Throws:

java.rmi.RemoteException

See Also:

FedoraAPIABindingSOAPHTTPSkeleton.java stub class for the API-A web services, DatastreamDef.java, Fedora batch processing

getSectionNumbers

public java.lang.String[] getSectionNumbers(java.lang.String docPID)
                                     throws java.rmi.RemoteException

Given the pid of a document fedora data object, this method will return all itemIDs that are part of that data object and are Sections, but just the Section numbers are returned. For further information see interface Comparable (implemented by String), SortedSet and TreeSet.

Specified by:

getSectionNumbers in interface FedoraGS3DL

Parameters:

docPID - is a fedora pid identifying a greenstone document object.

Returns:

an array of itemIDs of the Section numbers of the document indicated by docPID, in ascending order. Return values are of form: "1.*".

Throws:

java.rmi.RemoteException

See Also:

FedoraAPIABindingSOAPHTTPSkeleton.java stub class for the API-A web services, DatastreamDef.java, Fedora batch processing

getTitles

public java.lang.String[] getTitles(java.lang.String docPID,
                                    java.lang.String[] sectionIDs)
                             throws java.rmi.RemoteException,
                                    java.io.UnsupportedEncodingException,
                                    org.xml.sax.SAXException,
                                    java.io.IOException

Specified by:

getTitles in interface FedoraGS3DL

Parameters:

docPID - is a fedora pid identifying a greenstone document object.

sectionIDs - is a list of identifiers identifying sections in the document denoted by docPID, whose titles need to be returned. Each sectionID may sectionID may be either a section name (e.g. SECTION1.5.1) or a section number (eg. 1.5.1).

Returns:

the titles for the document sections denoted by the parameters.

Throws:

java.rmi.RemoteException

java.io.UnsupportedEncodingException

org.xml.sax.SAXException

java.io.IOException

getTitle

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

Specified by:

getTitle in interface FedoraGS3DL

Parameters:

docPID - is a fedora pid identifying a greenstone document object.

sectionID - identifies the particular section in the document denoted by docPID, whose title needs to be returned. The sectionID may be either a section name (e.g. SECTION1.5.1) or a section number (eg. 1.5.1).

Returns:

the title for the document section denoted by the parameters.

Throws:

java.rmi.RemoteException

java.io.UnsupportedEncodingException

org.xml.sax.SAXException

java.io.IOException

getSection

public java.lang.String getSection(java.lang.String docPID,
                                   java.lang.String sectionID)
                            throws java.rmi.RemoteException,
                                   java.io.UnsupportedEncodingException

Specified by:

getSection in interface FedoraGS3DL

Parameters:

docPID - - a fedora pid identifying a greenstone document object.

sectionID - - identifyies the particular section in the document denoted by docPID, may be a section name or number.

Returns:

the section's XML (as a String) as it is stored in fedora. Works out if sectionID is a sectionName or sectionNumber.

Throws:

java.rmi.RemoteException

java.io.UnsupportedEncodingException

getSectionDCMetadata

public java.lang.String getSectionDCMetadata(java.lang.String docPID,
                                             java.lang.String sectionID)
                                      throws java.rmi.RemoteException,
                                             java.io.UnsupportedEncodingException

Specified by:

getSectionDCMetadata in interface FedoraGS3DL

Parameters:

docPID - - a fedora pid identifying a greenstone document object.

sectionID - - identifyies the particular section in the document denoted by docPID, may be a section name or number.

Returns:

the required section's DC metadata XML datastream.

Throws:

java.rmi.RemoteException

java.io.UnsupportedEncodingException

getSectionEXMetadata

public java.lang.String getSectionEXMetadata(java.lang.String docPID,
                                             java.lang.String sectionID)
                                      throws java.rmi.RemoteException,
                                             java.io.UnsupportedEncodingException

Returns the section EX metadata XML datastream for SectionID which may be a section name or number. Currently a few EX files are named awkwardly: the EX file for section 1.* is actually associated with datastream EX.*. But subsequent EX datastreams are named appropriately: for instance, EX2.1.1 matches with section 2.1.1

Specified by:

getSectionEXMetadata in interface FedoraGS3DL

Parameters:

docPID - - a fedora pid identifying a greenstone document object.

sectionID - - identifyies the particular section in the document denoted by docPID, may be a section name or number.

Returns:

the required section's EX metadata XML datastream.

Throws:

java.rmi.RemoteException

java.io.UnsupportedEncodingException

getChildrenOfSectionXML

public org.w3c.dom.Element getChildrenOfSectionXML(java.lang.String docPID,
                                                   java.lang.String sectionID)
                                            throws java.rmi.RemoteException,
                                                   java.io.UnsupportedEncodingException,
                                                   org.xml.sax.SAXException,
                                                   java.io.IOException

Specified by:

getChildrenOfSectionXML in interface FedoraGS3DL

Parameters:

docPID - - a fedora pid identifying a greenstone document object.

sectionID - - identifyies the particular section in the document denoted by docPID, may be a section name or number.

Returns:

the XML content of the TOC of just that portion of the TOC which contains the section denoted by sectionID and its direct child subsections. The children are returned in the order they are encountered, which happens to be in the required order of ascending sectionID.

Throws:

java.rmi.RemoteException

java.io.UnsupportedEncodingException

org.xml.sax.SAXException

java.io.IOException

getChildrenOfSection

public java.lang.String getChildrenOfSection(java.lang.String docPID,
                                             java.lang.String sectionID)
                                      throws java.rmi.RemoteException,
                                             java.io.UnsupportedEncodingException,
                                             org.xml.sax.SAXException,
                                             java.io.IOException,
                                             javax.xml.transform.TransformerException

Specified by:

getChildrenOfSection in interface FedoraGS3DL

Parameters:

docPID - - a fedora pid identifying a greenstone document object.

sectionID - - identifyies the particular section in the document denoted by docPID, may be a section name or number.

Returns:

a string representing the XML content of the TOC of just that portion of the TOC which contains the section denoted by sectionID and its direct child subsections. The children are returned in the order they are encountered, which happens to be in the required order of ascending sectionID.

Throws:

java.rmi.RemoteException

java.io.UnsupportedEncodingException

org.xml.sax.SAXException

java.io.IOException

javax.xml.transform.TransformerException

getSubsectionXML

public org.w3c.dom.Element getSubsectionXML(java.lang.String docPID,
                                            java.lang.String sectionID)
                                     throws java.rmi.RemoteException,
                                            java.io.UnsupportedEncodingException,
                                            org.xml.sax.SAXException,
                                            java.io.IOException

Specified by:

getSubsectionXML in interface FedoraGS3DL

Parameters:

docPID - - a fedora pid identifying a greenstone document object.

sectionID - - identifyies the particular section in the document denoted by docPID, may be a section name or number.

Returns:

the part of the TOC XML file (which outlines doc structure) relating to the given section. This includes the section denoted by sectionID as well as all descendent subsections thereof.

Throws:

java.rmi.RemoteException

java.io.UnsupportedEncodingException

org.xml.sax.SAXException

java.io.IOException

getSubsection

public java.lang.String getSubsection(java.lang.String docPID,
                                      java.lang.String sectionID)
                               throws java.rmi.RemoteException,
                                      java.io.UnsupportedEncodingException,
                                      org.xml.sax.SAXException,
                                      java.io.IOException,
                                      javax.xml.transform.TransformerException

Specified by:

getSubsection in interface FedoraGS3DL

Parameters:

docPID - a fedora pid identifying a greenstone document object.

sectionID - identifyies the particular section in the document denoted by docPID, may be a section name or number.

Returns:

a String representation of the part of the TOC XML file (which outlines doc structure) relating to the given section. This includes the section denoted by sectionID as well as all descendent subsections thereof.

Throws:

java.rmi.RemoteException

java.io.UnsupportedEncodingException

org.xml.sax.SAXException

java.io.IOException

javax.xml.transform.TransformerException

browseTitlesByLetter

public java.lang.String[] browseTitlesByLetter(java.lang.String collName,
                                               java.lang.String letter)
                                        throws java.rmi.RemoteException,
                                               FedoraGS3Exception.FedoraVersionNotSupportedException

Implements browsing document titles of a greenstone collection stored in the fedora repository by letter.

Specified by:

browseTitlesByLetter in interface FedoraGS3DL

Parameters:

letter - - the starting letter to browse by.

Returns:

the document pids whose titles start with the given letter.

Throws:

java.rmi.RemoteException

FedoraGS3Exception.FedoraVersionNotSupportedException

searchDocumentTitles

public java.lang.String[] searchDocumentTitles(java.lang.String collName,
                                               java.lang.String titleContents,
                                               boolean startsWith)
                                        throws java.rmi.RemoteException,
                                               FedoraGS3Exception.FedoraVersionNotSupportedException

Implements querying document DC titles of a greenstone collection stored in the fedora repository for a term that may occur anywhere in their titles.

Specified by:

searchDocumentTitles in interface FedoraGS3DL

Parameters:

titleContents - - the word or phrase to search the collection's document titles for. Only one word, and this method finds Greenstone DOCUMENT titles CONTAINING that word (if any).

startsWith - - if true, searches for titles that start with titleContents. Else it searches for titles that contain titleContents.

Returns:

the document pids whose DC titles contain the parameter term.

Throws:

java.rmi.RemoteException

FedoraGS3Exception.FedoraVersionNotSupportedException

findObjectsWithTitlesContaining

protected fedora.server.types.gen.FieldSearchResult findObjectsWithTitlesContaining(java.lang.String collName,
                                                                                    java.lang.String titleWord)
                                                                             throws java.rmi.RemoteException,
                                                                                    FedoraGS3Exception.FedoraVersionNotSupportedException

Parameters:

collName - - the collection of documents we'll be searching in.

titleWord - - the word we'll be searching the document titles for. (Fedora's search returns all objects whose title contains that word). Two kinds of search are provided by Fedora as stated in FedoraAccess.java (see link):

 "There are two search methods: a search on all fields or a search on
 specific fields. To search all fields the setTerms function of the 
 FieldSearchQuery must be used, with the paramater being the desired string.
 
 To search by specific fields, you must create an array of Condition
 objects. Each condition consists of three parts: 
 the field to be searched (.setProperty()), 
 the operation to be used (.setOperator(ComparisonOperator. <operator>)), 
 and the search string (.setValue())"
 

We want to use the second search method above when browsing and searching, and search for: pid~greenstone:<collName>* title~<letter>* or pid~greenstone:<collName>* title~<first word of search phrase> See also fedora-2.2.1-src/src/java/fedora/client/search/Search.java. The fedora/tomcat/webapps/fedora/WEB-INF/web.xml is where the REST-based web services are defined. (The web.xml defines the "Servlets for REST-based interfaces to the Fedora Repository Server"). Do a search on the word "search": fedora.server.access.FieldSearchServlet is the class we need to look at It accesses a different Condition.java class: fedora.server.search.Condition.java The above is what is used by the REST-based interface in FieldSearchServlet.java While fedora-2.2.1-src/build/wsdl/fedora/server/types/gen/Condition.java is what's used in the fedora client application that makes use of the SOAP-based interface.

Throws:

java.rmi.RemoteException

FedoraGS3Exception.FedoraVersionNotSupportedException

See Also:

FedoraAccess.java, MaAPI, Fedora server type Condition.java, Fedora client test Search.java

getDocName

public java.lang.String getDocName(java.lang.String docPID)

Specified by:

getDocName in interface FedoraGS3DL

Parameters:

docPID - - pid of a greenstone document in the fedora repository.

Returns:

the <docName> in the parameter docPID (which is of the form: greenstone:<colname>-<docName>)

getCollectionName

public java.lang.String getCollectionName(java.lang.String collPID)

Specified by:

getCollectionName in interface FedoraGS3DL

Parameters:

collPID - - pid of a greenstone collection in the fedora repository.

Returns:

the <name> in the parameter collPID (greenstone:<name>-collection) If collPID is a docPID, this method does the same: return the <name> in the docPID (greenstone:<name>-docID).

getSubstructure

protected org.w3c.dom.Element getSubstructure(org.w3c.dom.Element e,
                                              boolean descendents)

Convert the given Element to a String representing the same XML.

Parameters:

e - - the element to start copying from.

descendents - - if true, e is copied with all its descendetns into the element that's returned. If false, only e and its direct children are copied

Returns:

an element containing a copy element e with either only its child elements or with all its descendents (depending on whether parameter descendents is true or false).

See Also:

Sun java thread on transforming a DOM XML to a String

getItem

protected java.lang.String getItem(java.lang.String docPID,
                                   java.lang.String itemID)
                            throws java.rmi.RemoteException,
                                   java.io.UnsupportedEncodingException

Return a datastream of a document, given the document's id and the item id of the datastream which is to be retrieved.

Parameters:

docPID - - pid of a greenstone document in the fedora repository.

itemID - - the itemID of a datastream of the fedora object identified by docPID.

Returns:

the XML (in String form) of the item denoted by itemID that's part of the fedora data object denoted by docPID. itemID may be something like EX.2.1/EX2.3.3 or SECTION1.4.3 Can't retrieve images denoted by itemID using this method, only items that are of XML format.

Throws:

java.rmi.RemoteException

java.io.UnsupportedEncodingException

removePrefix

protected java.lang.String removePrefix(java.lang.String str,
                                        java.lang.String prefix)

Given something like str="SECTION1.2.1" and prefix="SECTION" this method returns "1.2.1". The exception is that for cases like EX.2.1, which ought to have been EX1.2.1, this method would return "1.2.1". Similarly, DC.2.1 would return "1.2.1". However, the string str is returned unchanged if the prefix does not occur at the start of str.

Parameters:

prefix - - the prefix which ought to be removed from the itemID.

str - - the value of the itemID.

Returns:

the String parameter str without the prefix. It can be used to return the number of an itemID of a greenstone document stored in the fedora repository without the given prefix.

convertToMetaNumber

protected java.lang.String convertToMetaNumber(java.lang.String number)

Given a number of the form x(.y.z), this method returns this number as is, except when x = 1, in which case, it would return .y.z That is, given number=3.2.1, this method would return 3.2.1 But, given number=1.2.3, this method would return .2.3. When number=1, it is NOT a special case: "" is returned as explained.

Parameters:

number - - a proper (fedora-greenstone document) section number

Returns:

the same number as it ought to be for the associated EX, DC datastreama.

getBaseURL

public java.lang.String getBaseURL()

Specified by:

getBaseURL in interface FedoraGS3DL

Returns:

fedora's baseURL. It's of the form "http://localhost:8080/fedora"

getPortAddressURL

public java.lang.String getPortAddressURL()

Specified by:

getPortAddressURL in interface FedoraGS3DL

Returns:

the portAddressURL (in use) of the Fedora APIA web service (should be the endpoint location in the APIA's WSDL file). It's usually of the form baseURL+"/services/access"

getAssocFileBaseURL

public java.lang.String getAssocFileBaseURL()

Specified by:

getAssocFileBaseURL in interface FedoraGS3DL

Returns:

the baseURL for gsdlAssocFiles

main

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