Index: other-projects/gs3-webservices-java-client/trunk/Manifest.MF
===================================================================
--- other-projects/gs3-webservices-java-client/trunk/Manifest.MF (revision 21027)
+++ other-projects/gs3-webservices-java-client/trunk/Manifest.MF (revision 21027)
@@ -0,0 +1,14 @@
+Manifest-Version: 1.0
+Sealed: true
+Main-Class: org.greenstone.gs3client.GS3JavaClient
+Class-Path: lib/QBRdata.jar
+ lib/fedoraGS3.jar
+ lib/gs3_for_client.jar
+ lib/fedora.jar
+ lib/log4j-1.2.8.jar
+ lib/commons-logging-1.0.4.jar
+ lib/commons-discovery-0.2.jar
+ lib/saaj.jar
+ lib/jaxrpc.jar
+ lib/wsdl4j-1.5.1.jar
+ lib/axis.jar
Index: other-projects/gs3-webservices-java-client/trunk/README.txt
===================================================================
--- other-projects/gs3-webservices-java-client/trunk/README.txt (revision 21027)
+++ other-projects/gs3-webservices-java-client/trunk/README.txt (revision 21027)
@@ -0,0 +1,102 @@
+***********************************************************
+ README
+***********************************************************
+Application: Greenstone 3 (QBR) web services demo-client
+
+Summary: Demo-client application in Java for the QBR (Query,
+Browse and Retrieve) web services of Greenstone 3. Also
+provides similar access to a Fedora repository of Greenstone
+collections created by Greenstone's FLI application.
+
+This is a Java demonstration application for Greenstone 3
+that presents a graphical user interface to Greenstone 3's
+Query, Browsing and Retrieval functionality.
+
+The application allows one to search collections and browse
+them by classifiers, displaying the results.
+
+It uses the new QBRSOAPServer web services of Greenstone 3
+to access its search and (document and metadata) retrieval
+operations, thereby demonstrating the use of Greenstone
+3's QBR web services.
+
+It also lets you browse Greenstone collections exported by
+the FLI application into a Fedora repository. If Fedora
+Generic Search is installed and if your "Fedora-Greenstone"
+collections are indexed, some basic querying features will
+be available in the demo-client's interface. A tool to help
+install Fedora Generic Search once you have Fedora (2.2.1 or
+greater) installed is included.
+
+Documentation on how to use the application, as well as
+related matters like deploying the QBR web services and
+using FLI can be found in the docs/HowToFiles folder when
+the distribution is unzipped.
+
+
+***********************************************************
+ What you need and how to run
+***********************************************************
+- It runs on Windows XP (not tested on Vista yet) and Linux.
+- You need Java 1.5 or higher installed and JAVA_HOME set.
+- The Greenstone 3 server the demo-client is to communicate
+with must be up-to-date with the latest source code from
+the Greenstone SVN repository. The Greenstone 3 server must
+have the new QBRSOAPServer web services deployed on it. See
+section C.
+
+A. If you've downloaded the zip file:
+1. Unzip it into a folder.
+2. Open an xterm and go into the folder where you extracted
+it and type:
+ ./gs3democlient.sh
+(If you don't have execute permissions, type
+ chmod u+x gs3democlient.sh
+ ./gs3democlient.sh
+)
+If you're on Windows, you can double-click on
+gs3democlient.bat or otherwise open a DOS prompt, navigate
+into the folder where you extracted the zip folder and type
+ gs3democlient.bat
+3. From the drop-down box at the top choose "greenstone"
+and type the WSDL URL of the QBRSOAPServer deployed on the
+Greenstone 3 server you wish to connect to. See section C.
+
+
+B. If you've checked out the code and application from SVN,
+you'll need JDK 5 as it is used to compile the code. To get
+the application running from SVN:
+1. Go into the folder where you've checked it out into.
+2. (You'll need an internet connection for this step because
+it will download the file CheckJavaVersion.java)
+Open an x-term when on Linux or a DOS prompt when on windows
+and type:
+ ant build-demo-client
+This will generate the executable.
+To run, type
+ ./gs3democlient.sh
+on Linux and
+ gs3democlient.bat
+if you're on windows. (If you've got JAVA_HOME pointing to
+JDK 1.5, you can also double-click on gs3democlient.bat to
+get it running.)
+3. From the drop-down box at the top choose "greenstone"
+and type the WSDL URL of the QBRSOAPServer deployed on the
+Greenstone 3 server you wish to connect to. See section C.
+
+
+C. Deploying the QBRSOAPServer web services on the up-to-
+date Greenstone 3 server
+1. Go the Greenstone 3 installation folder
+2. Type
+ ant soap-deploy-site
+Then it will prompt you for 3 things. Press Enter to accept
+localsite, type "QBRSOAPServer" and Press Enter again to
+accept QBRSOAPServerlocalsite. Then point your browser to
+http://HOST:PORT/greenstone3/services to see if the QBRSOAP-
+Server web services are deployed and to get the link to its
+WSDL URL needed by the demo-client application.
+
+
+For detailed instructions, please refer to the html files
+in the folder docs/HowToFiles
Index: other-projects/gs3-webservices-java-client/trunk/build.xml
===================================================================
--- other-projects/gs3-webservices-java-client/trunk/build.xml (revision 21027)
+++ other-projects/gs3-webservices-java-client/trunk/build.xml (revision 21027)
@@ -0,0 +1,293 @@
+
+
+
+This buildfile is used to build the demo-client for Greenstone3's web services.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Type:
+ - ant build-demo-client
+ for (compiling) and creating the demo-client executable
+ - ant compile-demo-client
+ for compiling the democlient
+ - ant fedoraGS3jar
+ for generating the fedoraGS3.jar dependency file
+ - ant QBRdatajar
+ for generating the QBRdata.jar dependency file
+ - ant make-dist
+ for generating the zip/gzip/bzip file of the project
+ - ant clean-democlient
+ for deleting the *.class files from the GS3democlient's source
+ - ant clean
+ for deleting the *.class files from the GS3democlient and GS3Fedora sources
+ - ant dist-clean
+ for deleting the *.class files from the sources, the QBRdata.jar, fedoraGS3.jar, executable jar file, and any zips of the project folder
+ - ant update
+ for getting the latest version of CheckJavaVersion.java, and the files for creating the gs3_for_client.jar dependency from Greenstone's SVN repository
+ - ant GSearchInstallerjar
+ for generating the GSearchInstaller.jar application that helps in installing Fedora Generic Search (if you have Fedora installed).
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Getting java files GSXML, XMLConverter, GSPath and MyNodeList from Greenstone's SVN repository (${gs3forclient.svn.path}). Compiling and jarring them up into ${gs3.files.jar}...
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ If the filepaths are longer than 100 characters, GNU compatible tar commands are necessary to untar the tar.gz
+
+
+
+
+
+
+ If the filepaths are longer than 100 characters, GNU compatible tar commands are necessary to untar the tar.gz
+
+
+
+
+
+
+
+
+
+
+ What type of compressed output file do you want to generate?
+Type one of: zip, tar.gz, tar.bz2
+Press enter for default: zip />
+
+
+
+
+
+
+
+
+
+ You chose output file type: ${zip.type}
+
+
Index: other-projects/gs3-webservices-java-client/trunk/docs/GS3DemoClient/allclasses-frame.html
===================================================================
--- other-projects/gs3-webservices-java-client/trunk/docs/GS3DemoClient/allclasses-frame.html (revision 21027)
+++ other-projects/gs3-webservices-java-client/trunk/docs/GS3DemoClient/allclasses-frame.html (revision 21027)
@@ -0,0 +1,100 @@
+
+
+
+
+This API (Application Programming Interface) document has pages corresponding to the items in the navigation bar, described as follows.
+Overview
+
+
+
+The Overview page is the front page of this API document and provides a list of all packages with a summary for each. This page can also contain an overall description of the set of packages.
+
+Package
+
+
+
+Each package has a page that contains a list of its classes and interfaces, with a summary for each. This page can contain four categories:
+
Interfaces (italic)
Classes
Enums
Exceptions
Errors
Annotation Types
+
+
+Class/Interface
+
+
+
+Each class, interface, nested class and nested interface has its own separate page. Each of these pages has three sections consisting of a class/interface description, summary tables, and detailed member descriptions:
+
Class inheritance diagram
Direct Subclasses
All Known Subinterfaces
All Known Implementing Classes
Class/interface declaration
Class/interface description
+
+
Nested Class Summary
Field Summary
Constructor Summary
Method Summary
+
+
Field Detail
Constructor Detail
Method Detail
+Each summary entry contains the first sentence from the detailed description for that item. The summary entries are alphabetical, while the detailed descriptions are in the order they appear in the source code. This preserves the logical groupings established by the programmer.
+
+
+Annotation Type
+
+
+
+Each annotation type has its own separate page with the following sections:
+
Annotation Type declaration
Annotation Type description
Required Element Summary
Optional Element Summary
Element Detail
+
+
+
+Enum
+
+
+
+Each enum has its own separate page with the following sections:
+
Enum declaration
Enum description
Enum Constant Summary
Enum Constant Detail
+
+
+Tree (Class Hierarchy)
+
+There is a Class Hierarchy page for all packages, plus a hierarchy for each package. Each hierarchy page contains a list of classes and a list of interfaces. The classes are organized by inheritance structure starting with java.lang.Object. The interfaces do not inherit from java.lang.Object.
+
When viewing the Overview page, clicking on "Tree" displays the hierarchy for all packages.
When viewing a particular package, class or interface page, clicking "Tree" displays the hierarchy for only that package.
+
+
+Deprecated API
+
+The Deprecated API page lists all of the API that have been deprecated. A deprecated API is not recommended for use, generally due to improvements, and a replacement API is usually given. Deprecated APIs may be removed in future implementations.
+
+Index
+
+The Index contains an alphabetic list of all classes, interfaces, constructors, methods, and fields.
+
+Prev/Next
+These links take you to the next or previous class, interface, package, or related page.
+Frames/No Frames
+These links show and hide the HTML frames. All pages are available with or without frames.
+
+
+Serialized Form
+Each serializable or externalizable class has a description of its serialization fields and methods. This information is of interest to re-implementors, not to developers using the API. While there is no link in the navigation bar, you can get to this information by going to any serialized class and clicking "Serialized Form" in the "See also" section of the class description.
+
Event handler for actionEvents such as a change in the active digital
+ library, a collection being selected in the dropdown box or the collection
+ -Info button being pressed, or a service being selected in the service
+ dropdown box (browsing or searching).
+
Called when this QueryForm's search button is pressed: the data
+ entered/controls settings specified by the user are passed to the
+ digital library's Query Service in order to perform the search.
+
The multi-panel is laid out with a GridBagLayout in order to make
+ the layout more attractive (so that the form controls don't have as
+ odd sizes as before when GraphPaperLayout was used).
+
A beginning to the AdminSOAPServer class which will contain management/admin
+ related web services such as adding new documents, creating, building and
+ importing collections and configuring Greenstone modules.
Resets the internal data members of this BrowseResponseData object of
+ their values so that this BrowseResponseData can be reused for the
+ next Browse response message.
+
Resets the internal data members of this QueryResponseData object of
+ their values so that this QueryResponseData can be reused for the
+ next Query response message.
+
CollectionData represents a Greenstone 3 collection and contains the data
+ stored in a <collection></collection> element returned from a
+ MessageRouter's desribe response XML and a Collection describe response XML.
Static inner class MetaData: can import it into other files as
+ "import gs3client.CollectionData.MetaData;"
+ In this way, can use it as if it were a regular class (a.o.t.
Only the name and type of a <service></service> element is
+ stored, since this is all the service data available inside a collection's
+ response message to a describe request.
Creates combo boxes/drop-downs for the <param> elements
+ whose types are GSXML.PARAM_TYPE_ENUM_SINGLE and listboxes for those
+ whose types are GSXML.PARAM_TYPE_ENUM_MULTI.
+
Interface that defines the digital library methods that need to be
+ provided by a digital library that's going to be incorporated into the
+ Greenstone Java-Client, so that the client may be able to use/access
+ its functionality.
Will clear previous browse service's classification options and widgets,
+ and redisplay browse options as specified by the describe Response Message
+ XML returned from the browse Service.
+
Handles rightclicks on a treeview of documentNodeData objects by showing
+ the popupMenu with associated files that, when selected, can be displayed
+ in the htmlPane.
Constructor that creates an AssocFilePopupItem (popup menu item)
+ instance for each associated file of a documentNodeData that's been
+ rightclicked on.
+
Given tags of the form
+ <documentNode nodeID="HASHac0a04dd14571c60d7fbfd.4.2"
+ nodeType="x" docType="y">
+ <nodeContent>Text</nodeContent>
+ <nodeStructureInfo><info name="i" value="1" />
+ <info name = "ii" value = "2" /></nodeStructureInfo>
+ <metadataList><metadata name="a">Value
+ </metadata></metadataList>
+ <nodeStructure>
+ <documentNode ....></documentNode>
+ <documentNode ....></documentNode>
+ </nodeStructure>
+ </documentNode>
+ this constructor extracts the nodeId out of it and any other fields
+ that might be set in the docNodeTag <documentNode> element.
+
Sets up the the query form for display (queryPanel) given the XML of
+ the response-message returned by a "describe" request sent to a
+ Query Service.
+
Static method that gets all the descendant elements of a portion of XMl
+ within the same namespace as indicated by parameters namespacePrefix and
+ localName.
+
At method's end, Vector v will contain those descendent elements of
+ parentElement where the element's name is prefixed by namespacePrefix
+ and suffixed by localName.
+
Given an Element <parentEl>, finds all direct child elements called
+ <elName> that have an attribute named attrName:
+ <elName attrName=value>bodytext</elName>
+ This is particularly useful for extracting info for those cases where
+ elName=<displayItem> and where the attrName is "name".
+
Given an xml element ('parent'), it looks through its direct children
+ to find the <listElementName> tag and extracts each child called
+ <childElementName> element from it.
+
GS3ServicesAPIA does two things:
+ - it implements DigitalLibraryServicesAPIA for enabling the Java-client
+ to access Greenstone's repository of collections and documents.
GS3ServicesAPIA constructor, which, given the url to the wsdl file,
+ finds either service and port or the service's endpoint of the GS3 Web
+ Services and instantiates the associated Service and Call objects.
+
GS3ServicesAPIA constructor, that given the url to the wsdl file, finds
+ either service and port or the service's endpoint of the GS3 Web Services
+ and instantiates the associated Service and Call objects.
+
Since we are setting the descendents lazily (only setting the children
+ each time), we have a little flag to indicate whether this node has
+ any children.
+
Constructor that creates a MetaData object from a
+ <metadata></metadata> element by setting its members fields
+ using info extracted from the element.
+
Abstract superclass NodeData can represent either a the information in
+ a <classifierNode> (stored in a ClassifierNodeData object) or in a
+ <documentNode> (stored in a DocumentNodeData object).
map of (nodeIDs, references to associated NodeData) pairs,
+ stored in the order they are contained in the response XML messages
+ (the order in which data objects are parsed and created for them)
+
For some reason, the overriden getPreferredSize() is not
+ called upon resize of this panel, so I am calling it manually
+ whenever there's a call to paint this Panel.
+
Class QueryFormData represents the <param> and <option> elements
+ that can appear in a <paramList> tag in the xml response returned by
+ a describe request sent to *Query* Service (e.g.
Static inner class QueryFormParam is a subclass of QueryFormData and
+ uniquely represents the data that can be contained in any <param>
+ tag of the xml response that's returned when a describe request is sent to
+ a Query Service.
DocumentStructureRetrieve request sent to a collection's
+ DocumentStructureRetrieve service (manual pp.48, 49) to retrieve
+ the specified part of the document's structure.
+
DocumentStructureRetrieve request sent to a collection's
+ DocumentStructureRetrieve service (manual pp.48, 49) to retrieve
+ the specified part of the document's structure.
+
(b) DocumentStructureRetrieve request sent to a collection's
+ DocumentStructureRetrieve service (manual pp.48, 49) to retrieve
+ the entire document structure.
+
DocumentStructureRetrieve request sent to a collection's
+ DocumentStructureRetrieve service (manual pp.48, 49) to retrieve
+ the entire document structure.
+
Performs a structureRetrieve and title metadata retrieve message-
+ request for the docNode, but only iff the structure and title for
+ that docNode is not already set.
+
Given a ClassifierNodeData object for browsing, this method will
+ set the classNode's children (previously retrieved) and retrieve
+ all the children's metadata including the title.
+
After a DocumentContentRetrieve request for one or more documents
+ has returned a response, this method - when given the response XML -
+ will set the nodeContents of each document in the response (as long
+ as those documents already have an associated DocumentNodeData
+ object instantiated, which should/would always be the case).
+
Given a <nodeStructure></nodeStructure> element returned
+ from a request for the *ENTIRE* nodeStructure, this method will find the
+ <documentNode> that is the Root (nodeType=ROOT) and from there
+ on proceed to set all descendent <documentNode>s.
+
Gets a <collection></collection> element - as returned by a
+ describe response from a Collection - and sets the member vars using
+ the data in there.
+
This method sets the metadata for one or even all <documentNode>
+ data objects contained in the Map nodeIDsToNodes, using the <message>
+ element parameter (which is returned upon a documentMetadataRetrieve
+ request.
+
Sets member variable nodeContent with the text (if any) inside any
+ <nodeContent></nodeContent> child element of
+ <documentNode>, else the value of nodeContent is set to empty
+ string ("").
+
Sets structureInfo member variable <nodeStructureInfo> element is
+ present as child of <documentNode>, else value of structureInfo
+ remains unchanged.
+
Given an XML responseMessage to a request for the classification
+ Browse structure, this method sets its nodeIDsToNodes member variable
+ by instantiating classifierNodeData and/or documentNodeData objects
+ as given in the responseMessageTag.
+
Given the response to a query message (XML with root <message>
+ or <response> tag), a QueryResponseData object is created
+ to store all the document Identifiers and document data returned
+ as well as information about the terms that were searched on.
+
Subclasses must implement this method to parse the
+ <message><response></response></message>
+ that is returned upon executing a browse or query request.
+
This method can be called after a DocumentStructureRetrieve request
+ (for the entire structure of all/many of its documents) has returned
+ a response.
+
Sorts the metadata of the docNode into the required order and displays
+ metadata names in the JList metanames and the associated metadata values
+ in the JList metavalues.
+
+Inner class (not static, as it needs access to outerclass' this object.
+ This class represents a button that encapsulates a ClassifierData
+ object and sets its own name and tooltip text based on the displayName
+ and displayDescription of that ClassifierData object.
+
actionPerformed(java.awt.event.ActionEvent e)
+
+
+ Called when someone presses the ClassifierButton: when pressed,
+ perform the browse request associated with the classifier.
+Static inner class that represents the data in a <classifier>
+ element - itself nested inside a list (<classifierList>) of them.
+ These elements are to be found in the response returned for a describe
+ request sent to a collection's BrowseService.
+
+
+
+
+
+
+
+
+
+
+
+
+Field Summary
+
+
+
+ java.lang.String
+
content
+
+
+ The content attribute of the <classifier>
+The Browse panel inside the Java-client's tab pane that's labelled "Browse".
+ This panel contains a tree view for expanding classifiers and their documents.
+ It also contains an area where the metadata is displayed, and a text area where
+ the textual or image content of a selected documentNode is displayed.
+
BrowseDisplay.ClassifierData
+
+
+ Static inner class that represents the data in a <classifier>
+ element - itself nested inside a list (<classifierList>) of them.
+
+
+
+
+
+
Nested classes/interfaces inherited from class javax.swing.JPanel
+
+
+
javax.swing.JPanel.AccessibleJPanel
+
+
+
+
+
+
+
Nested classes/interfaces inherited from class javax.swing.JComponent
+
+
+
javax.swing.JComponent.AccessibleJComponent
+
+
+
+
+
+
+
Nested classes/interfaces inherited from class java.awt.Container
+
+
+
java.awt.Container.AccessibleAWTContainer
+
+
+
+
+
+
+
Nested classes/interfaces inherited from class java.awt.Component
BrowseDisplay(GS3JavaClient client)
+
+
+ Constructor that creates the Browse Panel and its internal GUI items.
+
+
+
+
+
+
+
+
+
+Method Summary
+
+
+
+ void
+
changeUIColour()
+
+
+ Changes the colour of the query form and its controls to the
+ current colours set in class ColourCombo.
+
+
+
+ void
+
clear()
+
+
+ Clears the service-specific buttons in the browseBar and the
+ service-specific display-data.
+
+
+
+ void
+
displayBrowseOptions(org.w3c.dom.Element describeRespMsgTag)
+
+
+ Will clear previous browse service's classification options and widgets,
+ and redisplay browse options as specified by the describe Response Message
+ XML returned from the browse Service.
getPreferredSize()
+
+
+ Overrode this method to resize the splitpanes within, upon resize.
+
+
+
+ void
+
paint(java.awt.Graphics g)
+
+
+ For some reason, the overriden getPreferredSize() is not
+ called upon resize of this panel, so I am calling it manually
+ whenever there's a call to paint this Panel.
+
+
+
+ void
+
treeWillCollapse(javax.swing.event.TreeExpansionEvent e)
+
+
+ Part of the TreeWillExpandListener interface.
+
+
+
+ void
+
treeWillExpand(javax.swing.event.TreeExpansionEvent e)
+
+
+ This method of the TreeWillExpandListener interface is called when
+ the user clicked on an expandable node in the browsingTree.
+
+
+
+ void
+
valueChanged(javax.swing.event.TreeSelectionEvent e)
+
+
+ Whenever an item is clicked in the browsingTree, this method is called.
Constructor that creates the Browse Panel and its internal GUI items.
+
+
+
Parameters:
client - is the running instance of the client application through
+ which its methods can be accessed.
+
+
+
+
+
+
+
+
+Method Detail
+
+
+
+
+clear
+
+public void clear()
+
+
Clears the service-specific buttons in the browseBar and the
+ service-specific display-data. The rest of the GUI (split panes, panels)
+ remain as they are.
+
+
+
+
+
+
+
+
+
+
+
+changeUIColour
+
+public void changeUIColour()
+
+
Changes the colour of the query form and its controls to the
+ current colours set in class ColourCombo. Specified by
+ the ColourCombo.ColourChangeable interface.
+
For some reason, the overriden getPreferredSize() is not
+ called upon resize of this panel, so I am calling it manually
+ whenever there's a call to paint this Panel. Painting will
+ be done when the parent container is resized (and this panel
+ made visible) anyway, so it might as well work out what size
+ the interior panels will have on every resize.
+
+
+
Overrides:
paint in class javax.swing.JComponent
+
+
+
Parameters:
g - is the Graphics object
See Also:
"JPanel's paint(Graphics g)"
+
+
+
+
+
+getPreferredSize
+
+public java.awt.Dimension getPreferredSize()
+
+
Overrode this method to resize the splitpanes within, upon resize.
+ It calculates the size of this panel, as well as setting those of
+ the splitpanes it contains based on the size of the parent container.
+
Will clear previous browse service's classification options and widgets,
+ and redisplay browse options as specified by the describe Response Message
+ XML returned from the browse Service.
+
+
+
+
+
+
Parameters:
describeRespMsgTag - - the (Classifier)Browse Service's describe
+ response message element, used to reset the classifier buttons in the
+ browseBar of this panel.
This method of the TreeWillExpandListener interface is called when
+ the user clicked on an expandable node in the browsingTree.
+ Since we are loading substructures in the tree lazily (i.e. loading
+ childnodes lazily) we have dummy/null childTreeNodes that make
+ expandable parentNodes look like folders (make the parents look
+ expandable).
+ Therefore, when the user clicks on an expandable node, we first check
+ whether we already have loaded the datastructure/subtree or whether
+ its child is a dummy (null). If a dummy (null child), then we work
+ out whether it's a classifierNodeData or a documentNodeData that the
+ expanding treeNode represents. Based on that, we retrieve the sub-
+ structure for the treeNode that's expanding.
+
+
+
Specified by:
treeWillExpand in interface javax.swing.event.TreeWillExpandListener
Whenever an item is clicked in the browsingTree, this method is called.
+ We display the document associated with a documentNode that is clicked,
+ or "" for classifierNodes.
+
+
+
Specified by:
valueChanged in interface javax.swing.event.TreeSelectionListener
public static interface ColourCombo.ColourChangeable
+
+
+
+Interface ColourChangeable defines one method, changeUIColour(),
+ which classes whose user-interface colours can change may
+ implement. They can then choose to call either of ColourCombo's
+ changeColor() methods or changeAncestorColor() if necessary.
+ Though it's not compulsory to implement this interface, it may
+ help in grouping the classes that are ColourChangeable.
+
+
+
+
+
+
+
+
+
+
+
+
+
+Method Summary
+
+
+
+ void
+
changeUIColour()
+
+
+ Subclasses define this method in order to change the
+ colour of the interface
+
+
+
+
+
+
+
+
+
+
+
+Method Detail
+
+
+
+
+changeUIColour
+
+void changeUIColour()
+
+
Subclasses define this method in order to change the
+ colour of the interface
+
+Background and selection color combinations for the Java-Client's
+ interface. Stores Greenstone, Fedora and default colour combinations
+ and has methods for converting colours of items.
+
+
+
+
+
Author:
+
ak19
+
+
+
+
+
+
+
+
+
+
+Nested Class Summary
+
+
+
+static interface
+
ColourCombo.ColourChangeable
+
+
+ Interface ColourChangeable defines one method, changeUIColour(),
+ which classes whose user-interface colours can change may
+ implement.
yellow
+
+
+ Selection colour for Fedora and Greenstone
+
+
+
+
+
+
+
+
+
+Constructor Summary
+
+
+
ColourCombo(java.awt.Color dark,
+ java.awt.Color light)
+
+
+ Constructor to create a ColourCombo combination of colours
+
+
+
+
+
+
+
+
+
+Method Summary
+
+
+
+static void
+
changeAncestorColor(java.awt.Component c)
+
+
+ Given a component, sets its ancestors to the dark colour setting.
+
+
+
+static void
+
changeColor(java.awt.Component c)
+
+
+ Given a Component, sets its background colours to a dark or
+ light colour setting as appropriate.
+
+
+
+static void
+
changeColor(java.awt.Component[] leafComponents)
+
+
+ Given an array of components, sets their background colours to a
+ dark or light colour setting as appropriate.
Greenstone transparent background colour. Useful for trees' text
+ backgrounds which otherwise default to white even when the tree
+ background is not white. Alpha value=0 for transparency
+
+
+
+
+
+
+
+green
+
+static final java.awt.Color green
+
+
Greenstone dark background colour
+
+
+
+
+
+
+
+lightGreen
+
+static final java.awt.Color lightGreen
+
+
Greenstone light background colour
+
+
+
+
+
+
+
+blue
+
+static final java.awt.Color blue
+
+
Fedora dark background colour
+
+
+
+
+
+
+
+lightBlue
+
+static final java.awt.Color lightBlue
+
+
Fedora light background colour
+
+
+
+
+
+
+
+yellow
+
+static final java.awt.Color yellow
+
+
Selection colour for Fedora and Greenstone
+
+
+
+
+
+
+
+grey
+
+static final java.awt.Color grey
+
+
Default background colour
+
+
+
+
+
+
+
+background
+
+static final java.awt.Color background
+
+
Fixed background colour for textareas, editorPanes (html)
+
+
+
+
+
+
+
+dark
+
+public final java.awt.Color dark
+
+
background colours for panels, labels
+
+
+
+
+
+
+
+light
+
+public final java.awt.Color light
+
+
background colours for comboboxes, lists, textfields, textareas
+
+public static void setCurrentCombo(ColourCombo c)
+
+
+
+
+
+
+
+
+setColour
+
+public static void setColour(int DL)
+
+
Sets the active colour combination based on the value of DL.
+
+
+
Parameters:
DL - represents the current digital library. Values can be
+ GS3JavaClient.GREENSTONE, GS3JavaClient.FEDORA, GS3JavaClient.SELECT.
+ Anything else and it defaults to GS3JavaClient.SELECT as well.
+
+
+
+
+
+isLightColor
+
+protected static boolean isLightColor(java.awt.Component c)
+
+
+
Parameters:
c - is the Component for which it is to be determined whether it
+ should be a lighter or darker colour.
+
Returns:
true if Component c should be a lighter colour (returns true
+ for non-editable JTextFields)
+Static inner class MetadataComparator is a Comparator for the metadata
+ fields stored as a list of Pair objects (name, values).
+ We want to display them alphabetised, grouped by prefix (dls.title, dls.x;
+ dc.title; dc.creator; greenstone's ex metadata does not have a prefix)
+ and in order of alphabet BUT all those starting with capital letters come
+ first, then come those starting with lowercase letters.
+ Those with prefixes come first of all.
+ Comparators can be passed to a sort method (such as Collections.sort) to
+ allow precise control over the sort order. Comparators can also be used to
+ control the order of certain data structures (such as TreeSet or TreeMap).
+
+Package access inner class. Not static, so it depends on outer class'
+ PopupListener instance.
+ Represents a popup MenuItem that appears on rightclick and contains the
+ name(s) of associated files which will be displayed - if any are selected
+ - in the main htmlpane.
+
+
+
+
+
+
+
+
+
+
+
+
+Nested Class Summary
+
+
+
+
+
+
Nested classes/interfaces inherited from class javax.swing.JMenuItem
+
+
+
javax.swing.JMenuItem.AccessibleJMenuItem
+
+
+
+
+
+
+
Nested classes/interfaces inherited from class javax.swing.AbstractButton
Displays.PopupListener.AssocFilePopupItem(DocumentNodeData docNode,
+ java.lang.String name)
+
+
+ Constructor that creates an AssocFilePopupItem (popup menu item)
+ instance for each associated file of a documentNodeData that's been
+ rightclicked on.
+
+
+
+
+
+
+
+
+
+Method Summary
+
+
+
+
+
+
Methods inherited from class javax.swing.JMenuItem
Constructor that creates an AssocFilePopupItem (popup menu item)
+ instance for each associated file of a documentNodeData that's been
+ rightclicked on. This popupitem displays the name of the associated
+ file as a menu item of the popup.
+ The outer PopupListener object is set to listen to mouseEvents on
+ this PopupMenuItem. It will listen to clicks on this menuItem to
+ then display the image.
+
+Handles rightclicks on a treeview of documentNodeData objects by showing
+ the popupMenu with associated files that, when selected, can be displayed
+ in the htmlPane. Listens to rightclick events, but also handles clicks on
+ popup menu items.
+
+Class containing static methods, static variables and inner classes that
+ are used by both SearchResultsDisplay and BrowseDisplay.
+
+
+
+
+
Author:
+
ak19
+
+
+
+
+
+
+
+
+
+
+Nested Class Summary
+
+
+
+static class
+
Displays.MetadataComparator
+
+
+ Static inner class MetadataComparator is a Comparator for the metadata
+ fields stored as a list of Pair objects (name, values).
+
+
+
+(package private) static class
+
Displays.PopupListener
+
+
+ Handles rightclicks on a treeview of documentNodeData objects by showing
+ the popupMenu with associated files that, when selected, can be displayed
+ in the htmlPane.
createNodesForChildren(DocumentNodeData docNode,
+ javax.swing.tree.DefaultMutableTreeNode treeNode)
+
+
+ Recursion to add all descendent docnodes into the tree.
showMeta(NodeData nodeData,
+ javax.swing.JList metanames,
+ javax.swing.JList metavalues)
+
+
+ Sorts the metadata of the docNode into the required order and displays
+ metadata names in the JList metanames and the associated metadata values
+ in the JList metavalues.
JEditorPane cannot deal with <img src="" />. It can only handle
+ it without ending slash: <img src="" >.
+ This method constructs complete html (with html, head and body tags) where
+ the parameter imgURL is enclosed inside an img src tag.
+
Sorts the metadata of the docNode into the required order and displays
+ metadata names in the JList metanames and the associated metadata values
+ in the JList metavalues.
+ The order is based on metanames: first come all the official metadata
+ sets which are recognised by the existence of a period in the metaname
+ (eg. dc.creator, dls.title). These are arranged alphabetically.
+ Next come all the metadata names that start with a capital letter -
+ arranged alphabetically;
+ the remainder are organised alphabetically as well, with the last ones
+ being those metadata whose names do not start with a letter
+ (e.g. "/srclink").
+
+
+
Parameters:
nodeData - is the NodeData object (classifierNodeData or
+ documentNodeData)
+ whose metadata is to be displayed in the metanames and metavalues components.
metanames - - a JList to display all the metadata names of nodeData
metavalues - - a JList to display all the metadata values of nodeData
+Inner class that handles authentication for any sites (urls, etc.)
+ that require it. A dialog pops up to request username and password
+ details from the user for each site's realm that needs authentication.
+
+
+
+
+
+
+
+
+
+
+
+
+Nested Class Summary
+
+
+
+
+
+
Nested classes/interfaces inherited from class java.net.Authenticator
+The main Javaclient class. Creates the main window containing:
+ - the radio button group for making either Greenstone 3 or Fedora the active DL.
+ - the comboboxes for selecting the collection and the service therein
+ - three panes - for executing queries, viewing search results and browsing.
+
dlAPIA
+
+
+ Reference to a digital library instance (Greenstone 3 or Fedora) that
+ allows this client to execute services offered by the digital library
executableServicesOnly
+
+
+ we want to display a drop-down box for the services available,
+ but only Services that can be executed (searching and browsing)
GS3JavaClient()
+
+
+ Default constructor that creates and initialises this main
+ window and its internal GUI components
+
+
+
+
+
+
+
+
+
+Method Summary
+
+
+
+ void
+
actionPerformed(java.awt.event.ActionEvent e)
+
+
+ Event handler for actionEvents such as a change in the active digital
+ library, a collection being selected in the dropdown box or the collection
+ -Info button being pressed, or a service being selected in the service
+ dropdown box (browsing or searching).
+
+
+
+protected void
+
changeDL(DigitalLibraryServicesAPIA dl)
+
+
+ Method that is called when the user chooses to change the active
+ digital library (between Greenstone3 and Fedora).
+
+
+
+ void
+
changeUIColour(int DL)
+
+
+ Changes the background colours of the client's user interface
+ based on what the active digital library is.
+
+
+
+protected boolean
+
createFedoraDLConnection()
+
+
+ Attempts to establish a connection to FedoraGS3.jar and instantiate
+ a FedoraServicesAPIA object and store it in the member variable fedoraDL.
+
+
+
+protected boolean
+
createGreenstoneDLConnection()
+
+
+ Attempts to establish a connection to GS3 Web services and instantiate
+ a GS3ServicesAPIA object and store it in the member variable greenstoneDL.
+
+
+
+ void
+
doBrowse(BrowseDisplay.ClassifierData classifier)
+
+
+ Given a ClassifierData object indicating what browsing category
+ was chosen, this method will retrieve all its descendants in the
+ hierarchy.
getResponseAsDOM(java.lang.String debugPrefix,
+ java.lang.String response)
+
+
+ Given an XML response string, returns the root document (element)
+ representing its DOM form.
+
+
+
+static void
+
main(java.lang.String[] args)
+
+
+ The main method of the GS3 java-client application.
+
+
+
+ void
+
performSearch(java.util.HashMap nameValParamsMap)
+
+
+ Called by the instance of the QueryForm class when the user has
+ pressed the queryPanel's search button to execute a query.
+
+
+
+ void
+
retrieveAllMetadataFor(DocumentNodeData docNode)
+
+
+ Performs a docMetadataRetrieve message request for the docNode
+ iff the metadata for that docNode is not already set.
+
+
+
+ void
+
retrieveContentFor(DocumentNodeData docNode)
+
+
+ Performs a docMetadataRetrieve message request for the docNode
+ iff the nodeContent for that docNode is not already set.
+
+
+
+ void
+
retrieveTitledStructureFor(ClassifierNodeData classNode)
+
+
+ Given a ClassifierNodeData object for browsing, this method will
+ set the classNode's children (previously retrieved) and retrieve
+ all the children's metadata including the title.
+
+
+
+ void
+
retrieveTitledStructureFor(DocumentNodeData docNode)
+
+
+ Performs a structureRetrieve and title metadata retrieve message-
+ request for the docNode, but only iff the structure and title for
+ that docNode is not already set.
+
+
+
+ void
+
setLanguage(java.lang.String lang)
+
+
+ Set the preferred language of the display items
Default constructor that creates and initialises this main
+ window and its internal GUI components
+
+
+
+
+
+
+
+
+
+Method Detail
+
+
+
+
+getLanguage
+
+public java.lang.String getLanguage()
+
+
+
+
+
+
+
Returns:
the language of the display items
+
+
+
+
+
+setLanguage
+
+public void setLanguage(java.lang.String lang)
+
+
Set the preferred language of the display items
+
+
+
+
+
+
Parameters:
lang - - the preferred language for display values
+
+
+
+
+
+createGreenstoneDLConnection
+
+protected boolean createGreenstoneDLConnection()
+
+
Attempts to establish a connection to GS3 Web services and instantiate
+ a GS3ServicesAPIA object and store it in the member variable greenstoneDL.
+ If it was unsuccessful, then this variable remains at null and an error
+ message is displayed.
+
+
+
+
+
+
+
+
+
+
+
+createFedoraDLConnection
+
+protected boolean createFedoraDLConnection()
+
+
Attempts to establish a connection to FedoraGS3.jar and instantiate
+ a FedoraServicesAPIA object and store it in the member variable fedoraDL.
+ If it was unsuccessful, then this variable remains at null and an error
+ message is displayed.
+
Event handler for actionEvents such as a change in the active digital
+ library, a collection being selected in the dropdown box or the collection
+ -Info button being pressed, or a service being selected in the service
+ dropdown box (browsing or searching).
+
+
+
Specified by:
actionPerformed in interface java.awt.event.ActionListener
Called by the instance of the QueryForm class when the user has
+ pressed the queryPanel's search button to execute a query. Based on
+ the user-entered values (stored in the parameter HashMap) this
+ method will call Greenstone to process the query.
+
+
+
+
+
+
Parameters:
nameValParamsMap - - the query form control names with the values
+ the user has entered for them. Example, the pair (fqv, the query string),
+ where fqv is the form control name for the query term.
Performs a structureRetrieve and title metadata retrieve message-
+ request for the docNode, but only iff the structure and title for
+ that docNode is not already set.
+
+
+
+
+
+
Parameters:
docNode - is the DocumentNodeData object for which the title
+ is to be retrieved along with the titles of all its descendants.
Given a ClassifierData object indicating what browsing category
+ was chosen, this method will retrieve all its descendants in the
+ hierarchy. Only the top-level descendents (children) of the
+ classification will be set initially.
+
+
+
+
+
+
Parameters:
classifier - is the ClassifierData object whose children are
+ to be retrieved.
Given a ClassifierNodeData object for browsing, this method will
+ set the classNode's children (previously retrieved) and retrieve
+ all the children's metadata including the title.
+
+
+
+
+
+
Parameters:
classNode - is the ClassifierNodeData object whose title is to
+ be retrieved along with the titles for its children.
+
+
+
+
+
+getBaseURL
+
+public java.lang.String getBaseURL()
+
+
+
+
+
+
+
Returns:
the baseURL of the active digital library interface object
the filepath of the documentNode in the active digital library
+
+
+
+
+
+changeUIColour
+
+public void changeUIColour(int DL)
+
+
Changes the background colours of the client's user interface
+ based on what the active digital library is.
+ See files greenstone3/gli/classes/xml/config.xml and
+ greenstone3/gli/src/org/greenstone/gatherer/Configuration.java
+
+
+
+
+
+
Parameters:
DL - indicates whether the active digital library is Greenstone or
+ Fedora (or neither, in which case the GUI defaults to the usual grey).
+The GraphPaperLayout class is a layout manager that
+ lays out a container's components in a rectangular grid, similar
+ to GridLayout. Unlike GridLayout, however, components can take
+ up multiple rows and/or columns. The layout manager acts as a
+ sheet of graph paper. When a component is added to the layout
+ manager, the location and relative size of the component are
+ simply supplied by the constraints as a Rectangle.
+
+ import java.awt.*;
+ import java.applet.Applet;
+ public class ButtonGrid extends Applet {
+ public void init() {
+ setLayout(new GraphPaperLayout(new Dimension(5,5)));
+ // Add a 1x1 Rect at (0,0)
+ add(new Button("1"), new Rectangle(0,0,1,1));
+ // Add a 2x1 Rect at (2,0)
+ add(new Button("2"), new Rectangle(2,0,2,1));
+ // Add a 1x2 Rect at (1,1)
+ add(new Button("3"), new Rectangle(1,1,1,2));
+ // Add a 2x2 Rect at (3,2)
+ add(new Button("4"), new Rectangle(3,2,2,2));
+ // Add a 1x1 Rect at (0,4)
+ add(new Button("5"), new Rectangle(0,4,1,1));
+ // Add a 1x2 Rect at (2,3)
+ add(new Button("6"), new Rectangle(2,3,1,2));
+ }
+ }
+
GraphPaperLayout()
+
+
+ Creates a graph paper layout with a default of a 1 x 1 graph, with no
+ vertical or horizontal padding.
+
+
+
GraphPaperLayout(java.awt.Dimension gridSize)
+
+
+ Creates a graph paper layout with the given grid size, with no vertical
+ or horizontal padding.
+
+
+
GraphPaperLayout(java.awt.Dimension gridSize,
+ int hgap,
+ int vgap)
+
+
+ Creates a graph paper layout with the given grid size and padding.
+
+
+
+
+
+
+
+
+
+Method Summary
+
+
+
+ void
+
addLayoutComponent(java.awt.Component comp,
+ java.lang.Object constraints)
+
+
+ Adds the specified component to the layout, using the specified
+ constraint object.
+
+
+
+ void
+
addLayoutComponent(java.lang.String name,
+ java.awt.Component comp)
+
+
+ Adds the specified component with the specified name to
+ the layout.
getLargestCellSize(java.awt.Container parent,
+ boolean isPreferred)
+
+
+ Algorithm for calculating the largest minimum or preferred cell size.
+
+
+
+ float
+
getLayoutAlignmentX(java.awt.Container target)
+
+
+ Returns the alignment along the x axis.
+
+
+
+ float
+
getLayoutAlignmentY(java.awt.Container target)
+
+
+ Returns the alignment along the y axis.
+
+
+
+protected java.awt.Dimension
+
getLayoutSize(java.awt.Container parent,
+ boolean isPreferred)
+
+
+ Algorithm for calculating layout size (minimum or preferred).
+
+
+
+ void
+
invalidateLayout(java.awt.Container target)
+
+
+ Invalidates the layout, indicating that if the layout manager
+ has cached information it should be discarded.
+
+
+
+ void
+
layoutContainer(java.awt.Container parent)
+
+
+ Lays out the container in the specified container.
+
+
+
+ java.awt.Dimension
+
maximumLayoutSize(java.awt.Container target)
+
+
+ Returns the maximum size of this component.
+
+
+
+ java.awt.Dimension
+
minimumLayoutSize(java.awt.Container parent)
+
+
+ Calculates the minimum size dimensions for the specified
+ panel given the components in the specified parent container.
+
+
+
+ java.awt.Dimension
+
preferredLayoutSize(java.awt.Container parent)
+
+
+ Calculates the preferred size dimensions for the specified
+ panel given the components in the specified parent container.
+
+
+
+ void
+
removeLayoutComponent(java.awt.Component comp)
+
+
+ Removes the specified component from the layout.
Algorithm for calculating layout size (minimum or preferred).
+
+ The width of a graph paper layout is the largest cell width
+ (calculated in getLargestCellSize() times the number of
+ columns, plus the horizontal padding times the number of columns
+ plus one, plus the left and right insets of the target container.
+
+ The height of a graph paper layout is the largest cell height
+ (calculated in getLargestCellSize() times the number of
+ rows, plus the vertical padding times the number of rows
+ plus one, plus the top and bottom insets of the target container.
+
+
+
+
+
+
Parameters:
parent - the container in which to do the layout.
isPreferred - true for calculating preferred size, false for
+ calculating minimum size.
+
Returns:
the dimensions to lay out the subcomponents of the specified
+ container.
Algorithm for calculating the largest minimum or preferred cell size.
+
+ Largest cell size is calculated by getting the applicable size of each
+ component and keeping the maximum value, dividing the component's width
+ by the number of columns it is specified to occupy and dividing the
+ component's height by the number of rows it is specified to occupy.
+
+
+
+
+
+
Parameters:
parent - the container in which to do the layout.
isPreferred - true for calculating preferred size, false for
+ calculating minimum size.
+
Returns the alignment along the x axis. This specifies how
+ the component would like to be aligned relative to other
+ components. The value should be a number between 0 and 1
+ where 0 represents alignment along the origin, 1 is aligned
+ the furthest away from the origin, 0.5 is centered, etc.
+
+
+
Specified by:
getLayoutAlignmentX in interface java.awt.LayoutManager2
Returns the alignment along the y axis. This specifies how
+ the component would like to be aligned relative to other
+ components. The value should be a number between 0 and 1
+ where 0 represents alignment along the origin, 1 is aligned
+ the furthest away from the origin, 0.5 is centered, etc.
+
+
+
Specified by:
getLayoutAlignmentY in interface java.awt.LayoutManager2
+Panel that represents a Query Form based on GS3 describe response XML
+ messages sent by a Query Service. An inner panel will contain all the
+ actual form controls. The form can be reset to empty which will clear
+ its contents. Its contents can be reset to display controls appropriate
+ to new Query Service describe response XML messages.
+
QueryForm(GS3JavaClient client)
+
+
+ Constructor that instantiates this Form's internal GUI items.
+
+
+
+
+
+
+
+
+
+Method Summary
+
+
+
+ void
+
actionPerformed(java.awt.event.ActionEvent e)
+
+
+ Called when this QueryForm's search button is pressed: the data
+ entered/controls settings specified by the user are passed to the
+ digital library's Query Service in order to perform the search.
+
+
+
+ void
+
changeUIColour()
+
+
+ Changes the colour of the query form and its controls to the
+ current colours set in class ColourCombo.
+
+
+
+ void
+
clear()
+
+
+ Call this method to empty all the form controls.
+
+
+
+ void
+
formFromQueryServiceDescribe(org.w3c.dom.Element el)
+
+
+ Sets up the the query form for display (queryPanel) given the XML of
+ the response-message returned by a "describe" request sent to a
+ Query Service.
+
+
+
+ void
+
keyPressed(java.awt.event.KeyEvent e)
+
+
+ Defined by KeyListener interface.
+
+
+
+ void
+
keyReleased(java.awt.event.KeyEvent e)
+
+
+ Called when the searchButton was in focus and a key was pressed.
+
+
+
+ void
+
keyTyped(java.awt.event.KeyEvent e)
+
+
+ Defined by KeyListener interface.
+
+
+
+protected void
+
searchButtonPressed()
+
+
+ Called when the searchButton was clicked or when it was in focus
+ and the enter key was pressed.
Constructor that instantiates this Form's internal GUI items.
+
+
+
Parameters:
client - - handle to the running instance of the GS3JavaClient
+
+
+
+
+
+
+
+
+Method Detail
+
+
+
+
+clear
+
+public void clear()
+
+
Call this method to empty all the form controls. This Query Form
+ component can then be reused.
+
+
+
+
+
+
+
+
+
+
+
+changeUIColour
+
+public void changeUIColour()
+
+
Changes the colour of the query form and its controls to the
+ current colours set in class ColourCombo. Specified by
+ the ColourCombo.ColourChangeable interface.
+
Called when this QueryForm's search button is pressed: the data
+ entered/controls settings specified by the user are passed to the
+ digital library's Query Service in order to perform the search.
+
+
+
Specified by:
actionPerformed in interface java.awt.event.ActionListener
Called when the searchButton was in focus and a key was pressed. If
+ this key was the Enter button, then the search is performed: the data
+ entered/controls settings specified by the user are passed to the
+ digital library's Query Service in order to perform the search.
+
+
+
Specified by:
keyReleased in interface java.awt.event.KeyListener
+
+
+
+
+
+
+
+
+searchButtonPressed
+
+protected void searchButtonPressed()
+
+
Called when the searchButton was clicked or when it was in focus
+ and the enter key was pressed. The search is performed by passing the
+ data entered/controls settings specified by the user to the digital
+ library's Query Service in order to perform the search.
+
Sets up the the query form for display (queryPanel) given the XML of
+ the response-message returned by a "describe" request sent to a
+ Query Service. That is, generates the query form as specified
+ by the given response XML for a Query describe.
+
+
+
+
+
+
Parameters:
el - - a serviceResponseXML for a describe request that specifies
+ how the paramsPanel should look.
+Represents a control in a query form. This wrapper class is a subclass of
+ QueryFormParam that presents its QueryFormParam details as an appropriate
+ GUI item *with* label (based on the QueryFormParam's type) for display
+ in its own JPanel.
+ This wrapper class is a widget that knows to display this QueryFormParam --
+ and any child <param>s or <option>s -- in its own JPanel.
+
+
+
+
+
Author:
+
ak19
+
+
+
+
+
+
+
+
+
+
+Nested Class Summary
+
+
+
+
+
+
Nested classes/interfaces inherited from class org.greenstone.gs3client.data.QueryFormData
QueryFormControl(org.w3c.dom.Element param)
+
+
+ Constructor that creates a QueryFormControl for a <param> element
+
+
+
QueryFormControl(org.w3c.dom.Element param,
+ javax.swing.JPanel parentPanel)
+
+
+ Constructor that creates a QueryFormControl for a <param> element
+ inside a panel.
+
+
+
+
+
+
+
+
+
+Method Summary
+
+
+
+protected void
+
addGridBagComponent(javax.swing.JPanel panel,
+ javax.swing.JComponent comp,
+ java.awt.GridBagLayout gbLayout,
+ java.awt.GridBagConstraints gbConstraints,
+ int col,
+ int row,
+ int w,
+ int h)
+
+
+ The multi-panel is laid out with a GridBagLayout in order to make
+ the layout more attractive (so that the form controls don't have as
+ odd sizes as before when GraphPaperLayout was used).
+
+
+
+ void
+
createBooleanField()
+
+
+ Creates check box controls for the <param> elements whose
+ types are GSXML.PARAM_TYPE_BOOLEAN.
+
+
+
+ void
+
createEnumListing(org.w3c.dom.Element param)
+
+
+ Creates combo boxes/drop-downs for the <param> elements
+ whose types are GSXML.PARAM_TYPE_ENUM_SINGLE and listboxes for those
+ whose types are GSXML.PARAM_TYPE_ENUM_MULTI.
+
+
+
+ void
+
createMultiPanel(org.w3c.dom.Element param,
+ javax.swing.JPanel parentPanel)
+
+
+ A multi-panel is created for a *set* of controls that occur more than
+ once.
+
+
+
+ void
+
createTextField()
+
+
+ Creates text fields for the <param> elements whose types are
+ GSXML.PARAM_TYPE_STRING or GSXML.PARAM_TYPE_INTEGER).
+
+
+
+ void
+
createWidget(org.w3c.dom.Element param)
+
+
+ Creates the appropriate form control for the <param> element,
+ based on its type.
+
+
+
+ void
+
setSelectedValue(java.util.HashMap nameValsMap)
+
+
+ If called after the form containing these param controls has been
+ displayed and the user has entered/selected values (i.e.
Creates combo boxes/drop-downs for the <param> elements
+ whose types are GSXML.PARAM_TYPE_ENUM_SINGLE and listboxes for those
+ whose types are GSXML.PARAM_TYPE_ENUM_MULTI.
+
+
+
Parameters:
param - - a <param> element in a Query Service's describe
+ response XML message
A multi-panel is created for a *set* of controls that occur more than
+ once.
+ Processes <param type="multi"> in a Query Service's describe
+ response XML. (I.e. the type is GSXML.PARAM_TYPE_MULTI)
+ Complicated case: can have 'occurs' field set. And this <param>
+ element can have multiple <param>s itself, each with the 'ignore'
+ possibly set and each with its own <option> elements.
+
+
+
Parameters:
param - - a <param> element in a Query Service's describe
+ response XML message
parentPanel - - the panel inside which the multipanel is to display
+ itself.
+
+
+
+
+
+addGridBagComponent
+
+protected void addGridBagComponent(javax.swing.JPanel panel,
+ javax.swing.JComponent comp,
+ java.awt.GridBagLayout gbLayout,
+ java.awt.GridBagConstraints gbConstraints,
+ int col,
+ int row,
+ int w,
+ int h)
+
+
The multi-panel is laid out with a GridBagLayout in order to make
+ the layout more attractive (so that the form controls don't have as
+ odd sizes as before when GraphPaperLayout was used).
+ This method sets the constraints for the given control and then adds
+ it to the given JPanel.
+ This method is called to add a control (or heading label) to the
+ multi-panel using GridBagLayout.
+
+
+
Parameters:
panel - is the panel to add the control (or heading label) to.
comp - is the Query Form control or heading JLabel to be laid out.
gbLayout - is the GridBagLayout object used to lay out the panel.
gbConstraints - is the GridBagConstraints object for the panel's
+ GridBagLayout.
col - is the column value of the top-left of the control (for
+ setting the GridBagLayout's gridx value).
row - is the row value of the top-left of the control (for
+ setting the GridBagLayout's gridy value).
w - is the number of columns spanned by the control (for setting
+ the GridBagLayout's gridwidth value).
h - is the number of rows spanned by the control (for setting
+ the GridBagLayout's gridheight value).
If called after the form containing these param controls has been
+ displayed and the user has entered/selected values (i.e. after the search
+ button to execute a query has been pressed), then this method puts
+ the controls' associated QueryFormParam names and the user-
+ entered/-selected values into the HashMap nameValsmap (= the argument).
+ Note that for the GSXML.PARAM_TYPE_MULTI case - where each related set
+ of controls may occur several times (depending on member variable
+ 'occurs') - the value entered/selected for each control that has the
+ same *name* (= key into the HashMap) is added into the HashMap as
+ a comma-separated list associated with its name-key.
+ This method requires that argument nameValsmap is a non-null HashMap.
+
+
+
Parameters:
nameValsMap - - a non-null HashMap. At the end of this method,
+ the nameValsMap HashMap will contain mappings from query parameter field
+ names to their user-entered values (for the field's associated
+ form controls).
+The Search panel inside the Java-client's tab pane that's labelled
+ "Search Results". This panel contains two tree views:
+ - one for displaying the list of search results (top-level documents or document
+ - one for displaying the structure of document nodes selected in the list of
+ search results.
+ This panel also contains an area where the selected documentNode's metadata is
+ displayed, and a text area where the textual or image content of a selected
+ documentNode is displayed.
+
changeUIColour()
+
+
+ Changes the colour of the query form and its controls to the
+ current colours set in class ColourCombo.
+
+
+
+ void
+
clear()
+
+
+ Clears the service-specific buttons in the browseBar and the
+ service-specific display-data.
+
+
+
+ java.awt.Dimension
+
getPreferredSize()
+
+
+ Overrode this method to resize the splitpanes within, upon resize.
+
+
+
+protected void
+
restructureWithNewRoot(DocumentNodeData rootDocNode)
+
+
+ Restructures the docStructureTree with a new rootNode when a different
+ search result has been clicked.
+
+
+
+ void
+
setResults(DocumentNodeData[] resultDocs)
+
+
+ Restructures the searchResultsTree when another search has been made, so
+ that the search results contain a new list of documentNodeData objects.
+
+
+
+ void
+
valueChanged(javax.swing.event.TreeSelectionEvent e)
+
+
+ Part of the TreeSelectionListener interface.
Constructor that creates the Search Panel and its internal GUI items.
+
+
+
Parameters:
client - is the running instance of the client application through
+ which its methods can be accessed.
+
+
+
+
+
+
+
+
+Method Detail
+
+
+
+
+getPreferredSize
+
+public java.awt.Dimension getPreferredSize()
+
+
Overrode this method to resize the splitpanes within, upon resize.
+ It calculates the size of this panel, as well as setting those of
+ the splitpanes it contains based on the size of the parent container.
+
+
+
Overrides:
getPreferredSize in class javax.swing.JComponent
+
+
+
+
Returns:
the preferred dimensions of this JPanel.
+
+
+
+
+
+changeUIColour
+
+public void changeUIColour()
+
+
Changes the colour of the query form and its controls to the
+ current colours set in class ColourCombo. Specified by
+ the ColourCombo.ColourChangeable interface.
+
Clears the service-specific buttons in the browseBar and the
+ service-specific display-data. The rest of the GUI (split panes, panels)
+ remain as they are. Resets the contents of the widgets in this panel.
+
Part of the TreeSelectionListener interface. When this is called, an item
+ has been clicked in either the searchResultsTree or the docStructureTree.
+ This method displays the metadata and textual contents accordingly
+ of the selected documentNodeData object.
+
+
+
Specified by:
valueChanged in interface javax.swing.event.TreeSelectionListener
+Stores the data contained in an XML response message to a request for
+ the classification Browse structure. An object of this class can be reused
+ after instatiation by calling setResponseData() with a new browse
+ response XML message. This will first call clear() to clear/release
+ its references to all the old data.
+
clear()
+
+
+ Resets the internal data members of this BrowseResponseData object of
+ their values so that this BrowseResponseData can be reused for the
+ next Browse response message.
setMetadataForClassifiers(org.w3c.dom.Element messageTag)
+
+
+ Given the response message element to a metadata request on
+ <classifierNode>s;, this method sets those classifierNodes' metadata.
+
+
+
+ void
+
setResponseData(org.w3c.dom.Element responseMsgTag)
+
+
+ Given an XML responseMessage to a request for the classification
+ Browse structure, this method sets its nodeIDsToNodes member variable
+ by instantiating classifierNodeData and/or documentNodeData objects
+ as given in the responseMessageTag.
+
+
+
+ java.lang.String
+
show()
+
+
+ Overloaded method to produce a String output of the data contained in
+ this BrowseResponseMessage.
+
+
+
+
+
+
Methods inherited from class org.greenstone.gs3client.data.ResponseData
Reference to the root browse classifier, which may contain further
+ descendent classifierNodes or documentNodes.
+
+
+
+
+
+
+
+
+
+
+
+Constructor Detail
+
+
+
+
+BrowseResponseData
+
+public BrowseResponseData()
+
+
Default constructor
+
+
+
+
+
+
+
+
+
+Method Detail
+
+
+
+
+clear
+
+public void clear()
+
+
Resets the internal data members of this BrowseResponseData object of
+ their values so that this BrowseResponseData can be reused for the
+ next Browse response message.
+
Given an XML responseMessage to a request for the classification
+ Browse structure, this method sets its nodeIDsToNodes member variable
+ by instantiating classifierNodeData and/or documentNodeData objects
+ as given in the responseMessageTag. This method will not process all
+ descendents of a classifierNode, but only those that are children
+ of the top level classifierNode.
+ The responseMessageTag contains *all the descendents* in one go. But
+ we don't set all the descendents, just the children of the
+ rootClassifierNode. However, as we store the responseMsgTag in pieces
+ (each child NodeData stores the bit relevant to it), we will work out
+ the children of each child etc as needed.
+
Given the response message element to a metadata request on
+ <classifierNode>s;, this method sets those classifierNodes' metadata.
+ It merely calls the the superclass' setMetadataForDocuments(messageTag,
+ tagName) method to parse out data for the tagName=<classifierNode>.
+
+
+
Parameters:
messageTag - - the response message Element to a metadata
+ request on <classifierNode>s
+ClassifierNodeData represents the information that can be stored in a
+ <classifierNode> element. A ClassifierNode may have children and
+ further descendents of type NodeData: either of type DocumentNodeData
+ or type ClassifierNodeData.
+
ClassifierNodeData(org.w3c.dom.Element classifierNodeTag)
+
+
+ Constructor that given a classifierNode element creates
+ a ClassifierNodeData instance to parse and store its data.
getChildren()
+
+
+ Gets the children of this node, but does not guarantee that *their*
+ children are set.
+
+
+
+ void
+
setChildren(java.util.Map idsToNodes_map)
+
+
+ Given a map of nodeIdsToNodes, this method instantiates any
+ children this ClassifierNodeData object might have.
+
+
+
+ void
+
setTitle(java.lang.String name)
+
+
+ This method is mainly useful for setting the top-level/root
+ classifierNode's name.
Constructor that given a classifierNode element creates
+ a ClassifierNodeData instance to parse and store its data.
+ A classifierNodeData <classifierNode> contains just a nodeID
+ and can contain children. When a response for a classifierNode's
+ children is returned in a <nodeStructure>, this can be used to
+ set the children.
+ This classifierNodeData object is constructed from the data
+ encapsulated in a <classifierNode> element
+
+
+
Parameters:
classifierNodeTag - is the <classifierNode> element in a
+ Greenstone3 response XML message
+
+
+
+
+
+
+
+
+Method Detail
+
+
+
+
+setTitle
+
+public void setTitle(java.lang.String name)
+
+
This method is mainly useful for setting the top-level/root
+ classifierNode's name. Otherwise, can use method setMetadataList
+ to set the various metadata (name, values) associated with a
+ classifierNode.
+ Adds a new title to nodeMetadata as long as it is not the same
+ as the previous title added.
+
Given a map of nodeIdsToNodes, this method instantiates any
+ children this ClassifierNodeData object might have. This
+ method will set member childnodes (or leave it at none)
+ and update idsToNodes_map as necessary.
+
+
+
Parameters:
idsToNodes_map - is a Hashmap of all the Node IDs to Node
+ objects being maintained (Classifier- or DocumentNode)
Gets the children of this node, but does not guarantee that *their*
+ children are set. Will return null either if this NodeData has no
+ children or if this node's children are not set yet.
+
an array of all the child Nodes of this ClassifierNode
+ (as per its hierarchical structure) or null if these are not yet set
+ or if it has no children
a string representation of the values stored in this
+ ClassifierNodeData object: outputs the nodeID and calls show() on any
+ children NodeData objects. It's mainly useful for debugging purposes.
+Static inner class MetaData: can import it into other files as
+ "import gs3client.CollectionData.MetaData;"
+ In this way, can use it as if it were a regular class (a.o.t. an inner
+ class). That is, don't need to prepend the outer-classname if imported
+ like this.
+ gs3client.MetaData, from which this class inherits, has name, value and
+ bodyText fields. This class adds an additional language field that is
+ sometimes present in a Collection's metadata information. So we include
+ the language as a member variable here in case we ever need it.
+
CollectionData.MetaData(org.w3c.dom.Element metadataTag)
+
+
+ Given a <metadata></metadata> element, constructs a
+ CollectionData sets its members using info extracted from it
+PluginData inner class of CollectionData, represents the data stored in
+ a <plugin></plugin> element. This class just stores the
+ Plugin's name, as well as option subelements (in variable optionnames).
+
+
+
+
+
+
+
+
+
+
+
+
+Field Summary
+
+
+
+ java.lang.String
+
name
+
+
+ name of the plugin represented by this PluginData object
+Only the name and type of a <service></service> element is
+ stored, since this is all the service data available inside a collection's
+ response message to a describe request. And we are here dealing with
+ just a CollectionData's service information (hence it's an inner class:
+ CollectionData.ServiceData).
+
+
+
+
+
+
+
+
+
+
+
+
+Field Summary
+
+
+
+ java.lang.String
+
name
+
+
+ name of the Greenstone service represented by this ServiceData object
+
+
+
+ java.lang.String
+
type
+
+
+ type attribute of <service></service> element.
+
+
+
+
+
+
+
+
+
+Constructor Summary
+
+
+
CollectionData.ServiceData(org.w3c.dom.Element serviceTag)
+
+
+ Gets a <service></service> element and sets its members using
+ info extracted from it
+CollectionData represents a Greenstone 3 collection and contains the data
+ stored in a <collection></collection> element returned from a
+ MessageRouter's desribe response XML and a Collection describe response XML.
+ A CollectionData object can therefore contain services (represented by
+ ServiceData), a list of collection-level metadata (represented by MetaData)
+ and a list of plugins (represented by PluginData).
+
+ ServiceData and PluginData are static inner classes of CollectionData.
+ To declare variables of these inner class types in other java files/classes,
+ import each one: e.g. "import gs3client.CollectionData.ServiceData".
+ Then they can be used without the outerclass' name for qualification:
+ i.e. can then use Servicedata sv = new ServiceData(...)
+ instead of CollectionData.ServiceData sv = new
+ CollectionData.ServiceData(...).
+
+
+
+
+
Author:
+
ak19
+
+
+
+
+
+
+
+
+
+
+Nested Class Summary
+
+
+
+static class
+
CollectionData.MetaData
+
+
+ Static inner class MetaData: can import it into other files as
+ "import gs3client.CollectionData.MetaData;"
+ In this way, can use it as if it were a regular class (a.o.t.
+
+
+
+static class
+
CollectionData.PluginData
+
+
+ PluginData inner class of CollectionData, represents the data stored in
+ a <plugin></plugin> element.
+
+
+
+static class
+
CollectionData.ServiceData
+
+
+ Only the name and type of a <service></service> element is
+ stored, since this is all the service data available inside a collection's
+ response message to a describe request.
+
+
+
+
+
+
+
+
+Field Summary
+
+
+
+protected java.lang.String
+
description
+
+
+ Description of the Greenstone collection represented by this
+ CollectionData
+
+
+
+protected java.lang.String
+
displayName
+
+
+ Display name for the Greenstone collection represented by this
+ CollectionData
url
+
+
+ Stores the location of images and stuff.
+
+
+
+
+
+
+
+
+
+Constructor Summary
+
+
+
CollectionData(org.w3c.dom.Element mrCollectionTag)
+
+
+ Gets a <collection></collection> element as returned by the
+ MessageRouter's describe response, with only the name field set.
setFields(org.w3c.dom.Element collectionTag)
+
+
+ Gets a <collection></collection> element - as returned by a
+ describe response from a Collection - and sets the member vars using
+ the data in there.
Stores the location of images and stuff. Not really used at present
+
+
+
+
+
+
+
+name
+
+public final java.lang.String name
+
+
The basic field of a collection: the name of the collection. This is
+ present for collection elements in all describe response messages,
+ whether sent from the MessageRouter or from Greenstone collections.
+
+
+
+
+
+
+
+displayName
+
+protected java.lang.String displayName
+
+
Display name for the Greenstone collection represented by this
+ CollectionData
+
+
+
+
+
+
+
+description
+
+protected java.lang.String description
+
+
Description of the Greenstone collection represented by this
+ CollectionData
+
Gets a <collection></collection> element - as returned by a
+ describe response from a Collection - and sets the member vars using
+ the data in there.
+
+
+
Parameters:
collectionTag - is the <collection></collection> element
+ as returned by a describe response from a Collection.
+
+
+
+
+
+toString
+
+public java.lang.String toString()
+
+
Useful when adding CollectionData objects to a JList or JCombobox.
+
+
+
Overrides:
toString in class java.lang.Object
+
+
+
+
Returns:
the name of the collection represented by this CollectionData
+
+
+
+
+
+show
+
+public java.lang.String show()
+
+
+
+
Returns:
a String displaying the contents of this CollectionData object.
+ Useful for debugging purposes.
+
+
+
+
+
+info
+
+public java.lang.String info()
+
+
+
+
Returns:
the Info string for the collection reprsented by this
+ CollectionData object.
executableServicesOnly - - if true, only the list of supported query
+ and browse services are returned. Otherwise, all the services in the
+ collection are returned.
+
Returns:
the list of services supported by this collection.
+Represents the data stored in the <documentNode> Elements
+ of Greenstone 3's XML response messages. A DocumentNodeData may
+ have descendants of type DocumentNodeData. Some DocumentNodeData
+ objects are the root of a structure, others are internal nodes or
+ leaves.
+ See p.47 to p.49 in the manual.
+
DocumentNodeData(org.w3c.dom.Element docNodeTag)
+
+
+ Given tags of the form
+ <documentNode nodeID="HASHac0a04dd14571c60d7fbfd.4.2"
+ nodeType="x" docType="y">
+ <nodeContent>Text</nodeContent>
+ <nodeStructureInfo><info name="i" value="1" />
+ <info name = "ii" value = "2" /></nodeStructureInfo>
+ <metadataList><metadata name="a">Value
+ </metadata></metadataList>
+ <nodeStructure>
+ <documentNode ....></documentNode>
+ <documentNode ....></documentNode>
+ </nodeStructure>
+ </documentNode>
+ this constructor extracts the nodeId out of it and any other fields
+ that might be set in the docNodeTag <documentNode> element.
descNodeIDsAsList(java.util.Vector v,
+ DocumentNodeData parent,
+ boolean onlyTheUntitled)
+
+
+ Recursive method that adds all the nodeIDs of the descendents
+ of DocumentNodeData parent into the Vector v.
setDescendentsOfRootNode(org.w3c.dom.Element nodeStructure,
+ java.util.Map nodeIDsToDocNodes_map)
+
+
+ Given a <nodeStructure></nodeStructure> element returned
+ from a request for the *ENTIRE* nodeStructure, this method will find the
+ <documentNode> that is the Root (nodeType=ROOT) and from there
+ on proceed to set all descendent <documentNode>s.
+
+
+
+ void
+
setNodeContent(org.w3c.dom.Element docNodeTag)
+
+
+ Sets member variable nodeContent with the text (if any) inside any
+ <nodeContent></nodeContent> child element of
+ <documentNode>, else the value of nodeContent is set to empty
+ string ("").
+
+
+
+ void
+
setNodeStructInfo(org.w3c.dom.Element docNodeTag)
+
+
+ Sets structureInfo member variable <nodeStructureInfo> element is
+ present as child of <documentNode>, else value of structureInfo
+ remains unchanged.
Given tags of the form
+ <documentNode nodeID="HASHac0a04dd14571c60d7fbfd.4.2"
+ nodeType="x" docType="y">
+ <nodeContent>Text</nodeContent>
+ <nodeStructureInfo><info name="i" value="1" />
+ <info name = "ii" value = "2" /></nodeStructureInfo>
+ <metadataList><metadata name="a">Value
+ </metadata></metadataList>
+ <nodeStructure>
+ <documentNode ....></documentNode>
+ <documentNode ....></documentNode>
+ </nodeStructure>
+ </documentNode>
+ this constructor extracts the nodeId out of it and any other fields
+ that might be set in the docNodeTag <documentNode> element.
+
+
+
Parameters:
docNodeTag - is an <documentNode> XML element to construct
+ this DocumentNodeData object from
Given a <nodeStructure></nodeStructure> element returned
+ from a request for the *ENTIRE* nodeStructure, this method will find the
+ <documentNode> that is the Root (nodeType=ROOT) and from there
+ on proceed to set all descendent <documentNode>s.
+ If either the root or any descendent <documentNode>s have already
+ been instantiated at any point during program execution, it will
+ be reused, else a new object representing that descendent/root
+ <documentNode> will be created.
+ The nodeIDsToDocNodes_map is a mapping of nodeIDs to existing
+ documentNodeData objects, so that the DocumentNodeData objects with
+ the same ID need not be instantiated where they already exist.
+ This method returns the rootNode if it completes successfully,
+ otherwise it returns null.
+
+
+
Parameters:
nodeStructure - is the <nodeStructure></nodeStructure>
+ element returned from a request for the *ENTIRE* nodeStructure
nodeIDsToDocNodes_map - is the Map of node IDs to DocumentNodeData
+ objects being maintained
+
Returns:
the root DocumentNodeData object of the <documentNode>s
+ in the <nodeStructure>
Recursive method.
+ Called by setDescendentsOfRootNode(). Given a docNodeTag (of the Root)
+ which was nested within a <nodeStructure> element, this method sets
+ all the descendents of that root. This means that each documentNodeData
+ object in the hierarchy of the root will have its childnodes[] variable
+ set, iff that object is not a nodeType==LEAF. With leaves, the
+ childnodes array will remain null.
+ The nodeIDsToDocNodes_map is a mapping of nodeIDs to existing
+ documentNodeData objects, so that the DocumentNodeData objects with the
+ same ID need not be instantiated where they already exist.
+
+
+
Parameters:
root - - the root element of this documentNodeData
docNodeTag - - the <documentNode> XML Element of the Root
+ nested within a <nodeStructure> element
nodeIDsToDocNodes_map - is the Map of node IDs to DocumentNodeData
+ objects being maintained
Sets structureInfo member variable <nodeStructureInfo> element is
+ present as child of <documentNode>, else value of structureInfo
+ remains unchanged. A <docNode> has no more than one child
+ <nodeStructureInfo> in a response to a DocumentStructureRetrieve.
+ However, the response can contain many such <docNodes>.
+ See manual p.49.
+
+
+
Parameters:
docNodeTag - is the <documentNode> XML element containing
+ the <nodeStructureInfo> Element that is to be processed
Sets member variable nodeContent with the text (if any) inside any
+ <nodeContent></nodeContent> child element of
+ <documentNode>, else the value of nodeContent is set to empty
+ string (""). The empty string will prevent it from being retrieved again
+ and again (which would happen if nodeContent remained at null) if it had
+ already been retrieved once.
+ However, if the docNodeTag parameter is not the response from
+ a documentContentRetrieve (if it doesn't have the proper XML
+ structure for that), nodeContent remains null and can be set
+ in future when given an appropriate docNodeTag.
+
+
+
Parameters:
docNodeTag - is the <documentNode> XML element containing
+ the content information for this DocumentNodeData object
the data stored in this DocumentNodeData object, all except
+ the document content which can be accessed by calling toString().
+ This method is useful for debugging purposes: to view what each
+ field's values are.
+
+
+
+
+
+isLeaf
+
+public boolean isLeaf()
+
+
+
+
Returns:
true if the (nodeType of) this DocumentNodeData is a leaf
the root of the structure of which this documentNodeData
+ is part (this docNodeData is either the root itself or its child
+ or descenedent). A null is returned if the Root docNode and its
+ descendents have not been set yet.
+
+
+
+
+
+getContent
+
+public java.lang.String getContent()
+
+
+
+
Returns:
this document's text content (which may be empty string
+ if there was none). It will return null if the nodeContent has
+ not been set yet.
an array of all this DocNode's children. Each childnode
+ in turn, can further contain children, etc. Null is returned if
+ there are no childnodes or if setDescendentsOfRootNode() has not
+ been called (that is, if the root has not yet been set).
gets the children (NodeData) of this DocumentNodeData
+ but does not guarantee that their children are set. That is,
+ it's possible that this DocumentNodeData's children may have
+ children of their own but that these may not be set yet (and
+ are temporarily still null).
When called on a rootNode, returns an array of all the descendents'
+ nodeIDs. If this object is not a rootNode, it returns null.
+ Parameter onlyTheUntitled, if true, makes this method return only the
+ nodeIDs of those documentNodeData descendents for whom the title has
+ not yet been set.
+ If false, the nodeIDs of all dDcumentNodeData descendents will be
+ returned, regardless of whether their titles are already set.
+
+
+
Parameters:
onlyTheUntitled - - if true this method is only to return those
+ descendants' IDs whose titles have not yet been set. If false,
+ all descendants' nodeIDs are returned.
+
Returns:
an array of all the descendant DocumentNodeData's NodeIDs
Recursive method that adds all the nodeIDs of the descendents
+ of DocumentNodeData parent into the Vector v.
+ If parameter onlyTheUntitled=true, then only the nodeIDs of the
+ untitled DocumentNodeData descendents are added in. Otherwise,
+ all descendents' nodeIDs are.
+
+
+
Parameters:
v - is the Vector being populated with descendant documentNodeData's
+ IDs.
parent - is the parent DocumentNodeData node currently being
+ considered in this recursion step.
onlyTheUntitled - should be true if only those descendant
+ DocumentNodeData objects that don't yet have a title need to be returned.
+ If false, it returns all descendants' nodeIDs in the Vector v.
+
+
+
+
+
+canBeImage
+
+public boolean canBeImage()
+
+
+
+
Returns:
true if this documentNode's root is associated with the
+ ImagePlug or PagedImgPlug.
value of "notext" metadata field, if any. If true, this
+ indicates that the document is purely an image. Otherwise it indicates
+ that there is both a text view and an image view associated with this
+ document.
+
+
+
+
+
+getImgURL
+
+public java.lang.String getImgURL()
+
+
+
+
Returns:
the image url stored in the "srcicon" metadata field, if any.
+
+
+
+
+
+getImgName
+
+public java.lang.String getImgName()
+
+
+
+
Returns:
the Source metadata value which represents the image file
+ name. Returns "" if this DocumentNodeData is not a root or does not
+ have Source meta.
+
+
+
+
+
+getAssociatedFileNames
+
+public java.util.Vector getAssociatedFileNames()
+
+
+
+
Returns:
the vector of values for metadata name "gsdlassocfile": a vector
+ of MetaPairs(filename, mimetype).
+ An empty vector is returned for all docNodes other than the root. And the
+ root too need not always have associated files listed in its metadata.
+
+
+
+
+
+getAssocFilePath
+
+public java.lang.String getAssocFilePath()
+
+
+
+
Returns:
the root document's assocfilepath metadata field, if any.
+ This will indicate the directory path where the associated images
+ and other files are stored.
value
+
+
+ Value attribute of a <metadata> - this may or may not be there
+
+
+
+
+
+
+
+
+
+Constructor Summary
+
+
+
MetaData(org.w3c.dom.Element metadataTag)
+
+
+ Constructor that creates a MetaData object from a
+ <metadata></metadata> element by setting its members fields
+ using info extracted from the element.
Value attribute of a <metadata> - this may or may not be there
+
+
+
+
+
+
+
+bodyText
+
+public final java.lang.String bodyText
+
+
Text node content of a <metadata> - the textnode may be empty, in
+ which case this will be set to ""
+
+
+
+
+
+
+
+
+
+
+
+Constructor Detail
+
+
+
+
+MetaData
+
+public MetaData(org.w3c.dom.Element metadataTag)
+
+
Constructor that creates a MetaData object from a
+ <metadata></metadata> element by setting its members fields
+ using info extracted from the element.
+
+
+
Parameters:
metadataTag - is the <metadata> element whose data is used
+ to construct this MetaData object
+
+
+
+
+
+
+
+
+Method Detail
+
+
+
+
+toString
+
+public java.lang.String toString()
+
+
+
Overrides:
toString in class java.lang.Object
+
+
+
+
Returns:
the name of this Metadata object. Useful when adding MetaData
+ objects to a JList or JCombobox
+
+
+
+
+
+show
+
+public java.lang.String show()
+
+
+
+
Returns:
a String displaying the contents of this MetaData object.
+ Useful for debugging purposes.
+Abstract superclass NodeData can represent either a the information in
+ a <classifierNode> (stored in a ClassifierNodeData object) or in a
+ <documentNode> (stored in a DocumentNodeData object).
+
+
+
+
+
Author:
+
ak19
+
+
+
+
+
+
+
+
+
+
+Field Summary
+
+
+
+ boolean
+
hasChildren
+
+
+ Since we are setting the descendents lazily (only setting the children
+ each time), we have a little flag to indicate whether this node has
+ any children.
+
+
+
+ java.lang.String
+
nodeID
+
+
+ The unique nodeID identifying this documentNode or classificationNode
+
+
+
+protected java.util.Map
+
nodeMetadata
+
+
+ Map of the metadata (name, value) pairs of this document-
+ or classifier-node
+
+
+
+protected org.w3c.dom.Element
+
nodeTag
+
+
+ stores this NodeData's tag element: can be either
+ <documentNode> or <classifierNode>
+
+
+
+
+
+
+
+
+
+Constructor Summary
+
+
+
NodeData(org.w3c.dom.Element nodeTag)
+
+
+ Constructor that extracts the nodeID value from the given nodeTag:
+ <classifierNode nodeID = "x" />
+ or <documentNode nodeID = "x" />
setChildren(java.util.Vector v,
+ java.util.Map idsToNodes_map)
+
+
+ Called when setting descendents lazily: only the children of this
+ node are set.
+
+
+
+ void
+
setMetadataList(org.w3c.dom.Element nodeTag)
+
+
+ Sets member metadataList if there is a <metadataList> subelement in
+ docNodeTag: first get the <metadataList> then its <metadata>
+ children
The unique nodeID identifying this documentNode or classificationNode
+
+
+
+
+
+
+
+hasChildren
+
+public final boolean hasChildren
+
+
Since we are setting the descendents lazily (only setting the children
+ each time), we have a little flag to indicate whether this node has
+ any children.
+
+
+
+
+
+
+
+nodeTag
+
+protected final org.w3c.dom.Element nodeTag
+
+
stores this NodeData's tag element: can be either
+ <documentNode> or <classifierNode>
+
+
+
+
+
+
+
+nodeMetadata
+
+protected java.util.Map nodeMetadata
+
+
Map of the metadata (name, value) pairs of this document-
+ or classifier-node
+
+
+
+
+
+
+
+
+
+
+
+Constructor Detail
+
+
+
+
+NodeData
+
+public NodeData(org.w3c.dom.Element nodeTag)
+
+
Constructor that extracts the nodeID value from the given nodeTag:
+ <classifierNode nodeID = "x" />
+ or <documentNode nodeID = "x" />
+
Sets member metadataList if there is a <metadataList> subelement in
+ docNodeTag: first get the <metadataList> then its <metadata>
+ children
+
+
+
Parameters:
nodeTag - is a documentNode or classifierNode XML Element that
+ contains metadata information which is used to set this NodeData object's
+ metadata (if there are any, the HashMap nodeMetadata will be set).
Called when setting descendents lazily: only the children of this
+ node are set. We don't care to setDescendents now, will set it later
+ when necessary.
+
+
+
Parameters:
v - is an empty/non-null Vector which will, at method's end, contain
+ all the Document- or ClassifierNodeData objects that are children of
+ this NodeData object.
+
+
+
+
+
+getMetadataList
+
+public java.util.Map getMetadataList()
+
+
+
+
Returns:
a hashmap of this document's metadata (name, val) pairs.
+ A null is returned if the nodeMetadata has not been set yet.
+
+
+
+
+
+getTitle
+
+public java.lang.String getTitle()
+
+
+
+
Returns:
the title of this docNodeData object, if any is set. If it's
+ not been set yet (title metadata not yet set, a null is returned.
+
+
+
+
+
+toString
+
+public java.lang.String toString()
+
+
+
Overrides:
toString in class java.lang.Object
+
+
+
+
Returns:
the title of this docNodeData object, if any.
+ Otherwise the nodeID is returned.
+ This method is useful for displaying this docNodeData object as a
+ node in a JTree. Some meaningful displayable value is returned,
+ unlike getTitle() which returns a null if title is not set yet.
+
+
+
+
+
+show
+
+public java.lang.String show()
+
+
+
+
Returns:
the details contained in this NodeData object.
+ Useful for debugging purposes.
+
+
+
+
+
+showMeta
+
+public java.lang.String showMeta()
+
+
+
+
Returns:
a String representation of the contains of the
+ nodeMetadata list (useful for debugging purposes).
+Pair is a simple utility class to represent two associated String values.
+ For instance, a Metadata (name, value) pair to be displayed in either
+ SearchResultsDisplay or BrowseDisplay's metanames and metavalues
+ JLists. (These two classes can be found in org.greenstone.gs3client.)
+ A Comparator--like the one provided by org.greenstone.gs3client.Displays'
+ inner class MetadataComparator--is necessary to ensure that the "natural
+ ordering" of any List of metadata Pairs will be as required. This class
+ does not implement Comparable so that it may be used for other purposes
+ than storing ordered Metadata pairs, which is why using an external
+ Comparator to provide the sorting facility is more useful.
+
getElementValuesForAttr(org.w3c.dom.Element parentEl,
+ java.lang.String elName,
+ java.lang.String attrName)
+
+
+ Given an Element <parentEl>, finds all direct child elements called
+ <elName> that have an attribute named attrName:
+ <elName attrName=value>bodytext</elName>
+ This is particularly useful for extracting info for those cases where
+ elName=<displayItem> and where the attrName is "name".
+
+
+
+static org.w3c.dom.Element
+
getFirstChildElementCalled(org.w3c.dom.Element parent,
+ java.lang.String childElementName)
+
+
+ Method that returns the first child element of parent whose tagname is
+ childElementName.
+
+
+
+static org.w3c.dom.Element
+
getFirstDescElementCalled(org.w3c.dom.Element parent,
+ java.lang.String descElementName)
+
+
+ Method that returns the first descendant element of parent whose tagname
+ is descElementName.
+
+
+
+static java.util.Vector
+
getListElementsAsArray(org.w3c.dom.Element parent,
+ java.lang.String listElementName,
+ java.lang.String childElementName)
+
+
+ Given an xml element ('parent'), it looks through its direct children
+ to find the <listElementName> tag and extracts each child called
+ <childElementName> element from it.
Given an xml element ('parent'), it looks through its direct children
+ to find the <listElementName> tag and extracts each child called
+ <childElementName> element from it. These are all added into a Vector
+ which is returned.
+
+
+
Parameters:
parent - is the XML element from which the specified descendant
+ elements are identified and returned.
listElementName - is the name of the child element of parent that we
+ are looking for, whose child elements will be returned.
+
Returns:
a vector of Element items, all children <childelementName> of
+ the first <listElementName> child of parameter called parent.
Given an Element <parentEl>, finds all direct child elements called
+ <elName> that have an attribute named attrName:
+ <elName attrName=value>bodytext</elName>
+ This is particularly useful for extracting info for those cases where
+ elName=<displayItem> and where the attrName is "name".
+
+
+
Parameters:
parentEl - is the parent element whose children are searched
elName - is the name to search for among the child elements of parentEl
attrName - is the name of the attribute to look for in the child
+ element (of parentEl) whose tag name is elName.
+
Returns:
a Hashmap of all the (value, body) instances found.
+Static inner class QueryFormParam is a subclass of QueryFormData and
+ uniquely represents the data that can be contained in any <param>
+ tag of the xml response that's returned when a describe request is sent to
+ a Query Service. As such, a QueryFormParam can contain further
+ QueryFormData (<param> or <option> elements) which are stored
+ as subElements of this QueryFormParam.
+
+
+
+
+
+
+
+
+
+
+
+
+Nested Class Summary
+
+
+
+
+
+
Nested classes/interfaces inherited from class org.greenstone.gs3client.data.QueryFormData
QueryFormData.QueryFormParam(org.w3c.dom.Element param)
+
+
+ Constructor that creates a QueryFormParam object from the data
+ contained in a <param>element of a Query response XML message.
A <param> element in a Query response XML message can contain
+ children that are <param> or <option>.
+ subElements therefore stores an array of QueryFormData to represent
+ these.
+ <param> CAN (need not) contain <options>s and/or more
+ <param>s. If subElements is null, it obviously has no child
+ <param>s.
+
+Class QueryFormData represents the <param> and <option> elements
+ that can appear in a <paramList> tag in the xml response returned by
+ a describe request sent to *Query* Service (e.g. FieldQuery, TextQuery).Its
+ subclass QueryFormParam more fully represents the <param> elements, but
+ this class covers the data shared by <param> and <option> elements.
+
+
+
+
+
Author:
+
ak19
+
+
+
+
+
+
+
+
+
+
+Nested Class Summary
+
+
+
+static class
+
QueryFormData.QueryFormParam
+
+
+ Static inner class QueryFormParam is a subclass of QueryFormData and
+ uniquely represents the data that can be contained in any <param>
+ tag of the xml response that's returned when a describe request is sent to
+ a Query Service.
+
+
+
+
+
+
+
+
+Field Summary
+
+
+
+ java.lang.String
+
displayItem
+
+
+ DisplayItem text content of the parameter or option this
+ QueryFormData represents
+
+
+
+ java.lang.String
+
name
+
+
+ Name of the parameter or option this QueryFormData represents
+
+
+
+static java.lang.String
+
OCCURS_ATT
+
+
+ Constant for the "occurs" attribute name
+
+
+
+
+
+
+
+
+
+Constructor Summary
+
+
+
QueryFormData(org.w3c.dom.Element param)
+
+
+ Contructor to create a QueryFormData object from <param>
+ or <option> elements of a Query response XML message.
+
+
+
+
+
+
+
+
+
+Method Summary
+
+
+
+protected java.lang.String
+
extractDisplayItem(org.w3c.dom.Element param)
+
+
+ Given an element, extracts the text value from the first direct child
+ element that is a <displayItem> element and returns this.
+Static inner class Term represents a <term> XML element
+ (these are nested in a <termList>) - see manual p. 45:
+ <term name="str" numDocsMatched="int" freq="int" field="int" stem="int"/>
+ <equivTermList>
+ <term name="str" numDocsMatched="int" freq="int" />
+ <term name="str" numDocsMatched="int" freq="int" />
+ ...
+ </equivTermList>
+ </term>
+ Can import this class as import gs3client.QueryResponseData.TermData
+ and can then use it just as "TermData" (don't need fully qualified name).
+
QueryResponseData.TermData(org.w3c.dom.Element termTag)
+
+
+ Constructs a Term object to represent the <term> element passed
+ in here as an argument.
Constructs a Term object to represent the <term> element passed
+ in here as an argument. Given a <term></term> element, it
+ sets this object's members.
+
+Represents the data fields that may be present in a response
+ to a Query-process request. Specifically, this class keeps track of
+ all the DocumentNodes returned in response to a query request.
+ It inherits Map nodeIDsToNodes of (nodeID, NodeData ref) pairs which
+ maintains the NodeData object refs in order of their insertion into
+ the Map (LinkedHashMap).
+ !!! QueryResponseData will only store DocumentNodeData object refs in
+ the nodeIDsToNodes Map.
+ An object of this class can be reused after instatiation by calling
+ setResponseData() with a new query response XML message. This will
+ first call clear() to clear/release its references to all the old data.
+
+
+
+
+
Author:
+
ak19
+
+
+
+
+
+
+
+
+
+
+Nested Class Summary
+
+
+
+static class
+
QueryResponseData.TermData
+
+
+ Static inner class Term represents a <term> XML element
+ (these are nested in a <termList>) - see manual p.
+
+
+
+
+
+
+
+
+Field Summary
+
+
+
+protected java.util.HashMap
+
metadataList
+
+
+ Metadata of the query's response - not a documentNode's metadata!
clear()
+
+
+ Resets the internal data members of this QueryResponseData object of
+ their values so that this QueryResponseData can be reused for the
+ next Query response message.
setResponseData(org.w3c.dom.Element responseMessageTag)
+
+
+ Given the response to a query message (XML with root <message>
+ or <response> tag), a QueryResponseData object is created
+ to store all the document Identifiers and document data returned
+ as well as information about the terms that were searched on.
+
+
+
+ java.util.Vector
+
setStructureForDocs(org.w3c.dom.Element messageTag)
+
+
+ This method can be called after a DocumentStructureRetrieve request
+ (for the entire structure of all/many of its documents) has returned
+ a response.
Metadata of the query's response - not a documentNode's metadata!
+
+
+
+
+
+
+
+
+
+
+
+Constructor Detail
+
+
+
+
+QueryResponseData
+
+public QueryResponseData()
+
+
Default constructor
+
+
+
+
+
+
+
+
+
+Method Detail
+
+
+
+
+clear
+
+public void clear()
+
+
Resets the internal data members of this QueryResponseData object of
+ their values so that this QueryResponseData can be reused for the
+ next Query response message.
+
Given the response to a query message (XML with root <message>
+ or <response> tag), a QueryResponseData object is created
+ to store all the document Identifiers and document data returned
+ as well as information about the terms that were searched on.
+ Furthermore, metadata such as the number of Docs that matched and
+ were returned (if any such are present in the response-message)
+ are also stored.
+ It first performs a clear to empty its data members and then fills
+ them with the new Query response message's data.
+
Given an nodeID, returns the DocumentNodeData object with that nodeID
+ if any. Otherwise, null is returned.
+ Superclass has method getNodeForID that returns NodeData instead.
+ This is just a convenience method.
+
+
+
Parameters:
ID - is the nodeID of the DocumentNodeData to be returned.
+
Returns:
the DocumentNodeData object for the given ID or null if not
+ present.
an array of the DocumentNodeData objects of the documents
+ returned by the executed Query Response and stored in this
+ QueryResponseData object. I.e. the documentNodes of the documents in
+ the search results.
+ In cases of an error (such as not being able to connect to a collection
+ like Infomine) this method may return an empty array (length = 0)
+ if docIDsToDocNodes is empty!
+
+
+
+
+
+getDocumentNodeIDs
+
+public java.lang.String[] getDocumentNodeIDs()
+
+
+
+
Returns:
an array of the IDs of the list of documentNodes maintained
+ by this QueryResponseData object (the documentNodes of the documents'
+ in the search results).
+ In cases of an error (such as not being able to connect to collection
+ such as Infomine) this method may return an empty array (length = 0)
+ if docIDsToDocNodes is empty!
metadata of the query's response. This includes values such
+ as numDocsMatched, numDocsReturned, query. This does not return any
+ document's metadata!
This method can be called after a DocumentStructureRetrieve request
+ (for the entire structure of all/many of its documents) has returned
+ a response. Given the response message (XML) element, this method
+ attempts to set the document structure for all the documentNodeData
+ objects it has, using the nodeStructure tags in the
+ response-message-XML. But only those documentNodeData whose nodeIDs
+ are mentioned in the response-message-XML are actually set!
+ This method returns a null vector if the responseMessage XMl does not
+ contain any <documentNodeList> element with <documentNode>s
+ each with <nodeStructure> children.
+ Otherwise it returns a Vector of all the rootNodes of the list of
+ docNodes that this QueryResponseData object maintains.
+
+
+
+
+
+
+
+
+toString
+
+public java.lang.String toString()
+
+
+
Overrides:
toString in class java.lang.Object
+
+
+
+
Returns:
some summary info on how the search went. This may include
+ how many documents matched the query, and how many of them have been
+ returned. With mult-term queries, the frequencies of each separate
+ term is also returned for display.
+Represents the data in a response XML message that is returned as
+ either a Browse or Query (Search) request.
+ Subclasses therefore are BrowseResponseData and QueryResponseData.
+ This class maintains a Map of (nodeID, NodeData ref) pairs
+ representing the resulting <classifierNode>s and <documentNode>s
+ that can be returned when executing a SINGLE browse or query request.
+
+
+
+
+
Author:
+
ak19
+
+
+
+
+
+
+
+
+
+
+Field Summary
+
+
+
+protected java.util.Map
+
nodeIDsToNodes
+
+
+ map of (nodeIDs, references to associated NodeData) pairs,
+ stored in the order they are contained in the response XML messages
+ (the order in which data objects are parsed and created for them)
+
+
+
+
+
+
+
+
+
+Constructor Summary
+
+
+
ResponseData()
+
+
+ Default constructor, creates the nodeIDsToNodes map
+
+
+
+
+
+
+
+
+
+Method Summary
+
+
+
+ void
+
clear()
+
+
+ Clears/resets this ResponseData object of all data, so that it can be
+ reused to process future Browse and Query requests.
getNodeForID(java.lang.String ID)
+
+
+ Given an nodeID, returns the NodeData object with that nodeID,
+ if any.
+
+
+
+ void
+
setContentForDocs(org.w3c.dom.Element messageTag)
+
+
+ After a DocumentContentRetrieve request for one or more documents
+ has returned a response, this method - when given the response XML -
+ will set the nodeContents of each document in the response (as long
+ as those documents already have an associated DocumentNodeData
+ object instantiated, which should/would always be the case).
+
+
+
+ boolean
+
setMetadataForDocuments(org.w3c.dom.Element messageTag)
+
+
+ This method sets the metadata for one or even all <documentNode>
+ data objects contained in the Map nodeIDsToNodes, using the <message>
+ element parameter (which is returned upon a documentMetadataRetrieve
+ request.
+
+
+
+protected boolean
+
setMetadataForNodes(org.w3c.dom.Element messageTag,
+ java.lang.String NODE_ELEM)
+
+
+ This method can be called after a DocumentMetadataRetrieve request
+ has returned a response.
+
+
+
+abstract void
+
setResponseData(org.w3c.dom.Element responseMsgTag)
+
+
+ Subclasses must implement this method to parse the
+ <message><response></response></message>
+ that is returned upon executing a browse or query request.
map of (nodeIDs, references to associated NodeData) pairs,
+ stored in the order they are contained in the response XML messages
+ (the order in which data objects are parsed and created for them)
+
+
+
+
+
+
+
+
+
+
+
+Constructor Detail
+
+
+
+
+ResponseData
+
+public ResponseData()
+
+
Default constructor, creates the nodeIDsToNodes map
+
Subclasses must implement this method to parse the
+ <message><response></response></message>
+ that is returned upon executing a browse or query request.
+ At the end of this method, the Map nodeIDsToNodes will contain
+ any DocumentNodeData or ClassifierNodeData objects described
+ in the responseMsgTag.
+
+
+
Parameters:
responseMsgTag - the XMl response message Element whose data will
+ be parsed and stored in the ResponseData subclass
+
+
+
+
+
+clear
+
+public void clear()
+
+
Clears/resets this ResponseData object of all data, so that it can be
+ reused to process future Browse and Query requests. In this case, it
+ merely clears the internal Map nodeIDsToNodes. Subclasses may need to
+ clear other variables.
+
+
+
+
+
+
+
+
+getIDToNodeMapping
+
+public java.util.Map getIDToNodeMapping()
+
+
+
+
Returns:
the Map of mappings from nodeIDs to NodeData object references
Given an nodeID, returns the NodeData object with that nodeID,
+ if any. Otherwise, null is returned. Subclass might want to add
+ a different method that converts this to DocumentNodeData type.
+
+
+
Parameters:
ID - is the nodeID whose NodeData object is requested
After a DocumentContentRetrieve request for one or more documents
+ has returned a response, this method - when given the response XML -
+ will set the nodeContents of each document in the response (as long
+ as those documents already have an associated DocumentNodeData
+ object instantiated, which should/would always be the case).
+
+
+
Parameters:
messageTag - is the DocumentContentRetrieve XML response message
+ containing the document contents for one or more documentNodes
This method can be called after a DocumentMetadataRetrieve request
+ has returned a response. Given the response message (XML) element,
+ this method attempts to set the metadata for all the documentNodeData
+ objects it has, using the metadata tags in the response-message-XML.
+ This method returns false if the responseMessage XMl does not contain
+ any <documentNodeList> elements.
+
+
+
Parameters:
NODE_ELEM - can be either GSXML defined constant for
+ <ClassifierNode> or <DocumentNode>
messageTag - is the DocumentMetadataRetrieve XML response message
+ containing the metadata for one or more documentNodes/classifierNodes
+ as specified by NODE_ELEM
This method sets the metadata for one or even all <documentNode>
+ data objects contained in the Map nodeIDsToNodes, using the <message>
+ element parameter (which is returned upon a documentMetadataRetrieve
+ request. Metadata for <classifierNodes> are not set with this method.
+ It merely calls the setMetadataForDocuments(messageTag, tagName)
+ method to parse out data for the tagName=<documentNode>.
+
+
+
Parameters:
messageTag - is the DocumentMetadataRetrieve XML response message
+ containing the metadata for one or more documentNodes
CollectionData represents a Greenstone 3 collection and contains the data
+ stored in a <collection></collection> element returned from a
+ MessageRouter's desribe response XML and a Collection describe response XML.
Static inner class MetaData: can import it into other files as
+ "import gs3client.CollectionData.MetaData;"
+ In this way, can use it as if it were a regular class (a.o.t.
Only the name and type of a <service></service> element is
+ stored, since this is all the service data available inside a collection's
+ response message to a describe request.
Abstract superclass NodeData can represent either a the information in
+ a <classifierNode> (stored in a ClassifierNodeData object) or in a
+ <documentNode> (stored in a DocumentNodeData object).
Class QueryFormData represents the <param> and <option> elements
+ that can appear in a <paramList> tag in the xml response returned by
+ a describe request sent to *Query* Service (e.g.
Static inner class QueryFormParam is a subclass of QueryFormData and
+ uniquely represents the data that can be contained in any <param>
+ tag of the xml response that's returned when a describe request is sent to
+ a Query Service.
+Interface that defines the digital library methods that need to be
+ provided by a digital library that's going to be incorporated into the
+ Greenstone Java-Client, so that the client may be able to use/access
+ its functionality.
+
+ Note that the Strings returned by all defined methods -- with the exception
+ of getLanguage() -- represent Greenstone3 XML response messages, as defined
+ in the Greenstone3 manual.
+ These methods do not throw exceptions, but rather embed any error information
+ in the XML Strings returned, as is done in Greenstone3 XML response
+ messages.
+
+ The final 'A' of DigitalLibraryServicesAPIA stands for Access, as the
+ methods defined here are to give access to a digital library's repository.
+
+
+
+
+
Author:
+
ak19
+
+
+
+
+
+
+
+
+
+
+Nested Class Summary
+
+
+
+static class
+
DigitalLibraryServicesAPIA.CancelException
+
+
+ If there's a dialog, then the CancelException can be used to indicate
+ that the user cancelled out of it rather than having seen it through.
+
+
+
+
+
+
+
+
+Field Summary
+
+
+
+static java.io.File
+
propertiesFile
+
+
+ The properties file containing the initial digital library connection
+ settings which get displayed in the connection dialog fields
setLanguage(java.lang.String language)
+
+
+ Sets the preferred language (code) for metadata and other content to be
+ returned on request messages.
+
+
+
+
+
+
+
+
+
+
+
+Field Detail
+
+
+
+
+propertiesFile
+
+static final java.io.File propertiesFile
+
+
The properties file containing the initial digital library connection
+ settings which get displayed in the connection dialog fields
+
+
+
+
+
+
+
+
+
+
+
+Method Detail
+
+
+
+
+getDisplayName
+
+java.lang.String getDisplayName()
+
+
+
+
Returns:
the name of this digital library for displaying in the client
+
+
+
+
+
+getAssocFileBaseURL
+
+java.lang.String getAssocFileBaseURL()
+
+
+
+
Returns:
the overall directory path for associated files (not including
+ the document's nodeID/pid). This can be used to formulate the base url of
+ JEditorPane's HTML documents. If the documents from any digital library
+ do not contain relative paths, or otherwise deal with the resolution of
+ relative urls themselves, then return "" from here.
the directory path to the associated files of the given document
+ node. For instance, the base url of a JEditorPane's HTML documents can be
+ set to this.
+
+
+
+
+
+setLanguage
+
+void setLanguage(java.lang.String language)
+
+
Sets the preferred language (code) for metadata and other content to be
+ returned on request messages. If the preferred language is not available,
+ the implementation may choose to send English back instead, or failing
+ that, send the data in any other available language.
+
+
+
Parameters:
language - has to be a language code as recognised by Greenstone3
+ (the language codes used by W3C probably). E.g. "en" for English.
+
+
+
+
+
+getLanguage
+
+java.lang.String getLanguage()
+
+
Gets the language that's set as the preferred language.
+
+
+
+
Returns:
the language code as recognised by Greenstone3 (which are the
+ language codes used by W3C probably). E.g. "en" for English.
+
+
+
+
+
+describe
+
+java.lang.String describe()
+
+
+
+
Returns:
Greenstone3 XML describe response message with information
+ about collections contained and services (and any serviceRacks) supported
+ by the Digital library.
collection - is the name of the collection to be described
+
Returns:
Greenstone3 XML describe response message originating from a
+ collection, describing the collection (display items) as well as
+ listing any services supported specifically by the collection.
service - is the name of the collection's service to be described
+
Returns:
Greenstone3 XML describe response message originating from a
+ general (non-collection specific) service, describing the requested
+ service (for example with GS3 display items).
docIDs - is an array of document identifiers of documents whose
+ hierarchical structures are requested
+
Returns:
a String representing Greenstone3 DocumentMetadataRetrieve XML
+ containing the document structure of the documents indicated by docIDs:
+ this means all their descendents
docID - is the document identifier of the document whose hierarchical
+ structure is requested
+
Returns:
a String representing Greenstone3 DocumentMetadataRetrieve XML
+ containing the document structure of the document indicated by docID:
+ this means all its descendents
docIDs - is an array of document identifiers of documents whose
+ hierarchical structures are requested
+
Returns:
a String representing Greenstone3 DocumentMetadataRetrieve XML
+ containing a view of the document structure of the documents denoted by
+ docs where only the requested documents and their direct children are
+ returned.
docID - is an document identifier of the document whose hierarchical
+ structure is requested
+
Returns:
a String representing Greenstone3 DocumentMetadataRetrieve XML
+ containing a view of the document structure of the document denoted by
+ docID where only the document and its direct children are returned.
classifierID - is of the form CL# where the number (#) marks
+ out structured sections like CL1.1.3 or CL2
collection - is the name of the collection
service - is the name of the browse service (=ClassifierBrowse usually)
+
Returns:
a String representing Greenstone3 ClassifierBrowse XML
+ giving the entire *structure* of the classification denoted by
+ classifierID (including the structures of document descendents of
+ the classifier).
nodeIDs - is of the form CL#.# where the number (#) marks
+ out structured sections like CL2.1.3. NodeIDs are generally subsections
+ of top-level classifierNodes (CL#, e.g. CL3).
collection - is the name of the collection
service - is the name of the Browse's MetadataRetrieve service
+ (usually the browse service is ClassifierBrowse, in which case it always
+ has a retrieve service called ClassifierBrowseMetadataRetrieve)
+
Returns:
a String representing Greenstone3
+ ClassifierBrowseMetadataRetrieve XML giving all the metadata for
+ all the subclassifiers denoted by nodeIDs.
nameValParamsMap - is a Map of name and value pairs for all the
+ query field data values. The names match the field names that
+ describeCollectionService() would have returned for the query service.
collection - is the name of the collection
service - is the name of the query service
+ This method is only ever called when any of the services in the digital
+ library described themselves as type=query. Therefore any digital
+ libraries that have no query services, can just return emtpy message
+ strings (or even "") since this method will never be called on them
+ anyway.
+
Returns:
a String representing Greenstone3 XML for a query process
+ response returning the results for the query denoted by parameter
+ nameValParamsMap.
+FedoraServicesAPIA implements DigitalLibraryServicesAPIA for enabling the
+ Java-client to access a Fedora repository of Greenstone digital objects.
+ This is made possible by its use of the FedoraGS3.jar file's functionality,
+ as made available through the FedoraGS3Connection class.
+
+
+
+
+
Author:
+
ak19
+
+
+
+
+
+
+
+
+
+
+Nested Class Summary
+
+
+
+
+
+
Nested classes/interfaces inherited from interface org.greenstone.gs3client.dlservices.DigitalLibraryServicesAPIA
the directory path to the associated files of the given document
+ node. For instance, the base url of a JEditorPane's HTML documents can be
+ set to this.
Greenstone3 XML describe response message with information
+ about collections contained and services (and any serviceRacks) supported
+ by the Digital library.
docIDs - is an array of document identifiers of documents whose
+ hierarchical structures are requested
+
Returns:
a String representing Greenstone3 DocumentMetadataRetrieve XML
+ containing the document structure of the documents indicated by docIDs:
+ this means all their descendents
docID - is the document identifier of the document whose hierarchical
+ structure is requested
+
Returns:
a String representing Greenstone3 DocumentMetadataRetrieve XML
+ containing the document structure of the document indicated by docID:
+ this means all its descendents
docIDs - is an array of document identifiers of documents whose
+ hierarchical structures are requested
+
Returns:
a String representing Greenstone3 DocumentMetadataRetrieve XML
+ containing a view of the document structure of the documents denoted by
+ docs where only the requested documents and their direct children are
+ returned.
docID - is the document identifier of the document whose hierarchical
+ structure is requested
+
Returns:
a String representing Greenstone3 DocumentMetadataRetrieve XML
+ containing a view of the document structure of the document denoted by
+ docID where only the document and its direct children are returned.
classifierID - is of the form CL# where the number (#) marks
+ out structured sections like CL1.1.3 or CL2
collection - is the name of the collection
service - is the name of the browse service (=ClassifierBrowse usually)
+
Returns:
a String representing Greenstone3 ClassifierBrowse XML
+ giving the entire *structure* of the classification denoted by
+ classifierID (including the structures of document descendents of
+ the classifier).
nodeIDs - is of the form CL#.# where the number (#) marks
+ out structured sections like CL2.1.3. NodeIDs are generally subsections
+ of top-level classifierNodes (CL#, e.g. CL3).
collection - is the name of the collection
service - is the name of the Browse's MetadataRetrieve service
+ (usually the browse service is ClassifierBrowse, in which case it always
+ has a retrieve service called ClassifierBrowseMetadataRetrieve)
+
Returns:
a String representing Greenstone3
+ ClassifierBrowseMetadataRetrieve XML giving all the metadata for
+ all the subclassifiers denoted by nodeIDs.
query in class org.greenstone.fedora.services.FedoraGS3Connection
+
+
+
Parameters:
nameValParamsMap - is a Map of name and value pairs for all the
+ query field data values. The names match the field names that
+ describeCollectionService() would have returned for the query service.
collection - is the name of the collection
service - is the name of the query service
+ This method is only ever called when any of the services in the digital
+ library described themselves as type=query. Therefore any digital
+ libraries that have no query services, can just return emtpy message
+ strings (or even "") since this method will never be called on them
+ anyway.
+
Returns:
a String representing Greenstone3 XML for a query process
+ response returning the results for the query denoted by parameter
+ nameValParamsMap.
+GS3ServicesAPIA does two things:
+ - it implements DigitalLibraryServicesAPIA for enabling the Java-client
+ to access Greenstone's repository of collections and documents. It
+ makes this possible through use of Greenstone 3's web services.
+ - it inherits from GS3WebServicesQBRAPI, which means it inherits all the
+ methods that deal with invoking the Greenstone 3 web services
+ functionality (through use of Apache Axis' Service and Call objects).
+ It therefore provides an equivalent method to each Greenstone 3 web
+ service operation, even if some of these web service operations are
+ never called by the Java-client and therefore not prescribed by the
+ DigitalLibraryServicesAPIA interface.
+
+
+
+
+
Author:
+
ak19
+
+
+
+
+
+
+
+
+
+
+Nested Class Summary
+
+
+
+
+
+
Nested classes/interfaces inherited from interface org.greenstone.gs3client.dlservices.DigitalLibraryServicesAPIA
GS3ServicesAPIA()
+
+
+ Displays a dialog to get user input for the location of the Greenstone 3
+ web services' WSDL file
+
+
+
GS3ServicesAPIA(java.lang.String wsdlURLName)
+
+
+ GS3ServicesAPIA constructor, which, given the url to the wsdl file,
+ finds either service and port or the service's endpoint of the GS3 Web
+ Services and instantiates the associated Service and Call objects.
+
+
+
+
+
+
+
+
+
+Method Summary
+
+
+
+ java.lang.String
+
describe()
+
+
+ Part of the GS3 Java-Client's DigitalLibraryServicesAPIA interface
+ contract
+
+
+
+ java.lang.String
+
describeCollection(java.lang.String collection)
+
+
+ Part of the GS3 Java-Client's DigitalLibraryServicesAPIA interface
+ contract.
+
+
+
+ java.lang.String
+
describeCollectionService(java.lang.String collection,
+ java.lang.String service)
+
+
+ Part of the GS3 Java-Client's DigitalLibraryServicesAPIA interface
+ contract.
+
+
+
+ java.lang.String
+
describeService(java.lang.String service)
+
+
+ Part of the GS3 Java-Client's DigitalLibraryServicesAPIA interface
+ contract.
+
+
+
+ java.lang.String
+
getAssocFileBaseURL()
+
+
+ Part of the GS3 Java-Client's DigitalLibraryServicesAPIA interface
+ contract.
GS3ServicesAPIA constructor, which, given the url to the wsdl file,
+ finds either service and port or the service's endpoint of the GS3 Web
+ Services and instantiates the associated Service and Call objects.
+
+
+
Parameters:
wsdlURLName - - location of the WSDL for Greenstone 3's
+ web services
+
Part of the GS3 Java-Client's DigitalLibraryServicesAPIA interface
+ contract.
+ Sets the preferred language (code) for metadata and other content to be
+ returned on request messages. If the preferred language is not available,
+ the implementation may choose to send English back instead, or failing
+ that, send the data in any other available language.
+
the overall directory path for associated files (not including
+ the document's nodeID/pid). This can be used to *formulate* the base url
+ of JEditorPane's HTML documents. If the documents from any digital library
+ do not contain relative paths, or otherwise deal with the resolution of
+ relative urls themselves, then return "" from here.
the directory path to the associated files of the given document
+ node. For instance, the base url of a JEditorPane's HTML documents can be
+ set to this.
+
+
+
+
+
+describe
+
+public java.lang.String describe()
+
+
Part of the GS3 Java-Client's DigitalLibraryServicesAPIA interface
+ contract
+
Greenstone3 XML describe response message originating from
+ the Message Router, describing the Collections, ServiceRacks
+ and Services supported by the Message Router for all collections.
collection - is the name of the collection to be described.
+
Returns:
Greenstone3 XML describe response message originating from a
+ collection, describing the collection (display items) as well as
+ listing any services supported specifically by the collection.
service - is the name of the collection's service to be described.
+
Returns:
Greenstone3 XML describe response message originating from a
+ general (non-collection specific) service, describing the requested
+ service (for example with GS3 display items).
docIDs - is an array of document identifiers of documents whose
+ hierarchical structures are requested
+
Returns:
a String representing Greenstone3 DocumentMetadataRetrieve XML
+ containing the document structure of the documents indicated by docIDs:
+ this means all their descendants
docID - is the document identifier of the document whose hierarchical
+ structure is requested
+
Returns:
a String representing Greenstone3 DocumentMetadataRetrieve XML
+ containing the document structure of the document indicated by docID:
+ this means all its descendants
docIDs - is an array of document identifiers of documents whose
+ hierarchical structures are requested
+
Returns:
a String representing Greenstone3 DocumentMetadataRetrieve XML
+ containing a view of the document structure of the documents denoted by
+ docs where only the requested documents and their direct children are
+ returned.
docID - is the document identifier of the document whose hierarchical
+ structure is requested
+
Returns:
a String representing Greenstone3 DocumentMetadataRetrieve XML
+ containing a view of the document structure of the document denoted by
+ docID where only the document and its direct children are returned.
classifierID - is of the form CL# where the number (#) marks
+ out structured sections like CL1.1.3 or CL2
collection - is the name of the collection
service - is the name of the browse service (=ClassifierBrowse usually)
+
Returns:
a String representing Greenstone3 ClassifierBrowse XML
+ giving the entire *structure* of the classification denoted by
+ classifierID (including the structures of document descendants of
+ the classifier).
nodeIDs - is of the form CL#.# where the number (#) marks
+ out structured sections like CL2.1.3. NodeIDs are generally subsections
+ of top-level classifierNodes (CL#, e.g. CL3).
collection - is the name of the collection
service - is the name of the Browse's MetadataRetrieve service
+ (usually the browse service is ClassifierBrowse, in which case it always
+ has a retrieve service called ClassifierBrowseMetadataRetrieve)
+
Returns:
a String representing Greenstone3
+ ClassifierBrowseMetadataRetrieve XML giving all the metadata for
+ all the subclassifiers denoted by nodeIDs.
nameValParamsMap - is a Map of name and value pairs for all the
+ query field data values. The names match the field names that
+ describeCollectionService() would have returned for the query service.
collection - is the name of the collection
service - is the name of the query service
+
Returns:
a String representing Greenstone3 XML for a query process
+ response returning the results for the query denoted by parameter
+ nameValParamsMap.
+GS3WebServicesQBRAPI deals with invoking the Greenstone 3 web services
+ functionality through use of Apache Axis' Service and Call objects.
+ Each Greenstone 3 web service operation has an equivalent method here
+ that invokes it, even if some of these web service operations are never
+ called by the Java-client and therefore not prescribed by the
+ DigitalLibraryServicesAPIA interface.
+
+
+
+
+
Author:
+
ak19
+
+
+
+
+
+
+
+
+
+
+Field Summary
+
+
+
+protected org.apache.axis.client.Call
+
call
+
+
+ Axis Call object for invoking Greenstone 3's WebServices
+ using its WSDL file
+
+
+
+static java.lang.String
+
defaultWsdlURL
+
+
+ The value that the input dialog's field wsdlURL will default
+ to if there is (no properties file and) no wsdlURL property
namespace
+
+
+ namespace of Greenstone 3's WebServices, as given in the WSDL file
+
+
+
+protected java.lang.String
+
portName
+
+
+ port Name of Greenstone 3's WebServices, as given in the WSDL file
+
+
+
+protected org.apache.axis.client.Service
+
service
+
+
+ Axis Service object for connecting to invoking Greenstone 3's WebServices
+ using its WSDL file
+
+
+
+protected java.lang.String
+
serviceName
+
+
+ service Name of Greenstone 3's WebServices, as given in the WSDL file
+
+
+
+protected java.lang.String
+
wsdlURLName
+
+
+ Url of the Greenstone 3 WebServices' WSDL
+
+
+
+
+
+
+
+
+
+Constructor Summary
+
+
+
GS3WebServicesQBRAPI(java.lang.String wsdlURLName)
+
+
+ GS3ServicesAPIA constructor, that given the url to the wsdl file, finds
+ either service and port or the service's endpoint of the GS3 Web Services
+ and instantiates the associated Service and Call objects.
basicQuery(java.lang.String collection,
+ java.lang.String lang,
+ java.lang.String query)
+
+
+ This method is used to perform the most basic query:
+ it assumes defaults for all other parameters and provides only
+ the query string.
+
+
+
+ java.lang.String
+
browse(java.lang.String collection,
+ java.lang.String browseService,
+ java.lang.String lang,
+ java.lang.String[] classifierNodeIDs,
+ java.lang.String[] structureParams)
+
+
+ To send a browse request for specific parts of a classifier node
+ (children, ancestors, descendants).
+
+
+
+ java.lang.String
+
browseDescendants(java.lang.String collection,
+ java.lang.String browseService,
+ java.lang.String lang,
+ java.lang.String[] classifierNodeIDs)
+
+
+ To send a browse request for all the descendants of a classifier node.
+
+
+
+ java.lang.String
+
describe(java.lang.String lang,
+ java.lang.String subsetOption)
+
+
+ Describe request message sent to the Message Router.
+
+
+
+ java.lang.String
+
describeCollection(java.lang.String collection,
+ java.lang.String lang,
+ java.lang.String subsetOption)
+
+
+ For sending Describe messages to Collections.
+
+
+
+ java.lang.String
+
describeCollectionService(java.lang.String collection,
+ java.lang.String service,
+ java.lang.String lang,
+ java.lang.String subsetOption)
+
+
+ For sending a describe message to a Collection's Service.
+
+
+
+ java.lang.String
+
describeService(java.lang.String service,
+ java.lang.String lang,
+ java.lang.String subsetOption)
+
+
+ For sending a describe message to a Service hosted by the Message Router
+ (no collection).
+
+
+
+ java.lang.String
+
describeServiceCluster(java.lang.String serviceCluster,
+ java.lang.String lang,
+ java.lang.String subsetOption)
+
+
+ For sending Describe messages to ServiceClusters.
+
+
+
+protected static java.util.Vector
+
getElementsByTagNameNS(org.w3c.dom.Element parentElement,
+ java.lang.String namespacePrefix,
+ java.lang.String localName)
+
+
+ Static method that gets all the descendant elements of a portion of XMl
+ within the same namespace as indicated by parameters namespacePrefix and
+ localName.
+
+
+
+protected static void
+
getElementsByTagNameNS(org.w3c.dom.Element parentElement,
+ java.lang.String namespacePrefix,
+ java.lang.String localName,
+ java.util.Vector v)
+
+
+ At method's end, Vector v will contain those descendent elements of
+ parentElement where the element's name is prefixed by namespacePrefix
+ and suffixed by localName.
retrieveAllBrowseMetadata(java.lang.String collection,
+ java.lang.String categoryName,
+ java.lang.String lang,
+ java.lang.String[] nodeIDs)
+
+
+ Retrieve all classification Metadata for browsing (sent to the
+ ClassifierBrowseMetadataRetrieve service).
+
+
+
+ java.lang.String
+
retrieveAllDocumentMetadata(java.lang.String collection,
+ java.lang.String lang,
+ java.lang.String[] docNodeIDs)
+
+
+ (c) DocumentMetadataRetrieve request sent to a collection's
+ DocumentMetadataRetrieve service to retrieve all of a document's metadata.
+
+
+
+ java.lang.String
+
retrieveBrowseMetadata(java.lang.String collection,
+ java.lang.String categoryName,
+ java.lang.String lang,
+ java.lang.String[] nodeIDs,
+ java.lang.String[] metaNames)
+
+
+ ClassifierBrowseMetadataRetrieve service to retrieve some specific
+ metadata values of a document.
+
+
+
+ java.lang.String
+
retrieveDocumentContent(java.lang.String collection,
+ java.lang.String lang,
+ java.lang.String[] docNodeIDs)
+
+
+ (a) DocumentContentRetrieve request sent to a collection's
+ DocumentContentRetrieve service (p.48)
+
+
+
+ java.lang.String
+
retrieveDocumentMetadata(java.lang.String collection,
+ java.lang.String lang,
+ java.lang.String[] docNodeIDs,
+ java.lang.String[] metaNames)
+
+
+ DocumentMetadataRetrieve service to retrieve some specific
+ metadata values of a document.
+
+
+
+ java.lang.String
+
retrieveDocumentStructure(java.lang.String collection,
+ java.lang.String lang,
+ java.lang.String[] docNodeIDs,
+ java.lang.String[] structure,
+ java.lang.String[] info)
+
+
+ DocumentStructureRetrieve request sent to a collection's
+ DocumentStructureRetrieve service (manual pp.48, 49) to retrieve
+ the specified part of the document's structure.
+
+
+
+ java.lang.String
+
retrieveEntireDocumentStructure(java.lang.String collection,
+ java.lang.String lang,
+ java.lang.String[] docNodeIDs)
+
+
+ (b) DocumentStructureRetrieve request sent to a collection's
+ DocumentStructureRetrieve service (manual pp.48, 49) to retrieve
+ the entire document structure.
GS3ServicesAPIA constructor, that given the url to the wsdl file, finds
+ either service and port or the service's endpoint of the GS3 Web Services
+ and instantiates the associated Service and Call objects.
+
+
+
Parameters:
wsdlURLName - - location of the WSDL URL for Greenstone 3's
+ web services
+
Static method that gets all the descendant elements of a portion of XMl
+ within the same namespace as indicated by parameters namespacePrefix and
+ localName.
+
+
+
Parameters:
namespacePrefix - - a String for the namespacePrefix to search for.
+ This can be the wildcard * for any/allnamespaces.
localName - - the suffix of the namespaceprefix. For instance, localName
+ "soap" will return elements that have the tag wsdlsoap.
parentElement - - the XML element whose descendants will be returned if
+ their element names conform to the specified namespacePrefix and localName
+ parameters.
+
Returns:
a Vector of all descendant elements whose namespace-qualfied tag
+ names are as specified by the parameters namespacePrefix and localName.
+ Had to implement my own getElementsByTagNameNS() method since the original
+ Element.getElementsByTagNameNS() does not work for Elements created using
+ DOM level 1 (such as with document.createElement()). See the API for Element.
+ This method is slightly more generic, as it returns all descendent elements
+ in a vector where the element name is prefixed by "namespacePrefix" (which
+ need not be a namespace uri at all) and is suffixed by an equally arbitrary
+ String called localName.
+ If "*" is passed instead of namespacePrefix, this method will ignore any
+ prefixes and check only for element names that end on the suffix localName.
+
+ Old versions of this method had all the same functionality in one method,
+ but it was not so optimised (several if-statement checks would have been executed an unnecessary
+ number of times. This (current) version is split into 3 methods: this one
+ and two helper functions that deal with the case where namespacePrefix can
+ be anything and where it is particularly specified.
Recursive method.
+ At method's end, Vector v will contain those descendent elements of
+ parentElement where the element's name is suffixed by/ends with parameter
+ localName.
+ Related to local method getElementsByTagNameNS(). Deals with the case
+ where any and all (namespace)Prefix of an element is accepted, but where
+ an element name's suffix should match with the given localName.
+
+
+
Parameters:
parentElement - us the XML element whose descendants are to be
+ retrieved by the given TagNameSuffix.
localName - is the tagName suffix to retrieve the descendants of
+ parentElement by.
v - is a Vector of all the previously retrieved elements whose tag
+ names are suffixed by localName. This Vector is appended to by recursive
+ calls to this method.
At method's end, Vector v will contain those descendent elements of
+ parentElement where the element's name is prefixed by namespacePrefix
+ and suffixed by localName.
+ Related to local method getElementsByTagNameNS(). Deals with the case
+ where a particular (namespace)Prefix of an element and suffix (localname)
+ are given and an element's name should match both prefix and suffix.
+
+
+
Parameters:
parentElement - is the XML element whose descendants are to be
+ retrieved by the given TagNameSuffix.
namespacePrefix - is the namespace prefix to look for in the
+ descendants of parentElement that will be collected in Vector v.
localName - is the tagName suffix to look for in the descendants of
+ parentElement that will be collected in Vector v.
v - is a Vector of all the previously retrieved elements whose tag
+ names are prefixed by namespacePrefix and suffixed by localName.
+ This Vector is appended to by recursive calls to this method.
+
+
+
+
+
+getNamespace
+
+public java.lang.String getNamespace()
+
+
+
+
Returns:
the namespace of the wsdl file.
+
+
+
+
+
+getService
+
+public java.lang.String getService()
+
+
+
+
Returns:
the web service's serviceName without the namespace
Describe request message sent to the Message Router.
+
+
+
Parameters:
lang - is the language of the display content in the response
subsetOption - is the requested list of items to return in the response
+ For the Message Router this can be collectionList, serviceClusterList,
+ serviceList, siteList
For executing a (process-type message) query-type service.
+
+
+
Parameters:
collection - is the name of the Collection whose query service this
+ query-process request is sent to. If "", then the Message Router is assumed.
service - is the name of the Query Service (of that collection) to
+ which this request is sent.
lang - is the language of the display content in the response
nameToValsMap - is a Map of the (fieldname, value) pairs for the
+ parameters of the query. The field names should be those recognised by
+ Greenstone 3. That is, the names must exist for the (Collection-)Service Query that this
+ message is sent To (as given in 'to' argument).
+ For names of arguments,
This method is used to perform the most basic query:
+ it assumes defaults for all other parameters and provides only
+ the query string. It is built on top of a TextQuery.
+
+
+
Parameters:
collection - is the Greenstone collection to be searched
lang - is the preferred language of the display content in
+ the response to be returned.
query - is the string to be sought in the Greenstone collection
+
Returns:
a Greenstone 3 XML response message for the query specifying
+ the search results.
(b) DocumentStructureRetrieve request sent to a collection's
+ DocumentStructureRetrieve service (manual pp.48, 49) to retrieve
+ the entire document structure.
+
+
+
Parameters:
collection - is the name of the Collection whose
+ DocumentStructureRetrieve is requested
lang - is the language of the display content in the response
docNodeIDs - is the list of documentNodeIDs for which the
+ entire structure ought to be retrieved.
DocumentStructureRetrieve request sent to a collection's
+ DocumentStructureRetrieve service (manual pp.48, 49) to retrieve
+ the specified part of the document's structure.
+
+
+
Parameters:
collection - is the name of the Collection whose
+ DocumentStructureRetrieve is requested
lang - is the language of the display content in the response
docNodeIDs - is the list of documentNodeIDs for which the
+ structure ought to be retrieved.
structure - specifies what structure information needs to
+ be retrieved. The values can be one or more of ancestors, parent,
+ siblings, children, descendents (NOTE SPELLING), entire.
info - - for specifying extra information to be retrieved.
+ Possible values for info parameters are numSiblings, siblingPosition,
+ numChildren.
To send a browse request for all the descendants of a classifier node.
+ Useful for getting the entire structure of a top-level
+ <classificationNode>.
+
+
+
Parameters:
collection - is the name of the Collection whose browse Classifier
+ Browse Service is called
browseService - is the name of the (Classifier) Browse Service (of
+ the given collection) to which this request message is sent.
lang - is the language of the display content in the response
classifierNodeIDs - is an array of classifierNodeIDs for which the
+ structures ought to be retrieved.
To send a browse request for specific parts of a classifier node
+ (children, ancestors, descendants). Useful for getting specific parts
+ of the structure of a top-level <classificationNode>.
+
+
+
Parameters:
collection - is the name of the Collection whose browse Classifier
+ Browse Service is called
browseService - is the name of the (Classifier) Browse Service (of
+ the given collection) to which this request message is sent.
lang - is the language of the display content in the response
classifierNodeIDs - is the list of classifierNodeIDs for which the
+ structure ought to be retrieved.
structureParams - the list of parameters indicating what structure
+ information is requested. Accepted values are ancestors, parent, siblings,
+ children, descendants.
Interface that defines the digital library methods that need to be
+ provided by a digital library that's going to be incorporated into the
+ Greenstone Java-Client, so that the client may be able to use/access
+ its functionality.
GS3ServicesAPIA does two things:
+ - it implements DigitalLibraryServicesAPIA for enabling the Java-client
+ to access Greenstone's repository of collections and documents.
Handles rightclicks on a treeview of documentNodeData objects by showing
+ the popupMenu with associated files that, when selected, can be displayed
+ in the htmlPane.
+A beginning to the AdminSOAPServer class which will contain management/admin
+ related web services such as adding new documents, creating, building and
+ importing collections and configuring Greenstone modules.
+
+ NOTE: to run this class, the folder containing this web service class'
+ properties helpFile should be on the classpath.
+
+
+
+
+
+
+
+
+
+
+
+
+Field Summary
+
+
+
+protected org.greenstone.gsdl3.util.XMLConverter
+
converter
+
+
+ A converter class to parse XML and create Docs
mr
+
+
+ Message Router object to pass requests messages to and which
+ will process them.
+
+
+
+protected static java.util.Properties
+
properties
+
+
+ Properties map with mappings from methodname to help
+ description string
+
+
+
+protected java.lang.String
+
site_name
+
+
+ site_name the MessageRouter works with, here set to "localsite"
+
+
+
+
+
+
+
+
+
+Constructor Summary
+
+
+
AdminSOAPServer()
+
+
+ Constructor that initializes the web services' MessageRouter object
+ Reads from GlobalProperties to get gsdl3_home and set the sitename.
+
+
+
+
+
+
+
+
+
+Method Summary
+
+
+
+ java.lang.String
+
activate(java.lang.String systemModuleType,
+ java.lang.String systemModuleName)
+
+
+ Sends a (re-)activate system-type message to activate a Greenstone module.
+
+
+
+ java.lang.String
+
deactivate(java.lang.String systemModuleType,
+ java.lang.String systemModuleName)
+
+
+ Sends a deactivate system-type message to activate a Greenstone module.
+
+
+
+protected java.lang.String
+
error(java.lang.String errorMessage)
+
+
+ Creates a String response message to represent an XML error response
+ message using the error specified in the message parameter.
+
+
+
+ java.lang.String
+
format(java.lang.String collection,
+ java.lang.String service,
+ java.lang.String language)
+
+
+ Sends a format-type message to a Service containing format (Greenstone
+ Format, GSF) XSLT statements to specify how a collection looks.
processInternal(org.w3c.dom.Element message)
+
+
+ Called by most other methods in order to send the constructed message
+ to the Greenstone's MessageRouter, intercept the response and return it.
+
+
+
+ java.lang.String
+
reconfigure(java.lang.String subset)
+
+
+ Sends a configure system-type message to configure the Message Router.
+
+
+
+ java.lang.String
+
reconfigureMessageRouter()
+
+
+ Sends a configure system-type message to configure all of the Message Router.
+
+
+
+ java.lang.String
+
status(java.lang.String to,
+ java.lang.String language,
+ java.lang.String pid)
+
+
+ Sends a status-type message to poll the status of a process that was
+ initiated but which may not yet have terminated.
Sends a configure system-type message to configure the Message Router.
+
+
+
Parameters:
subset - - the particular subset of the module which is to be
+ reconfigured. For a collection/serviceRack it can be metadataList,
+ serviceList. For the MessageRouter this can be siteList, collectionList,
+ clusterList, serviceList
For sending system-type messages.
+ For parameter type=configure, the subset value is set (or "").
+ For parameter type=(de)activate, the systemModuleName and systemModuleType
+ are set.
+
+
+
Parameters:
type - - one of GSXML.SYSTEM_TYPE_CONFIGURE,
+ GSXML.SYSTEM_TYPE_ACTIVATE, GSXML.SYSTEM_TYPE_DEACTIVATE
+ (configure, activate or deactivate, respectively).
subset - - for system type configure, this can specify the To module's
+ subset that needs to be reconfigured.
systemModuleName - - for system type (de)activate, this specifies the
+ name of the module to be (de)activated.
systemModuleType - - for system type (de)activate, this specifies the
+ type of the module to be (de)activated. For instance, this may be
+ site or collection.
Creates a String response message to represent an XML error response
+ message using the error specified in the message parameter. A String is
+ created because this method ensures that a response message is reliably
+ constructed (no exceptions are thrown) that can be sent to clients.
+
+
+
Parameters:
errorMessage - - the errormessage to be conveyed
+
Returns:
an XML response message containing an GS3 error element.
+
+
+
+
+
+help
+
+public static java.lang.String help()
+
+
+
+
Returns:
a help string for listing all the web service methods.
+Class that provides the basic Query, Browse and Retrieve (QBR) web service
+ operations for Greenstone 3.
+ It contains a MessageRouter that carries out all the tasks by calling the
+ appropriate Greenstone functionality for each request message passed to it,
+ and returning a response message.
+
+ All response messages are returned from the MessageRouter to clients invoking
+ the web services. All return values are strings that represent XML messages.
+
+ Method help() reads from the file QBRWebServicesHelp.properties to list the web
+ service operations available. Method helpWithMethod(String methodName)
+ reads from the same file to display a description of the requested operation.
+ (These method descriptions are mostly the same as those in the Javadoc
+ comments.)
+
+ NOTE: to run this class, the folder containing this web service class'
+ properties helpFile should be on the classpath.
+
site_name
+
+
+ site_name the MessageRouter works with, here set to "localsite"
+
+
+
+
+
+
+
+
+
+Constructor Summary
+
+
+
QBRSOAPServer()
+
+
+ Constructor that initializes the web services' MessageRouter object
+ Reads from GlobalProperties to get gsdl3_home and set the sitename.
+
+
+
+
+
+
+
+
+
+Method Summary
+
+
+
+ java.lang.String
+
basicQuery(java.lang.String collection,
+ java.lang.String lang,
+ java.lang.String query)
+
+
+ This method is used to perform the most basic query:
+ it assumes defaults for all other parameters and provides only
+ the query string.
+
+
+
+ java.lang.String
+
browse(java.lang.String collection,
+ java.lang.String browseService,
+ java.lang.String lang,
+ java.lang.String[] classifierNodeIDs,
+ java.lang.String[] structureParams)
+
+
+ To send a browse request for specific parts of a classifier node
+ (children, ancestors, descendants).
+
+
+
+ java.lang.String
+
browseDescendants(java.lang.String collection,
+ java.lang.String browseService,
+ java.lang.String lang,
+ java.lang.String[] classifierNodeIDs)
+
+
+ To send a browse request for all the descendants of a classifier node.
+
+
+
+ java.lang.String
+
describe(java.lang.String lang,
+ java.lang.String subsetOption)
+
+
+ Sends a describe message to the MessageRouter.
+
+
+
+protected java.lang.String
+
describe(java.lang.String to,
+ java.lang.String lang,
+ java.lang.String subsetOption,
+ java.lang.String validSubsetOptions)
+
+
+ For sending a describe message.
+
+
+
+ java.lang.String
+
describeCollection(java.lang.String collection,
+ java.lang.String lang,
+ java.lang.String subsetOption)
+
+
+ For sending Describe messages to Collections.
+
+
+
+ java.lang.String
+
describeCollectionService(java.lang.String collection,
+ java.lang.String service,
+ java.lang.String lang,
+ java.lang.String subsetOption)
+
+
+ For sending a describe message to a Collection's Service.
+
+
+
+ java.lang.String
+
describeService(java.lang.String service,
+ java.lang.String lang,
+ java.lang.String subsetOption)
+
+
+ For sending a describe message to a Service hosted by the Message Router
+ (no collection).
+
+
+
+ java.lang.String
+
describeServiceCluster(java.lang.String serviceCluster,
+ java.lang.String lang,
+ java.lang.String subsetOption)
+
+
+ For sending Describe messages to ServiceClusters.
+
+
+
+protected java.lang.String
+
error(java.lang.String errorMessage)
+
+
+ Creates a String response message to represent an XML error response
+ message using the error specified in the message parameter.
metadataRetrieve(java.lang.String to,
+ java.lang.String lang,
+ java.lang.String[] nodeIDs,
+ java.lang.String[] metaNames,
+ java.lang.String NODE_ELEM)
+
+
+ Performs a metadata retrieve for documents and (browse) classification
+ hierarchies.
+
+
+
+protected java.lang.String
+
processInternal(org.w3c.dom.Element message)
+
+
+ Called by most other methods in order to send the constructed message
+ to the Greenstone's MessageRouter, intercept the response and return it.
retrieveAllBrowseMetadata(java.lang.String collection,
+ java.lang.String categoryName,
+ java.lang.String lang,
+ java.lang.String[] nodeIDs)
+
+
+ Retrieve all classification Metadata for browsing (sent to the
+ ClassifierBrowseMetadataRetrieve service).
+
+
+
+ java.lang.String
+
retrieveAllDocumentMetadata(java.lang.String collection,
+ java.lang.String lang,
+ java.lang.String[] docNodeIDs)
+
+
+ DocumentMetadataRetrieve request sent to a collection's
+ DocumentMetadataRetrieve service to retrieve all of a document's metadata.
+
+
+
+ java.lang.String
+
retrieveBrowseMetadata(java.lang.String collection,
+ java.lang.String categoryName,
+ java.lang.String lang,
+ java.lang.String[] nodeIDs,
+ java.lang.String[] metaNames)
+
+
+ ClassifierBrowseMetadataRetrieve service to retrieve some specific
+ metadata values of a document.
+
+
+
+ java.lang.String
+
retrieveDocumentContent(java.lang.String collection,
+ java.lang.String lang,
+ java.lang.String[] docNodeIDs)
+
+
+ DocumentContentRetrieve request sent to a collection's
+ DocumentContentRetrieve service (see manual, p.48)
+
+
+
+ java.lang.String
+
retrieveDocumentMetadata(java.lang.String collection,
+ java.lang.String lang,
+ java.lang.String[] docNodeIDs,
+ java.lang.String[] metaNames)
+
+
+ DocumentMetadataRetrieve service to retrieve some specific
+ metadata values of a document.
+
+
+
+ java.lang.String
+
retrieveDocumentStructure(java.lang.String collection,
+ java.lang.String lang,
+ java.lang.String[] docNodeIDs,
+ java.lang.String[] structure,
+ java.lang.String[] info)
+
+
+ DocumentStructureRetrieve request sent to a collection's
+ DocumentStructureRetrieve service (manual pp.48, 49) to retrieve
+ the specified part of the document's structure.
+
+
+
+ java.lang.String
+
retrieveEntireDocumentStructure(java.lang.String collection,
+ java.lang.String lang,
+ java.lang.String[] docNodeIDs)
+
+
+ DocumentStructureRetrieve request sent to a collection's
+ DocumentStructureRetrieve service (manual pp.48, 49) to retrieve
+ the entire document structure.
lang - is the language of the display content in the response.
subsetOption - are the requested list of items to return in the
+ response. For the Message Router this can be collectionList,
+ serviceClusterList, serviceList, siteList
For sending a describe message.
+ If public, this method would give full access: a describe message that
+ lets the user specify all the details of who the receiver is, and what
+ details are requested.
+
+
+
Parameters:
to - - the Greenstone module (MessageRouter, Collection,
+ ServiceCluster or (Collection-)Service to send this describe message to.
+ (The module asked to describe itself.)
lang - - the language of the display content in the response.
subsetOption - - the set of elements of the describe response that
+ are requested. These vary depending on the GS3 module asked to describe
+ itself.
validSubsetOptions - - the list of subsetOptions that are allowed
+ for the module this describe message is sent to. Parameter subsetOption
+ has to be among the list of validSubsetOptions.
For executing a (process-type message) query-type service.
+
+
+
Parameters:
collection - is the name of the Collection whose query service this
+ query-process request is sent to. If "", then the Message Router is assumed.
service - is the name of the Query Service (of that collection) to
+ which this request is sent.
lang - is the language of the display content in the response
nameToValsMap - is a Map of the (fieldname, value) pairs for the
+ parameters of the query. The field names should be those recognised by
+ Greenstone 3. That is, the names must exist for the (Collection-)Service Query that this
+ message is sent To (as given in 'to' argument).
+ For names of Greenstone-accepted arguments,
This method is used to perform the most basic query:
+ it assumes defaults for all other parameters and provides only
+ the query string. It is built on top of a TextQuery.
+
+
+
Parameters:
collection - is the Greenstone collection to be searched
lang - is the preferred language of the display content in
+ the response to be returned.
query - is the string to be sought in the Greenstone collection
+
Returns:
a Greenstone 3 XML response message for the query specifying
+ the search results.
DocumentStructureRetrieve request sent to a collection's
+ DocumentStructureRetrieve service (manual pp.48, 49) to retrieve
+ the entire document structure.
+
+
+
Parameters:
collection - is the name of the Collection whose
+ DocumentStructureRetrieve is requested
lang - is the language of the display content in the response
docNodeIDs - is the list of documentNodeIDs for which the
+ entire structure ought to be retrieved.
DocumentStructureRetrieve request sent to a collection's
+ DocumentStructureRetrieve service (manual pp.48, 49) to retrieve
+ the specified part of the document's structure.
+
+
+
Parameters:
collection - is the name of the Collection whose
+ DocumentStructureRetrieve is requested
lang - is the language of the display content in the response
docNodeIDs - is the list of documentNodeIDs for which the
+ structure ought to be retrieved.
structure - specifies what structure information needs to
+ be retrieved. The values can be one or more of ancestors, parent,
+ siblings, children, descendants (note spelling), entire.
info - - for specifying extra information to be retrieved.
+ Possible values for info parameters are numSiblings, siblingPosition,
+ numChildren
Performs a metadata retrieve for documents and (browse) classification
+ hierarchies. Sends a Document- or ClassifierBrowse- MetadataRetrieve message
+ to the Document- or ClassifierBrowse- MetadataRetrieve service.
+
+
+
Parameters:
to - - the Document- or ClassifierBrowse- MetadataRetrieve service to
+ send this metadata retrieve message to.
lang - - the language of the display content in the response
nodeIDs - - the list of (document or classifier) nodeIDs for which
+ to retrieve the metadata for
metaNames - - a list specifiying the names of the metadata items
+ to be retrieved for each nodeID. E.g. "Title", but a list is allowed.
NODE_ELEM - - either of GSXML's names for the <documentNode> or
+ <classifierNode> elements.
To send a browse request for specific parts of a classifier node
+ (children, ancestors, descendants). Useful for getting specific parts
+ of the structure of a top-level <classificationNode>.
+
+
+
Parameters:
collection - is the name of the Collection whose browse Classifier
+ Browse Service is called
browseService - is the name of the (Classifier) Browse Service (of
+ the given collection) to which this request message is sent.
lang - is the language of the display content in the response
classifierNodeIDs - is the list of classifierNodeIDs for which the
+ structure ought to be retrieved.
structureParams - the list of parameters indicating what structure
+ information is requested. Accepted values are ancestors, parent, siblings,
+ children, descendants.
Creates a String response message to represent an XML error response
+ message using the error specified in the message parameter. A String is
+ created because this method ensures that a response message is reliably
+ constructed (no exceptions are thrown) that can be sent to clients.
+
+
+
Parameters:
errorMessage - - the errormessage to be conveyed
+
Returns:
an XML response message containing an GS3 error element.
+
+
+
+
+
+help
+
+public static java.lang.String help()
+
+
+
+
Returns:
a help string for listing all the web service methods.
A beginning to the AdminSOAPServer class which will contain management/admin
+ related web services such as adding new documents, creating, building and
+ importing collections and configuring Greenstone modules.
"\nUnable to connect. Either the host and/or port contain invalid values\nOR the fedora server at that location is down/not yet running.\nTry once more by changing the values for host or port."
+This API (Application Programming Interface) document has pages corresponding to the items in the navigation bar, described as follows.
+Package
+
+
+
+Each package has a page that contains a list of its classes and interfaces, with a summary for each. This page can contain four categories:
+
Interfaces (italic)
Classes
Enums
Exceptions
Errors
Annotation Types
+
+
+Class/Interface
+
+
+
+Each class, interface, nested class and nested interface has its own separate page. Each of these pages has three sections consisting of a class/interface description, summary tables, and detailed member descriptions:
+
Class inheritance diagram
Direct Subclasses
All Known Subinterfaces
All Known Implementing Classes
Class/interface declaration
Class/interface description
+
+
Nested Class Summary
Field Summary
Constructor Summary
Method Summary
+
+
Field Detail
Constructor Detail
Method Detail
+Each summary entry contains the first sentence from the detailed description for that item. The summary entries are alphabetical, while the detailed descriptions are in the order they appear in the source code. This preserves the logical groupings established by the programmer.
+
+
+Annotation Type
+
+
+
+Each annotation type has its own separate page with the following sections:
+
Annotation Type declaration
Annotation Type description
Required Element Summary
Optional Element Summary
Element Detail
+
+
+
+Enum
+
+
+
+Each enum has its own separate page with the following sections:
+
Enum declaration
Enum description
Enum Constant Summary
Enum Constant Detail
+
+
+Tree (Class Hierarchy)
+
+There is a Class Hierarchy page for all packages, plus a hierarchy for each package. Each hierarchy page contains a list of classes and a list of interfaces. The classes are organized by inheritance structure starting with java.lang.Object. The interfaces do not inherit from java.lang.Object.
+
When viewing the Overview page, clicking on "Tree" displays the hierarchy for all packages.
When viewing a particular package, class or interface page, clicking "Tree" displays the hierarchy for only that package.
+
+
+Deprecated API
+
+The Deprecated API page lists all of the API that have been deprecated. A deprecated API is not recommended for use, generally due to improvements, and a replacement API is usually given. Deprecated APIs may be removed in future implementations.
+
+Index
+
+The Index contains an alphabetic list of all classes, interfaces, constructors, methods, and fields.
+
+Prev/Next
+These links take you to the next or previous class, interface, package, or related page.
+Frames/No Frames
+These links show and hide the HTML frames. All pages are available with or without frames.
+
+
+Serialized Form
+Each serializable or externalizable class has a description of its serialization fields and methods. This information is of interest to re-implementors, not to developers using the API. While there is no link in the navigation bar, you can get to this information by going to any serialized class and clicking "Serialized Form" in the "See also" section of the class description.
+
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).
+
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.
+
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.
+
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.
+
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.
+
All collections in this Digital Library (Fedora Repository) share
+ the same services, so this method returns the same as
+ describeService(serviceName).
+
Appends children to the parameter service Element that make the
+ final service Element into a describe response XML for FedoraGS3's
+ FieldQuery service.
+
All collections in this Digital Library (Fedora Repository) share
+ the same services, so this method returns the same as
+ describeCollectionService(collName, serviceName).
+
All collections in this Digital Library (Fedora Repository) share
+ the same services, so this method returns the same as
+ describeCollectionService(collName, serviceName).
+
Appends children to the parameter service Element that make the
+ final service Element into a describe response XML for FedoraGS3's
+ TextQuery service.
+
DLS -
+Static variable in interface org.greenstone.fedora.services.FedoraGS3DL
+
DLS metadata of Greenstone documents - this metadata set is optionally
+ provided for top level documents.
+
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.
Single argument constructor that takes the name of the properties file
+ defining the values of the initialisation parameters required to
+ instantiate a FedoraConnection.
+
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.
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.
+
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.
+
This AuthenticationFailedException can be thrown when the user enters
+ an invalid username and password into the FedoraConnection Authentication
+ popup dialog (displayed upon FedoraConnection object construction).
When the user chooses to cancel out of the FedoraConnection dialog of
+ the constructor (where they have to enter authentication information),
+ this exception is thrown, so that classes making use of FedoraConnection
+ may choose whether to exit their program or deal with it differently.
Static inner class FedoraGS3InitFailureException is an Exception
+ that is thrown when no connection can be made to the Fedora server
+ and therefore the FedoraGS3 object construction failed.
Certain functionality in Fedora - in particular fielded search - is
+ implemented differently or uses slightly different Fedora types in older
+ versions of Fedora (fielded search in 2.0 uses a different Condition class).
This AuthenticationFailedException can be thrown when there is some
+ server listening at the host and port values entered by the user, but
+ when this server is (most likely) not a Fedora Server.
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.
+
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.
+
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.
+
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.
+
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.
+
Some "greenstone:*" top-level documents in the fedora repository (but not
+ greenstone collections or document sections) have a DLS metadata datastream.
+
Some "greenstone:*" top-level documents in the fedora repository (but not
+ greenstone collections or document sections) have a DLS metadata datastream.
+
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>
+ ...
+
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.
+
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.
+
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.
+
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.
+
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>
+ ...
+
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>
+
Constructor that takes a String representing the url of the WSDL
+ file for FedoraGSearch's web services, and tries to establish a
+ connection to those web services.
+
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"
+
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.
+
Constant string message to check against if "AXIS engine
+ could not find a target service to invoke" message is the cause
+ for an AxisFault exception embedded in a RemoteException
+
+
+
+N
+
+
NAME -
+Static variable in interface org.greenstone.fedora.services.FedoraGS3DL
+
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.
+
FedoraGSearch accepts a query of the form:
+ <"cyclone val" "Gender Inequalities" ds.fulltext:"cyclone val"
+ ds.fulltext:"worst storm">
+ where the first two phrases are searched for in all indexed fields,
+ (in this case dc.title and ds.fulltext), while the last two are
+ searched for in the ds.fulltext field.
+
Uses FedoraGSearch to perform a search where the query is embedded in
+ fieldedSearchTerms, which not only provides the terms to search on, but
+ also the fields to search the (various) given terms in.
+
Implements querying document DC titles of a greenstone collection stored in
+ the fedora repository for a term that may occur anywhere in their titles.
+
Static method that displays a popup to allow the user to provide Fedora
+ authentication (username, pwd) and connection (protocol+host, port) details.
+
If a problem occurs converting the error message into XML
+ this string is created in the format of XML stating the
+ problem that occurred when trying to convert XML to String.
+
+
+
+_
+
+
_COLLECTION -
+Static variable in interface org.greenstone.fedora.services.FedoraGS3DL
+
+This document is designed to be viewed using the frames feature. If you see this message, you are using a non-frame-capable web client.
+
+Link toNon-frame version.
+
+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
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
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.
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.
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.
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.
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.
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.
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>
+ ...
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.
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.
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"
+
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 ("").
+
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.
+
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.
+
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.
+
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).
+
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.
+
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
+
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.
+
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:
+
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.
+
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.)
+
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.
+
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.)
+
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.
+
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.)
+
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.
+
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.
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.
+
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.)
+
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
+
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.)
+
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!
+
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.
+
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.
+
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.
+
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.
+
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
+
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.
+
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.
+
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.
+
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.
+
Implements querying document DC titles of a greenstone collection stored in
+ the fedora repository for a term that may occur anywhere in their titles.
+
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.
+
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.
+
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).
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.
+
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.
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.
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"
+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
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
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
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.
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
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).
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.
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.
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>
+ ...
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.
setGSearchIndexName(java.lang.String indexName)
+
+
+ Sets the member variable gSearchIndexName that specifies the name
+ of the index containing indexed GS3 documents.
+
+
+
+ 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.
+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
+
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"
+
+
+
+
+
+
+
+gSearchIndexName
+
+protected java.lang.String gSearchIndexName
+
+
The name of the index that FedoraGSearch will index the GS3
+ documents into. If no name is specified in the properties file,
+ this will default to FedoraIndex.
+
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.
+
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.
+
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.
+
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.)
+ - name of the index into which the GS3 documents have been indexed
+ and which FedoraGenericSearch should use to perform searches. If none is
+ given in the properties file, then the index name defaults "FedoraIndex".
+
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 "gsearch.wsdlURL".
+ At the end of this method, properties' "gsearch.wsdlURL" will be set
+ to whatever the final value of this.gSearchWSDLURL is, and
+ "gsearch.indexName" will be set to to whatever the final value of
+ this.gSearchIndexName is.
+
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.
+
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.
+
Sets the member variable gSearchIndexName that specifies the name
+ of the index containing indexed GS3 documents. Then it attempts
+ to instantiate a connection to the Fedora GSearch web services using
+ this changed value for indexName.
+
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.
+
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
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.
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
+
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.
+
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.
+
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
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
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
+
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).
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.
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).
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.
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.
+
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.
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
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.
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.
+
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!
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.
+
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!
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).
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.
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.
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.
All collections in this Digital Library (Fedora Repository) share
+ the same services, so this method returns the same as
+ describeCollectionService(collName, serviceName).
+
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).
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.
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.
All collections in this Digital Library (Fedora Repository) share
+ the same services, so this method returns the same as
+ describeService(serviceName).
+
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).
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.
+
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.
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>
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).
+
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).
+
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.
browseTitlesByLetter(java.lang.String collName,
+ java.lang.String letter)
+
+
+ Allows browsing document titles of a greenstone collection stored in
+ the fedora repository by letter.
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.
getDC(java.lang.String pid)
+
+
+ All objects (incl "greenstone:*" objects) in fedora - be they collections,
+ top-level documents or document sections) have an EX 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.
getEX(java.lang.String pid)
+
+
+ All "greenstone:*" objects in fedora (be they collections, top-level
+ documents or document sections) have an EX datastream.
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.
getTOC(java.lang.String pid)
+
+
+ All "greenstone:*" objects in fedora (be they collections or documents)
+ have a TOC datastream.
+
+
+
+ java.lang.String[]
+
searchDocumentTitles(java.lang.String collName,
+ java.lang.String titleContents,
+ boolean startsWith)
+
+
+ Allows querying document titles of a greenstone collection stored in
+ the fedora repository for a term that may occur anywhere in their titles.
+
+
+
+ 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.
+
+
+
+
+
+
+
+
+
+
+
+Field Detail
+
+
+
+
+FEDORA_GS3
+
+static final java.lang.String FEDORA_GS3
+
+
Instead of message router, we indicate that request messages
+ sent here come from FedoraGS3
+
DLS metadata of Greenstone documents - this metadata set is optionally
+ provided for top level documents. Not all Greenstone top-level documents
+ in the Fedora repository may have associated DLS metadata, however.
+
the default language used to query for titles (and anything else
+ where there are multiple language options). Upon initialisation, this
+ defaults to English.
+
+
+
+
+
+setLanguage
+
+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.
+
+
+
Parameters:
lang - - the two-letter language code to set the default language to.
+
+
+
+
+
+getMaxResults
+
+int getMaxResults()
+
+
The default maximum number of search results returned for a search. Upon
+ initialisation, this defaults to Java's Integer.MAX_VALUE.
+
+
+
+
+
+
+
+
+setMaxResults
+
+void setMaxResults(int maxresults)
+
+
Set the default maximum number of search results returned for a search.
+
+
+
Parameters:
maxresults - - the new default maximum number of search results to
+ be returned.
+
+
+
+
+
+getBaseURL
+
+java.lang.String getBaseURL()
+
+
+
+
Returns:
fedora's baseURL
+
+
+
+
+
+getPortAddressURL
+
+java.lang.String getPortAddressURL()
+
+
+
+
Returns:
the portAddressURL of the Fedora APIA web service
+ (should be the endpoint location in the APIA's WSDL file).
+ Else set this in the .properties file to something else.
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.
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.
+
+
+
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.
+
colPID - is the pid of the greenstone collection stored in
+ the fedora repository.
+
Returns:
a list of the fedora pids of all (document) objects in the
+ given greenstone collection stored in fedora's repository. All
+ pids that do not map to a collection are assumed to be documents.
+
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.
+
+
+
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.*".
+
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.
+
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 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.
+
All objects (incl "greenstone:*" objects) in fedora - be they collections,
+ top-level documents or document sections) have an EX datastream. This method
+ returns the content (XML) of the DC datastream as it is stored in fedora's
+ repository.
+
+
+
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.
+
All "greenstone:*" objects in fedora (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.
+
+
+
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.
+
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.
+
+
+
Parameters:
pid - - the fedora persistent identifier for an item in the fedora
+ repository.
+
Returns:
a String version of the XML in the DLS datastream for the fedora
+ object denoted by pid.
+
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.)
+
+
+
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.
+
docPID - is a fedora pid identifying a greenstone document object.
sectionID - identifies 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.
+
docPID - is a fedora pid identifying a greenstone document object.
sectionID - identifies 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.
+
docPID - is a fedora pid identifying a greenstone document object.
sectionID - identifies 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.
+
docPID - is a fedora pid identifying a greenstone document object.
sectionID - identifies 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.
+
public static class FedoraGS3Exception.AuthenticationFailedException
extends java.lang.Exception
+
+
+
+This AuthenticationFailedException can be thrown when the user enters
+ an invalid username and password into the FedoraConnection Authentication
+ popup dialog (displayed upon FedoraConnection object construction).
+
public static class FedoraGS3Exception.CancelledException
extends java.lang.Exception
+
+
+
+When the user chooses to cancel out of the FedoraConnection dialog of
+ the constructor (where they have to enter authentication information),
+ this exception is thrown, so that classes making use of FedoraConnection
+ may choose whether to exit their program or deal with it differently.
+
+Static inner class FedoraGS3InitFailureException is an Exception
+ that is thrown when no connection can be made to the Fedora server
+ and therefore the FedoraGS3 object construction failed.
+ Its constructor allows other exceptions to be encapsulated within
+ it, via the cause object (a Throwable, superclass of Exception)
+ parameter. This (the actual exception that caused the
+ FedoraGS3InitFailureException) can be queried by interested parties
+ via the getCause() method.
+
specifics
+
+
+ Some extra information as to what when wrong
+
+
+
+protected static java.lang.String
+
xmlToStringConversionFailureResponseMsg
+
+
+ If a problem occurs converting the error message into XML
+ this string is created in the format of XML stating the
+ problem that occurred when trying to convert XML to String.
+
+
+
+
+
+
Fields inherited from class org.greenstone.fedora.services.FedoraGS3Exception
If a problem occurs converting the error message into XML
+ this string is created in the format of XML stating the
+ problem that occurred when trying to convert XML to String.
+
public static class FedoraGS3Exception.FedoraVersionNotSupportedException
extends java.lang.Exception
+
+
+
+Certain functionality in Fedora - in particular fielded search - is
+ implemented differently or uses slightly different Fedora types in older
+ versions of Fedora (fielded search in 2.0 uses a different Condition class).
+ In that case, the fielded search web service cannot be performed, and
+ this FedoraVersionNotSupportedException is thrown.
+
public static class FedoraGS3Exception.NotAFedoraServerException
extends java.lang.Exception
+
+
+
+This AuthenticationFailedException can be thrown when there is some
+ server listening at the host and port values entered by the user, but
+ when this server is (most likely) not a Fedora Server.
+ The IOException message received in such cases is:
+ "Unable to instantiate FedoraConnection
+ java.io.IOException: Request failed [404 /fedora/describe]"
+ And in such cases, we can throw this NotAFedoraServerException
+ to deal with it more particularly than more general IOExceptions.
+
public static class FedoraGS3Exception.ServerNotFoundException
extends java.lang.Exception
+
+
+
+This ServerNotFoundException can be thrown when the user enters
+ there is no (Fedora) server listening at a given host and port.
+ Thrown when a 404 Not Found occurs.
+
+The exceptions that can be thrown by FedoraGS3. This class
+ represents a general FedoraGS3 exception. It will LOG the
+ exceptions for all the (static inner) subclasses. And, through
+ the Cause object, also for the static inner Exception classes
+ that do not inherit but are encapsulated in subclass
+ FedoraGS3RunException when its constructor is called with the
+ particular Exception type. The 'Cause' Exception classes therefore
+ indicate the root causes for why a FedoraGS3RunException was thrown.
+
FedoraGS3Exception.AuthenticationFailedException
+
+
+ This AuthenticationFailedException can be thrown when the user enters
+ an invalid username and password into the FedoraConnection Authentication
+ popup dialog (displayed upon FedoraConnection object construction).
+
+
+
+static class
+
FedoraGS3Exception.CancelledException
+
+
+ When the user chooses to cancel out of the FedoraConnection dialog of
+ the constructor (where they have to enter authentication information),
+ this exception is thrown, so that classes making use of FedoraConnection
+ may choose whether to exit their program or deal with it differently.
+
+
+
+static class
+
FedoraGS3Exception.FedoraGS3InitFailureException
+
+
+ Static inner class FedoraGS3InitFailureException is an Exception
+ that is thrown when no connection can be made to the Fedora server
+ and therefore the FedoraGS3 object construction failed.
FedoraGS3Exception.FedoraVersionNotSupportedException
+
+
+ Certain functionality in Fedora - in particular fielded search - is
+ implemented differently or uses slightly different Fedora types in older
+ versions of Fedora (fielded search in 2.0 uses a different Condition class).
+
+
+
+static class
+
FedoraGS3Exception.NotAFedoraServerException
+
+
+ This AuthenticationFailedException can be thrown when there is some
+ server listening at the host and port values entered by the user, but
+ when this server is (most likely) not a Fedora Server.
+
+
+
+static class
+
FedoraGS3Exception.ServerNotFoundException
+
+
+ This ServerNotFoundException can be thrown when the user enters
+ there is no (Fedora) server listening at a given host and port.
missingTargetService
+
+
+ Constant string message to check against if "AXIS engine
+ could not find a target service to invoke" message is the cause
+ for an AxisFault exception embedded in a RemoteException
+
+
+
+static java.lang.String
+
sslHandshakeExceptionMessage
+
+
+ Constant string message to display if the sslHandshake fails
+ when trying to connect to Fedora using https
+
+
+
+
+
+
+
+
+
+Constructor Summary
+
+
+
FedoraGS3Exception()
+
+
+ No argument constructor merely sets the message to
+ this class' name.
+
+
+
FedoraGS3Exception(java.lang.String message)
+
+
+ Constructs a FedoraGS3Exception with the given message.
+
+
+
FedoraGS3Exception(java.lang.String message,
+ java.lang.Throwable cause)
+
+
+ Constructs a FedoraGS3Exception with the given message and cause.
+
+
+
FedoraGS3Exception(java.lang.Throwable cause)
+
+
+ Constructs a FedoraGS3Exception with the given cause.
+public static final java.lang.String missingTargetService
+
+
Constant string message to check against if "AXIS engine
+ could not find a target service to invoke" message is the cause
+ for an AxisFault exception embedded in a RemoteException
+
+Most of the following methods return the same data as FedoraGS3DL, but
+ formatted as Greenstone Response-Message XML. This way our java-client can
+ parse the returned XML in the same way and store them in the same data
+ structures.
+
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
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).
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).
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 a list of document identifiers that are either docPIDs or
+ concatenations of docPID+sectionID, this method retrieves their contents.
+
+
+
+ java.lang.String
+
getContent(java.lang.String[] docIDs)
+
+
+ Given a document identifier that is either a docPID or a concatenation
+ of docPID+sectionID, this method retrieves the content for 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.
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.
setGSearchIndexName(java.lang.String indexName)
+
+
+ Sets the member variable gSearchIndexName that specifies the name
+ of the index containing indexed GS3 documents.
+
+
+
+ void
+
setGSearchWSDLURL(java.lang.String url)
+
+
+ Sets the member variable gSearchWSDLURL that specify the location of
+ the WSDL file of FedoraGSearch's web services.
+
+
+
+
+
+
+
+
+
+
+
+Method Detail
+
+
+
+
+getGSearchWSDLURL
+
+java.lang.String getGSearchWSDLURL()
+
+
+
+
Returns:
the gSearchWSDLURL, the url of the WSDL for the
+ FedoraGSearch web services
+
+
+
+
+
+setGSearchWSDLURL
+
+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
+
+
+
+
+
+getGSearchIndexName
+
+java.lang.String getGSearchIndexName()
+
+
+
+
Returns:
the gSearchIndexName, the name of the index Fedora Generic
+ Search will search in (where GS3 docs have been indexed into).
Sets the member variable gSearchIndexName that specifies the name
+ of the index containing indexed GS3 documents. Then it attempts
+ to instantiate a connection to the Fedora GSearch web services using
+ this changed value for indexName.
+
+
+
Parameters:
indexName - is the new name of the index containing indexed GS3
+ docs that GSearch should search in.
+
+
+
+
+
+getServiceList
+
+java.lang.String getServiceList()
+
+
+
+
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, BrowseByLetter - as indicated by member
+ variable serviceNames.
+
+
+
+
+
+getCollectionList
+
+java.lang.String getCollectionList()
+
+
+
+
Returns:
a GS3 describe response message listing the collections and
+ collection-specific metadata stored in the Fedora-Greenstone repository.
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.
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, browse.
All collections in this Digital Library (Fedora Repository) share
+ the same services, so this method returns the same as
+ describeService(serviceName).
+
+
+
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
+ describeCollectionService(collName, serviceName).
+
+
+
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).
Given a list of document identifiers that are either docPIDs or
+ concatenations of docPID+sectionID, this method retrieves their contents.
+
+
+
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.
Given a document identifier that is either a docPID or a concatenation
+ of docPID+sectionID, this method retrieves the content for it.
+
+
+
Parameters:
docIDs - an array of document IDs where each 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.
docID - the identifier for the document whose structure is required.
+ This is either of the format "greenstone:<collectionName>-<docPID>"
+ OR "greenstone:<collectionName>-<docPID>-"
+ 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 descendents included).
docID - the identifier for the document whose structure is required.
+ This is of the format "greenstone:<collectionName>-<docPID>"
+ OR "greenstone:<collectionName>-<docPID>-"
+ 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.
docIDs - an array of document identifiers whose structures are requested
+ These are of the format "greenstone:<collectionName>-<docPID>"
+ OR "greenstone:<collectionName>-<docPID>-<sectionNumber>"
+ 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 descendents included).
docIDs - an array of document identifiers whose structures are requested
+ These are of the format "greenstone:<collectionName>-<docPID>"
+ OR "greenstone:<collectionName>-<docPID>-<sectionNumber>"
+ 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 descendents).
+ The structure is returned in the XML format of a Greenstone3
+ DocumentStructureRetrieve response message.
Given a document identifier, returns a GS3 DocumentMetadataRetrieve
+ response message containing the metadata for the document.
+
+
+
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 all the requested document
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.
Given a document identifier, returns a GS3 DocumentMetadataRetrieve
+ response message containing ONLY the Title metadata for the document.
+
+
+
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
Given a document identifier, returns a GS3 DocumentMetadataRetrieve
+ response message containing ONLY the Title metadata for the documents.
+
+
+
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
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.
+
+
+
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.
nameValParamsMap - is a Map of name and value pairs for all the
+ query field data values. The names match the field names that
+ describeCollectionService() would have returned for the query service.
collection - is the name of the collection
service - is the name of the query service
+ This method is only ever called when any of the services in the digital
+ library described themselves as type=query. Therefore any digital
+ libraries that have no query services, can just return emtpy message
+ strings (or even "") since this method will never be called on them
+ anyway.
+
Returns:
a String representing Greenstone3 XML for a query process
+ response returning the results for the query denoted by parameter
+ nameValParamsMap.
+Class GSearchConnection connects to FedoraGSearch's web services.
+ FedorGSearch offers indexing and full-text search functionality for
+ Fedora repositories. Its search web service (method gFindObjects)
+ returns the response of a search as XML.
+ GSearchConnection offers more convenient methods that extract just
+ the parts of search results that FedoraGS3Connection needs and returns
+ that.
+
+
+
+
+
Author:
+
ak19
+
+
+
+
+
+
+
+
+
+
+Field Summary
+
+
+
+protected javax.xml.parsers.DocumentBuilder
+
builder
+
+
+ A DocumentBuilder object used to construct and parse XML
+
+
+
+protected org.apache.axis.client.Call
+
call
+
+
+ The Call object used to connect to the FedoraGSearch web services
GSearchConnection(java.lang.String wsdlFileLocation,
+ java.lang.String indexName)
+
+
+ Constructor that takes a String representing the url of the WSDL
+ file for FedoraGSearch's web services, and tries to establish a
+ connection to those web services.
+
+
+
+
+
+
+
+
+
+Method Summary
+
+
+
+protected java.lang.String
+
formatSearchTermsInField(java.lang.String field,
+ java.lang.String fieldName)
+
+
+ Each field is a comma separated list of terms that may be either a word
+ OR a phrase.
+
+
+
+ java.lang.String[]
+
getPIDsFromSearchResult(java.lang.String collectionName,
+ java.lang.String searchResult)
+
+
+ Call this method with the return value of calling search().
+
+
+
+protected java.lang.String
+
gFindObjects(java.lang.String searchFieldedTerms,
+ java.lang.String sort,
+ int hitPageStart,
+ int hitPageSize,
+ int snippetsMax,
+ int fieldMaxLength,
+ java.lang.String indexName,
+ java.lang.String resultPageXslt)
+
+
+ Method to invoke gfindObjects operation of Fedora Generic Search
+ web services.
search(java.util.Map fieldsToSearchTerms,
+ int hitPageStart,
+ int hitPageSize)
+
+
+ FedoraGSearch accepts a query of the form:
+ <"cyclone val" "Gender Inequalities" ds.fulltext:"cyclone val"
+ ds.fulltext:"worst storm">
+ where the first two phrases are searched for in all indexed fields,
+ (in this case dc.title and ds.fulltext), while the last two are
+ searched for in the ds.fulltext field.
+
+
+
+ java.lang.String
+
search(java.lang.String fieldedSearchTerms,
+ int hitPageStart,
+ int hitPageSize,
+ int snippetsMax)
+
+
+ Uses FedoraGSearch to perform a search where the query is embedded in
+ fieldedSearchTerms, which not only provides the terms to search on, but
+ also the fields to search the (various) given terms in.
+
+
+
+ java.lang.String
+
search(java.lang.String searchFieldName,
+ java.lang.String searchTerm,
+ int hitPageStart,
+ int hitPageSize,
+ int snippetsMax)
+
+
+ Method that performs a search for the given searchTerm inside the given
+ indexed field.
The name of the Index wherein FedoraGSearch has indexed all the GS3 docs.
+ This final member is public here so that others may read the indexName
+ that this GSearchConnection works with.
+
+
+
+
+
+
+
+service
+
+protected final org.apache.axis.client.Service service
+
+
The Service object used to connect to the FedoraGSearch web services
+
+
+
+
+
+
+
+call
+
+protected final org.apache.axis.client.Call call
+
+
The Call object used to connect to the FedoraGSearch web services
+
+
+
+
+
+
+
+portName
+
+protected final javax.xml.namespace.QName portName
+
+
The portName object used when connecting to FedoraGSearch's web services
+
+
+
+
+
+
+
+builder
+
+protected final javax.xml.parsers.DocumentBuilder builder
+
+
A DocumentBuilder object used to construct and parse XML
+
Constructor that takes a String representing the url of the WSDL
+ file for FedoraGSearch's web services, and tries to establish a
+ connection to those web services.
+
+
+
Parameters:
wsdlFileLocation - is a String representing the url of the WSDL file
indexName - is the name of the index that Fedora Generic Search
+ should work with (the index wherein the indexed GS3 documents have been
+ placed).
+
Throws:
+
java.net.MalformedURLException
+
javax.xml.rpc.ServiceException
+
javax.xml.parsers.ParserConfigurationException
+
+
+
+
+
+
+
+
+Method Detail
+
+
+
+
+gFindObjects
+
+protected java.lang.String gFindObjects(java.lang.String searchFieldedTerms,
+ java.lang.String sort,
+ int hitPageStart,
+ int hitPageSize,
+ int snippetsMax,
+ int fieldMaxLength,
+ java.lang.String indexName,
+ java.lang.String resultPageXslt)
+ throws java.lang.Exception
+
+
Method to invoke gfindObjects operation of Fedora Generic Search
+ web services.
+
+ Parameter types, parameter order and return type of gFindObjects are as
+ obtained from the wsdl file for the Fedora Generic Search web services
+ located at:
+ http://localhost:8080/fedoragsearch/services/FgsOperations?wsdl
+ <wsdl:message name="gfindObjectsRequest">
+ <wsdl:part name="query" type="xsd:string"/>
+ <wsdl:part name="sort" type="xsd:string"/>
+ <wsdl:part name="hitPageStart" type="xsd:int"/>
+ <wsdl:part name="hitPageSize" type="xsd:int"/>
+ <wsdl:part name="snippetsMax" type="xsd:int"/>
+ <wsdl:part name="fieldMaxLength" type="xsd:int"/>
+ <wsdl:part name="indexName" type="xsd:string"/>
+ <wsdl:part name="resultPageXslt" type="xsd:string"/>
+ </wsdl:message>
+
+ <wsdl:message name="gfindObjectsResponse">
+ <wsdl:part name="gfindObjectsReturn" type="xsd:string"/>
+ </wsdl:message>
+
+ <wsdl:operation name="gfindObjects"
+ parameterOrder="query sort hitPageStart hitPageSize snippetsMax
+ fieldMaxLength indexName resultPageXslt">
+
+ This method works: it searches the dc.title field of our FedoraIndex
+ for the term (e.g. "interview") and the result returned is an XML String.
+
+ There's no example on how to call gFindObjects with parameters. In
+ particular, I don't know what values the parameter sort can take.
+ But topazproject has an example on how to call updateIndex().
+
+public java.lang.String search(java.lang.String searchFieldName,
+ java.lang.String searchTerm,
+ int hitPageStart,
+ int hitPageSize,
+ int snippetsMax)
+ throws java.lang.Exception
+
+
Method that performs a search for the given searchTerm inside the given
+ indexed field.
+
+
+
+
+
+
Parameters:
searchFieldName - is the name of the indexed field within which the
+ given searchTerm is to be searched for.
searchTerm - is the term to be searched for.
hitPageStart - is the page of search results to start returning.
hitPageSize - is the number of search result pages to return,
+ starting from hitPageStart.
snippetsMax - is the maximum number of separate snippets containing
+ the searchTerm that are to be returned. (snippetsMax or a fewer number of
+ occurrences of the word in the text will be returned)
+
Throws:
+
java.lang.Exception
+
+
+
+
+
+search
+
+public java.lang.String search(java.util.Map fieldsToSearchTerms,
+ int hitPageStart,
+ int hitPageSize)
+ throws java.lang.Exception
+
+
FedoraGSearch accepts a query of the form:
+ <"cyclone val" "Gender Inequalities" ds.fulltext:"cyclone val"
+ ds.fulltext:"worst storm">
+ where the first two phrases are searched for in all indexed fields,
+ (in this case dc.title and ds.fulltext), while the last two are
+ searched for in the ds.fulltext field.
+ Another example:
+ <gender dc.title:interview ds.fulltext:"cyclone val">
+ titles and fulltexts are searched for "gender", while title index
+ is searched for "interview" and fulltexts are searched for the phrase
+ "cyclone val"
+
+
+
+
+
+
Parameters:
fieldsToSearchTerms - is a Hashmap of searchfields and
+ associated search terms (words or phrases). The terms are in a
+ comma-separated list. fieldsToSearchTerms is a Hashmap of
+ (Searchfields, associated-searchTerms) pairs. It can contain 3
+ searchfields: allfields, titles, text. The value for each is a
+ comma-separated list of search terms in that field.
+ Internally the field names get converted to what FedoraGSearch's
+ gfindObjects understands: titles becomes dc.title:, text becomes
+ ds.fulltext and allfields becomes nothing.
hitPageStart - is the page of search results to start returning.
hitPageSize - is the number of search result pages to return,
+ starting from hitPageStart.
+
Returns:
the XML (in string format) returned from Fedora Generic Search's
+ gfindObjects method
+
Each field is a comma separated list of terms that may be either a word
+ OR a phrase. We're going to separate each term from the list, and put
+ quotes around phrases, then combine all the terms together again with
+ spaces to separate them. Examples:
+
+ This is required to facilitate fielded searching with fedoraGSearch.
+
+
+
+
+
+
Parameters:
field - is a comma separated list of search terms (corresponding
+ to one fieldName) to be reorganised
fieldName - is the name of the field to prepend to the reorganised
+ field value. FieldName ALL_FIELDS is ignored.
+
Returns:
parameter field reorganised such that terms that are phrases
+ are in quotes and each term is separated by a space from the previous one.
+
+
+
+
+
+search
+
+public java.lang.String search(java.lang.String fieldedSearchTerms,
+ int hitPageStart,
+ int hitPageSize,
+ int snippetsMax)
+ throws java.lang.Exception
+
+
Uses FedoraGSearch to perform a search where the query is embedded in
+ fieldedSearchTerms, which not only provides the terms to search on, but
+ also the fields to search the (various) given terms in.
+
+
+
+
+
+
Parameters:
fieldedSearchTerms - is the String specifying all the search terms
+ with their fields (or no field if it should search for the terms in
+ all fields). The terms with no associated search-fields should come first.
+ Search terms may be in quotes.
snippetsMax - is the maximum number of separate snippets containing
+ the searchTerm (snippetsMax number of occurrences of the word in the text)
+ returned.
hitPageStart - is the page of search results to start returning.
hitPageSize - is the number of search result pages to return,
+ starting from hitPageStart.
+
Returns:
the XML (in string format) returned from Fedora Generic Search's
+ gfindObjects method
+
Call this method with the return value of calling search().
+ Search results are returned in GSearch's XML response format,
+ containing information that includes the PIDs of the documents that
+ matched the search. These PIDs are returned in the array.
+
+
+
+
+
+
Parameters:
collectionName - is the name of the collection to restrict the
+ search results by. If it's "", then results from all collections are
+ returned. Generally, don't want to pass "", because, theoretically,
+ all indexed collections in the repository could be considered and
+ not all of them may be Greenstone collections. If all Greenstone
+ collections should be searched for, pass "greenstone" as the
+ collection name instead.
searchResult - is the Fedora Generic Search XML response returned
+ from performing a gfindObjects() operations.
+
Returns:
an array of the pids of documents found for the search.
+
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.
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 AuthenticationFailedException can be thrown when the user enters
+ an invalid username and password into the FedoraConnection Authentication
+ popup dialog (displayed upon FedoraConnection object construction).
When the user chooses to cancel out of the FedoraConnection dialog of
+ the constructor (where they have to enter authentication information),
+ this exception is thrown, so that classes making use of FedoraConnection
+ may choose whether to exit their program or deal with it differently.
Static inner class FedoraGS3InitFailureException is an Exception
+ that is thrown when no connection can be made to the Fedora server
+ and therefore the FedoraGS3 object construction failed.
Certain functionality in Fedora - in particular fielded search - is
+ implemented differently or uses slightly different Fedora types in older
+ versions of Fedora (fielded search in 2.0 uses a different Condition class).
This AuthenticationFailedException can be thrown when there is some
+ server listening at the host and port values entered by the user, but
+ when this server is (most likely) not a Fedora Server.
+This API (Application Programming Interface) document has pages corresponding to the items in the navigation bar, described as follows.
+Package
+
+
+
+Each package has a page that contains a list of its classes and interfaces, with a summary for each. This page can contain four categories:
+
Interfaces (italic)
Classes
Enums
Exceptions
Errors
Annotation Types
+
+
+Class/Interface
+
+
+
+Each class, interface, nested class and nested interface has its own separate page. Each of these pages has three sections consisting of a class/interface description, summary tables, and detailed member descriptions:
+
Class inheritance diagram
Direct Subclasses
All Known Subinterfaces
All Known Implementing Classes
Class/interface declaration
Class/interface description
+
+
Nested Class Summary
Field Summary
Constructor Summary
Method Summary
+
+
Field Detail
Constructor Detail
Method Detail
+Each summary entry contains the first sentence from the detailed description for that item. The summary entries are alphabetical, while the detailed descriptions are in the order they appear in the source code. This preserves the logical groupings established by the programmer.
+
+
+Annotation Type
+
+
+
+Each annotation type has its own separate page with the following sections:
+
Annotation Type declaration
Annotation Type description
Required Element Summary
Optional Element Summary
Element Detail
+
+
+
+Enum
+
+
+
+Each enum has its own separate page with the following sections:
+
Enum declaration
Enum description
Enum Constant Summary
Enum Constant Detail
+
+
+Tree (Class Hierarchy)
+
+There is a Class Hierarchy page for all packages, plus a hierarchy for each package. Each hierarchy page contains a list of classes and a list of interfaces. The classes are organized by inheritance structure starting with java.lang.Object. The interfaces do not inherit from java.lang.Object.
+
When viewing the Overview page, clicking on "Tree" displays the hierarchy for all packages.
When viewing a particular package, class or interface page, clicking "Tree" displays the hierarchy for only that package.
+
+
+Deprecated API
+
+The Deprecated API page lists all of the API that have been deprecated. A deprecated API is not recommended for use, generally due to improvements, and a replacement API is usually given. Deprecated APIs may be removed in future implementations.
+
+Index
+
+The Index contains an alphabetic list of all classes, interfaces, constructors, methods, and fields.
+
+Prev/Next
+These links take you to the next or previous class, interface, package, or related page.
+Frames/No Frames
+These links show and hide the HTML frames. All pages are available with or without frames.
+
+
+Serialized Form
+Each serializable or externalizable class has a description of its serialization fields and methods. This information is of interest to re-implementors, not to developers using the API. While there is no link in the navigation bar, you can get to this information by going to any serialized class and clicking "Serialized Form" in the "See also" section of the class description.
+
Creates the Lucene index directory in the right location inside
+ FEDORA_HOME into which FedoraGSearch will store the indexes for
+ the Greenstone contents in the Fedora repository.
+
Loads properties from the property file denoted by propFileName
+ and replaces all place-holders (such as FEDORA_HOME, CATALINA_HOME,
+ HOST, PORT) with the custom values specified for this installation.
+
This class essentially follows the instructions at
+ http://drama.ramp.org.au/cgi-bin/trac.cgi/wiki/InstallingFedoraGSearch
+ in order to install Fedora Generic Search from their optimised
+ fedoragsearch.war file.
Reads from gsearch.properties file which contains default
+ directory paths (using variables like FEDORA_HOME and
+ CATALINA_HOME) and HOST and PORT, and sets these to custom values.
+
Given a DOM document, finds the first element where nodeName=tagName
+ where one of the attributes has the name attrName and whose value
+ contains attrValueContent.
+
Displays a dialog to get user input for
+ - fedora server host, port, username and password,
+ - the names for the fedora generic search index and repository
+ that are to be created, and
+ - for the location of fedoragenericsearch.war (the installer is
+ meant to work specifically with Muradora's fedoragenericsearch.war
+ since they have edited various property and xml files to make it
+ all easier).
+
+This document is designed to be viewed using the frames feature. If you see this message, you are using a non-frame-capable web client.
+
+Link toNon-frame version.
+
static class GSearchInstaller.IgnoreDTDEntityResolver
extends java.lang.Object
implements org.xml.sax.EntityResolver
+
+
+
+This EntityResolver allows the XML parser to ignore validating
+ against the DTD specified in the XML since it is pointing to the
+ wrong location. After parsing, we will put the DTD back in.
+ (Package class, only used here.)
+ See http://forum.java.sun.com/thread.jspa?threadID=284209&forumID=34
+
resolveEntity(java.lang.String publicId,
+ java.lang.String systemId)
+
+
+ If the systemId matches the one this IgnoreDTDEntityResolver
+ was created for, then the specified DTD is skipped.
+This class essentially follows the instructions at
+ http://drama.ramp.org.au/cgi-bin/trac.cgi/wiki/InstallingFedoraGSearch
+ in order to install Fedora Generic Search from their optimised
+ fedoragsearch.war file. (I've also tested it on the original war file
+ fedoragsearch.war available from http://defxws2006.cvt.dk/fedoragsearch/
+ and it works.)
+ It then does a few minor extra things in order to make Fedora Generic
+ Search work specifically with a Fedora repository of Greenstone documents.
+
+
+
+
+
Author:
+
ak19
+
+
+
+
+
+
+
+
+
+
+Nested Class Summary
+
+
+
+(package private) static class
+
GSearchInstaller.IgnoreDTDEntityResolver
+
+
+ This EntityResolver allows the XML parser to ignore validating
+ against the DTD specified in the XML since it is pointing to the
+ wrong location.
gSearchProperties
+
+
+ Reads from gsearch.properties file which contains default
+ directory paths (using variables like FEDORA_HOME and
+ CATALINA_HOME) and HOST and PORT, and sets these to custom values.
copyPropFile(java.util.Properties properties,
+ java.lang.String propFileName,
+ java.io.File outputPath)
+
+
+ Stores the given properties in the file outputPath/propFileName.
+
+
+
+protected void
+
copyTemplateFile(java.lang.String src,
+ java.io.File dest,
+ boolean replace)
+
+
+ Copies internal template src file (in executable jar) to dest file.
+
+
+
+protected void
+
createLuceneIndexDir()
+
+
+ Creates the Lucene index directory in the right location inside
+ FEDORA_HOME into which FedoraGSearch will store the indexes for
+ the Greenstone contents in the Fedora repository.
customiseProperties(java.lang.String propFileName,
+ boolean display)
+
+
+ Loads properties from the property file denoted by propFileName
+ and replaces all place-holders (such as FEDORA_HOME, CATALINA_HOME,
+ HOST, PORT) with the custom values specified for this installation.
+
+
+
+static java.lang.String
+
elementToFormattedString(org.w3c.dom.Element e,
+ java.lang.String dtd_SystemId)
+
+
+ Given an Element, this will return its String representation properly
+ indented for display.
+
+
+
+protected static java.lang.String
+
getSafeValue(javax.swing.JTextField field,
+ java.lang.String property)
+
+
+ This method returns the value of the textfield for the given
+ GSearchInstaller initialiser property, if this is not the empty string.
+
+
+
+static java.lang.String
+
getValue(org.w3c.dom.Element e)
+
+
+ Extract the text from an element, if any.
+
+
+
+ void
+
indexGreenstoneContents(boolean emptyFirst)
+
+
+ Indexes the contents of the repository(name) specified during Fedora
+ Generic Search installation.
main(java.lang.String[] args)
+
+
+ The main method creates a GSearchInstaller to install Fedora Generic
+ Search from a (Muradora) fedoragsearch.war file.
+
+
+
+protected void
+
moveUnpackWarFile(java.io.File gsearchWarFile)
+
+
+ Moves the (fedoragsearch.war) war file from the given location
+ into FEDORA_HOME's tomcat folder (i.e.
+
+
+
+static java.util.Properties
+
parseInstallationArgs(java.lang.String[] args)
+
+
+ Called to process multiple command line arguments where these
+ arguments are GSearchInstaller constructor options followed by
+ their values.
+
+
+
+protected org.w3c.dom.Document
+
readXML(java.lang.Object xmlSource,
+ java.lang.String dtd_SystemId,
+ java.lang.String sourceFileName)
+
+
+ Reads from an xmlFile.
+
+
+
+protected boolean
+
replaceDir(java.lang.String outputPath,
+ java.lang.String src,
+ java.lang.String dest)
+
+
+ Method that renames folder src in outputPath to dest.
+
+
+
+protected boolean
+
replaceElementWithAttrValue(org.w3c.dom.Document doc,
+ java.lang.String tagName,
+ java.lang.String attrName,
+ java.lang.String attrValueContent,
+ java.lang.String replacementContent,
+ boolean onceOnly,
+ boolean wholeItem)
+
+
+ Given a DOM document, finds the first element where nodeName=tagName
+ where one of the attributes has the name attrName and whose value
+ contains attrValueContent.
+
+
+
+protected boolean
+
replaceElementWithValue(org.w3c.dom.Document doc,
+ java.lang.String tagName,
+ java.lang.String contentValue,
+ java.lang.String replacement,
+ boolean onceOnly,
+ boolean wholeItem)
+
+
+ Given a DOM document, finds the first element where nodeName=tagName
+ and where the element's inner text contains the string contentValue.
+
+
+
+protected int
+
runProcess(java.lang.String[] args,
+ boolean ignoreWindows)
+
+
+ Method that will run the process associated with the gSearchProperties key.
+
+
+
+static java.util.Properties
+
showInputDialog()
+
+
+ Displays a dialog to get user input for
+ - fedora server host, port, username and password,
+ - the names for the fedora generic search index and repository
+ that are to be created, and
+ - for the location of fedoragenericsearch.war (the installer is
+ meant to work specifically with Muradora's fedoragenericsearch.war
+ since they have edited various property and xml files to make it
+ all easier).
+
+
+
+static java.lang.String
+
usage()
+
+
+ If the program is run from the command line and the user executed
+ it with -help or help, then this usage String is displayed.
+
+
+
+ void
+
waitForFedoraServer()
+
+
+ Waits for the fedora server to be ready after a server start.
Reads from gsearch.properties file which contains default
+ directory paths (using variables like FEDORA_HOME and
+ CATALINA_HOME) and HOST and PORT, and sets these to custom values.
+ Some of the keys in the properties file include executable
+ processes (such as for starting and stopping tomcat).
+
+
+
+
+
+
+
+indexName
+
+public final java.lang.String indexName
+
+
+
+
+
+
+
+repositoryName
+
+public final java.lang.String repositoryName
+
+
+
+
+
+
+
+host
+
+public final java.lang.String host
+
+
+
+
+
+
+
+port
+
+public final java.lang.String port
+
+
+
+
+
+
+
+fedoraUsername
+
+public final java.lang.String fedoraUsername
+
+
+
+
+
+
+
+fedoraPassword
+
+public final java.lang.String fedoraPassword
+
+
+
+
+
+
+
+gsearchWarFileName
+
+public final java.lang.String gsearchWarFileName
+
+
+
+
+
+
+
+PROP_REPOS
+
+protected static java.lang.String PROP_REPOS
+
+
+
+
+
+
+
+PROP_INDEX
+
+protected static java.lang.String PROP_INDEX
+
+
+
+
+
+
+
+PROP_UNAME
+
+protected static java.lang.String PROP_UNAME
+
+
+
+
+
+
+
+PROP_PASSW
+
+protected static java.lang.String PROP_PASSW
+
+
+
+
+
+
+
+PROP_HOST
+
+protected static java.lang.String PROP_HOST
+
+
+
+
+
+
+
+PROP_PORT
+
+protected static java.lang.String PROP_PORT
+
+
+
+
+
+
+
+PROP_FILE
+
+protected static java.lang.String PROP_FILE
+
+
+
+
+
+
+
+defaults
+
+protected static final java.util.Properties defaults
+
+
Default initialisation/customisation values. In case the Installer
+ was not provided all parameters, these are used as fallback values
+
Indexes the contents of the repository(name) specified during Fedora
+ Generic Search installation. To do so, it runs the FedoraGenericSearch's
+ runSOAPClient.sh with "host:port updateIndex fromFoxmlFiles".
+
+
+
Parameters:
emptyFirst - means the index will be created from scratch by first
+ executing runSOAPClient.sh with the arguments
+ "host:port updateIndex createEmpty" before updating from FOXML files.
+
Throws:
+
java.lang.Exception
+
+
+
+
+
+runProcess
+
+protected int runProcess(java.lang.String[] args,
+ boolean ignoreWindows)
+ throws java.lang.Exception
+
+
Method that will run the process associated with the gSearchProperties key.
+ Waits until the process is executed.
+
+
+
Parameters:
args - signify the executable process and its arguments. The first element
+ must be the key into gSearchProperties whose value denotes the executable process
+ that is to be run. Subsequent elements are the actual arguments to that process.
ignoreWindows - if true will not plug the cmd /c start "" at the start of
+ the arguments. If false, and only of the OS is windows, then these additional
+ arguments get prepended to those already in the args array.
+
Loads properties from the property file denoted by propFileName
+ and replaces all place-holders (such as FEDORA_HOME, CATALINA_HOME,
+ HOST, PORT) with the custom values specified for this installation.
+ These customised properties are returned in the Properties map.
+ Never overwrite the property file given by propFileName!
+ They are defaults, meant to be customised elsewhere.
+
+
+
Parameters:
propFileName - is the name of the template properties file
+ to be opened and read from. (Keep it read-only!)
display - - if true, then prints the contents of the properties
+ if false, does not.
+
Returns:
the properties in the template properties file
+ customised with the values provided during installation.
+
Copies internal template src file (in executable jar) to dest file.
+ If replace is true, then if the dest file exists, it will be overwritten.
+ From http://exampledepot.com/egs/java.io/CopyFile.html
+
+
+
Parameters:
src - is the internal file (internal to the jar) to be copied
+ its inputStream is obtained and copied.
dest - is the file into which the contents of src are to be copied
replace - indicates whether dest is to be replaced if it already
+ exists. If replace is true, then any existing dest is replaced with the
+ copied output file of the same name. If false, the copy operation does
+ not take place
+
Reads from an xmlFile. If dtd_SystemId is not an empty String,
+ then the XMLFile is not validated against the doctype statement it
+ contains (the dtd_SystemId entity in the xmlFile is ignored) so
+ that parsing still succeeds. However, if the DOM Structure returned
+ by this method is written back out to a file, then make sure that
+ this doctype is added back into the output file.
+
+
+
Parameters:
xmlSource - is either an xmlFile or xml InputStream (of a jarred
+ file, for example) to be read into a DOM structure.
dtd_SystemId - - if specified, validation against the given DTD
+ is ignored. The DOM structure returned will not contain the DOCTYPE
+ entity with the given dtd file reference. If writing the DOM out to
+ a file later on, then it is advised that this DOC_TYPE is added back
+ in. If there is no dtd to be validated or whose validation is to be
+ ignored, pass the empty string for dtd_SystemId.
sourceFileName - is the name of the (possibly internal) file
+ that is to be read.
+
Throws:
+
java.lang.Exception - if an error occurred during parsing.
dtdToAddBackIn - is "" if there's no special DTD to add
+ back into the DOCTYPE. If not "", it specifies the dtd file to
+ be added in the DOCTYPE of the XML output file.
+
Given a DOM document, finds the first element where nodeName=tagName
+ where one of the attributes has the name attrName and whose value
+ contains attrValueContent. The portion of the attribute value
+ that matches is then replaced by replacementContent.
+ If onceOnly is true, the first replacement is made and the method
+ returns. If false, all matching replacements are made.
+
+
+
Parameters:
doc - is the DOM Document object in which to search for
+ the element to be replaced
tagName - is the name of the element to search for
attrName - is the name of the attribute of the element to search for
attrValueContent - is the portion of the attribute value that will
+ be replaced by replacementContent.
replacementContent - is the replacement string that will overwrite
+ the part of the attrName attribute's value that matched attrValueContent
onceOnly - - if true will look for the first match and perform the
+ replacement once. If false, it will replace all matches found.
wholeItem - - if true, the entire string containing attrValueContent
+ will be replaced by the string replacementContent. If false, only the
+ attrValueContent portion of the original string will be replaced.
+
Given a DOM document, finds the first element where nodeName=tagName
+ and where the element's inner text contains the string contentValue.
+ Once found, the entire textnode contents of the matching element
+ is then replaced with the replacement string.
+
+
+
Parameters:
doc - is the DOM Document object in which to search for
+ the element to be replaced
tagName - is the name of the element to search for
contentValue - is the portion of the textual content of the
+ element that should match for the replacement to happen
replacement - is value that will overwrite the matching portion
+ of the element's textual content (it will overwrite contentValue).
onceOnly - - if true will look for the first match and perform the
+ replacement once. If false, it will replace all matches found.
wholeItem - - if true, the entire string containing attrValueContent
+ will be replaced by the string replacementContent. If false, only the
+ attrValueContent portion of the original string will be replaced.
+
Given an Element, this will return its String representation properly
+ indented for display. (The XML declaration will be added at the top
+ since this method will be used here to write proper XML out to a file.)
+
+
+
Parameters:
e - is the element to be converted to its string representation.
dtd_SystemId - (if not "") is any DOCTYPE with systemId that needs
+ to be added back into the file. If "", then no new DOCTYPE entity is
+ added into the DOM structure represented by Element e.
+
Returns:
a string representation of e, formatted for display.
+
Moves the (fedoragsearch.war) war file from the given location
+ into FEDORA_HOME's tomcat folder (i.e. into CATALINA_HOME) and
+ unpacks it there. Unpacking is achieved by starting the fedora
+ server after the move. If a fedoragsearch is already unpacked
+ in CATALINA_HOME, this method will not move the given
+ fedoragsearch.war file.
+ This method does more than merely move fedoragsearch.war:
+ regardless of whether the war file exists and is moved or not,
+ the fedora server is first stopped and at the end it is started.
+
+
+
Parameters:
gsearchWarFile - the fedoragsearch.war file to be moved and
+ unpacked.
+
Throws:
+
java.lang.Exception - if an unpacked fedoragsearch does not exist
+ in the CATALINA_HOME/webapps folder at the end.
Makes changes to the fedora.fcfg file located inside FEDORA_HOME.
+ It changes the fedora.server.storage.DOManager to the GSearchDOManager
+ and sets the gSearchRESTURL to the specific fedora host and port values
+ specified for installation.
+ This method also checks that "greenstone" is in the list of PIDs that
+ Fedora recognises. If it's not in the list already, it is added in
+ there.
+
Creates the Lucene index directory in the right location inside
+ FEDORA_HOME into which FedoraGSearch will store the indexes for
+ the Greenstone contents in the Fedora repository.
+ If it already exists, the Lucene index directory is not created.
+
+
+
+
Throws:
+
java.lang.Exception - if the Lucene index directory cannot be created
+ in the appropriate location inside FEDORA_HOME
Displays a dialog to get user input for
+ - fedora server host, port, username and password,
+ - the names for the fedora generic search index and repository
+ that are to be created, and
+ - for the location of fedoragenericsearch.war (the installer is
+ meant to work specifically with Muradora's fedoragenericsearch.war
+ since they have edited various property and xml files to make it
+ all easier).
+ The dialog displays the default values to the user.
+
+
+
+
Returns:
a Properties map containing the values entered by the
+ user for the various initialisation parameters required by the
+ Fedora Generic Search Installer GSearchInstaller.
This method returns the value of the textfield for the given
+ GSearchInstaller initialiser property, if this is not the empty string.
+ If it is the empty string, the default value for this property is
+ returned.
+
+
+
Parameters:
field - is the TextField whose value is being extracted
property - is the GSearchInstaller property that the TextField
+ value maps to.
+
Returns:
the contents of the textfield for the property or the defaults
+ value for the property if the textfield contained "".
+
+
+
+
+
+info
+
+public static java.lang.String info()
+
+
+
+
Returns:
a string specifying the requirements of this program.
+
+
+
+
+
+usage
+
+public static java.lang.String usage()
+
+
If the program is run from the command line and the user executed
+ it with -help or help, then this usage String is displayed.
+
+
+
+
Returns:
String describing how to use this program when running it
+ from the command line.
Called to process multiple command line arguments where these
+ arguments are GSearchInstaller constructor options followed by
+ their values.
+
+
+
Parameters:
args - are the command-line arguments received by main
+ which consist of one or more multiple "-option value" pairs.
+
Returns:
a Properties map containing (option, value) pairs
+ that will be used by GSearchInstaller to install Muradora's
+ Fedora Generic Search. Empty strings for recognised options
+ are replaced by defaults.
+
+
+
+
+
+main
+
+public static void main(java.lang.String[] args)
+
+
The main method creates a GSearchInstaller to install Fedora Generic
+ Search from a (Muradora) fedoragsearch.war file.
+ The program can be run in one of two ways:
+ - with no arguments: a dialog is displayed requesting inputs for the
+ parameters used by the GSearchInstaller initialisation.
+ - with arguments for command-line invocation. (Run with -help or help
+ to find out what parameter options are there.)
+
This class essentially follows the instructions at
+ http://drama.ramp.org.au/cgi-bin/trac.cgi/wiki/InstallingFedoraGSearch
+ in order to install Fedora Generic Search from their optimised
+ fedoragsearch.war file.
Deploy the QBRSOAPServer as follows. Use a Linux x-term/Windows DOS-prompt to cd into the greenstone 3 installation folder. Then type:
+
ant soap-deploy-site
+It will prompt you for 3 things:
+
+
the Site you wish to deploy it for (example "localsite")
+
the web services you wish to deploy. Type "QBRSOAPServer", since these are the web services the demo-client works with.
+
a name for the web services. If you don't want to remember the name, accept the default "QBRSOAPServerlocalsite".
+
+This will have deployed the QBRSOAPServer for the Site specified at http://HOST:PORT/greenstone3/services, where the values for HOST and PORT depend on where your greenstone 3 server for the chosen Site is listening.
+
+
Get the demo-client application: download tar.gz/zip version of the GS3 web services demo-client, and unzip it.
+
+
Run the demo-client:
+
+
If you're on windows, go into the demo-client installation folder and double click on the gs3democlient.bat file.
+
If you're on Linux, use an x-term to cd into the demo-client installation folder and run the application by typing
+
./gs3democlient.sh
+
+
+
+
Once the application starts, choose Greenstone from the drop-down box at the top as the digital library you wish to connect to. A dialogue will prompt you for the wsdl URL of the QBRSOAPServer web services which you can obtain from the Greenstone 3 services page http://HOST:PORT/greenstone3/services You need to copy the link to the wsdl file of the QBRSOAPServer web services you deployed in 2.
+
+
To run the demo-client on a separate computer from the Greenstone server where the web services are deployed:
+Move to another computer. Download and run the demo-client as described in the first three steps. Once the application opens up and you choose to connect to the greenstone 3 digital library, remember to type the HOST and PORT of the remote Greenstone 3 server when specifying the web services' wsdl URL. Basically, the steps are the same as before.
+
Get and install Fedora 2.2.1 (you could try a later version, though I haven't yet attempted this). See the document on Installing Fedora.
+
+
Use the FLI application (Fedora Librarian Interface) that comes with Greenstone 3 to export Greenstone 3 documents into FedoraMETS format and put these in the Fedora repository. To run FLI, go to your greenstone 3 installation folder's gli directory.
+Then, if you're on Linux, type in an X-term
+
./fli.sh
+If you're on Windows, double click on fli.bat. The opening dialogue requires you to provide the details necessary for connecting to the Fedora repository. Otherwise you can use FLI as you would GLI.
+
+
Optional: If you want full-text searching in Fedora, get and install Fedora Generic Search, then use it to index the Greenstone 3 docs you exported into the Fedora repository. For details see the document on Installing Fedora Generic Search.
+
+
Run the demo-client as in point 3 of Section A above.
+
+
Once the application starts, choose Fedora from the drop-down box. A dialogue will ask you for the host and port that the fedora server is listening on and your fedora server username and password.
+
+
To run the demo-client on a separate computer from the Fedora server's repository containing GS3 docs:
+Move to another computer. Download and run the demo-client as described in the first three steps. Once the application opens up and you choose to connect to the fedora digital library, remember to type the HOST and PORT of the remote fedora server along with its username and password. Basically, the steps are the same as before.
+
+
+
+
NOTE: If you have both Fedora and Greenstone 3 set up as described in Sections A and B above, the client can be run against either digital library's repository. The application will require you to connect to both only once.
+
+
Index: other-projects/gs3-webservices-java-client/trunk/docs/HowToFiles/1GettingGS3WebServicesRunning.html
===================================================================
--- other-projects/gs3-webservices-java-client/trunk/docs/HowToFiles/1GettingGS3WebServicesRunning.html (revision 21027)
+++ other-projects/gs3-webservices-java-client/trunk/docs/HowToFiles/1GettingGS3WebServicesRunning.html (revision 21027)
@@ -0,0 +1,124 @@
+
+
+
+
+Getting web services running on the Greenstone 3 server
+
+
+Back to index page
+
+
Getting web services running on the Greenstone 3 server
+
+You need:
+
+
Greenstone 3 (an up-to-date version, as described in Section A below)
+
+
+In this document,
+
+
$GSDL3HOME refers to the full path to your Greenstone 3 installation.
+
GS3 may be used as a shorthand to refer to Greenstone 3.
+We'll look at the example of deploying the "QBRSOAPServer" web service which is used by the GS3-webservices-democlient application.
+
+
Go into your $GSDLHOME folder and start tomcat by typing in an X-term or ms-dos prompt:
+
ant start
+
+
(NOTE: Previously, only the fundamental SOAPServer class offered web services for Greenstone. And those web services could and can still be deployed with
+
ant deploy-localsite
+This deploys SOAPServer's "process" web service operation on your localhost server. And you can view the effects of deploying it by going to http://localhost:8080/greenstone3/services. Its WSDL can be accessed via that page as well.)
+
+
While "ant deploy-localsite" deploys the same default SOAPServer web service, we want to deploy another web service this time.
+
+
We'll be deploying the new QBRSOAPServer web services, which will provide basic query, browse and retrieval web service operations. This is what the GS3-webservices-democlient uses:
+
ant soap-deploy-site
+
+
The first time it prompts you, you need to choose the Greenstone3 site you want to deploy the services for. (Localsite on localhost is the default).
+
The next time, you need to type the name of the set of web services you wish to deploy. In this case, type
+
QBRSOAPServer
+Note the use of caps and lowercase letters.
+
Finally it will ask you want you want to call this set of web services. You can either accept the default name—which would be QBRSOAPServerlocalsite if you had chosen to deploy it for localsite—or you can type some other name for the web services. (For instance, GS3AccessWebServices.)
+At present, just accept the default service name of QBRSOAPServerlocalsite.
+
+If all went well, it would now have been deployed.
+
+
+
Point your browser to the Greenstone site you deployed them for and go to the "services" page. For example, if the services were deployed for localsite and your port was 8080, you'd go to:
+
http://localhost:8080/greenstone3/services
+And on this page, it will mention QBRSOAPServerlocalsite (or whatever name you chose for the web services) among the list of web services deployed.
+There will be a link named wsdl next to the web service name. (You can click on the wsdl link to view the contents of this XML file. This file describes the web services: the url of the services, the operations it provides, the number and types of the values the operations take and returns.) We won't do anything special with all this other than copy the url for the WSDL file.
+
+
For example, depending on the serviceName you chose and the host/port where the services have been deployed on, this might be
+
+When you don't want the web services deployed anymore, you can undeploy them.
+
+
Go into $GSDLHOME folder. Make sure tomcat is running (if not, type "ant start").
+
Type in an X-term:
+
ant soap-undeploy-site
+
+
Type the name of the web services you wish to undeploy.
+If you don't remember what the name is anymore, point your browser to the Greenstone site you deployed them for and go to the "services" page again.
+For instance, if my Greenstone3 server is listening at port 8080 on my local computer, I'd go to:
+
http://localhost:8080/greenstone3/services
+The services page will list the deployed web services. Get the name of the web service you want to undeploy from here. Go back to your x-term and type this in to undeploy the chosen web service.
+For instance, if we had a web service with the name "QBRSOAPServerlocalsite" deployed and wanted it removed, we'd type that name.
+
+
+
+
+
Index: other-projects/gs3-webservices-java-client/trunk/docs/HowToFiles/2RunningGS3DemoClientWithGs3.html
===================================================================
--- other-projects/gs3-webservices-java-client/trunk/docs/HowToFiles/2RunningGS3DemoClientWithGs3.html (revision 21027)
+++ other-projects/gs3-webservices-java-client/trunk/docs/HowToFiles/2RunningGS3DemoClientWithGs3.html (revision 21027)
@@ -0,0 +1,137 @@
+
+
+
+
+Running the GS3 web services demo-client application
+
+
+Back to index page
+
+
Running the GS3 web services demo-client application
+In this document,
+
+
GS3 refers to Greenstone 3.
+
"client" refers to the "GS3 web services demo-client" application.
Greenstone 3 installed and running on an accessible server with the QBRSOAPServer web services deployed on it. See
+
+
wiki pages for installing Greenstone
+
Getting web services running on the Greenstone 3 server to find out how to deploy these services. (If you have Greenstone 3 installed on your machine, you can deploy the QBRSOAPServer web services on there and run the client against it as a test.)
Easy: You can download the *.tar.gz or *.zip version which contains the executable files (and the source files too). Download the gs3-webservices-democlient from LOCATION and unzip it.
+
Involves compiling: You can compile the source files that are included in the *.tar.gz and *.zip versions. You will need Apache Ant 1.6.5 and JDK1.5 (Java 5) for this. Unzip the zip/tar.gz file and follow the steps in the section Compiling the Client below.
+
Involves compiling: You can also obtain the client source code from Greenstone 3's SVN repository and compile it up. You will need Apache Ant 1.6.5, JDK1.5 (Java 5) and an SVN command line client in order to do this. (See the GS3 wiki page Walkthrough: installing Greenstone 3 from SVN source on Windows, section "Preparation: what you need" for more information on where to get an SVN command-line client and how to install it.)
+The SVN repository location for the gs3-webservices-democlient is:
+
+Depending on the speed of your internet connection, this may take some time. Once it has finished checking out the code from the repository, follow the steps in section Compiling the Client below.
+NOTE: This step is not necessary if you have downloaded the zip/tar.gz containing the executable. It's only necessary if you want to try compiling it up yourself, or if you want to make changes to the code then need to compile it.
+
+
+
Open a Linux x-term or Windows DOS-prompt and navigate into the top-level folder of the gs3-webservices-democlient.
+
+
Now, if you've made changes to the code, type
+
ant build-demo-client
+to create the executable jar file.
+
+If you want to recompile it from scratch, type
+
ant clean
+ant build-demo-client
+
+If you want a list of other available ant commands (targets), type
+
+Once you've got an executable version--either by compiling it yourself or by having downloaded a zipped version containing the executable jar-file--you can run the client application.
+
+
+
To be able to run the client, go into the unzipped gs3-webservices-democlient folder it would have created. And follow whichever of the steps below is applicable to you:
+
+
If you are on Linux, open an X-term and type:
+
./gs3democlient.sh
+
+
If you are on Windows, you can double-click the gs3democlient.bat to launch the application
+
Alternatively, if you've setup Java properly, you can open a Linux X-term or Windows DOS-prompt, go into the gs3-webservices-democlient folder and try typing:
+
java -jar GS3democlient.jar
+
+
+
+
Continue on with the section How To Use The Client, below.
+Once you have the application running, the application window should open up.
+
+
+
At the top, select the Digital Library you want to connect to from the drop-down list.
+(If you don't have Fedora installed, the choosing the Fedora option will not make the connection to a Fedora server. See this page for details on installing Fedora and for links to the official Fedora installation instructions page.)
+
+
Choose Greenstone. It will ask you for the "Wsdl" of the QBRSOAPServer web services.
+This means you will need the QBRSOAPServer web services deployed on the Greenstone3 server you want to connect to. See the document Getting web services running on the Greenstone 3 server on how to do that. If they're deployed, then you can find the url of the web services' wsdl file by going to the "/services" page of the Greenstone 3 server
http://HOST:PORT/greenstone3/services
+For instance,
+
http://localhost:9090/greenstone3/services
+(If you're behind a firewall, you can try setting the proxy settings at the top of the GS3 demo-client application window. Press the Set button and try connecting to the digital library.)
+
+
If you know of a Fedora 2.2.1 server for a Fedora repository containing Greenstone-exported documents, you can choose the Fedora option from the drop down box. A dialogue will pop up asking for the host and port on which the Fedora server is listening and for your username and password details. Alternatively, if you want to install a Fedora server, see here for details on installing Fedora and for links to the official Fedora installation instructions page.
+
+
+
+
Once you're connected to the digital library, the available collections can be viewed in the collection drop-down box. Select one you want.
+
The list of Query and Browse services available for a chosen collection are visible in the service drop down box. If you choose a Browse service the Browse tab will open and you can browse on the different classifiers represented by the buttons at the top of the Browse tab.
Query services are available for collections in the Greenstone digital library. If you have Fedora Generic installed next to Fedora, there will also be Query services available for the Fedora digital library. (If you have a Fedora repository, see Installing Fedora Generic Search for installation steps.)
+If you select a Query service, a form will be displayed in the Query tab. Fill in the query form, hit the search button and you'll be taken to the Search results (if any) in the Search tab.
+
The search results are documents that you can click on. If they have a hierarchical structure then the documents can be expanded further.
+
You can view the metadata associated with selected documents (or classifications) in both the Browse and Query tabs.
+This section is on how to run the client on one computer when the QBRSOAPServer web services have been deployed on a remote machine.
+Assuming you have the QBRSOAPServer web services deployed on the Greenstone 3 server (as described in Getting web services running on the Greenstone 3 server) on one machine, your gs3-webservices-democlient can access these services if you install this client application on another machine.
+
+
+
If you haven't already done so, deploy the QBRSOAPServer web services on one computer.
+
Point your web browser to the http://HOST:PORT/greenstone3/services page (substitute the host and port on which your Greenstone server resides).
+
Write down the URL address of "wsdl" link next to the QBRSOAPServer web service. (You can either click on the wsdl link and copy the url from the browser's address bar or hover over the link and rightclick>copy address location.) You need the url of the QBRSOAPServer web services' wsdl file in order to get your client application to work with it later (Step 7).
+
Move to another computer.
+
Download the client application as described in the section Obtaining The gs3-webservices-democlient above.
+
Run the client as described in the section Running the gs3-webservices-democlient
+
Then, follow on the steps in the section "How To Use The Client" BUT when you choose to connect to the Greenstone digital library, you will need to type in the wsdl url of the QBRSOAPServer web services deployed on the remote machine running the Greenstone 3 server. This is the wsdl url that you made a note of in step 3.
+
+We've now tested Fedora 2.2.1 and Fedora 3.0 with the GS3 web services demo-client application, where Fedora 2.2.1 was installed on Linux and Fedora 3.0 on Windows.
+
+
+
You need Greenstone 3.
+Since we will be working with Greenstone 3 documents stored in Fedora's repository as "Fedora Digital Objects", Greenstone 3 is needed for its functionality to convert GS3 documents into FedoraMETS format and put them into the Fedora repository.
+(If you only want a walkthrough on installing Fedora, then you don't need Greenstone 3 of course and can skip the parts of this document relating to that.)
+
Fedora 2.2.1 requires Java 5 (I used jdk1.5.0_10).
+If you wish to compile it yourself, you will need Apache Ant 1.6.5 and put it on your PATH.
Let's assume that when you have downloaded Fedora 2.2.1 and extracted it (as you will in Section B below), the Fedora executable stuff will go into a folder called "fedora" whose location is /full/path/to/fedora. With that in mind, we need to set the following environment variables:
+
+
JAVA_HOME - set this to the path of your JDK folder
+
FEDORA_HOME - set this to the full path to that "fedora" folder just mentioned
+
CATALINA_HOME should be set to the /full/path/to/fedora/tomcat folder.
+
The PATH variable must contain your JDK 1.5's bin folder, and the 2 bin folders of Fedora: /full/path/to/fedora/server/bin and /full/path/to/fedora/client/bin
+
If you plan on compiling it all yourself, have the full paths to Apache Ant 1.6.5 and of your JDK's bin/javac on your PATH.
+
+
+
If you're on Linux, you can set the environment variables by editing your ~/.profile file and then, after saving the edits, logging out or doing a "source ~/.profile" in the x-term.
+For example:
+
On Windows, adjustments to your PATH variable, and creation of new variables (like FEDORA_HOME, CATALINA_HOME, JAVA_HOME) are made by going to:
Start > Control Panel > (Performance and Maintenance icon OR click on Switch to Classic View on the left >) System > Advanced tab. Press the Environment Variables button. Add new System Variables and edit the existing Path variable.
+Note that on Windows, you use the ; sign to append new items to your path, and when referring to previously declared environment variables you have to surround them with % signs:
+E.g.
+
Make sure you have the environment variables set as described in Preliminary Steps above.
+
+
+
+If using Linux, then do the following from an x-term. If you're on Windows, do the same from a DOS prompt:
+
+
Move into the extracted directory (e.g. fedora-2.2.1-src/) and type:
+
ant installer
+Then go into the dist folder of the extraction directory (e.g. fedora-2.2.1-src/dist/) and type:
+
java -jar fedora-2.2.1-installer.jar
+
+
This will run the command-line installer. Choose "quick" installation.
+
+
Accept everything as given and set a password for your Fedora Administrator account whose default username is "fedoraAdmin".
+By accepting the defaults, the server will be set to run on localhost, port 8080 (with shutdown port 8005).
+Note: if you have Greenstone 3 installed at port 8080 as well, then you should not be running both at the same time (they will conflict and probably neither will work). You will need to stop Greenstone 3 in order to run Fedora on the same port, and stop Fedora to run Greenstone 3 again on the same port. Alternatively, you can choose to change the port on which Greenstone 3 runs.
+
+
+
+You will need to remember the following details of your installation:
+
+
the username for your Fedora account (default would be: fedoraAdmin)
+In order to work with the Greenstone3 client application, you will need to create a custom pid prefix for Greenstone 3 in fedora, and call it "greenstone".
+To do this, you will need to:
+
+
+
Shutdown the fedora server
+
$FEDORA_HOME/tomcat/bin/shutdown.sh
+
+
Open up fedora's configuration file in a text editor
+
$FEDORA_HOME/server/config/fedora.fcfg
+
+
Go down to where it says:
+
<param name="retainPIDs" value="demo test changeme fedora-bdef fedora-bmech tutorial">
+And append greenstone to the list of values, so you get something like:
+
<param name="retainPIDs" value="demo test changeme fedora-bdef fedora-bmech tutorial greenstone">
+
+
Restart the fedora server
+
$FEDORA_HOME/tomcat/bin/startup.sh
+
+
+
+
Having made the change in the fedora config file, it will now recognise "greenstone" as a valid PID and allow you to create/ingest digital data objects with a pid where the prefix is "greenstone".
+For more information, you may want to look at the Fedora Release Notes:
+
"PID generation has been activated. Upon ingestion, Fedora objects that pass validation are automatically assigned a unique persistent identifer or PID. The namespace prefix on the PID is determined by the namespace parameter in the fedora.cfg configuration file."
There is nothing in our Fedora repository yet. We want to have Greenstone 3 documents exported into Fedora format stored here. This is what we need Greenstone 3 for. We will be using its functionality for converting Greenstone 3 docs into FedoraMETS and exporting them into Fedora.
+Use the FLI—Fedora Librarian Interface—application to do this. Refer to the document Running FLI for information on how to do this.
+
+
+
+
http://trac.greenstone.org/browser/gsdl/trunk/bin/script/g2f-buildcol.pl
+http://trac.greenstone.org/browser/gsdl/trunk/bin/script/g2f-import.pl
+Greenstone to Fedora scripts. Similar to import.pl and buildcol.pl, g2f-import.pl first converts documents into FedoraMETS and then g2f-buildcol.pl ingests them into a Fedora repository. Needs to have FEDORA_HOME set.
To run the Fedora-client application, you would type
+
cd $FEDORA_HOME/client
+fedora-admin.sh
+
+
+
The location of the Fedora Basic Search Interface ("REST interface" as it uses Fedora's URL-based web services) is
+
http://HOST:PORT/fedora/search
+where HOST and PORT depend on what you chose when you installed it. E.g. http://localhost:8080/fedora/search
+Note that the default search functionality that Fedora's own access web services (API-A) provide do not include full-text indexing and searching.
+
+
To install Fedora Generic Search—which provides full-text indexing and search capabilities for content stored in a Fedora repository—see the document Installing Fedora Generic Search.
+
Fedora Generic Search (Fedora GSearch) provides full-text indexing and searching for Fedora. This functionality is not offered by Fedora out-of-the-box, which is why it's a good idea to install Fedora GSearch alongside it.
+
+In this document,
+
+
$FEDORA_HOME refers to the full path to your Fedora installation directory.
+
You need to have Fedora installed in order to install Fedora Generic Search.
+For a walkthrough on installing Fedora (and for links to the official Fedora instructions for installation) see Installing Fedora.
+
+
+
+This document describes two ways in which you can install Fedora Generic Search:
+
+
By downloading Muradora's version of the fedoragsearch.war file and then using the GSearchInstaller application, or
Download the GSearchInstaller.jar from the same place where you got the GS3 Web Services Demo-Client (GSearchInstaller.jar is part of the GS3 Web Services Demo-Client distribution file).
+
In a Linux x-term or a Windows DOS prompt, go to the location where your GSearchInstaller.jar is located, and type
+
java -jar GSearchInstaller.jar
+This will launch the installer's opening dialog.
+(It is recommended that Windows users don't just double-click on the jar file as the application's output will indicate whether and where anything failed during installation. This output is sent to the DOS console which won't be there if you run the jar-file by double-clicking.)
+
Type in your Fedora server host, port, username and password. Then choose a name for the Fedora GSearch index and repository. (By default, the GS3 Web Services Demo-Client application expects the index name to be FedoraIndex. If you choose something other than FedoraIndex as the index name, follow the steps in Important Note #2.) Finally, browse to the location of your Muradora fedorgsearch.war file.
+Note: GSearchInstaller can also be run from the command-line, by passing command-line arguments to GSearchInstaller.jar. To find out what the accepted arguments are, run it with the -help flag:
+
java -jar GSearchInstaller.jar -help
+
+
It will take a little while to run, and if nothing went wrong, it will have installed Fedora Generic Search and indexed the Greenstone documents that were ingested into Fedora using FLI.
+If you're running on Windows, GSearchInstaller will sadly open quite a number of DOS consoles and leave them open. You'll have to manually close each of them (for instance, by typing exit in them).
Next to the steps above, you will need to make some more changes in order to enable full-text indexing and searching of the Greenstone documents ingested into the Fedora repository.
+
+
+At present, Muradora's file allows all digital objects in your Fedora repository to be indexed and searchable. If you're alright with indexing just the Greenstone documents stored in Fedora's repository, then we'll add the following to the above file:
+
+The field ds.label and a document's full-text can now be searched and will appear in the search results. (Only a customisable snippet-size of a document's full-text will present in the results of a search.)
+
Once installed, the FedoraGSearch rest url will by default be at:
+
http://localhost:8080/fedoragsearch/rest
+If you visit this page, there are links to doing searches and browsing the Fedora repository's full-text contexts.
+
Make sure that upon installing Fedora Generic Search (whether using GSearchInstaller or installing manually), you either:
+
+
choose to call your index FedoraIndex since this is what the demo-client expects by default, or
+
create a file called gs3democlient.properties in the same folder as where the demo-client executable is, unless such a file already exists. Then in that properties file, write down the name of your index for the property gsearch.indexName as follows:
+
gsearch.indexName=your-fedora-index-name
+If you had to create the properties file, you'd have to create this property as well. But if the file already existed, then the property gsearch.indexName would have been in there and you need only adjust the index name it is set to to your own.
+
+
+
+
IMPORTANT: Fedora Generic Search only supports indexing and searching Fedora Digital Objects (Fedora repository contents) whose MIME-type is one of
+
+
text/html
+
text/plain
+
application/pdf
+
+Text/xml is not accepted. (Therefore Greenstone documents exported to FedoraMETS and ingested into Fedora must be of one of the above MIME-types, else they will not be indexed by Fedora Generic Search.)
+At present, FLI sets the content-type of the Fedora METS documents it exports to being text/xml. Therefore these documents don't yet get indexed by Fedora Generic Search. In order to do that, you need to use Fedora's Admin-Client application to change the content-type for the documents FLI puts into Fedora from text/xml to text/html.
+
+
+
+
Index: other-projects/gs3-webservices-java-client/trunk/docs/HowToFiles/5ExposingYourGS3WebServicesOnGS3Server.html
===================================================================
--- other-projects/gs3-webservices-java-client/trunk/docs/HowToFiles/5ExposingYourGS3WebServicesOnGS3Server.html (revision 21027)
+++ other-projects/gs3-webservices-java-client/trunk/docs/HowToFiles/5ExposingYourGS3WebServicesOnGS3Server.html (revision 21027)
@@ -0,0 +1,97 @@
+
+
+
+
+How to expose custom Greenstone 3 web services on GS3's server
+
+
+Back to index page
+
+
How to expose custom Greenstone 3 web services on GS3's server
+
+What you need:
+
+
Java JDK installed
+
Greenstone 3
+
+
+In this document,
+
+
$GSDL3HOME refers to the full path to your Greenstone 3 installation.
+
GS3 may be used as a shorthand to refer to Greenstone 3.
+In the steps below, I am assuming that your web service class will be passing either
+
+
simple data types: strings, ints, floats, characters, boolean, arrays of simple data types, etc., or
+
Java Collection data types: HashMap, Sets, Lists of simple data types, for which Apache Axis--which comes with Greenstone 3--already provides web service support.
+
+If this is indeed the case, the default behaviour that will apply when the steps below are followed will be appropriate.
+DETAILS: This default behaviour is that the "provider" property of the web service will be set to Java:RPC in the web service descriptor file (*.wsdd) used by Apache Axis to deploy your web service.
+
+
Assuming that your web service class is going to make use of Greenstone 3 functionality, the classpath to all of Greenstone 3's java code is already available in the Ant buildfile that will be used to expose your web services on Greenstone 3's services page.
+
+
+
Write the Java class that will contain the methods you wish to expose as operations on Greenstone's "services" page.
+Note that I haven't tried working with constructors other than the default constructors (the ones that take no parameters).
+
Copy the contents of the java file into a new java file and name it <someWebService>SOAPServer.java.in. For example, this duplicate file would be called MyServicesSOAPServer.java.in
+
Edit <someWebService>SOAPServer.java.in so that
+
+
its class name is <someWebService>SOAPServer@sitename@
+
its constructor is similarly called <someWebService>SOAPServer@sitename@
+
Any other explicit references in the file to the class name must similarly be renamed to <someWebService>SOAPServer@sitename@. For instance, a Logger object for the class or static references to the class must now refer to <someWebService>SOAPServer@sitename@.
+
+
+
Place the file <someWebService>SOAPServer.java.in into the folder $GSDL3HOME/resources/java, alongside the other SOAPServer.java.in already in here.
+
OPTIONAL STEP: Open $GSDL3HOME/build.xml and you can add your web service name (<someWebService>SOAPServer) to the list of web services already mentioned in there. This will then be available in the command-line menu when you try to deploy a web service using Apache Ant.
Open an X-term or DOS-prompt and go into the $GSDL3HOME directory.
+
Make sure that Greenstone 3's Tomcat server is running. If it's not running, do:
+
ant start
+
+
Deploy your site by typing:
+
ant soap-deploy-site
+It will ask you 3 things:
+
+
Type the name of the Site you wish to deploy it for. It can be any existing remote Site that you have access to, or if you wish to deploy it locally, you would type
+
localsite
+
+
Type the name of the Greenstone 3 web service you wish to deploy. The default Greenstone 3 SOAPServer and QBRSOAPServer (for Query, Browse and Retrieve operations) are already in the list of web services that can be deployed. And because you have now added your web service class in there as well, you can type its name:
+
<someWebService>SOAPServer
+
+
Finally, give the web service a name. For instance, you can type "MyGS3WebServices" or something more descriptive of the web services you have created. Alternatively, you can choose the default web service name it will give you, which will be of the form
+It's handy to remember the name of the web services you deployed in case you wish to undeploy it (see Section C below).
+
+
+
+
If all goes well, it will have deployed your web service. To check that this is indeed the case, point your web browser to the greenstone server's services page for the Site you deployed the web service for. This page will list all the web services deployed.
+For example, the http://HOST:PORT/greenstone3/services page, when deployed for the Site "localsite" if on localhost and port 8080, would be http://localhost:8080/greenstone3/services
+
You need the name of the web services you deployed. If you don't remember, go to the services page for the Site you deployed it on. (http://HOST:PORT/greenstone3/services for the HOST and PORT values that apply to your deployment situation).
+
+
Open an X-term or DOS prompt and go into the $GSDL3HOME folder.
+
Type:
+
soap-undeploy-site
+It will ask you for the name of the web service you wish to undeploy. Type the name.
+
If your web service was deployed and you typed the web service name correctly, it will now be undeployed. To check, go to http://HOST:PORT/greenstone3/services and check that your web service is no longer in the list of hosted services.
+
+
+
+
+
Index: other-projects/gs3-webservices-java-client/trunk/docs/HowToFiles/6WritingAWebServiceClient.html
===================================================================
--- other-projects/gs3-webservices-java-client/trunk/docs/HowToFiles/6WritingAWebServiceClient.html (revision 21027)
+++ other-projects/gs3-webservices-java-client/trunk/docs/HowToFiles/6WritingAWebServiceClient.html (revision 21027)
@@ -0,0 +1,496 @@
+
+
+
+
+How to write a simple client for Greenstone 3 web services
+
+
+Back to index page
+
+
How to write a simple client for Greenstone 3 web services
+We'll be going through an example of how to write a simple client for Greenstone 3's Query, Browse and Retrieval web services provided by QBRSOAPServer.
+
+
In this document,
+
+
$GSDLHOME is the full path to your greenstone 3 directory.
First we need Greenstone 3 to deploy the web services in order for our client to have access to its operations.
+Go to $GSDLHOME and type in an X-term:
+
ant soap-deploy-site
+
+It will ask you for the
+
+
The greenstone Site you wish to deploy the services for.
+
The name of the web services you wish to deploy. There are two available for Greenstone 3 so far (the default fundamental SOAPServer and the QBRSOAPServer that provides basic query, browse and retrieve functions for GS3). Choose from one of these.
+
Give the web service a name.
+
+
+If you go to the page
+
http://HOST:PORT/greenstone3/services
+you will see links to various wsdl files. The one for the QBRSOAPServer we just deployed for "localsite" is the one our example program will be using to communicate with Greenstone 3's QBRSOAPServer functionality. The localsite web service has several query, browse and retrieve operations as well as describe operations which will describe the details of these Greenstone 3 services.
+
+
Now you can invoke the localsite process method by writing a client.
+The basics of invoking a web service operation in Java when using Apache Axis, is to
+
+
Then write a constructor that will create the Service object using the url for the web service's wsdl file and the (namespace-qualified) name of the web service.
+
try {
+ service = new Service(wsdlURLName, new QName(namespace, serviceName));
+ } catch(ServiceException e) {
+ System.err.println("Unable to connect to web services.\nExiting...");
+ throw(e);
+ }
+
+
+
In order to invoke a web service operation, use that Service object to create a Call object for the operation. You need the (namespace-qualified) portName of the web service, which can be found in the wsdl file. Similarly, you need the name of the operation, also found in the wsdl file:
+
Call call = (Call)this.service.createCall(
+ new QName(namespace, portName),
+ new QName(namespace, OPERATION_NAME)
+ );
+
+
+
Finally, invoke the operation using that call object by
+
+
putting the operation's parameters in the right order into an array of Objects and passing that to Call's invoke() method.
+
by casting the return value to the expected return type.
+
+We're going to write a simple client for the QBRSOAPServer.
+
+
+
Deploy the QBRSOAPServer in order to have our client access it.
+Go to $GSDLHOME and type in an X-term:
+
ant soap-deploy-site
+For our example:
+
+
type "localsite", to deploy the services locally.
+
type "QBRSOAPServer", to deploy the Query, Browse and Retrieve services.
+
press Enter to accept the default web service name of "QBRSOAPServerlocalsite".
+
+
+
The following GreenstoneConnection class is a simple client for QBRSOAPServer web service that merely uses its query and describeCollectionService web service operations in order to execute a FieldQuery on the gs2mgppdemo collection:
+
+import org.apache.axis.client.Call;
+import org.apache.axis.client.Service;
+import javax.xml.namespace.QName;
+import javax.xml.rpc.ServiceException;
+
+import java.util.Map;
+import java.util.HashMap;
+
+/** The class that connects to Greenstone 3's QBRSoapServerLocalsite web service
+ * For this to work, you need to have the QBRSOAPServer web services deployed for
+ * localsite. Once deployed, the wsdl file of QBRSOAPServer describing its web
+ * services can be found off the page http://HOST:PORT/greenstone3/services/
+*/
+public class GreenstoneConnection {
+ static final String HOST = "localhost";
+ static final String PORT = "9090";
+
+ // Name of web service methods we are going to invoke.
+ // We can get these from wsdl file.
+ static final String QUERY_METHOD = "query";
+ static final String DESCRIBE_COLLECTION_SERVICE_METHOD
+ = "describeCollectionService";
+
+
+ /** Axis Service object for connecting to Greenstone 3's 'QBRSOAPServer' Web Services
+ * using its WSDL file, in order to invoke these web services */
+ protected Service service;
+
+ // Inspect the wsdl file to find, at the very bottom, the service name, port name and soap address
+ //endpoint locations:
+ // <wsdl:service name="QBRSOAPServerlocalsiteService">
+ // <wsdl:port binding="impl:QBRSOAPServerlocalsiteSoapBinding" name="QBRSOAPServerlocalsite">
+ // <wsdlsoap:address location="http://HOST:PORT/greenstone3/services/QBRSOAPServerlocalsite"/>
+ // </wsdl:port>
+ // </wsdl:service>
+ // Using the above, we can create the axis Service and Call
+ // objects. At present, I am hard coding the values here as
+ // an example but you would usually discover the names of the
+ // xml tags programmatically, by either letting the Service
+ // object parse the wsdl for you or by parsing it yourself.
+ // Read-only instance variables
+ final String wsdlURLName;
+ final String namespace = "http://"+HOST+":"+PORT+"/greenstone3/services/QBRSOAPServerlocalsite";
+ final String serviceName = "QBRSOAPServerlocalsiteService";
+ final String portName = "QBRSOAPServerlocalsite";
+
+
+ // Constructor, takes a String representing the URL of the web service's
+ // wsdl file. This can be found off the Greenstone 3 services page
+ // http://HOST:PORT/greenstone3/services/
+ public GreenstoneConnection(String wsdlURLName)
+ throws Exception
+ {
+ this.wsdlURLName = wsdlURLName;
+ // create the service object needed to invoke the web service later on
+ try {
+ service = new Service(wsdlURLName, new QName(namespace, serviceName));
+ } catch(ServiceException e) {
+ System.err.println("Unable to connect to web services.\nExiting...");
+ throw(e);
+ }
+ }
+
+ /** See http://ws.apache.org/axis/java/apiDocs/org/apache/axis/client/Service.html#createCall(javax.xml.namespace.QName,%20javax.xml.namespace.QName)
+ * public Call createCall(QName portName,QName operationName)throws ServiceException
+ * "Creates a new Call object - will prefill as much info from the
+ * WSDL as it can. Right now it's target URL, SOAPAction, Parameter types,
+ * and return type of the Web Service."
+ * This query method invokes the query web service operation.
+ * One way you can find the parameters required by the query method
+ * is by inspecting the wsdl file.
+ * <wsdl:message name="queryRequest">
+ * <wsdl:part name="collection" type="xsd:string"/>
+ * <wsdl:part name="service" type="xsd:string"/>
+ * <wsdl:part name="lang" type="xsd:string"/>
+ * <wsdl:part name="nameToValsMap" type="apachesoap:Map"/>
+ * </wsdl:message>
+ *
+ * From the wsdl file, we also know that the return type is String:
+ * <wsdl:message name="queryResponse">
+ * <wsdl:part name="queryReturn" type="xsd:string"/>
+ * </wsdl:message>
+ */
+ public String query(String collection, String service, String lang,
+ Map nameToValsMap)
+ {
+ try {
+ // try invoking the process() method
+ Call call = (Call)this.service.createCall(
+ new QName(namespace, portName),
+ new QName(namespace, QUERY_METHOD)
+ );
+
+ // Now call the web service and pass it all the parameters as part
+ // of an array of Objects.
+ // Knowing that the return type is String, we cast the Object
+ // returned into String prior to returning it.
+ String response = (String) call.invoke(new Object[]{
+ collection, service, lang, nameToValsMap});
+
+ // later cast the return type to the correct format and return it:
+ return response;
+
+ // Note that for more complicated return types (like certain collection
+ // types or complex types), you may have to find out what the class
+ // of the return value is. For instance, when a group of elements are
+ // returned, the return type may be Array or ArrayList or something similar.
+ // In such cases, you need to find the type of each element in the array.
+ // This is necessary in order to cast the return value into the correct type.
+ // System.err.println("Return type is: " + response.getClass().getName());
+ // later cast the return type to the correct format and return it:
+ // return (Element[])response;
+ } catch(Exception e) {
+ System.err.println("ERROR trying to invoke web service" + e);
+ }
+ return "";
+ }
+
+ /** Sending a describe request to the FieldQuery service in order to
+ * find out what parameters a Greenstone 3 FieldQuery operation requires.
+ * This method invokes the web service operation describeCollectionService()
+ * for the FieldQuery service of gs2mgppdemo. */
+ public String describeFieldQueryService(String collection, String lang) {
+ // One of the query services available for collections gs2mgppdemo
+ // and gs2mgdemo
+ final String FIELD_QUERY_SERVICE = "FieldQuery";
+ try {
+ // try invoking the process() method
+ Call call = (Call)this.service.createCall(
+ new QName(namespace, portName),
+ new QName(namespace, DESCRIBE_COLLECTION_SERVICE_METHOD)
+ );
+
+ // We know that the describeService returns a String, so we
+ // cast the return value appropriately.
+ // From the wsdl, the describeCollectionService web service
+ // operation takes 4 String parameters: collection, service,
+ // language and subsetOption.
+ // We'll pass "" for that last one, since we don't want to
+ // retrieve a subset of the describeCollService XML response,
+ // but all of the response.
+ String response = (String) call.invoke(new Object[]{
+ collection, FIELD_QUERY_SERVICE, lang, ""});
+
+ // later cast the return type to the correct format and return it:
+ return response;
+
+ // Note that for more complicated return types (like certain collection
+ // types or complex types), you may have to find out what the class
+ // of the return value is. For instance, when a group of elements are
+ // returned, the return type may be Array or ArrayList or something similar.
+ // In such cases, you need to find the type of each element in the array.
+ // This is necessary in order to cast the return value into the correct type.
+ // System.err.println("Return type is: " + response.getClass().getName());
+ // later cast the return type to the correct format and return it:
+ // return (Element[])response;
+ } catch(Exception e) {
+ System.err.println("ERROR trying to invoke web service" + e);
+ }
+ return "";
+ }
+
+
+ public static void main(String[] args) {
+ try {
+ // Constructor requires wsdl url of the localsite's web services.
+ // Once the QBRSOAPServer web services have been deployed, we can
+ // find this url off greenstone's services page
+ // http://HOST:PORT/greenstone3/services/
+ GreenstoneConnection gCon = new GreenstoneConnection(
+ "http://"+HOST+":"+PORT+"/greenstone3/services/QBRSOAPServerlocalsite?wsdl");
+
+ final String language = "en"; // for English
+ String fieldQueryDescription = gCon.describeFieldQueryService(
+ "gs2mgppdemo", language);
+
+ // Inspect the output in order to move on to the next step.
+ System.out.println("THE DESCRIPTION RETURNED FOR THE FieldQuery"
+ + " SERVICE IS: " + fieldQueryDescription);
+
+ // Now that we sent a describe message to the FieldQuery Service to
+ // tell us the parameters required by the FieldQuery web service
+ // operation, the XML response told us all the parameters required.
+ // Let's use the gs2mgppdemo collection's FieldQuery service to
+ // query for "snails". The query web service operation takes a
+ // Map of (name, value) pairs where name is the name of the query
+ // parameter (e.g. which indexed field to search in,
+ // the search terms themselves or whether casefolding is on or off)
+ HashMap map = new HashMap();
+ map.put("maxDocs", "100");
+ map.put("level", "Sec");
+ map.put("accent", "1");
+ map.put("matchMode", "some");
+ map.put("fqf", "ZZ,ZZ,ZZ,ZZ");
+ map.put("case", "1");
+ map.put("sortBy", "1");
+ map.put("fqv", "snail,water,,");
+
+ String queryResult = gCon.query("gs2mgppdemo", "FieldQuery", language, map);
+
+ // print out the response to the query request
+ System.out.println("RESULT OF EXECUTING THE QUERY: " + queryResult);
+
+ }catch (Exception e) {
+ System.err.println("In main. Exception: " + e);
+ }
+ }
+}
+
+
+
In order to compile the above client code, the required jar files are
+
+
$GSDLHOME/web/WEB-INF/lib/axis.jar
+
$GSDLHOME/web/WEB-INF/lib/jaxrpc.jar
+
+
+
To get above client code to run you need to have the necessary jar files in the run path as well. (If you try to run the application, it will throw errors telling you which jars are missing.)
+For running the above example code, you need to add the following jar files to the execution classpath:
+
+
commons-logging-**.jar
+
commons-discovery-**.jar
+
saaj.jar
+
wsdl4j-**.jar
+
activation.jar
+
+All of these can be found in the $GSDLHOME/web/WEB-INF/lib folder.
+
+
Try executing the code in 2 above. My output is:
+
+Here, we will write a web service in Java and use Apache Axis (which is installed with Greenstone 3) to deploy the web services. Otherwise we won't really be using Greenstone 3.
+
+
+
Write a Java class that will become the web service.
+For example here's UsernameService.java:
+
+package org.greenstone;
+
+public class UsernameService {
+ public String getUsername() { return "pinky"; }
+}
+
+Compile it. (Say in Eclipse.)
+
+
Copy the *.class file into the correct package structure inside web/WEB-INF/lib/classes folder of Apache axis.
+Since we are using Greenstone 3, this is $GSDLHOME/web/WEB-INF/classes/. Therefore, in our example, we would copy UsernameService.class into $GSDLHOME/web/WEB-INF/lib/classes/org/greenstone/
+
+
+
Once you have deployed localsite (or other site) in Greenstone3 using
+
ant deploy-localsite
+the file $GSDLHOME/web/WEB-INF/server-config.wsdd would have been generated.
+It would contain one or more <service> elements.
+
+
Stop Greenstone's tomcat:
+
ant stop
+
+Copy an existing <service> element in order to create a <service> element for your web service.
+In our example case, you could have:
+
Set the service's provider attribute to "java:RPC"
+
The serviceName is what you want appearing in the wsdl file (it need not be the same as the class name)
+
the className value is your web service Java class with full-package structure.
+
set the parameter allowedMethods to either the single method to be exposed, or if there is a list of them, then set the value to a comma-separated list of method names, or if you want ALL the class' public methods exposed, put a * for the value. See example below:
+
+Tried to run axis AdminClient on the server-config.wsdd (service descriptor) file and got an AxisFault Exception?
+SOLUTION: You have to run tomcat (ant start) before running AdminClient.
+
+
+
Index: other-projects/gs3-webservices-java-client/trunk/docs/HowToFiles/8RunFedoraLibrarianInterface.html
===================================================================
--- other-projects/gs3-webservices-java-client/trunk/docs/HowToFiles/8RunFedoraLibrarianInterface.html (revision 21027)
+++ other-projects/gs3-webservices-java-client/trunk/docs/HowToFiles/8RunFedoraLibrarianInterface.html (revision 21027)
@@ -0,0 +1,68 @@
+
+
+
+
+Running FLI, the Fedora Librarian Interface
+
+
+Back to index page
+
+
FLI is built on top of GLI. Just as with GLI, it allows you to drag-and-drop documents into a collection which it will then build. The building process of FLI is different in that it will export the documents into a Fedora repository.
You need the Greenstone server to be running on the same machine as where your Fedora machine is running. This may not be a requirement in the future, but it is at present.
You need Fedora installed (which would have required you to set the environment variables FEDORA_HOME, CATALINA_HOME and JAVA_HOME, which are also needed by FLI). And:
+
+
You need to add a new environment variable called FEDORA_VERSION. If the version you have installed is Fedora 2.*, then you set this to 2, if you have Fedora 3.* installed, then you'd set this environment variable to 3.
+
+
+
+
You need the Greenstone server running on the same machine as where your Fedora server is installed.
If you have more than one Greenstone installed (Greenstone 2 and Greenstone 3), then first run the setup file for the Greenstone installation you want to use, so that your Greenstone environment is set up.
+If you were on linux, you would have to source the setup scripts by going into the Greenstone installation directory.
+For Greenstone 2, you'd have typed:
+
source setup.bash
+And for Greenstone 3:
+
source gs3-setup.sh
+If you're on Windows you would run setup.bat in the Greenstone 2 folder or gs3-setup.bat in the Greenstone 3 folder.
+
+
If you're using a Linux xterm, you'd go into Greenstone's gli folder and type:
+
./fli.sh
+If you're on Windows, go into Greenstone's gli folder and double-click on fli.bat
+
+
Once FLI starts up, it will ask you the Fedora server details and your Fedora username and password to access the Fedora repository.
+
Drag and drop documents into a collection as before, go to the Build tab and press the Build button. Once the building is finished, pressing the preview button will open the browser onto the Fedora search page.
+
+
If you have other digital objects in your Fedora repository besides the content generated by Greenstone, you will have to type
+
"greenstone:*"
+or just
+
"greenstone*"
+in the search box—with the quotes.
+If your Fedora repository only contains documents built in FLI, then pressing just the search button should be fine.
+
+
+
+
+
Index: other-projects/gs3-webservices-java-client/trunk/docs/HowToFiles/index.html
===================================================================
--- other-projects/gs3-webservices-java-client/trunk/docs/HowToFiles/index.html (revision 21027)
+++ other-projects/gs3-webservices-java-client/trunk/docs/HowToFiles/index.html (revision 21027)
@@ -0,0 +1,29 @@
+
+
+
+
+List of documents related to GS3 web services and the demo-client
+
+
+
List of documents related to GS3 web services and the demo-client application
+ * Copyright (C) 2008 New Zealand Digital Library Project
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *########################################################################
+ */
+package org.greenstone.gs3client;
+
+import javax.swing.JPopupMenu;
+import javax.swing.JList;
+import javax.swing.JPanel;
+import javax.swing.JScrollPane;
+import javax.swing.JEditorPane;
+import javax.swing.BorderFactory;
+import javax.swing.JButton;
+import javax.swing.JSplitPane;
+import javax.swing.JLabel;
+
+import java.awt.event.ActionListener;
+import java.awt.event.ActionEvent;
+
+import java.awt.Component;
+import java.awt.Container;
+import java.awt.Cursor;
+import java.awt.Dimension;
+import java.awt.BorderLayout;
+
+import org.w3c.dom.Element;
+import org.w3c.dom.NodeList;
+
+import java.net.MalformedURLException;
+import java.net.URL;
+import java.util.Vector;
+import java.util.HashMap;
+
+import javax.swing.JTree;
+import javax.swing.text.html.HTMLDocument;
+import javax.swing.tree.DefaultMutableTreeNode;
+import javax.swing.tree.TreeSelectionModel;
+import javax.swing.tree.DefaultTreeModel;
+import javax.swing.event.TreeWillExpandListener;
+import javax.swing.event.TreeExpansionEvent;
+import javax.swing.event.TreeSelectionEvent;
+import javax.swing.event.TreeSelectionListener;
+
+import org.apache.log4j.Logger;
+import org.greenstone.gs3client.data.BrowseResponseData;
+import org.greenstone.gs3client.data.DocumentNodeData;
+import org.greenstone.gs3client.data.ClassifierNodeData;
+import org.greenstone.gs3client.data.NodeData;
+import org.greenstone.gs3client.data.ParseUtil;
+import org.greenstone.gsdl3.util.GSXML;
+
+/**
+ * The Browse panel inside the Java-client's tab pane that's labelled "Browse".
+ * This panel contains a tree view for expanding classifiers and their documents.
+ * It also contains an area where the metadata is displayed, and a text area where
+ * the textual or image content of a selected documentNode is displayed.
+ * @author ak19
+*/
+public class BrowseDisplay extends JPanel
+ implements TreeSelectionListener, TreeWillExpandListener,
+ ColourCombo.ColourChangeable
+{
+ /** The Logger for this class */
+ static Logger LOG = Logger.getLogger(SearchResultsDisplay.class);
+
+ /** Access to the running instance of GS3JavaClient */
+ protected GS3JavaClient client;
+ /** A HashMap to store the displayData for the Browse operation. Usually
+ * just 2 elements long at most: displayName and displayDescription. */
+ protected HashMap displayData;
+
+ /* GUI items of this Browse Panel */
+ protected JLabel browseLabel;
+ protected JPanel browsePanel;
+ protected JSplitPane splitViewPane, structureMetaView;
+ protected JPanel browseBar;
+ protected ClassifierButton[] classifierList;
+ protected JTree browsingTree;
+ protected JEditorPane htmlPane;
+ protected JList metanames, metavalues;
+ /** Context menu that pops up when users right click in the browse tree area */
+ protected JPopupMenu popup;
+
+ /** Constructor that creates the Browse Panel and its internal GUI items.
+ * @param client is the running instance of the client application through
+ * which its methods can be accessed. */
+ public BrowseDisplay(GS3JavaClient client) {
+ super(new BorderLayout());
+ this.client = client;
+ displayData = new HashMap(2); //usual maxsize
+
+ browseBar = new JPanel(); // default FlowLayout L to R, centre aligned
+ classifierList = null;
+ this.add(browseBar, BorderLayout.NORTH);
+
+ browsingTree = new JTree(new DefaultMutableTreeNode(null));
+ browsingTree.getSelectionModel().setSelectionMode(
+ TreeSelectionModel.SINGLE_TREE_SELECTION);
+ browsingTree.addTreeSelectionListener(this);
+ browsingTree.addTreeWillExpandListener(this);
+
+ browsePanel = new JPanel(new BorderLayout());
+ // new FlowLayout(FlowLayout.LEFT)); // don't use this,
+ // else view of tree is limited to the very minimum
+ browsePanel.add(new JScrollPane(browsingTree), BorderLayout.CENTER);
+ browseLabel = new JLabel("Browsing by...");
+ browsePanel.add(browseLabel, BorderLayout.NORTH);
+
+ JPanel metadataPanel = new JPanel(new BorderLayout());
+ this.metanames = new JList();
+ this.metavalues = new JList();
+ metadataPanel.add(metanames, BorderLayout.WEST);
+ metadataPanel.add(metavalues, BorderLayout.CENTER);
+
+ JPanel metaSuperPanel = new JPanel(new BorderLayout());
+ metaSuperPanel.add(new JLabel("Metadata"), BorderLayout.NORTH);
+ //metaSuperPanel.add(metadataPanel, BorderLayout.CENTER);
+ metaSuperPanel.add(
+ new JScrollPane(metadataPanel), BorderLayout.CENTER);
+
+ structureMetaView = new JSplitPane(JSplitPane.VERTICAL_SPLIT);
+ structureMetaView.setTopComponent(browsePanel);
+ structureMetaView.setBottomComponent(new JScrollPane(metaSuperPanel));
+ structureMetaView.setOneTouchExpandable(true);
+
+ htmlPane = new JEditorPane();
+ htmlPane.setEditable(false);
+ htmlPane.setContentType("text/html");
+
+ // Add the docStructure and metadata panels next to each
+ // other within a split pane
+ splitViewPane = new JSplitPane(JSplitPane.HORIZONTAL_SPLIT);
+ splitViewPane.setLeftComponent(structureMetaView);
+ splitViewPane.setRightComponent(new JScrollPane(htmlPane));
+ splitViewPane.setOneTouchExpandable(true);
+
+ this.add(splitViewPane, BorderLayout.CENTER);
+
+
+ // add a (rightclick) popup menu to the browsing tree
+ // (can only do this after tree and htmlPane have been instantiated):
+ popup = new JPopupMenu();
+ browsingTree.setComponentPopupMenu(popup);
+ browsingTree.addMouseListener(new Displays.PopupListener(
+ popup, browsingTree, client, this.htmlPane));
+ }
+
+ /** Clears the service-specific buttons in the browseBar and the
+ * service-specific display-data. The rest of the GUI (split panes, panels)
+ * remain as they are. */
+ public void clear() {
+ // empty the docStructureTree's popup menu too
+ popup.removeAll();
+
+ browseBar.removeAll();
+ displayData.clear();
+
+ htmlPane.setText("");
+ // empty any classification/document metadata
+ final String[] empty = {};
+ BrowseDisplay.this.metanames.setListData(empty);
+ BrowseDisplay.this.metavalues.setListData(empty);
+ //metanames.removeAll(); // doesn't work
+ //metavalues.removeAll(); // doesn't work
+
+ // empty the tree:
+ ((DefaultTreeModel)browsingTree.getModel()).setRoot(null);
+
+ classifierList = null;
+ System.gc();
+
+ this.validate();
+ }
+
+ /** Changes the colour of the query form and its controls to the
+ * current colours set in class ColourCombo. Specified by
+ * the ColourCombo.ColourChangeable interface. */
+ public void changeUIColour() {
+ Component[] comps = { this, this.browseBar, this.browsePanel,
+ browsingTree, metanames, metavalues, popup };
+ ColourCombo.changeColor(comps);
+ // ensures that the "metadata" JLabel (not an instance variable)
+ // is coloured appropriately as well
+ ColourCombo.changeAncestorColor(metanames);
+
+ }
+
+ /** For some reason, the overriden getPreferredSize() is not
+ * called upon resize of this panel, so I am calling it manually
+ * whenever there's a call to paint this Panel. Painting will
+ * be done when the parent container is resized (and this panel
+ * made visible) anyway, so it might as well work out what size
+ * the interior panels will have on every resize.
+ * @param g is the Graphics object
+ * @see "JPanel's paint(Graphics g)"
+ */
+ public void paint(java.awt.Graphics g) {
+ super.paint(g); // let the usual JPanel paint event happen
+ this.getPreferredSize();
+ }
+
+ // FIX ME: The following problem was 'fixed' by overriding paint:
+ // Strangely, this method is called only once! Even though it should
+ // always be called on resize as indeed happens correctly in
+ // SearchResultsDisplay.java.
+ // Reason might be because components are arranged differently in the
+ // JSplitPanes nested in this JPanel (they're arranged different from
+ // SearchResultsDisplay.java)
+ /** Overrode this method to resize the splitpanes within, upon resize.
+ * It calculates the size of this panel, as well as setting those of
+ * the splitpanes it contains based on the size of the parent container.
+ * @return the preferred dimensions of this JPanel. */
+ public Dimension getPreferredSize() {
+ Dimension size = this.getParent().getSize();
+ int x = (int)size.getWidth() / 3; // WHY DOES THIS NOT WORK?????
+ int y = (int)(size.getHeight() / 5 * 3); // WHY DOES THIS NOT WORK?????
+ structureMetaView.setDividerLocation(y); // 400
+ // structureMetaView.setDividerLocation(1.0); // as far down as
+ // possible to give more space to browse structure and less to meta
+ splitViewPane.setDividerLocation(x); // 300
+ splitViewPane.setPreferredSize(size);
+ //System.err.println("SIZE: " + this.getSize() + "y: " + y);
+ return size;
+ }
+
+ /** Will clear previous browse service's classification options and widgets,
+ * and redisplay browse options as specified by the describe Response Message
+ * XML returned from the browse Service.
+ * @param describeRespMsgTag - the (Classifier)Browse Service's describe
+ * response message element, used to reset the classifier buttons in the
+ * browseBar of this panel. */
+ public void displayBrowseOptions(Element describeRespMsgTag){
+ this.clear();
+ // First set the displayItems
+ Element service = ParseUtil.getFirstDescElementCalled(
+ describeRespMsgTag, GSXML.SERVICE_ELEM);
+
+ Vector displayItems = ParseUtil.getAllChildElementsCalled(
+ service, GSXML.DISPLAY_TEXT_ELEM);
+ if(displayItems != null) {
+ for(int i = 0; i < displayItems.size(); i++) {
+ Element e = (Element)displayItems.get(i);
+ if(!e.hasAttribute(GSXML.NAME_ATT))
+ continue;
+ // we are looking for value
+ String name = e.getAttribute(GSXML.NAME_ATT);
+ String value = ParseUtil.getBodyTextValue(e);
+ this.displayData.put(name, value);
+ }
+
+ // get descr
+ String descr = (String)displayData.get(
+ GSXML.DISPLAY_TEXT_DESCRIPTION);
+ if(descr != null)
+ this.setBorder(BorderFactory.createTitledBorder(descr));
+ }
+
+ // Now, process all items inside
+ NodeList nl = describeRespMsgTag.getElementsByTagName(
+ GSXML.CLASSIFIER_ELEM+GSXML.LIST_MODIFIER);
+ // There will be only one, as far as I can tell from the describe
+ // response returned from gs2mgppdemo's ClassifierBrowse service
+ if(nl.getLength() <= 0)
+ return; // nothing to do; but this should not happen
+ Element classifierListTag = (Element)nl.item(0);
+
+ // now get the s children from
+ nl = classifierListTag.getElementsByTagName(GSXML.CLASSIFIER_ELEM);
+ int size = nl.getLength();
+ if(size > 0)
+ classifierList = new ClassifierButton[size];
+
+ for(int i = 0; i < size; i++) {
+ Element classifier = (Element)nl.item(i);
+ classifierList[i] = new ClassifierButton(
+ new ClassifierData(classifier));
+ this.browseBar.add(classifierList[i]);
+ }
+ }
+
+ /** Called to populate the browsing tree with browse data. Only the
+ * data for the top-level classifier and its direct descendants are
+ * retrieved.
+ * @param browseResponseObj - stores the data of the response XML
+ * message returned by the (Classifier)Browse service.
+ * @param rootName - the title/name of the root classifier */
+ public void displayBrowseResults(
+ BrowseResponseData browseResponseObj, String rootName)
+ {
+ browsingTree.removeAll();
+ DefaultTreeModel model = (DefaultTreeModel)browsingTree.getModel();
+
+ ClassifierNodeData rootClassNode
+ = browseResponseObj.getRootClassifier();
+ rootClassNode.setTitle(rootName);
+ DefaultMutableTreeNode newRoot
+ = new DefaultMutableTreeNode(rootClassNode);
+
+ NodeData[] childNodes = rootClassNode.getChildren();
+ // First set their titles:
+ client.retrieveTitledStructureFor(rootClassNode);
+
+ if(childNodes != null) {
+ for(int i = 0; i < childNodes.length; i++) {
+ DefaultMutableTreeNode child
+ = new DefaultMutableTreeNode(childNodes[i]);
+ newRoot.add(child);
+ if(childNodes[i].hasChildren)
+ child.add(new DefaultMutableTreeNode(null));
+ //browsingTree.setRootVisible(false); //No, because it
+ // has a root: the root classifierNode
+ }
+ model.setRoot(newRoot);
+ }
+ }
+
+ /** This method of the TreeWillExpandListener interface is called when
+ * the user clicked on an expandable node in the browsingTree.
+ * Since we are loading substructures in the tree lazily (i.e. loading
+ * childnodes lazily) we have dummy/null childTreeNodes that make
+ * expandable parentNodes look like folders (make the parents look
+ * expandable).
+ * Therefore, when the user clicks on an expandable node, we first check
+ * whether we already have loaded the datastructure/subtree or whether
+ * its child is a dummy (null). If a dummy (null child), then we work
+ * out whether it's a classifierNodeData or a documentNodeData that the
+ * expanding treeNode represents. Based on that, we retrieve the sub-
+ * structure for the treeNode that's expanding.
+ */
+ public void treeWillExpand(TreeExpansionEvent e)
+ {
+ DefaultMutableTreeNode node = null;
+
+ // Don't use browsingTree.getLastSelectedPathComponent(). That
+ // method doesn't deal with the case when someone clicked on the
+ // expand/collapse knob next to folders.
+ // Use e.getPath().getLastPathComponent() instead:
+ node = (DefaultMutableTreeNode)e.getPath().getLastPathComponent();
+ if(node == null || node.isLeaf())
+ return; // leafnode, shouldn't happen: we're in Expansion method!
+
+ Object nodeInfo = node.getUserObject();
+
+ // First check whether this expanding/folder node's child contains
+ // a dummy object (null) or is already set:
+ DefaultMutableTreeNode child
+ = (DefaultMutableTreeNode)node.getFirstChild();
+ Object childNodeInfo = child.getUserObject();
+ // if the child is null (therefore not a NodeData object), it was a
+ // dummy we added for delayed lazy-loading - so remove child
+ if(childNodeInfo != null) {
+ return; // we've already retrieved the structure for
+ // this node, don't need to process it any further
+ }
+
+ // Child is null: not a NodeData object, so we change the dummy child.
+ // This is done by populating the node's children with the actual
+ // document node/classifier node structure:
+ node.removeAllChildren(); // first remove the dummy child
+
+ // now, construct the structure of the treenode that's expanding
+ // based on whether it represents a classifierNodeData or
+ // documentNodeData object:
+ NodeData nodeData = (NodeData)nodeInfo;
+ if(nodeData instanceof ClassifierNodeData) {
+ ClassifierNodeData classNode = (ClassifierNodeData)nodeData;
+ this.client.retrieveTitledStructureFor((classNode));
+
+ // The above will have set the expanding classNode's children.
+ // Now, we add a treeNode for each child of classNode -
+ // and for each childclassNode that's expandable, add a dummy
+ // child for them to make them expandable:
+ NodeData[] children = classNode.getChildren();
+ for(int i = 0; i < children.length; i++) {
+ DefaultMutableTreeNode childTreeNode
+ = new DefaultMutableTreeNode(children[i]);
+ node.add(childTreeNode);
+ // If the classifier node has children (expands further), make
+ // it a folder by adding in a null child to allow lazy tree-
+ // expansion as when required
+ if(children[i].hasChildren)
+ childTreeNode.add(new DefaultMutableTreeNode(null));
+ }
+ } else { // if instanceof DocumentNodeData
+ DocumentNodeData docNode = (DocumentNodeData)nodeData;
+ if(docNode.nodeType.equals(GSXML.NODE_TYPE_ROOT)) {
+ this.client.retrieveTitledStructureFor(docNode);
+
+ Displays.createNodesForChildren(docNode, node);
+ } //else { document can't be a leaf node *and* expand at the
+ // same time. So shouldn't ever be here!
+ // After all, this is the method that's called when a node
+ // is expanding, and leaf nodes should not expand.
+ //}
+ }
+ }
+
+ /** Part of the TreeWillExpandListener interface. Nothing to do here. */
+ public void treeWillCollapse(TreeExpansionEvent e) {}
+
+ /* THE FOLLOWING DOES NOT APPLY ANYMORE:
+ * In this method, we are not dealing with expandable nodes
+ * (we check for whether the clicked node is a leaf), but with document-
+ * NodeData objects that are leaves: for these, we display the document. */
+ /**
+ * Whenever an item is clicked in the browsingTree, this method is called.
+ * We display the document associated with a documentNode that is clicked,
+ * or "" for classifierNodes.
+ */
+ public void valueChanged(TreeSelectionEvent e) {
+ // remove any menuItems in the popup from the previously
+ // selected docNode
+ popup.removeAll();
+
+ DefaultMutableTreeNode node = null;
+ node = (DefaultMutableTreeNode)
+ browsingTree.getLastSelectedPathComponent();
+
+ if(node == null) return;
+ Object nodeInfo = node.getUserObject();
+ // after construction there's nothing in the trees, so check for that:
+ if(nodeInfo == null) return;
+
+ // We need to change to a Wait cursor while we load the documentNode
+ Container c = client.getContentPane();
+ c.setCursor(Cursor.getPredefinedCursor(Cursor.WAIT_CURSOR));
+
+
+ if(nodeInfo instanceof DocumentNodeData) {
+ //whether leaf or folder, the document element may contain text
+ DocumentNodeData docNode = (DocumentNodeData)nodeInfo;
+ client.retrieveContentFor(docNode);
+ // for docNodes, there's more than title metadata, so ensure
+ // all metadata has been retrieved
+ client.retrieveAllMetadataFor(docNode);
+
+ if(docNode.hasNoText()) { //NoText field is 1, meaning it's an img
+ // now display the image
+ this.htmlPane.setText(
+ Displays.getImgUrlEnclosedInHtml(docNode.getImgURL()));
+ } else { // it has text
+ // Java's htmlpane does not recognise justified alignment.
+ // It displays them all centred.
+ // So here we replace all ALIGN="JUSTIFY" with ALIGN="LEFT"
+ // (we don't do this in the DocumentNodeData class itself,
+ // because our nodeContent should not be transformed: it will
+ // display properly in browsers and other html displays).
+ //System.err.println("docNode can not be an image");
+ String docContent = docNode.getContent().replaceAll(
+ "ALIGN=\"JUSTIFY\"", "ALIGN=\"LEFT\"");
+ String baseURL = client.getBaseURL();
+ // TODO: make the docNode itself work out its URL by passing
+ // baseURL to the docNode?
+ if(!baseURL.equals("") && docNode.getRoot() != null) {
+ // "" is the case where dlAPIA = gs3
+ // where the _httpdocimg_ macro will deal with
+ // resolving the relative urls into their full ones
+ // We don't want to set the base and meddle with macro
+ // for those cases.
+ // For Fedora's case:
+ HTMLDocument doc
+ = (HTMLDocument)this.htmlPane.getDocument();
+ try{
+ URL url = new URL(baseURL+docNode.getRoot().nodeID+"/");
+ //System.err.println("url: " + url.toString());
+ doc.setBase(url);
+ //docContent = docContent.replaceAll("_httpdocimg_/", "");
+ LOG.debug(docContent);
+ }catch(MalformedURLException mex) {
+ ; //nothing to be done, leave the base as it is
+ }
+ }
+ this.htmlPane.setText(docContent);
+ }
+ this.htmlPane.setCaretPosition(0);
+ } else // treenode is a ClassifierNodeData, clear the html Pane
+ this.htmlPane.setText("");
+
+ // In any case -- whatever kind of nodedata it may be -- we display
+ // the metadata for this NodeData:
+ Displays.showMeta((NodeData)nodeInfo, metanames, metavalues);
+
+ c.setCursor(Cursor.getDefaultCursor()); // set the cursor back to normal
+ }
+
+ /** Inner class (not static, as it needs access to outerclass' this object.
+ * This class represents a button that encapsulates a ClassifierData
+ * object and sets its own name and tooltip text based on the displayName
+ * and displayDescription of that ClassifierData object. */
+ public class ClassifierButton
+ extends JButton implements ActionListener
+ {
+ /** Encapsulated classifierData obj */
+ public ClassifierData classifier;
+
+ /** Constructor that creates a button to visually represent
+ * the classifier.
+ * @param classifier - the ClassifierData object for which to
+ * create a button, using its display data. */
+ public ClassifierButton(ClassifierData classifier) {
+ super(classifier.displayName);
+ this.classifier = classifier;
+ this.setToolTipText(classifier.displayDescription);
+ this.addActionListener(this);
+ }
+
+ /** Called when someone presses the ClassifierButton: when pressed,
+ * perform the browse request associated with the classifier. */
+ public void actionPerformed(ActionEvent e) {
+ Container c = client.getContentPane();
+ c.setCursor(Cursor.getPredefinedCursor(Cursor.WAIT_CURSOR));
+ // empty the previous classification's/document's metadata
+ // and any text in the html pane
+ final String[] empty = {};
+ BrowseDisplay.this.metanames.setListData(empty);
+ BrowseDisplay.this.metavalues.setListData(empty);
+ BrowseDisplay.this.htmlPane.setText("");
+
+ // Now use the outerclass' MessagerClient object to perform the
+ // browse request:
+ BrowseDisplay.this.client.doBrowse(this.classifier);
+ BrowseDisplay.this.browseLabel.setText("Browsing by "
+ + classifier.displayName);
+ c.setCursor(Cursor.getDefaultCursor());
+ }
+ }
+
+ /** Static inner class that represents the data in a <classifier>
+ * element - itself nested inside a list (<classifierList>) of them.
+ * These elements are to be found in the response returned for a describe
+ * request sent to a collection's BrowseService. */
+ public static class ClassifierData {
+ /** The content attribute of the <classifier> */
+ public final String content;
+ /** The name attribute of the <classifier> */
+ public final String name;
+ /** The display name attribute of the <classifier> */
+ public final String displayName;
+ /** The description attribute of the <classifier> */
+ public final String displayDescription;
+
+ /** Constructor.
+ * @param classifierTag - creates a ClassifierData object from the
+ * data stored in a <classifier> element */
+ public ClassifierData(Element classifierTag) {
+ content = classifierTag.hasAttribute(GSXML.CLASSIFIER_CONTENT_ATT) ?
+ classifierTag.getAttribute(GSXML.CLASSIFIER_CONTENT_ATT) : "";
+ name = classifierTag.hasAttribute(GSXML.NAME_ATT) ?
+ classifierTag.getAttribute(GSXML.NAME_ATT) : "";
+
+ // now get value
+ // and descr
+ HashMap displayData = new HashMap(2); //size = 2, because
+ // generally expecting only display Name and Description
+ NodeList nl = classifierTag.getElementsByTagName(
+ GSXML.DISPLAY_TEXT_ELEM);
+ for(int i = 0; i < nl.getLength(); i++) {
+ Element displayItem = (Element)nl.item(0);
+ if(displayItem.hasAttribute(GSXML.NAME_ATT)) {
+ String nameAtt = displayItem.getAttribute(GSXML.NAME_ATT);
+ String value = ParseUtil.getBodyTextValue(displayItem);
+ displayData.put(nameAtt, value);
+ }
+ }
+ String dName = (String)displayData.get(GSXML.DISPLAY_TEXT_NAME);
+ String dDescr = (String)displayData.get(
+ GSXML.DISPLAY_TEXT_DESCRIPTION);
+ this.displayName = (dName == null) ? "" : dName;
+ this.displayDescription = (dDescr == null) ? "" : dDescr;
+
+ // Can get rid of HashMap now:
+ displayData.clear();
+ displayData = null;
+ }
+
+ /** The displayName can be used as a label in any widget.
+ * @return the displayName of this ClassifierData object */
+ public String toString() { return this.displayName; }
+
+ /** @return a display String with the data stored in this ClassifierData
+ * object. Useful for debugging purposes. */
+ public String show() {
+ StringBuffer buf = new StringBuffer(this.name);
+ buf.append(" ");
+ buf.append(this.content);
+ buf.append(" ");
+ buf.append(this.displayName);
+ buf.append(" ");
+ buf.append(this.displayDescription);
+
+ return buf.toString();
+ }
+ }
+}
Index: other-projects/gs3-webservices-java-client/trunk/src/GS3DemoClient/org/greenstone/gs3client/ColourCombo.java
===================================================================
--- other-projects/gs3-webservices-java-client/trunk/src/GS3DemoClient/org/greenstone/gs3client/ColourCombo.java (revision 21027)
+++ other-projects/gs3-webservices-java-client/trunk/src/GS3DemoClient/org/greenstone/gs3client/ColourCombo.java (revision 21027)
@@ -0,0 +1,191 @@
+package org.greenstone.gs3client;
+
+import java.awt.Color;
+import java.awt.Component;
+import javax.swing.JTextField;
+
+
+/**
+ * Background and selection color combinations for the Java-Client's
+ * interface. Stores Greenstone, Fedora and default colour combinations
+ * and has methods for converting colours of items.
+ * @author ak19
+*/
+public class ColourCombo {
+ /** Interface ColourChangeable defines one method, changeUIColour(),
+ * which classes whose user-interface colours can change may
+ * implement. They can then choose to call either of ColourCombo's
+ * changeColor() methods or changeAncestorColor() if necessary.
+ * Though it's not compulsory to implement this interface, it may
+ * help in grouping the classes that are ColourChangeable. */
+ public interface ColourChangeable {
+ /** Subclasses define this method in order to change the
+ * colour of the interface */
+ public void changeUIColour();
+ }
+
+ /* Some fixed colours to be used in the user interface of GS3JavaClient */
+ /** Greenstone transparent background colour. Useful for trees' text
+ * backgrounds which otherwise default to white even when the tree
+ * background is not white. Alpha value=0 for transparency */
+ static final Color transparent = new Color(0, 0, 0, 0);
+ /** Greenstone dark background colour */
+ static final Color green = new Color(176, 208, 176);
+ /** Greenstone light background colour */
+ static final Color lightGreen = new Color(224, 240, 224);
+ /** Fedora dark background colour */
+ static final Color blue = new Color(128, 180, 216);
+ /** Fedora light background colour */
+ static final Color lightBlue = new Color(218, 237, 252);
+ /** Selection colour for Fedora and Greenstone */
+ static final Color yellow = new Color(240, 240, 140);
+
+ /* Some default colours (system greys and selection colors) */
+ /** Default background colour */
+ static final Color grey = new Color(238, 238, 238);
+ /** Fixed background colour for textareas, editorPanes (html) */
+ static final Color background = Color.white;
+
+ /** background colours for panels, labels */
+ public final Color dark;
+ /** background colours for comboboxes, lists, textfields, textareas */
+ public final Color light;
+
+ /* The fixed colour combination settings for Greenstone, Fedora and default */
+ /** System default greys */
+ public static final ColourCombo defaultColors
+ = new ColourCombo(grey, grey);
+ /** Greenstone greens */
+ public static final ColourCombo greenstoneColors
+ = new ColourCombo(green, lightGreen);
+ /** Fedora's colour combinations of blue */
+ public static final ColourCombo fedoraColors
+ = new ColourCombo(blue, lightBlue);
+ /** The colour combination currently being used in the interface */
+ protected static ColourCombo current = defaultColors;
+
+ /** Constructor to create a ColourCombo combination of colours
+ * @param dark is the colour to set JPanels to.
+ * @param light is the colour to set comboboxes, lists and non-editable
+ * textfields to.
+ */
+ public ColourCombo(Color dark, Color light)
+ {
+ this.dark = dark;
+ this.light = light;
+ }
+
+ // access methods
+ public static ColourCombo getCurrentCombo() { return current; }
+ public static void setCurrentCombo(ColourCombo c) { current = c; }
+
+ /** Sets the active colour combination based on the value of DL.
+ * @param DL represents the current digital library. Values can be
+ * GS3JavaClient.GREENSTONE, GS3JavaClient.FEDORA, GS3JavaClient.SELECT.
+ * Anything else and it defaults to GS3JavaClient.SELECT as well.
+ */
+ public static void setColour(int DL) {
+ switch(DL) {
+ case GS3JavaClient.GREENSTONE:
+ setCurrentCombo(greenstoneColors);
+ break;
+
+ case GS3JavaClient.FEDORA:
+ setCurrentCombo(fedoraColors);
+ break;
+
+ case GS3JavaClient.SELECT:
+ default:
+ setCurrentCombo(defaultColors);
+ break;
+ }
+ }
+
+ /**
+ * @param c is the Component for which it is to be determined whether it
+ * should be a lighter or darker colour.
+ * @return true if Component c should be a lighter colour (returns true
+ * for non-editable JTextFields)
+ */
+ protected static boolean isLightColor(Component c) {
+ // JTextAreas and JEditorPane left white
+
+ // Only JComboBoxes, JLists (and non-editable TextFields) are turned to
+ // the light colour
+ if(c.getClass().getName().equalsIgnoreCase("javax.swing.JComboBox")) {
+ return true;
+ }
+ if(c.getClass().getName().equalsIgnoreCase("javax.swing.JList")) {
+ return true;
+ }
+ // NO LONGER TRUE: Although we can set the the tree pane background to
+ // a light colour, we are unable to get the CellRenderer to do anything
+ // upon selection so leave this white=the colour of selections
+ // INSTEAD: since we have now set the textbackground of treenodes to
+ // transparent, we can colour the background of tree displays.
+ if(c.getClass().getName().toLowerCase().contains("tree")) {
+ return true;
+ }
+ return false;
+ }
+
+ /** Given an array of components, sets their background colours to a
+ * dark or light colour setting as appropriate.
+ * @param leafComponents is the array of components whose background
+ * colours are to change.
+ */
+ public static void changeColor(Component[] leafComponents)
+ {
+ for(int i = 0; i < leafComponents.length; i++) {
+ changeColor(leafComponents[i]);
+ }
+ }
+
+ /** Given a Component, sets its background colours to a dark or
+ * light colour setting as appropriate.
+ * @param c is the component whose background colours are to change.
+ */
+ public static void changeColor(Component c)
+ {
+ // NOT NEEDED: since we made text background of treenodes transparent!
+ // skip all trees, leave them with their default (white) colouring
+ //if(c.getClass().getName().toLowerCase().contains("tree")) {
+ //return;
+ //}
+
+ // deal with JTextFields next, based on whether they are editable
+ // or not
+ if(c.getClass().getName().equalsIgnoreCase("javax.swing.JTextField")) {
+ JTextField field = (JTextField)c;
+ if(field.isEditable()) {
+ field.setBackground(background); // default white
+ } else { // must be set to light (non-editable) colour
+ field.setBackground(current.light); // default white
+ }
+ } else if(isLightColor(c)) {
+ // for JLists, JComboBoxes, JTextFields need
+ // to set light background color
+ c.setBackground(current.light);
+ } else { // need to set background color to dark
+ c.setBackground(current.dark);
+ }
+ }
+
+ /** Given a component, sets its ancestors to the dark colour setting.
+ * @param c is the component whose ancestors' background colours are
+ * to be set.
+ */
+ public static void changeAncestorColor(Component c) {
+ // assume c's background color has been changed
+ do {
+ c = c.getParent(); // change parent color
+ // Leave tabbed panes grey, but change the colour of all other
+ // containers - all ancestor components will be containers of
+ // some kind (labels or panels)
+ if(!c.getClass().getName().equalsIgnoreCase("javax.swing.JTabbedPane"))
+ {
+ c.setBackground(current.dark);
+ }
+ } while(c.getParent() != null); // cycle through all ancestors
+ }
+}
Index: other-projects/gs3-webservices-java-client/trunk/src/GS3DemoClient/org/greenstone/gs3client/Displays.java
===================================================================
--- other-projects/gs3-webservices-java-client/trunk/src/GS3DemoClient/org/greenstone/gs3client/Displays.java (revision 21027)
+++ other-projects/gs3-webservices-java-client/trunk/src/GS3DemoClient/org/greenstone/gs3client/Displays.java (revision 21027)
@@ -0,0 +1,359 @@
+/**
+ *#########################################################################
+ * Displays.java - part of the demo-client for Greenstone 3, of the
+ * Greenstone digital library suite from the New Zealand Digital Library
+ * Project at the * University of Waikato, New Zealand.
+ *
+ * Copyright (C) 2008 New Zealand Digital Library Project
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *########################################################################
+ */
+
+package org.greenstone.gs3client;
+
+import org.greenstone.gs3client.data.Pair;
+import java.awt.event.ActionEvent;
+import java.awt.event.ActionListener;
+import java.awt.event.MouseAdapter;
+import java.awt.event.MouseEvent;
+import java.util.Collections;
+import java.util.Comparator;
+import java.util.Iterator;
+import java.util.Map;
+import java.util.Vector;
+import java.util.Map.Entry;
+
+import javax.swing.JEditorPane;
+import javax.swing.JList;
+import javax.swing.JMenuItem;
+import javax.swing.JPopupMenu;
+import javax.swing.JTree;
+import javax.swing.tree.DefaultMutableTreeNode;
+import javax.swing.tree.TreePath;
+
+import org.greenstone.gs3client.data.DocumentNodeData;
+import org.greenstone.gs3client.data.ClassifierNodeData;
+import org.greenstone.gs3client.data.NodeData;
+
+/**
+ * Class containing static methods, static variables and inner classes that
+ * are used by both SearchResultsDisplay and BrowseDisplay.
+ * @author ak19
+*/
+public class Displays {
+ /** Static Comparator object for Pair objects of (name, value) Metadata */
+ protected static final MetadataComparator comparator = new MetadataComparator();
+
+ /* Static methods. */
+ /** Recursion to add all descendent docnodes into the tree.
+ * @param docNode - the documentNodeData object for whose children treenodes
+ * need to be created.
+ * @param treeNode - the treeNode associated with the docNode parameter. */
+ public static void createNodesForChildren(DocumentNodeData docNode,
+ DefaultMutableTreeNode treeNode)
+ {
+ if(docNode == null)
+ return;
+ DocumentNodeData[] children = docNode.getDescendents();
+ if(children == null)
+ return; // base case, the child was a leaf
+
+ for(int i = 0; i < children.length; i++) {
+ DefaultMutableTreeNode childTreeNode
+ = new DefaultMutableTreeNode(children[i]);
+ treeNode.add(childTreeNode);
+
+ // recursion step to add this child node's children to
+ // the treeNode representing it
+ createNodesForChildren(children[i], childTreeNode);
+ }
+ }
+
+ /** JEditorPane cannot deal with <img src="" />. It can only handle
+ * it without ending slash: <img src="" >.
+ * This method constructs complete html (with html, head and body tags) where
+ * the parameter imgURL is enclosed inside an img src tag.
+ * @param imgURL - src URL for a (web) image
+ * @return the imgURL parameter enclosed in complete html */
+ public static String getImgUrlEnclosedInHtml(String imgURL)
+ {
+ return "";
+ }
+
+ /** Sorts the metadata of the docNode into the required order and displays
+ * metadata names in the JList metanames and the associated metadata values
+ * in the JList metavalues.
+ * The order is based on metanames: first come all the official metadata
+ * sets which are recognised by the existence of a period in the metaname
+ * (eg. dc.creator, dls.title). These are arranged alphabetically.
+ * Next come all the metadata names that start with a capital letter -
+ * arranged alphabetically;
+ * the remainder are organised alphabetically as well, with the last ones
+ * being those metadata whose names do not start with a letter
+ * (e.g. "/srclink").
+ * @param nodeData is the NodeData object (classifierNodeData or
+ * documentNodeData)
+ * whose metadata is to be displayed in the metanames and metavalues components.
+ * @param metanames - a JList to display all the metadata names of nodeData
+ * @param metavalues - a JList to display all the metadata values of nodeData */
+ public static void showMeta(NodeData nodeData, JList metanames, JList metavalues)
+ {
+ // get the metadata names and values, put them
+ // into separate arrays and set the contents of
+ // JLists metanames and metavalues to these arrays.
+ Map metadata = nodeData.getMetadataList();
+ if(metadata != null && metadata.size() > 0) {
+ Iterator i = metadata.entrySet().iterator();
+ Vector nameValuePairs = new Vector(metadata.size());
+ while(i.hasNext()) {
+ Entry entry = (Entry)i.next();
+ String name = (String)entry.getKey();
+ Vector values = (Vector)entry.getValue();
+ for(int j = 0; j < values.size(); j++) {
+ nameValuePairs.add(new Pair(name, (String)values.get(j)));
+ }
+ }
+ // first sort the Vectors with our comparator:
+ // see http://java.sun.com/j2se/1.4.2/docs/api/java/util/Collections.html
+ // method Collections.sort(List l, Comparator c)
+ // and see http://java.sun.com/j2se/1.4.2/docs/api/java/util/Comparator.html
+
+ // Need to sort the nameValuePairs based on the ordering of the
+ // *names* portion of each Pair.
+ // This ordering is defined by the MetadataComparator object
+ // comparator
+ // OLD: This ordering is defined by the Comparable interface implemented
+ // by the vector contents. No comparator was passed into
+ // Collections.sort(List l) because the vector's contents were Pairs
+ // which implemented Comparable and therefore the elements were sorted
+ // based on their "natural ordering".
+ // see http://java.sun.com/j2se/1.4.2/docs/api/java/lang/Comparable.html
+ // Collections.sort(nameValuePairs);
+ Collections.sort(nameValuePairs, comparator);
+ metanames.setListData(Pair.getFirst(nameValuePairs));
+ metavalues.setListData(Pair.getSecond(nameValuePairs));
+
+ nameValuePairs.clear();
+ nameValuePairs = null;
+ }
+ }
+
+ /** Handles rightclicks on a treeview of documentNodeData objects by showing
+ * the popupMenu with associated files that, when selected, can be displayed
+ * in the htmlPane. Listens to rightclick events, but also handles clicks on
+ * popup menu items.
+ * @see Java tutorial on menus
+ */
+ static class PopupListener extends MouseAdapter implements ActionListener
+ {
+ /** Handle to the running GS3JavaClient object to have access to its
+ * methods */
+ final GS3JavaClient client;
+ /** A popup component */
+ final JPopupMenu popupMenu;
+ /** The treeView component on which the rightclicks occurred */
+ final JTree tree;
+ /** The htmlPane wherein associated files are to be displayed */
+ final JEditorPane htmlArea;
+
+ /** Package access inner class. Not static, so it depends on outer class'
+ * PopupListener instance.
+ * Represents a popup MenuItem that appears on rightclick and contains the
+ * name(s) of associated files which will be displayed - if any are selected
+ * - in the main htmlpane. */
+ class AssocFilePopupItem extends JMenuItem {
+ /** The documentNodeData that was rightclicked upon */
+ final DocumentNodeData docNode;
+
+ /** Constructor that creates an AssocFilePopupItem (popup menu item)
+ * instance for each associated file of a documentNodeData that's been
+ * rightclicked on. This popupitem displays the name of the associated
+ * file as a menu item of the popup.
+ * The outer PopupListener object is set to listen to mouseEvents on
+ * this PopupMenuItem. It will listen to clicks on this menuItem to
+ * then display the image. */
+ public AssocFilePopupItem(DocumentNodeData docNode, String name)
+ {
+ super(name);
+ this.docNode = docNode;
+ // PopupListener will also process clicks on this shortcut menuitem
+ this.addActionListener(PopupListener.this);
+ }
+ }
+
+ /** Constructor for the PopupListener.
+ * @param popupMenu - the JPopupMenu object this PopupListener
+ * will handle mouseEvents for
+ * @param tree - the JTree object whose documentNodeData was clicked
+ * @param client - handle to the running GS3JavaClient instance
+ * @param htmlArea - the html editor pane in which to display the
+ * associated file chosen from the popupMenu. */
+ public PopupListener(JPopupMenu popupMenu, JTree tree,
+ GS3JavaClient client, JEditorPane htmlArea)
+ {
+ this.client = client;
+ this.popupMenu = popupMenu;
+ this.tree = tree;
+ this.htmlArea = htmlArea;
+ }
+
+ /** Called when one of the popup's menuItems was clicked.
+ * The associated file represented by the menuItem is displayed in the
+ * html editor pane. */
+ public void actionPerformed(ActionEvent e) {
+ // TODO: later, when all gsdlassocfiles are available for each docNode,
+ // need to change the setText below to make use of imageName and
+ // the docNode's root's assocFilePath
+ AssocFilePopupItem menuItem = (AssocFilePopupItem)e.getSource();
+ DocumentNodeData docNode = menuItem.docNode;
+
+ if(docNode.canBeImage())
+ htmlArea.setText(
+ getImgUrlEnclosedInHtml(docNode.getImgURL()));
+ // JEditorPane does not understand ! So use only
+ else {
+ String filename = menuItem.getText();
+ String filepath = client.getFilePath(docNode);
+ // for the latest exported greenstone colllections
+ // into fedora, Greenstone prefixes FG in front of image name...
+ htmlArea.setText(getImgUrlEnclosedInHtml(filepath+filename));
+ }
+
+ htmlArea.setCaretPosition(0);
+ popupMenu.removeAll();
+ }
+
+ /** Possibly a popupEvent */
+ public void mouseReleased(MouseEvent e) {
+ // for some reason the popup is visible in miniature, make it
+ // invisible, then decide whether it needs to be shown again
+ popupMenu.setVisible(false);
+ maybeShowPopup(e);
+ }
+
+ /** Possibly a popupEvent */
+ public void mousePressed(MouseEvent e) {
+ maybeShowPopup(e);
+ }
+
+ /** If the mouseEvent was a trigger (rightclick), displays the popup
+ * context menu. */
+ protected void maybeShowPopup(MouseEvent e) {
+ // For some reason e.isPopupTrigger() does not work. (Probably
+ // because the rightclick sometimes happens on the tiny popup
+ // which is visible but too small to see.)
+ // The rightclick appears to only be registered on the popup:
+ // and popup.isPopupTrigger(e) responds even when the popup
+ // is already visible
+ if(popupMenu.isPopupTrigger(e)) {
+ // remove old rightclick menu items
+ popupMenu.removeAll();
+
+ // get the closest node in the docStructureTree to that which
+ // was rightclicked
+ TreePath path = tree.getClosestPathForLocation(
+ e.getX(), e.getY());
+ // the following line will select this nearest node and trigger
+ // TreeSelectionListener by calling valueChanged(), which will
+ // retrieve the structure and display the metadata:
+ (tree.getSelectionModel()).setSelectionPath(path);
+ DefaultMutableTreeNode node
+ = (DefaultMutableTreeNode)path.getLastPathComponent();
+ if(node.getUserObject() instanceof ClassifierNodeData) //
+ return; //
+ DocumentNodeData docNode = (DocumentNodeData)node.getUserObject();
+ // We need the root and the image url part of the metadata, so
+ // ensure we have that:
+ if(docNode.getRoot() == null) //
+ client.retrieveTitledStructureFor(docNode); //
+
+ Vector v = docNode.getAssociatedFileNames();
+ if(v.size() > 0) { // there are associated files
+ for(int i = 0; i < v.size(); i++) {
+ Pair p = (Pair)v.get(i);
+ JMenuItem menuItem
+ = new AssocFilePopupItem(docNode, p.first);
+ popupMenu.add(menuItem);
+ }
+ popupMenu.show(e.getComponent(), e.getX(), e.getY());
+ } else if(docNode.canBeImage()) { // add rightclick popup menu that will
+ // display image upon click
+ JMenuItem menuItem = new AssocFilePopupItem(docNode, docNode.getImgName());
+ popupMenu.add(menuItem);
+ popupMenu.show(e.getComponent(), e.getX(), e.getY());
+ }
+ }
+ }
+ }
+
+ /** Static inner class MetadataComparator is a Comparator for the metadata
+ * fields stored as a list of Pair objects (name, values).
+ * We want to display them alphabetised, grouped by prefix (dls.title, dls.x;
+ * dc.title; dc.creator; greenstone's ex metadata does not have a prefix)
+ * and in order of alphabet BUT all those starting with capital letters come
+ * first, then come those starting with lowercase letters.
+ * Those with prefixes come first of all.
+ * @see http://java.sun.com/j2se/1.4.2/docs/api/java/util/Comparator.html
+ * Comparators can be passed to a sort method (such as Collections.sort) to
+ * allow precise control over the sort order. Comparators can also be used to
+ * control the order of certain data structures (such as TreeSet or TreeMap). */
+ public static class MetadataComparator implements Comparator {
+ public int compare(Object nodeID1, Object nodeID2) {
+ if(nodeID1 == null && nodeID2 == null)
+ return 0;
+ if(nodeID1 == null)
+ return 1;
+ if(nodeID2 == null)
+ return -1;
+
+ String metaName1 = ((Pair)nodeID1).first;
+ String metaName2 = ((Pair)nodeID2).first;
+
+ if(metaName1.equals(metaName2))
+ return 0; // same
+
+ if(metaName1.indexOf('.') != -1 && metaName2.indexOf('.') == -1)
+ return -1; // only c1 has a period, so c1 comes before c2
+ if(metaName2.indexOf('.') != -1 && metaName1.indexOf('.') == -1)
+ return 1; // only c2 has a period, so c2 comes before c1
+
+ // we're going to inspect the first letters, so store these
+ char c1 = metaName1.charAt(0);
+ char c2 = metaName2.charAt(0);
+
+ if(Character.isUpperCase(c1) && Character.isLowerCase(c2))
+ return -1; // only c1 starts with uppercase, so c1 comes before c2
+ if(Character.isUpperCase(c2) && Character.isLowerCase(c1))
+ return 1; // only c2 starts with uppercase, so c2 comes before c1
+
+ // we want metadatanames like "/srclink" to come at the end, because
+ // they don't start with a letter
+ if(!Character.isLetter(c2) && Character.isLetter(c1))
+ return -1; // if c2 starts with some strange character,
+ // c1 comes before c2 in the ordering
+ if(!Character.isLetter(c1) && Character.isLetter(c2))
+ return 1; // if c1 starts with some strange character,
+ // c2 comes before c1 in the ordering
+
+ // otherwise, all else being equal (both start with
+ // uppercase/lowercase or both contain/don't contain periods or
+ // both start with/don't start with letters): so sort them in
+ // alphabetic order.
+ return metaName1.compareTo(metaName2);
+ }
+
+ //public boolean equals(Object obj) {
+ // return obj.equals(this);
+ //}
+ }
+}
Index: other-projects/gs3-webservices-java-client/trunk/src/GS3DemoClient/org/greenstone/gs3client/GS3JavaClient.java
===================================================================
--- other-projects/gs3-webservices-java-client/trunk/src/GS3DemoClient/org/greenstone/gs3client/GS3JavaClient.java (revision 21027)
+++ other-projects/gs3-webservices-java-client/trunk/src/GS3DemoClient/org/greenstone/gs3client/GS3JavaClient.java (revision 21027)
@@ -0,0 +1,1072 @@
+/**
+ *#########################################################################
+ * GS3JavaClient.java - part of the demo-client for Greenstone 3, of the
+ * Greenstone digital library suite from the New Zealand Digital Library
+ * Project at the * University of Waikato, New Zealand.
+ *
+ * Copyright (C) 2008 New Zealand Digital Library Project
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *########################################################################
+ */
+
+package org.greenstone.gs3client;
+
+
+import org.apache.log4j.Logger;
+import org.apache.log4j.PropertyConfigurator;
+import org.greenstone.gs3client.BrowseDisplay.ClassifierData;
+
+import org.greenstone.gs3client.data.BrowseResponseData;
+import org.greenstone.gs3client.data.CollectionData;
+import org.greenstone.gs3client.data.DocumentNodeData;
+import org.greenstone.gs3client.data.ClassifierNodeData;
+import org.greenstone.gs3client.data.NodeData;
+import org.greenstone.gs3client.data.ParseUtil;
+import org.greenstone.gs3client.data.QueryResponseData;
+import org.greenstone.gs3client.data.ResponseData;
+//By importing this *static* inner class of CollectionData, can refer
+//to it by its unqualified name 'ServiceData'. (Learnt this from
+//http://today.java.net/pub/a/today/2006/03/23/multi-split-pane.html)
+import org.greenstone.gs3client.data.CollectionData.ServiceData;
+import org.greenstone.gs3client.dlservices.DigitalLibraryServicesAPIA;
+import org.greenstone.gs3client.dlservices.FedoraServicesAPIA;
+import org.greenstone.gs3client.dlservices.GS3ServicesAPIA;
+
+import javax.swing.*;
+import java.awt.BorderLayout;
+import java.awt.GridLayout;
+import java.awt.FlowLayout;
+import java.awt.event.ActionListener;
+import java.awt.event.ActionEvent;
+import java.awt.Container;
+import java.awt.Toolkit; // for making this JFrame client fullsize
+
+import java.net.Authenticator;
+import java.net.PasswordAuthentication;
+
+import org.w3c.dom.Document;
+import org.w3c.dom.Element;
+import org.w3c.dom.NodeList;
+
+import java.util.Vector;
+import java.util.HashMap;
+
+import java.io.StringReader;
+import javax.xml.parsers.DocumentBuilderFactory;
+import javax.xml.parsers.DocumentBuilder;
+import org.xml.sax.InputSource;
+
+import org.greenstone.gsdl3.util.GSXML;
+import java.awt.Cursor;
+
+/*
+ To make this class compile with Java 5/Java 1.5 need to rename the file
+ xalan.jar.tmp (located in $GS3_HOME/web/WEB-INF/lib) to xalan.jar
+ Without doing that, it will complain (unless compiled with Java 1.4.2).
+
+ RUNTIME Configuration of this class:
+ - this client needs the jar files:
+ log4j, xercesImpl, mail, lucene, javagdbm,
+ And possibly: xml-apis, activation, axis, mg, mgpp
+ - VM arguments: -Djava.library.path=/research/ak19/greenstone3/lib/jni
+
+ COMPILE Configuration of this class:
+ - BUILD PATH needs the jar files:
+ gsdl3 (or just the class GSXML), jaxrpc, axis
+ */
+/**
+ * The main Javaclient class. Creates the main window containing:
+ * - the radio button group for making either Greenstone 3 or Fedora the active DL.
+ * - the comboboxes for selecting the collection and the service therein
+ * - three panes - for executing queries, viewing search results and browsing.
+ * @author ak19
+*/
+public class GS3JavaClient extends JFrame implements ActionListener {
+ // static final long serialVersionUID = 1; //eclipse keeps warning
+ /** The Logger for this class */
+ static Logger LOG = Logger.getLogger(GS3JavaClient.class);
+
+ /** The value of the SEARCHING activity */
+ public static int SEARCHING = 0;
+ /** The value of the BROWSING activity */
+ public static int BROWSING = 1;
+ /** we want to display a drop-down box for the services available,
+ * but only Services that can be executed (searching and browsing) */
+ protected static final boolean executableServicesOnly = true;
+
+ /** To keep track of whether we are searching or browsing.
+ * Value of activity can be SEARCHING OR BROWSING */
+ protected int activity = 0; //
+
+ /** Reference to a digital library instance (Greenstone 3 or Fedora) that
+ * allows this client to execute services offered by the digital library */
+ protected DigitalLibraryServicesAPIA dlAPIA = null;
+ /** Reference to the object that interacts with Greenstone3's web services */
+ protected GS3ServicesAPIA greenstoneDL = null;
+ /** Reference to the object that interacts with the FedoraGS3.jar component */
+ protected FedoraServicesAPIA fedoraDL = null;
+
+ /** Object that stores the data of a query response XML message */
+ protected QueryResponseData queryResponseObj = null;
+
+ /** Object that stores the data of a browse response XML message
+ * (response for classification hierarchies) */
+ protected BrowseResponseData browseResponseObject = null;
+
+ /** Preferred language of display items in responses.
+ * "" or "en" for English */
+ protected String lang = "";
+
+ /** The currently selected collection */
+ protected String colName = "";
+ /** The currently selected service */
+ protected String serviceName = "";
+
+ /* The always-visible GUI objects of this main window */
+ protected JComboBox dlChooser = null;
+ protected JTextField proxyhostField = null;
+ protected JTextField proxyportField = null;
+ protected JTextField nonProxyHostNamesField = null;
+ protected JButton setProxySettings = null;
+
+ protected JComboBox serviceBox = null;
+ protected JComboBox collBox = null;
+ protected JButton collInfoButton = null;
+ protected JButton searchButton = null;
+ protected JTabbedPane tabbedPane = null;
+
+ protected static final int SELECT = 0;
+ protected static final int GREENSTONE = 1;
+ protected static final int FEDORA = 2;
+ protected static final String[] dlOptions = {"select", "greenstone", "fedora"};
+
+ /* Components of the query tab */
+ protected QueryForm queryPanel = null;
+ protected JTextField collectionNameField = null;
+
+ /* Components of the search tab */
+ protected SearchResultsDisplay searchResultsDisplay = null;
+ protected JPanel searchPanel = null;
+ protected JTextArea searchSummary = null;
+
+ /* Components of the browse tab */
+ protected BrowseDisplay browsePanel = null;
+
+ /** @return the language of the display items */
+ public String getLanguage() { return lang; }
+ /** Set the preferred language of the display items
+ * @param lang - the preferred language for display values */
+ public void setLanguage(String lang) { this.lang = lang; }
+
+ /** Inner class that handles authentication for any sites (urls, etc.)
+ * that require it. A dialog pops up to request username and password
+ * details from the user for each site's realm that needs authentication.
+ */
+ static class PasswordAuthenticator extends Authenticator {
+ protected PasswordAuthentication getPasswordAuthentication() {
+ JTextField username = new JTextField();
+ JTextField password = new JPasswordField();
+ JPanel panel = new JPanel(new GridLayout(2,2));
+ panel.add(new JLabel("User Name"));
+ panel.add(username);
+ panel.add(new JLabel("Password") );
+ panel.add(password);
+ int option = JOptionPane.showConfirmDialog(null, new Object[] {
+ "Site: "+getRequestingHost(),
+ "Realm: "+getRequestingPrompt(), panel},
+ "Enter Network Password",
+ JOptionPane.OK_CANCEL_OPTION, JOptionPane.PLAIN_MESSAGE);
+ if ( option == JOptionPane.OK_OPTION ) {
+ return new PasswordAuthentication(
+ username.getText(), password.getText().toCharArray());
+ } else {
+ return null;
+ }
+ }
+ }
+
+ /** Default constructor that creates and initialises this main
+ * window and its internal GUI components */
+ public GS3JavaClient() {
+ super();
+ this.setTitle("Greenstone 3 web services demo-client");
+
+ // digital library panel lets the user choose the digital library
+ // repository to access and to set the proxy settings
+ JPanel dlPanel = new JPanel(new FlowLayout(FlowLayout.LEFT));
+ dlChooser = new JComboBox(dlOptions);
+ dlPanel.add(new JLabel("Use digital library:"));
+ dlPanel.add(dlChooser);
+ dlChooser.addActionListener(this);
+ dlPanel.setBorder(BorderFactory.createTitledBorder(
+ "Digital library settings"));
+
+ this.proxyhostField = new JTextField(15);
+ this.proxyportField = new JTextField(4);
+ this.nonProxyHostNamesField = new JTextField(20);
+ this.setProxySettings = new JButton("Set");
+ nonProxyHostNamesField.setToolTipText("The hosts for which no proxies are required "
+ + "(separate hosts with |, * wildcard allowed)");
+ JPanel topProxyPanel = new JPanel(new FlowLayout(FlowLayout.LEFT));
+ topProxyPanel.add(new JLabel("Proxy host:"));
+ topProxyPanel.add(proxyhostField);
+ topProxyPanel.add(new JLabel("Proxy port:"));
+ topProxyPanel.add(proxyportField);
+ JPanel bottomProxyPanel = new JPanel(new FlowLayout(FlowLayout.LEFT));
+ bottomProxyPanel.add(new JLabel("No proxy for:"));
+ bottomProxyPanel.add(nonProxyHostNamesField);
+ bottomProxyPanel.add(setProxySettings);
+ setProxySettings.addActionListener(this);
+ JPanel proxyPanel = new JPanel(new BorderLayout());
+ proxyPanel.add(topProxyPanel, BorderLayout.CENTER);
+ proxyPanel.add(bottomProxyPanel, BorderLayout.SOUTH);
+ proxyPanel.setBorder(BorderFactory.createTitledBorder(
+ "Connection settings"));
+
+ // Add the dlPanel and proxyPanel next to each other at the top
+ JPanel topPanel = new JPanel(new BorderLayout());
+ topPanel.add(dlPanel, BorderLayout.CENTER);
+ topPanel.add(proxyPanel, BorderLayout.EAST);
+
+ // Setting up the GUI of this client
+ // create a JComboBox, and an item in it for each collection
+ collBox = new JComboBox();
+ serviceBox = new JComboBox();
+
+ JPanel collPanel = new JPanel(new FlowLayout(FlowLayout.LEFT));
+ collPanel.add(new JLabel("Choose collection:"));
+ collPanel.add(collBox);
+ // displayName
+ collPanel.add(new JLabel("Full name:"));
+ collectionNameField = new JTextField(18);
+ collectionNameField.setEditable(false);
+ collectionNameField.setCaretPosition(0);
+ collPanel.add(collectionNameField);
+ // detailed information button, shows collection's description
+ collInfoButton = new JButton("Info");
+ collInfoButton.addActionListener(this);
+ collPanel.add(collInfoButton);
+
+ JPanel servicePanel = new JPanel(new FlowLayout(FlowLayout.LEFT));
+ servicePanel.add(new JLabel("Available services:"));
+ servicePanel.add(serviceBox);
+
+ JPanel collServicesPanel = new JPanel(new BorderLayout());
+ collServicesPanel.add(collPanel, BorderLayout.NORTH);
+ collServicesPanel.add(servicePanel, BorderLayout.SOUTH);
+
+ tabbedPane = new JTabbedPane(); // tabs on top
+ queryPanel = new QueryForm(this);
+ tabbedPane.add("Query", queryPanel);
+ searchResultsDisplay = new SearchResultsDisplay(this);
+ searchResultsDisplay.setOpaque(true); //necessary for JTree
+
+ JScrollPane searchView = new JScrollPane(searchResultsDisplay);
+ searchSummary = new JTextArea();
+ searchSummary.setEditable(false);
+
+ searchPanel = new JPanel(new BorderLayout());
+ searchPanel.add(searchView, BorderLayout.CENTER);
+ searchPanel.add(searchSummary, BorderLayout.NORTH);
+ tabbedPane.add("Search Results", searchPanel);
+
+ JPanel activityPanel = new JPanel(new BorderLayout());
+ activityPanel.add(collServicesPanel, BorderLayout.NORTH);
+ activityPanel.add(tabbedPane, BorderLayout.CENTER);
+
+ Container c = this.getContentPane();
+ c.setLayout(new BorderLayout()); // new BoxLayout(c, BoxLayout.Y_AXIS));
+ c.add(topPanel, BorderLayout.NORTH);
+ c.add(activityPanel, BorderLayout.CENTER);
+
+ // browse panel
+ browsePanel = new BrowseDisplay(this);
+ tabbedPane.add("Browse", browsePanel);
+
+ // add actionlisteners
+ collBox.addActionListener(this);
+ serviceBox.addActionListener(this);
+
+ // GUI DONE, now instantiate the DATA and DIGITAL LIBRARY objects
+ // instantiate the objects that deal with storing query response data
+ // and browse response data
+ queryResponseObj = new QueryResponseData();
+ browseResponseObject = new BrowseResponseData();
+
+ // The java.net.Authenticator can be used to send user credentials
+ // when needed. When no username/password are provided then a popup
+ // is shown to ask for the credentials. *Only* when a site/realm
+ // requires password and username does the Authenticator show the
+ // dialog. For example, the dialog will appear when pwd & username
+ // are needed for proxy authorisation.
+ Authenticator.setDefault(new PasswordAuthenticator());
+
+ changeDL(null); // no dl selected
+
+ // Set the selection colours that will be uniform for all DLs
+ UIManager.put("Tree.textBackground", ColourCombo.transparent);
+ // Instead of the white tree text background, set it to transparent
+ UIManager.put("Tree.selectionBackground", ColourCombo.yellow);
+ UIManager.put("TabbedPane.selected", ColourCombo.yellow);
+ UIManager.put("TabbedPane.selected", ColourCombo.yellow);
+ UIManager.put("ComboBox.selectionBackground", ColourCombo.yellow);
+ UIManager.put("List.selectionBackground", ColourCombo.yellow);
+ UIManager.put("TextArea.selectionBackground", ColourCombo.yellow);
+ UIManager.put("TextField.selectionBackground", ColourCombo.yellow);
+ // force the UI to load these new UIManager defaults
+ javax.swing.SwingUtilities.updateComponentTreeUI(this);
+ // We can't change the UIManager defaults (properly) throughout GUI
+ // display-time, only upon creation and first display. This is
+ // because updateComponentTreeUI() has no effect once components
+ // have been displayed. For this reason, the various changeUIColor()
+ // methods and class ColourCombo have been written.
+ }
+
+ /** Attempts to establish a connection to GS3 Web services and instantiate
+ * a GS3ServicesAPIA object and store it in the member variable greenstoneDL.
+ * If it was unsuccessful, then this variable remains at null and an error
+ * message is displayed. */
+ protected boolean createGreenstoneDLConnection()
+ {
+ // store the old choice of dl, if there was any
+ int oldSetting = (dlAPIA == null) ? SELECT : FEDORA;
+ // try instantiating a GS3 dl handle
+ try {
+ greenstoneDL = new GS3ServicesAPIA();
+ return true; // success
+ } catch(DigitalLibraryServicesAPIA.CancelException e){
+ // The user pressed cancel in the gs3 services instantiation dialog
+ // Set the dl drop-down list option back to whatever it was
+ } catch(Exception e) {
+ // still unable to instantiate greenstone, but show
+ // the error for what went wrong
+ JOptionPane.showMessageDialog(
+ null,
+ "Error connecting to Greenstone 3 QBRSOAPServer web services.\n"
+ + "When attempting to process its wsdl file, encountered the problem:\n"
+ + e,
+ "Fatal error instantiating Digital Library Services interface. Exiting...",
+ JOptionPane.ERROR_MESSAGE
+ );
+ //e.printStackTrace(System.err);
+ LOG.error("Error connecting to Greenstone 3 web services:\n" + e);
+ }
+ // We'd be here if an exception occurred. Need to back to the old dl
+ // settings
+ dlChooser.setSelectedIndex(oldSetting);
+ return false;
+ }
+
+ /** Attempts to establish a connection to FedoraGS3.jar and instantiate
+ * a FedoraServicesAPIA object and store it in the member variable fedoraDL.
+ * If it was unsuccessful, then this variable remains at null and an error
+ * message is displayed. */
+ protected boolean createFedoraDLConnection()
+ {
+ // store the old choice of dl, if there was any
+ int oldSetting = oldSetting = (dlAPIA == null) ? SELECT : GREENSTONE;
+ // Try to instantiate a Fedora dl handle
+ try {
+ fedoraDL = new FedoraServicesAPIA();
+ return true; // success
+ } catch(
+ org.greenstone.fedora.services.FedoraGS3Exception.CancelledException e)
+ {
+ // The user pressed cancel in the fedora services instantiation dlg
+ // Set the dl drop-down list option back to whatever it was
+ } catch(Exception e) {
+ JOptionPane.showMessageDialog(
+ null,
+ "Error instantiating the interface to the Fedora Repository\n"+ e,
+ "Unable to connect to Fedora's digital library services.",
+ JOptionPane.ERROR_MESSAGE
+ );
+ //e.printStackTrace(System.err);
+ LOG.error(
+ "Error instantiating the interface to the Fedora Repository:\n"+ e);
+ }
+ // We'd be here if an exception occurred. Need to go back to the old dl
+ // settings
+ dlChooser.setSelectedIndex(oldSetting);
+ return false;
+ }
+
+ /** Method that is called when the user chooses to change the active
+ * digital library (between Greenstone3 and Fedora).
+ * @param dl is the new active digital library (the
+ * DigitalLibraryServicesAPIA object to change to). */
+ protected void changeDL(DigitalLibraryServicesAPIA dl) {
+ // change the colour of the interface
+ this.changeUIColour(dlChooser.getSelectedIndex());
+
+ // clear up remnants of previously selected digital library's
+ // processing
+ browsePanel.clear();
+ searchResultsDisplay.clear();
+ this.searchSummary.setText("");
+ browseResponseObject.clear();
+ queryResponseObj.clear();
+
+ // set current digital library to selected one
+ dlAPIA = dl;
+
+ if(dlAPIA == null) {
+ // clear some panels so the user can't do anything
+ this.queryPanel.clear();
+ collBox.removeAllItems();
+ collBox.setEnabled(false);
+ serviceBox.removeAllItems();
+ serviceBox.setEnabled(false);
+ this.collectionNameField.setText("");
+ this.collInfoButton.setEnabled(false);
+ return;
+ }
+
+ // start retrieving the information related to the chosen dl
+ String response = dlAPIA.describe();
+ if(response == null) {
+ LOG.error("Error: no response from dlAPIA.describe() of "
+ + dlAPIA.getDisplayName());
+ System.exit(1);
+ }
+
+ Element responseXML = getResponseAsDOM(
+ "DESCRIBE RESPONSE:\n", response);
+
+ // Get the collectionList element of the response
+ // from the default messageRouter-describe:
+ Element collectionList = ParseUtil.getFirstDescElementCalled(
+ responseXML, // (, "collectionList")
+ GSXML.COLLECTION_ELEM+GSXML.LIST_MODIFIER
+ );
+ if(collectionList == null)
+ LOG.error("collectionList is null!");
+
+ // Next, create a CollectionData object for each collection using
+ // its name
+ CollectionData[] collData = null;
+ Vector v = ParseUtil.getAllChildElementsCalled(collectionList,
+ GSXML.COLLECTION_ELEM); // (, "collection")
+ if(v == null)
+ LOG.error("collections are null!");
+
+ if(v != null) {
+ StringBuffer buf = new StringBuffer("Collections:\n");
+ collData = new CollectionData[v.size()];
+ for(int i = 0; i < v.size(); i++){
+ collData[i] = new CollectionData((Element)v.get(i));
+ buf.append(collData[i].name + ", ");
+ }
+ }
+
+ // Now send a describe request to each collection
+ // And set the fields for each collData using the response
+ for(int i = 0; i < collData.length; i++){
+ response = dlAPIA.describeCollection(collData[i].name);
+ responseXML = getResponseAsDOM(
+ "describeCollection "+collData[i].name+":", response);
+ Element collectionTag = ParseUtil.getFirstDescElementCalled(
+ responseXML, GSXML.COLLECTION_ELEM);
+
+ // set the other fields of the CollectionData object using
+ // the collectionTag of the response from Collection-describe:
+ collData[i].setFields(collectionTag);
+ }
+
+ if(collData == null) {
+ LOG.debug("No collections in the chosen repository");
+ return;
+ } else {
+ this.collInfoButton.setEnabled(true);
+ collBox.setEnabled(true);
+ serviceBox.setEnabled(true);
+ }
+
+ // fill in the combobox containing the collections and the one
+ // containing the services
+ collBox.removeAllItems();
+ for(int i = 0; i < collData.length; i++)
+ collBox.addItem(collData[i]);
+ collBox.setSelectedItem(collData[0]);
+
+ this.serviceBox.removeAllItems();
+ ServiceData[] serviceData = collData[0].getServiceList(
+ executableServicesOnly);
+ for(int i = 0; i < serviceData.length; i++)
+ serviceBox.addItem(serviceData[i]);
+ serviceBox.setSelectedIndex(0); // whichever might be the first
+ }
+
+ /** Given an XML response string, returns the root document (element)
+ * representing its DOM form.
+ * @param response - the XML response string to be converted into
+ * its DOM form
+ * @return the response as an XML DOM Element */
+ protected Element getResponseAsDOM(String debugPrefix, String response) {
+ if(response == null) // will not be the case, because an empty
+ return null; // response message will be sent instead
+
+ // First let's print out the response to the LOG
+ // Note that the response is XML and will start on new line already
+ LOG.debug(debugPrefix + "\n" + response);
+ // The following line when uncommented will output all response
+ // msgs coming back from the web services
+ //System.out.println(debugPrefix + "\n" + response);
+
+ // At present, assuming response is okay - later need to first look
+ // for element and process this meaningfully before returning
+ // XML DOM version of response. Example error:
+ //
+ //
+ //
+ // IOException during connection to http://infominehelper.ucr.edu/cgi-bin/canned_search?theme=gsdl3&query=water&fields=kw,au,su,ti,de,fu,&no_of_records_per_page=10&start_page_no=1: java.net.ConnectException: Connection refused
+ //
+ //
+
+ Element message = null;
+ try{
+ // turn the String xml response into a DOM tree:
+ DocumentBuilder builder
+ = DocumentBuilderFactory.newInstance().newDocumentBuilder();
+ Document doc
+ = builder.parse(new InputSource(new StringReader(response)));
+ message = doc.getDocumentElement();
+ } catch(Exception e){
+ if(response == null) {
+ response = "";
+ }
+ JOptionPane.showMessageDialog(this,
+ "An error occurred while trying to parse the response:\n"
+ + response
+ + "\nException message:\n" + e.getMessage(),
+ "Parse error", JOptionPane.ERROR_MESSAGE);
+ e.printStackTrace();
+ }
+
+ NodeList errorList = message.getElementsByTagName(GSXML.ERROR_ELEM);
+ if(errorList.getLength() == 0)
+ return message;
+
+ // else we have one (or more?) error(s):
+ Element error = (Element)errorList.item(0);
+ String errorMessage = ParseUtil.getBodyTextValue(error);
+ String errorType = error.getAttribute("type");
+
+ // no need to display error message if it was a query that was
+ // just executed and no results were found
+ if(//errorType.equals(GSXML.ERROR_TYPE_SYNTAX) &&
+ errorMessage.toLowerCase().indexOf("no documentnode found") != -1)
+ {
+ // if we're in here, we know that a search/query was performed
+ // That means we are dealing with the searchResultsDisplay
+ // and can clear it.
+ this.searchResultsDisplay.clear();
+ this.searchSummary.setText("");
+ }
+ else { // display error message
+ final int numLetters = 60; // number of letters per line
+ String[] words = errorMessage.split(" "); //get the individual words
+ String line = words[0];
+ errorMessage = "";
+ // go through all the words and build up lines where none is
+ // longer than the specified number of letters
+ for(int i = 1; i < words.length; i++) { // append the word
+ // and a space to the same line unless the line is too long
+ if(numLetters > line.length() + words[i].length()) {
+ if(line.equals(""))
+ line = words[i];
+ else line = line + " " + words[i];
+
+ // check if line is full after adding new word
+ if(line.length() == numLetters) { // finish the line
+ errorMessage = errorMessage + line + "\n";
+ line = "";
+ }
+ } // else the word has to go on the next line
+ else { //finish the line and move on:
+ errorMessage = errorMessage + line + "\n";
+ line = words[i];
+ }
+ if(i == (words.length-1)) { // extra word on last line
+ errorMessage = errorMessage + line;
+ }
+ }
+ LOG.debug("errorMessage:\n" + errorMessage);
+ JOptionPane.showMessageDialog(this, errorMessage, "Error: "+errorType,
+ JOptionPane.ERROR_MESSAGE);
+ }
+ return message;
+ }
+
+ /** Event handler for actionEvents such as a change in the active digital
+ * library, a collection being selected in the dropdown box or the collection
+ * -Info button being pressed, or a service being selected in the service
+ * dropdown box (browsing or searching). */
+ public void actionPerformed(ActionEvent e) {
+ if(e.getSource() == dlChooser) {
+ // We need to change to a Wait cursor while we do the switch
+ Container c = this.getContentPane();
+ c.setCursor(Cursor.getPredefinedCursor(Cursor.WAIT_CURSOR));
+
+ boolean success = true;
+ // Change the dlAPIA handle to the chosen digital library,
+ // instantiating DigitalLibraryServicesAPIA objects when necessary:
+ // if they haven't yet been created
+ switch(dlChooser.getSelectedIndex())
+ {
+ case GREENSTONE:
+ if(this.greenstoneDL == null) {
+ success = createGreenstoneDLConnection();
+ }
+ // no need to do anything if the user chose
+ // the same DL again
+ if(success && dlAPIA!=this.greenstoneDL) {
+ // current DL not already set to greenstoneDL
+ // so set it
+ this.changeDL(greenstoneDL);
+ }
+ break;
+ case FEDORA:
+ if(this.fedoraDL == null) {
+ success = createFedoraDLConnection();
+ }
+ // no need to do anything if the user chose
+ // the same DL again
+ if(success && dlAPIA!=this.fedoraDL) {
+ // current DL not already set to fedoraDL
+ // so set it
+ this.changeDL(fedoraDL);
+ }
+ break;
+ case SELECT:
+ default:
+ this.changeDL(null); // no dl, so default colours
+ break;
+ }
+ // set the cursor back
+ c.setCursor(Cursor.getDefaultCursor());
+ } else if(e.getSource() == collBox) {
+ CollectionData collDataEl
+ = (CollectionData)collBox.getSelectedItem();
+
+ if(collDataEl == null) // need to check for this here, because
+ return; // removing all items from collBox fires actionPerformed
+
+ // display the collection's full name
+ this.collectionNameField.setText(collDataEl.getDisplayName());
+ this.collectionNameField.setCaretPosition(0);
+
+ // display the services in the selected collection
+ serviceBox.removeAllItems();
+ ServiceData[] servicelist = collDataEl.getServiceList(
+ executableServicesOnly);
+ for(int i = 0; i < servicelist.length; i++)
+ serviceBox.addItem(servicelist[i]);
+
+ } else if(e.getSource() == serviceBox) {
+ ServiceData selService = (ServiceData)serviceBox.getSelectedItem();
+ if(selService == null || selService.type == null)
+ return; // nothing valid chosen
+
+ if(selService.type.equals(GSXML.SERVICE_TYPE_QUERY)) {
+ // Make sure we can't accidentally work with already deallocated
+ // data objects in the browsePanel
+ browsePanel.clear();
+ searchSummary.setText(""); // empty any text in the search summary
+
+ this.activity = SEARCHING; // ensures the components are
+ // displayed and shown again, whereas a call to repaint()
+ // did not do the trick
+
+ tabbedPane.setSelectedComponent(this.queryPanel);
+
+ // send off a describe request to the service
+ // in that collection
+ CollectionData selColl
+ = (CollectionData)collBox.getSelectedItem();
+ colName = selColl.name;
+ serviceName = selService.name;
+
+ String response = dlAPIA.describeCollectionService(
+ colName, serviceName);
+ Element serviceResponseXML = getResponseAsDOM(
+ "DescribeCollectionService "+colName+"/"+serviceName,
+ response);
+
+ // generate the appropriate query form as per how the
+ // query has described itself
+ queryPanel.formFromQueryServiceDescribe(serviceResponseXML);
+ } else if(selService.type.equals(GSXML.SERVICE_TYPE_BROWSE)) {
+ LOG.debug("Browse option chosen");
+ this.searchResultsDisplay.clear();
+ this.searchSummary.setText("");
+ this.queryPanel.clear(); // can't do any searching either
+ this.activity = BROWSING;
+ tabbedPane.setSelectedComponent(this.browsePanel);
+
+ CollectionData selColl
+ = (CollectionData)collBox.getSelectedItem();
+ colName = selColl.name;
+ serviceName = selService.name;
+
+ // first send a request for the browse service's metadata
+ // see manual pp.37 and 48
+ String response = dlAPIA.describeCollectionService(
+ colName, serviceName);
+ Element responseMsg = getResponseAsDOM(
+ colName+"/"+serviceName+":", response);
+ browsePanel.displayBrowseOptions(responseMsg);
+ } else { // clicked on non-query, non-browse option, remove form
+ queryPanel.clear();
+ }
+ } else if(e.getSource() == collInfoButton){
+ CollectionData collDataEl
+ = (CollectionData)collBox.getSelectedItem();
+
+ // Create the HTML viewing pane.
+ JEditorPane information = new JEditorPane();
+ information.setEditable(false);
+ information.setContentType("text/html");
+ information.setText(collDataEl.info());
+
+ // Display the dialog with the information in a scrollpane
+ JDialog dialog = new JDialog(this, collDataEl.toString());
+ dialog.getContentPane().add(new JScrollPane(information));
+ dialog.setDefaultCloseOperation(DISPOSE_ON_CLOSE); // not EXIT!
+ dialog.pack();
+ dialog.setSize(400, 300);
+ dialog.setVisible(true);
+ }
+ else if(e.getSource() == setProxySettings) { // proxy settings button
+ // Sthe proxy settings as given in the fields
+ String proxyHost = this.proxyhostField.getText();
+ String proxyPort = this.proxyportField.getText();
+ if(proxyHost.equals("") && proxyPort.equals("")) {
+ return;
+ } else {
+ // Handle proxy settings
+ // (don't need to write to propertiesFile, since proxy
+ // settings are System properties)
+ java.util.Properties systemSettings = System.getProperties();
+ systemSettings.put("http.proxyHost", proxyHost);
+ systemSettings.put("http.proxyPort", proxyPort);
+ // give the hosts for which no proxies are required:
+ systemSettings.put("http.nonProxyHosts",
+ this.nonProxyHostNamesField.getText());
+ System.setProperties(systemSettings);
+ }
+ }
+ }
+
+ /** Called by the instance of the QueryForm class when the user has
+ * pressed the queryPanel's search button to execute a query. Based on
+ * the user-entered values (stored in the parameter HashMap) this
+ * method will call Greenstone to process the query.
+ * @param nameValParamsMap - the query form control names with the values
+ * the user has entered for them. Example, the pair (fqv, the query string),
+ * where fqv is the form control name for the query term. */
+ public void performSearch(HashMap nameValParamsMap) {
+ //Container c = this.getContentPane();
+ //c.setCursor(Cursor.getPredefinedCursor(Cursor.WAIT_CURSOR));
+ this.setCursor(Cursor.getPredefinedCursor(Cursor.WAIT_CURSOR));
+
+ // (1) Now let's process this query request - passing the
+ // currently selected collection and service:
+ String responseXML = dlAPIA.query(
+ colName, serviceName, nameValParamsMap);
+
+ // (2) The search results: document identifiers are returned,
+ // use these to construct a QueryResponseData object
+ Element responseMessage
+ = getResponseAsDOM("Search response:", responseXML);
+ queryResponseObj.setResponseData(responseMessage);
+ LOG.debug(queryResponseObj);
+
+ DocumentNodeData[] doclist = queryResponseObj.getDocumentNodeList();
+
+ // (3) To retrieve Title metadata, need to call with "Title"!!!!
+ // (1st letter in caps)
+ // Retrieving just metadata name=Title for ALL docs (=all docIDs)
+ String metaResponseXML = dlAPIA.retrieveTitleMetadata(this.colName,
+ queryResponseObj.getDocumentNodeIDs());
+ Element metaResponse
+ = getResponseAsDOM("Meta response:", metaResponseXML);
+ queryResponseObj.setMetadataForDocuments(metaResponse);
+
+ // doclist should now have been updated with title metadata for
+ // each doc (docNode)
+ //for(int i = 0; i < doclist.length; i++)
+ //LOG.debug(doclist[i].show());
+
+ // (4) Display this in the search results TreeView
+ tabbedPane.setSelectedComponent(searchPanel);
+ searchResultsDisplay.setResults(doclist);
+ searchSummary.setText(queryResponseObj.toString());
+ searchResultsDisplay.validate();
+ this.searchPanel.validate();
+ this.searchPanel.repaint();
+
+ // set the cursor back
+ //c.setCursor(Cursor.getDefaultCursor());
+ this.setCursor(Cursor.getDefaultCursor());
+ }
+
+
+ /* SEARCH RELATED METHODS */
+ /** Performs a docMetadataRetrieve message request for the docNode
+ * iff the metadata for that docNode is not already set.
+ * @param docNode is the DocumentNodeData object for which all the
+ * metadata is to be retrieved. */
+ public void retrieveAllMetadataFor(DocumentNodeData docNode) {
+ // Lazy retrieval: only retrieve metadata of docNode when required
+ // and if metadata not already set
+ if(docNode.getMetadataList() == null
+ || docNode.getMetadataList().size() <= 1)
+ { // not set yet or only title set,
+ // so do a docMetadataRetrieve for the docNode (all
+ // metadata fields retrieved):
+ String metaResponseXML = dlAPIA.retrieveDocumentMetadata(
+ this.colName, new String[] { docNode.nodeID });
+ Element metaResponse
+ = getResponseAsDOM("Meta response", metaResponseXML);
+
+ // Set the metadata for the docNode
+ if(this.activity == SEARCHING)
+ queryResponseObj.setMetadataForDocuments(metaResponse);
+ else if(this.activity == BROWSING)
+ browseResponseObject.setMetadataForDocuments(metaResponse);
+ } //else docNode's list of metadata already set
+ }
+
+ /** Performs a docMetadataRetrieve message request for the docNode
+ * iff the nodeContent for that docNode is not already set.
+ * @param docNode is the DocumentNodeData object for which the content
+ * is to be retrieved. */
+ public void retrieveContentFor(DocumentNodeData docNode) {
+ // Lazy retrieval: only retrieve content when required.
+ // If it is not yet set, then we do the retrieval, else
+ // our work here is done
+ if(docNode.getContent() == null) { // not set yet, so
+ // retrieve the content for the docNode
+ String contentResponseXML = dlAPIA.retrieveDocumentContent(
+ this.colName, new String[] { docNode.nodeID });
+ Element contentResponse = getResponseAsDOM(
+ "Content response:", contentResponseXML);
+ // probably when infomine is down
+ // Set the content for the docNode
+ if(this.activity==SEARCHING)
+ queryResponseObj.setContentForDocs(contentResponse);
+ else if(this.activity==BROWSING)
+ browseResponseObject.setContentForDocs(contentResponse);
+ }
+ }
+
+ /** Performs a structureRetrieve and title metadata retrieve message-
+ * request for the docNode, but only iff the structure and title for
+ * that docNode is not already set.
+ * @param docNode is the DocumentNodeData object for which the title
+ * is to be retrieved along with the titles of all its descendants. */
+ public void retrieveTitledStructureFor(DocumentNodeData docNode) {
+ DocumentNodeData root = docNode.getRoot();
+ if(root == null) { //then its structure has not yet been set
+ // do a structure retrieve for this document:
+ String structureResponseXML = dlAPIA.retrieveDocumentStructure(
+ this.colName, new String[] { docNode.nodeID });
+ Element structureResponse = getResponseAsDOM(
+ "STRUCTURE: ", structureResponseXML);
+
+ // Get the nodeStructure of this docNode, find its root and
+ // from there set all the descendents
+ // Instead of the following 2 statements can also do:
+ // queryResponseObj.setStructureForDocs(structureResponse);
+
+ Element nodeStructure = ParseUtil.getFirstDescElementCalled(
+ structureResponse, GSXML.NODE_STRUCTURE_ELEM);
+
+ // now we set the root and its descendents using whatever
+ ResponseData responseObject = browseResponseObject;
+ // true if(this.activity == BROWSING)
+ if(this.activity == SEARCHING)
+ responseObject = queryResponseObj;
+
+ root = docNode.setDescendentsOfRootNode(nodeStructure,
+ responseObject.getIDToNodeMapping());
+
+ // Now get only the DocumentNodeData elements in the root's
+ // descendents whose titles have not yet been set
+ String[] setTitleForTheseNodeIDs = root.getDescNodeIDsAsList(true);
+ // Will be null if all titles already set! But this should not be
+ // the case if we have just set the descendents of the root node
+ if(setTitleForTheseNodeIDs != null) {
+ // Retrieve the title metadata for these and set their titles
+ // with the response:
+ String titleMetaResponseXML = dlAPIA.retrieveTitleMetadata(
+ this.colName, setTitleForTheseNodeIDs);
+ Element titleMetaResponse = getResponseAsDOM(
+ "titleMetaResponseXML:", titleMetaResponseXML);
+
+ // Use whatever responseObject is active to set the metadata
+ responseObject.setMetadataForDocuments(titleMetaResponse);
+ }
+ }
+ }
+
+ /* BROWSE RELATED METHODS */
+ /** Given a ClassifierData object indicating what browsing category
+ * was chosen, this method will retrieve all its descendants in the
+ * hierarchy. Only the top-level descendents (children) of the
+ * classification will be set initially.
+ * @param classifier is the ClassifierData object whose children are
+ * to be retrieved. */
+ public void doBrowse(ClassifierData classifier) {
+ String response = dlAPIA.retrieveBrowseStructure(
+ this.colName, this.serviceName, classifier.name);
+
+ browseResponseObject.clear();
+ Element responseMsgTag = this.getResponseAsDOM(
+ "browseResponse:", response);
+ browseResponseObject.setResponseData(responseMsgTag); //classifier.name
+
+ LOG.debug(browseResponseObject.show());
+
+ this.browsePanel.displayBrowseResults(browseResponseObject,
+ classifier.displayName);
+ this.browsePanel.validate();
+ }
+
+ /** Given a ClassifierNodeData object for browsing, this method will
+ * set the classNode's children (previously retrieved) and retrieve
+ * all the children's metadata including the title.
+ * @param classNode is the ClassifierNodeData object whose title is to
+ * be retrieved along with the titles for its children. */
+ public void retrieveTitledStructureFor(ClassifierNodeData classNode) {
+ // we will only be setting the children in this method and retrieving
+ // the names for them, as it concerns a classifierNodeData (and not
+ // a documentNodeData).
+
+ classNode.setChildren(browseResponseObject.getIDToNodeMapping());
+
+ //String rootID = browseResponseObject.getRootClassifier().nodeID;
+
+ NodeData[] children = classNode.getChildren();
+ Vector docNodeChildren = new Vector(children.length);
+ Vector classNodeChildren = new Vector(children.length);
+ //String nodeIDs[] = new String[children.length];
+ for(int i = 0; i < children.length; i++) {
+ // don't bother setting the metadata if it was
+ // already set (check for empty metadata
+ if(children[i].getMetadataList() == null) {
+ if(children[i] instanceof ClassifierNodeData)
+ classNodeChildren.add(children[i]);
+ else if(children[i] instanceof DocumentNodeData)
+ docNodeChildren.add(children[i]);
+ }
+ }
+ String[] nodeIDs = null;
+
+ // First set the metadata for any classifiers:
+ if(classNodeChildren.size() > 0) {
+ nodeIDs = new String[classNodeChildren.size()];
+ for(int i = 0; i < nodeIDs.length; i++)
+ nodeIDs[i] = ((NodeData)classNodeChildren.get(i)).nodeID;
+
+ // let's just retrieve all the metadata - need to display it
+ // soon anyway
+ String response = dlAPIA.retrieveBrowseMetadata(this.colName,
+ this.serviceName, nodeIDs);
+ Element responseXML = this.getResponseAsDOM(
+ "MetadataRetrieve response: ", response);
+ browseResponseObject.setMetadataForClassifiers(responseXML);
+
+ for(int i = 0; i < nodeIDs.length; i++)
+ LOG.debug("Title: "
+ + ((NodeData)classNodeChildren.get(i)).getTitle());
+ }
+
+ nodeIDs = null;
+ // Now set the metadata for any documentNodes for which metadata
+ // has not been set yet
+ if(docNodeChildren.size() > 0) {
+ nodeIDs = new String[docNodeChildren.size()];
+ for(int i = 0; i < nodeIDs.length; i++)
+ nodeIDs[i] = ((NodeData)docNodeChildren.get(i)).nodeID;
+
+ // let's just retrieve all the metadata - need to display it
+ // soon anyway
+ String response = dlAPIA.retrieveDocumentMetadata(
+ this.colName, nodeIDs);
+ Element responseXML = this.getResponseAsDOM(
+ "MetadataRetrieve response: ", response);
+ browseResponseObject.setMetadataForDocuments(responseXML);
+
+ for(int i = 0; i < nodeIDs.length; i++)
+ LOG.debug("Title: "
+ + ((NodeData)docNodeChildren.get(i)).getTitle());
+ }
+ }
+
+ /** @return the baseURL of the active digital library interface object */
+ public String getBaseURL() {
+ return this.dlAPIA.getAssocFileBaseURL();
+ }
+
+ /** @return the filepath of the documentNode in the active digital library */
+ public String getFilePath(DocumentNodeData docNode) {
+ return this.dlAPIA.getAssocFileBaseURL(docNode);
+ }
+
+ /**
+ * Changes the background colours of the client's user interface
+ * based on what the active digital library is.
+ * See files greenstone3/gli/classes/xml/config.xml and
+ * greenstone3/gli/src/org/greenstone/gatherer/Configuration.java
+ * @param DL indicates whether the active digital library is Greenstone or
+ * Fedora (or neither, in which case the GUI defaults to the usual grey).
+ * @see Java UIManager tutorial
+ */
+ public void changeUIColour(int DL)
+ {
+ ColourCombo.setColour(DL);
+ ColourCombo.changeColor(this.collBox);
+ ColourCombo.changeColor(this.collectionNameField);
+ ColourCombo.changeColor(this.serviceBox);
+
+ // change anonymous super panels' colours:
+ ColourCombo.changeAncestorColor(this.collBox);
+ ColourCombo.changeAncestorColor(this.serviceBox);
+
+ // change tab pane panels and their colouring
+ this.queryPanel.changeUIColour();
+ this.browsePanel.changeUIColour();
+ this.searchResultsDisplay.changeUIColour();
+ }
+
+ /** The main method of the GS3 java-client application. It instantiates
+ * an instance of the GS3JavaClient main window and makes it visible. */
+ public static void main(String[] args) {
+ // set it up for logging
+ final String logPropsFile = "log4j.properties";
+ PropertyConfigurator.configure(logPropsFile);
+
+ GS3JavaClient client = new GS3JavaClient();
+ client.pack();
+ // make the main window fullscreen (except for on Windows,
+ // where it disappears under the bar at the bottom)
+ java.awt.Dimension d = Toolkit.getDefaultToolkit().getScreenSize();
+ if(System.getProperty("os.name").toLowerCase().contains("windows")) {
+ d.setSize(d.getWidth()-100, d.getHeight()-100);
+ }
+ client.setSize(d);
+ client.setVisible(true);
+ client.setDefaultCloseOperation(EXIT_ON_CLOSE);
+ }
+}
Index: other-projects/gs3-webservices-java-client/trunk/src/GS3DemoClient/org/greenstone/gs3client/GraphPaperLayout.java
===================================================================
--- other-projects/gs3-webservices-java-client/trunk/src/GS3DemoClient/org/greenstone/gs3client/GraphPaperLayout.java (revision 21027)
+++ other-projects/gs3-webservices-java-client/trunk/src/GS3DemoClient/org/greenstone/gs3client/GraphPaperLayout.java (revision 21027)
@@ -0,0 +1,314 @@
+package org.greenstone.gs3client;
+import java.awt.*;
+import java.util.Hashtable;
+
+/**
+ * The GraphPaperLayout class is a layout manager that
+ * lays out a container's components in a rectangular grid, similar
+ * to GridLayout. Unlike GridLayout, however, components can take
+ * up multiple rows and/or columns. The layout manager acts as a
+ * sheet of graph paper. When a component is added to the layout
+ * manager, the location and relative size of the component are
+ * simply supplied by the constraints as a Rectangle.
+ *
+ * import java.awt.*;
+ * import java.applet.Applet;
+ * public class ButtonGrid extends Applet {
+ * public void init() {
+ * setLayout(new GraphPaperLayout(new Dimension(5,5)));
+ * // Add a 1x1 Rect at (0,0)
+ * add(new Button("1"), new Rectangle(0,0,1,1));
+ * // Add a 2x1 Rect at (2,0)
+ * add(new Button("2"), new Rectangle(2,0,2,1));
+ * // Add a 1x2 Rect at (1,1)
+ * add(new Button("3"), new Rectangle(1,1,1,2));
+ * // Add a 2x2 Rect at (3,2)
+ * add(new Button("4"), new Rectangle(3,2,2,2));
+ * // Add a 1x1 Rect at (0,4)
+ * add(new Button("5"), new Rectangle(0,4,1,1));
+ * // Add a 1x2 Rect at (2,3)
+ * add(new Button("6"), new Rectangle(2,3,1,2));
+ * }
+ * }
+ *
+ *
+ * @author Michael Martak
+ */
+
+public class GraphPaperLayout implements LayoutManager2 {
+ int hgap; //horizontal gap
+ int vgap; //vertical gap
+ Dimension gridSize; //grid size in logical units (n x m)
+ Hashtable compTable; //constraints (Rectangles)
+
+ /**
+ * Creates a graph paper layout with a default of a 1 x 1 graph, with no
+ * vertical or horizontal padding.
+ */
+ public GraphPaperLayout() {
+ this(new Dimension(1,1));
+ }
+
+ /**
+ * Creates a graph paper layout with the given grid size, with no vertical
+ * or horizontal padding.
+ */
+ public GraphPaperLayout(Dimension gridSize) {
+ this(gridSize, 0, 0);
+ }
+
+ /**
+ * Creates a graph paper layout with the given grid size and padding.
+ * @param gridSize size of the graph paper in logical units (n x m)
+ * @param hgap horizontal padding
+ * @param vgap vertical padding
+ */
+ public GraphPaperLayout(Dimension gridSize, int hgap, int vgap) {
+ if ((gridSize.width <= 0) || (gridSize.height <= 0)) {
+ throw new IllegalArgumentException(
+ "dimensions must be greater than zero");
+ }
+ this.gridSize = new Dimension(gridSize);
+ this.hgap = hgap;
+ this.vgap = vgap;
+ compTable = new Hashtable();
+ }
+
+ /**
+ * @return the size of the graph paper in logical units (n x m)
+ */
+ public Dimension getGridSize() {
+ return new Dimension( gridSize );
+ }
+
+ /**
+ * Set the size of the graph paper in logical units (n x m)
+ */
+ public void setGridSize( Dimension d ) {
+ setGridSize( d.width, d.height );
+ }
+
+ /**
+ * Set the size of the graph paper in logical units (n x m)
+ */
+ public void setGridSize( int width, int height ) {
+ gridSize = new Dimension( width, height );
+ }
+
+ public void setConstraints(Component comp, Rectangle constraints) {
+ compTable.put(comp, new Rectangle(constraints));
+ }
+
+ /**
+ * Adds the specified component with the specified name to
+ * the layout. This does nothing in GraphPaperLayout, since constraints
+ * are required.
+ */
+ public void addLayoutComponent(String name, Component comp) {
+ }
+
+ /**
+ * Removes the specified component from the layout.
+ * @param comp the component to be removed
+ */
+ public void removeLayoutComponent(Component comp) {
+ compTable.remove(comp);
+ }
+
+ /**
+ * Calculates the preferred size dimensions for the specified
+ * panel given the components in the specified parent container.
+ * @param parent the component to be laid out
+ *
+ * @see #minimumLayoutSize
+ */
+ public Dimension preferredLayoutSize(Container parent) {
+ return getLayoutSize(parent, true);
+ }
+
+ /**
+ * Calculates the minimum size dimensions for the specified
+ * panel given the components in the specified parent container.
+ * @param parent the component to be laid out
+ * @see #preferredLayoutSize
+ */
+ public Dimension minimumLayoutSize(Container parent) {
+ return getLayoutSize(parent, false);
+ }
+
+ /**
+ * Algorithm for calculating layout size (minimum or preferred).
+ *
+ * The width of a graph paper layout is the largest cell width
+ * (calculated in getLargestCellSize() times the number of
+ * columns, plus the horizontal padding times the number of columns
+ * plus one, plus the left and right insets of the target container.
+ *
+ * The height of a graph paper layout is the largest cell height
+ * (calculated in getLargestCellSize() times the number of
+ * rows, plus the vertical padding times the number of rows
+ * plus one, plus the top and bottom insets of the target container.
+ *
+ * @param parent the container in which to do the layout.
+ * @param isPreferred true for calculating preferred size, false for
+ * calculating minimum size.
+ * @return the dimensions to lay out the subcomponents of the specified
+ * container.
+ * @see GraphPaperLayout#getLargestCellSize
+ */
+ protected Dimension getLayoutSize(Container parent, boolean isPreferred) {
+ Dimension largestSize = getLargestCellSize(parent, isPreferred);
+ Insets insets = parent.getInsets();
+ largestSize.width = ( largestSize.width * gridSize.width ) +
+ ( hgap * ( gridSize.width + 1 ) ) + insets.left + insets.right;
+ largestSize.height = ( largestSize.height * gridSize.height ) +
+ ( vgap * ( gridSize.height + 1 ) ) + insets.top + insets.bottom;
+ return largestSize;
+ }
+
+ /**
+ * Algorithm for calculating the largest minimum or preferred cell size.
+ *
+ * Largest cell size is calculated by getting the applicable size of each
+ * component and keeping the maximum value, dividing the component's width
+ * by the number of columns it is specified to occupy and dividing the
+ * component's height by the number of rows it is specified to occupy.
+ *
+ * @param parent the container in which to do the layout.
+ * @param isPreferred true for calculating preferred size, false for
+ * calculating minimum size.
+ * @return the largest cell size required.
+ */
+ protected Dimension getLargestCellSize(Container parent,
+ boolean isPreferred) {
+ int ncomponents = parent.getComponentCount();
+ Dimension maxCellSize = new Dimension(0,0);
+ for ( int i = 0; i < ncomponents; i++ ) {
+ Component c = parent.getComponent(i);
+ Rectangle rect = (Rectangle)compTable.get(c);
+ if ( c != null && rect != null ) {
+ Dimension componentSize;
+ if ( isPreferred ) {
+ componentSize = c.getPreferredSize();
+ } else {
+ componentSize = c.getMinimumSize();
+ }
+ // Note: rect dimensions are already asserted to be > 0 when the
+ // component is added with constraints
+ maxCellSize.width = Math.max(maxCellSize.width,
+ componentSize.width / rect.width);
+ maxCellSize.height = Math.max(maxCellSize.height,
+ componentSize.height / rect.height);
+ }
+ }
+ return maxCellSize;
+ }
+
+ /**
+ * Lays out the container in the specified container.
+ * @param parent the component which needs to be laid out
+ */
+ public void layoutContainer(Container parent) {
+ synchronized (parent.getTreeLock()) {
+ Insets insets = parent.getInsets();
+ int ncomponents = parent.getComponentCount();
+
+ if (ncomponents == 0) {
+ return;
+ }
+
+ // Total parent dimensions
+ Dimension size = parent.getSize();
+ int totalW = size.width - (insets.left + insets.right);
+ int totalH = size.height - (insets.top + insets.bottom);
+
+ // Cell dimensions, including padding
+ int totalCellW = totalW / gridSize.width;
+ int totalCellH = totalH / gridSize.height;
+
+ // Cell dimensions, without padding
+ int cellW = (totalW - ( (gridSize.width + 1) * hgap) )
+ / gridSize.width;
+ int cellH = (totalH - ( (gridSize.height + 1) * vgap) )
+ / gridSize.height;
+
+ for ( int i = 0; i < ncomponents; i++ ) {
+ Component c = parent.getComponent(i);
+ Rectangle rect = (Rectangle)compTable.get(c);
+ if ( rect != null ) {
+ int x = insets.left + ( totalCellW * rect.x ) + hgap;
+ int y = insets.top + ( totalCellH * rect.y ) + vgap;
+ int w = ( cellW * rect.width ) - hgap;
+ int h = ( cellH * rect.height ) - vgap;
+ c.setBounds(x, y, w, h);
+ }
+ }
+ }
+ }
+
+ // LayoutManager2 /////////////////////////////////////////////////////////
+
+ /**
+ * Adds the specified component to the layout, using the specified
+ * constraint object.
+ * @param comp the component to be added
+ * @param constraints where/how the component is added to the layout.
+ */
+ public void addLayoutComponent(Component comp, Object constraints) {
+ if (constraints instanceof Rectangle) {
+ Rectangle rect = (Rectangle)constraints;
+ if ( rect.width <= 0 || rect.height <= 0 ) {
+ throw new IllegalArgumentException(
+ "cannot add to layout: rectangle must have positive width and height");
+ }
+ if ( rect.x < 0 || rect.y < 0 ) {
+ throw new IllegalArgumentException(
+ "cannot add to layout: rectangle x and y must be >= 0");
+ }
+ setConstraints(comp, rect);
+ } else if (constraints != null) {
+ throw new IllegalArgumentException(
+ "cannot add to layout: constraint must be a Rectangle");
+ }
+ }
+
+ /**
+ * Returns the maximum size of this component.
+ * @see java.awt.Component#getMinimumSize()
+ * @see java.awt.Component#getPreferredSize()
+ * @see LayoutManager
+ */
+ public Dimension maximumLayoutSize(Container target) {
+ return new Dimension(Integer.MAX_VALUE, Integer.MAX_VALUE);
+ }
+
+ /**
+ * Returns the alignment along the x axis. This specifies how
+ * the component would like to be aligned relative to other
+ * components. The value should be a number between 0 and 1
+ * where 0 represents alignment along the origin, 1 is aligned
+ * the furthest away from the origin, 0.5 is centered, etc.
+ */
+ public float getLayoutAlignmentX(Container target) {
+ return 0.5f;
+ }
+
+ /**
+ * Returns the alignment along the y axis. This specifies how
+ * the component would like to be aligned relative to other
+ * components. The value should be a number between 0 and 1
+ * where 0 represents alignment along the origin, 1 is aligned
+ * the furthest away from the origin, 0.5 is centered, etc.
+ */
+ public float getLayoutAlignmentY(Container target) {
+ return 0.5f;
+ }
+
+ /**
+ * Invalidates the layout, indicating that if the layout manager
+ * has cached information it should be discarded.
+ */
+ public void invalidateLayout(Container target) {
+ // Do nothing
+ }
+}
Index: other-projects/gs3-webservices-java-client/trunk/src/GS3DemoClient/org/greenstone/gs3client/QueryForm.java
===================================================================
--- other-projects/gs3-webservices-java-client/trunk/src/GS3DemoClient/org/greenstone/gs3client/QueryForm.java (revision 21027)
+++ other-projects/gs3-webservices-java-client/trunk/src/GS3DemoClient/org/greenstone/gs3client/QueryForm.java (revision 21027)
@@ -0,0 +1,255 @@
+/**
+ *#########################################################################
+ * QueryForm.java - part of the demo-client for Greenstone 3, of the
+ * Greenstone digital library suite from the New Zealand Digital Library
+ * Project at the * University of Waikato, New Zealand.
+ *
+ * Copyright (C) 2008 New Zealand Digital Library Project
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *########################################################################
+ */
+
+package org.greenstone.gs3client;
+
+import java.util.HashMap;
+import java.util.Vector;
+
+import org.greenstone.gs3client.data.QueryFormData;
+import org.greenstone.gsdl3.util.GSXML;
+
+import org.w3c.dom.Element;
+import org.w3c.dom.NodeList;
+import org.w3c.dom.Node;
+
+import java.awt.Cursor;
+import java.awt.BorderLayout;
+import javax.swing.BoxLayout;
+import javax.swing.BorderFactory;
+import javax.swing.JButton;
+import javax.swing.JPanel;
+import javax.swing.JScrollPane;
+import javax.swing.border.TitledBorder;
+
+import java.awt.event.KeyListener;
+import java.awt.event.KeyEvent;
+import java.awt.event.ActionListener;
+import java.awt.event.ActionEvent;
+
+/**
+ * Panel that represents a Query Form based on GS3 describe response XML
+ * messages sent by a Query Service. An inner panel will contain all the
+ * actual form controls. The form can be reset to empty which will clear
+ * its contents. Its contents can be reset to display controls appropriate
+ * to new Query Service describe response XML messages.
+ * @author ak19
+*/
+public class QueryForm extends JPanel
+ implements ActionListener, KeyListener, ColourCombo.ColourChangeable
+{
+ /** Handle to the running instance of the GS3JavaClient in order to have
+ * access to its methods */
+ protected GS3JavaClient client;
+ /** Panel to contain all the form controls specific to the chosen Query
+ * Service. */
+ protected JPanel paramsPanel = null;
+ /** Search button that will cause the search to be executed when pressed */
+ protected JButton searchButton = null;
+ /** Query parameters specified by the query services */
+ protected QueryFormData[] paramTags = null;
+
+ /** Constructor that instantiates this Form's internal GUI items.
+ * @param client - handle to the running instance of the GS3JavaClient */
+ public QueryForm(GS3JavaClient client) {
+ super(new BorderLayout());
+ this.client = client;
+
+ // Create the search button and register listeners for button pressed
+ // and Enter key pressed events on it.
+ searchButton = new JButton();
+ searchButton.addActionListener(this);
+ searchButton.addKeyListener(this);
+
+ paramsPanel = new JPanel();
+ paramsPanel.setLayout(new BoxLayout(paramsPanel, BoxLayout.Y_AXIS));
+ }
+
+ /** Call this method to empty all the form controls. This Query Form
+ * component can then be reused. */
+ public void clear() {
+ // empty all controls
+
+ paramsPanel.removeAll();
+ paramTags = null; //get rid of the Params data for the query
+
+ this.removeAll();
+ this.validate();
+ this.setBorder(null);
+ this.repaint();
+ }
+
+ /** Changes the colour of the query form and its controls to the
+ * current colours set in class ColourCombo. Specified by
+ * the ColourCombo.ColourChangeable interface. */
+ public void changeUIColour() {
+ ColourCombo.changeColor(this);
+ ColourCombo.changeColor(this.paramsPanel);
+ }
+
+ /** Called when this QueryForm's search button is pressed: the data
+ * entered/controls settings specified by the user are passed to the
+ * digital library's Query Service in order to perform the search. */
+ public void actionPerformed(ActionEvent e) {
+ this.searchButtonPressed();
+ }
+
+ /** Defined by KeyListener interface. Does nothing. */
+ public void keyPressed(KeyEvent e) {}
+ /** Defined by KeyListener interface. Does nothing. */
+ public void keyTyped(KeyEvent e) {}
+
+ /** Called when the searchButton was in focus and a key was pressed. If
+ * this key was the Enter button, then the search is performed: the data
+ * entered/controls settings specified by the user are passed to the
+ * digital library's Query Service in order to perform the search. */
+ public void keyReleased(KeyEvent e) {
+ if(e.getKeyCode() == KeyEvent.VK_ENTER) {
+ this.searchButtonPressed();
+ }
+ }
+
+ /** Called when the searchButton was clicked or when it was in focus
+ * and the enter key was pressed. The search is performed by passing the
+ * data entered/controls settings specified by the user to the digital
+ * library's Query Service in order to perform the search. */
+ protected void searchButtonPressed() {
+ // (1) Search button pressed: obtain all the user-input from the
+ // query form. Use these to create a HashMap of name-val pairs
+ // representing the parameters for the query.
+ HashMap nameValParamsMap = new HashMap();
+ for(int i = 0; i < paramTags.length; i++) {
+ QueryFormControl formControl = (QueryFormControl)paramTags[i];
+ formControl.setSelectedValue(nameValParamsMap);
+ }
+ // (2) Let the main java-client class handle the rest:
+ this.client.performSearch(nameValParamsMap);
+ }
+
+ /**
+ * Sets up the the query form for display (queryPanel) given the XML of
+ * the response-message returned by a "describe" request sent to a
+ * Query Service. That is, generates the query form as specified
+ * by the given response XML for a Query describe.
+ * @param el - a serviceResponseXML for a describe request that specifies
+ * how the paramsPanel should look.
+ */
+ public void formFromQueryServiceDescribe(Element el) {
+ this.clear();
+
+ // Display the form controls associated with the Query Servie
+
+ // Get the service element embedded inside message:
+ //
+ // service = (Element)el.getElementsByTagName("service").item(0);
+ Element service
+ = (Element)el.getElementsByTagName(GSXML.SERVICE_ELEM).item(0);
+ if(service == null) // shouldn't be the case
+ return; // do nothing
+ Element paramList = null;
+
+ // Some heading information for each Query service display form
+ String nameVal = "", description = "", submit ="";
+
+ // Get all the children. For *services*, these can only be
+ // or elements, as per the manual p.37:
+ // "Subset options for the request [sent to a service] include
+ // paramList and displayItemList."
+ NodeList serviceInfo = service.getChildNodes();
+ for(int i = 0; i < serviceInfo.getLength(); i++){
+ Node n = serviceInfo.item(i);
+ // Skip non-element nodes
+ if(n.getNodeType() != Node.ELEMENT_NODE)
+ continue;
+
+ Element e = (Element)n;
+
+ // Process elements that are *direct* children
+ // of
+ if(e.getTagName().equals(GSXML.DISPLAY_TEXT_ELEM)) {
+ // Retrieve values for attributes where name="name",
+ // name="description", name="submit"
+ if(e.hasAttributes()) {
+ // get value of attribute where name=name:
+ String attribute = e.getAttribute(GSXML.DISPLAY_TEXT_NAME);
+ // now based on the attribute value set the appropriate var:
+ if(attribute.equals(GSXML.DISPLAY_TEXT_NAME))
+ // get text node of element and get its text
+ nameVal = e.getFirstChild().getNodeValue();
+ // name=description
+ else if(attribute.equals(GSXML.DISPLAY_TEXT_DESCRIPTION))
+ description = e.getFirstChild().getNodeValue();
+ else if(attribute.equals(GSXML.DISPLAY_TEXT_SUBMIT))
+ submit = e.getFirstChild().getNodeValue();// text
+ }
+ }
+ // element which contains param elements as children
+ else if(e.getTagName().equals(GSXML.PARAM_ELEM+GSXML.LIST_MODIFIER))
+ {
+ paramList = e;
+ } // else skip the element
+ }
+
+ if(paramList == null) // shouldn't be the case
+ return;
+ // Now process the parameters contained in the element
+
+ if(paramList != null && paramList.hasChildNodes()) {
+ NodeList nl = paramList.getChildNodes();
+ // NodeList nl = paramList.getElementsByTagName(GSXML.PARAM_ELEM);
+ if(nl != null && nl.getLength() > 0) {
+ Vector v = new Vector(nl.getLength());
+ for(int i = 0; i < nl.getLength(); i++) {
+ Node n = nl.item(i);
+ // For Element Nodes, getNodeName() returns the tag name,
+ // and it *never* returns null for *any* Node type
+ if(n.getNodeName().equals(GSXML.PARAM_ELEM)) {
+ v.add((Element)n);
+ }
+ }
+ paramTags = new QueryFormData[v.size()];
+ for(int i = 0; i < paramTags.length; i++) {
+ // we've obtained only elements of type (no
+ //