org.greenstone.fedora.installer
Class GSearchInstaller

java.lang.Object
  org.greenstone.fedora.installer.GSearchInstaller

public class GSearchInstaller
extends java.lang.Object

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.

Field Summary

java.lang.String	CATALINA_HOME
protected static java.util.Properties	defaults Default initialisation/customisation values.
java.lang.String	FEDORA_HOME
static java.lang.String	FEDORAGSEARCH
java.lang.String	fedoraPassword
java.lang.String	fedoraUsername
protected java.util.Properties	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.
java.lang.String	gsearchWarFileName
java.lang.String	host
java.lang.String	indexName
java.lang.String	port
protected static java.lang.String	PROP_FILE
protected static java.lang.String	PROP_HOST
protected static java.lang.String	PROP_INDEX
protected static java.lang.String	PROP_PASSW
protected static java.lang.String	PROP_PORT
protected static java.lang.String	PROP_REPOS
protected static java.lang.String	PROP_UNAME
java.lang.String	repositoryName
java.lang.String	scriptExtension
static java.lang.String	TOMCAT

Constructor Summary

GSearchInstaller()
GSearchInstaller constructor sets all custom values to defaults

GSearchInstaller(java.util.Properties options)
GSearchInstaller constructor sets the custom values

Method Summary

protected void	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.
protected void	customiseFedoraConfigFile() Makes changes to the fedora.fcfg file located inside FEDORA_HOME.
protected java.util.Properties	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.
static java.lang.String	info()
void	install()
static void	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.
void	waitForServerToStop() Waits for the fedora server to stop
protected void	writeXML(org.w3c.dom.Document doc, java.io.File xmlFile, java.lang.String dtdToAddBackIn) Writes out a DOM structure to a file.

Methods inherited from class java.lang.Object

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

Field Detail

FEDORAGSEARCH

public static final java.lang.String FEDORAGSEARCH

See Also:

Constant Field Values

TOMCAT

public static final java.lang.String TOMCAT

See Also:

Constant Field Values

FEDORA_HOME

public final java.lang.String FEDORA_HOME

CATALINA_HOME

public final java.lang.String CATALINA_HOME

scriptExtension

public final java.lang.String scriptExtension

gSearchProperties

protected java.util.Properties 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. 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

Constructor Detail

GSearchInstaller

public GSearchInstaller()
                 throws java.lang.Exception

GSearchInstaller constructor sets all custom values to defaults

Throws:

java.lang.Exception

GSearchInstaller

public GSearchInstaller(java.util.Properties options)
                 throws java.lang.Exception

GSearchInstaller constructor sets the custom values

Throws:

java.lang.Exception

Method Detail

install

public void install()
             throws java.lang.Exception

Throws:

java.lang.Exception

indexGreenstoneContents

public void indexGreenstoneContents(boolean emptyFirst)
                             throws java.lang.Exception

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.

Throws:

java.lang.Exception

customiseProperties

protected java.util.Properties customiseProperties(java.lang.String propFileName,
                                                   boolean display)
                                            throws java.lang.Exception

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.

Throws:

java.lang.Exception

waitForServerToStop

public void waitForServerToStop()
                         throws java.lang.Exception

Waits for the fedora server to stop

Throws:

java.lang.Exception

waitForFedoraServer

public void waitForFedoraServer()
                         throws java.lang.Exception

Waits for the fedora server to be ready after a server start.

Throws:

java.lang.Exception

replaceDir

protected boolean replaceDir(java.lang.String outputPath,
                             java.lang.String src,
                             java.lang.String dest)

Method that renames folder src in outputPath to dest.

Parameters:

outputPath - is the directory in which src resides.

src - is the name of the folder in outputPath that is to be renamed.

dest - is what src is to be renamed to.

copyPropFile

protected void copyPropFile(java.util.Properties properties,
                            java.lang.String propFileName,
                            java.io.File outputPath)
                     throws java.lang.Exception

Stores the given properties in the file outputPath/propFileName.

Parameters:

properties - is the Properties map to be written out to a file.

propFileName - is the name of the output properties file.

outputPath - is the directory into which the properties file is to be written.

Throws:

java.lang.Exception

copyTemplateFile

protected void copyTemplateFile(java.lang.String src,
                                java.io.File dest,
                                boolean replace)
                         throws java.io.IOException

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

Throws:

java.io.IOException - if the copying failed.

readXML

protected org.w3c.dom.Document readXML(java.lang.Object xmlSource,
                                       java.lang.String dtd_SystemId,
                                       java.lang.String sourceFileName)
                                throws java.lang.Exception

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.

writeXML

protected void writeXML(org.w3c.dom.Document doc,
                        java.io.File xmlFile,
                        java.lang.String dtdToAddBackIn)
                 throws java.lang.Exception

Writes out a DOM structure to a file.

Parameters:

doc - is the DOM to be written out to a file

xmlFile - is the file to write the XML out to

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.

Throws:

java.lang.Exception

replaceElementWithAttrValue

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

Returns:

true if any replacements have been made.

replaceElementWithValue

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

Returns:

true if any replacements have been made.

getValue

public static java.lang.String getValue(org.w3c.dom.Element e)

Extract the text from an element, if any.

Parameters:

e - is the element whose value is to be extracted.

Returns:

the text that's nested in an element's body or "" if there's none.

elementToFormattedString

public static java.lang.String elementToFormattedString(org.w3c.dom.Element e,
                                                        java.lang.String dtd_SystemId)
                                                 throws java.lang.Exception

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.

Throws:

java.lang.Exception

moveUnpackWarFile

protected void moveUnpackWarFile(java.io.File gsearchWarFile)
                          throws java.lang.Exception

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.

customiseFedoraConfigFile

protected void customiseFedoraConfigFile()
                                  throws java.lang.Exception

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.

Throws:

java.lang.Exception

createLuceneIndexDir

protected void createLuceneIndexDir()
                             throws java.lang.Exception

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

showInputDialog

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

getSafeValue

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

parseInstallationArgs

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

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