Index: other-projects/trunk/gs3-webservices-democlient/docs/HowToFiles/0InstallDemoClientInBrief.html
===================================================================
--- other-projects/trunk/gs3-webservices-democlient/docs/HowToFiles/0InstallDemoClientInBrief.html	(revision 15338)
+++ other-projects/trunk/gs3-webservices-democlient/docs/HowToFiles/0InstallDemoClientInBrief.html	(revision 15338)
@@ -0,0 +1,72 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+
+<html>
+<head>
+<title>In brief: getting the GS3 web services demo-client to run</title>
+</head>
+<body>
+<a href="index.html">Back to index page</a>
+
+<h1>In brief: getting the GS3 web services demo-client to run</h1>
+<h2>Sections</h2>
+<ul>
+<li><a href="#A">A Running the demo-client against a Greenstone 3 digital library</a></li>
+<li><a href="#B">B Running the demo-client against a Fedora repository of Greenstone 3 content</a></li>
+</ul>
+
+<h2><a name="A">A Running the demo-client against a Greenstone 3 digital library</a></h2>
+<ol>
+<li>Get and install the latest version of Greenstone 3 from SVN:
+<pre>http://svn.greenstone.org/greenstone3/trunk</pre>
+See the <a href="http://wiki.greenstone.org/wiki/index.php/Installing_Greenstone3">Installing Greenstone 3 wiki page</a> for installation instructions and walkthroughs.
+</li>
+<li>Deploy the QBRSOAPServer as follows. Use a Linux x-term/Windows DOS-prompt to cd into the greenstone 3 installation folder. Then type:
+<pre>ant soap-deploy-localsite</pre>
+It will prompt you for 3 things:
+<ul> 
+<li>the Site you wish to deploy it for (example "localsite")</li> 
+<li>the web services you wish to deploy. Type "QBRSOAPServer", since these are the web services the demo-client works with.</li>
+<li>a name for the web services. If you don't want to remember the name, accept the default "QBRSOAPServerlocalsite".</li>
+</ul>
+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.
+</li>
+<li>Get the demo-client application: download tar.gz/zip version of the GS3 web services demo-client, and unzip it.
+</li>
+<li>Run the demo-client:
+<ul> 
+<li>If you're on windows, go into the demo-client installation folder and double click on the gs3democlient.bat file.</li> 
+<li>If you're on Linux, use an x-term to cd into the demo-client installation folder and run the application by typing 
+<pre>./gs3democlient.sh</pre>
+</li>
+</ul>
+</li>
+<li>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.
+</li>
+<li>To run the demo-client on a separate computer from the Greenstone server where the web services are deployed:<br />
+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.
+</li>
+</ol>
+
+<h2><a name="B">B Running the demo-client against a Fedora repository of Greenstone 3 content</a></h2>
+<ol>
+<li>Get and install Fedora 2.2.1 (you could try a later version, though I haven't yet attempted this). See the document on <a href="3InstallingFedora.html">Installing Fedora</a>.
+</li>
+<li>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.<br />
+Then, if you're on Linux, type in an X-term
+<pre>./fli.sh</pre>
+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.
+</li>
+<li><b>Optional:</b> If you want full-text searching in Fedora, get and install Fedora Generic Search, then use it index the Greenstone 3 docs you exported into the Fedora repository. For details see the document on <a href="4InstallingFedoraGSearch.html">Installing Fedora Generic Search</a>.
+</li>
+<li>Run the demo-client as in point 3 of <a href="#A">Section A</a> above.
+</li>
+<li>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.
+</li>
+<li>To run the demo-client on a separate computer from the Fedora server to the repository containing GS3 docs:<br />
+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.
+</li>
+</ol>
+
+<p><b>NOTE:</b> If you have both Fedora and Greenstone 3 set up as described in Sections <a href="#A">A</a> and <a href="#B">B</a> above, the client can be run against either digital library's repository. The application will require you to connect to both only once.</p>
+</body>
+</html>
Index: other-projects/trunk/gs3-webservices-democlient/docs/HowToFiles/1GettingGS3WebServicesRunning.html
===================================================================
--- other-projects/trunk/gs3-webservices-democlient/docs/HowToFiles/1GettingGS3WebServicesRunning.html	(revision 15338)
+++ other-projects/trunk/gs3-webservices-democlient/docs/HowToFiles/1GettingGS3WebServicesRunning.html	(revision 15338)
@@ -0,0 +1,124 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+
+<html>
+<head>
+<title>Getting web services running on the Greenstone 3 server</title>
+</head>
+<body>
+<a href="index.html">Back to index page</a>
+
+<h1>Getting web services running on the Greenstone 3 server</h1>
+
+You need:
+<ul>
+<li>Greenstone 3 (an up-to-date version, as described in Section A below)</li>
+</ul>
+
+In this document,
+<ul>
+<li>$GSDL3HOME refers to the full path to your Greenstone 3 installation.</li>
+<li>GS3 may be used as a shorthand to refer to Greenstone 3.</li>
+</ul>
+
+<h2>Sections</h2>
+<ul>
+<li><a href="#A">A Preliminary step: need to do this only once</a></li>
+<li><a href="#B">B How to deploy web services on Greenstone 3</a></li>
+<li><a href="#C">C Undeploying web services from Greenstone 3</a></li>
+</ul>
+
+
+<h2><a name="A">A Preliminary step: need to do this only once</a></h2>
+In all likelihood, this step will not be required for versions later than Greenstone 3.03.
+<ul>
+<li>You can either download the latest Greenstone 3 source code from SVN, then compile and install it.</li>
+<li>OR, if you have got a version of Greenstone 3 installed from source already and don't want to get it all over again, then try the following: 
+<ol>
+<li>Make a folder to store back up copies of the files
+<ul>
+<li>$GSDLHOME/build.xml</li>
+<li>$GSDLHOME/build.properties</li>
+<li>$GSDLHOME/resources/soap/site.wsdd.template </li>
+<li>$GSDLHOME/resources/soap/undeploy-site.wsdd.template</li>
+</ul>
+</li>
+
+<li>You need to download the following files. Make sure you click on the files and go to the bottom of the pages where there's a download link.
+<ul>
+<li>go to http://trac.greenstone.org/browser/greenstone3/trunk and download build.xml and build.properties</li>
+<li>go to http://trac.greenstone.org/browser/greenstone3/trunk/resources/soap and download site.wsdd.template and undeploy-site.wsdd.template</li>
+<li>go to http://trac.greenstone.org/browser/greenstone3/trunk/resources/java and get QBRSOAPServer.java.in</li>
+<li>go to http://trac.greenstone.org/browser/greenstone3/trunk/web/WEB-INF/classes and download QBRWebServicesHelp.properties</li>
+</ul>
+</li>
+
+<li>Put these downloaded files into similar locations on in your $GSDLHOME installation:
+<ul>
+<li>$GSDLHOME/build.xml</li>
+<li>$GSDLHOME/build.properties</li>
+<li>$GSDLHOME/resources/soap/site.wsdd.template </li>
+<li>$GSDLHOME/resources/soap/undeploy-site.wsdd.template</li>
+<li>$GSDLHOME/resources/java/QBRSOAPServer.java.in</li>
+<li>$GSDLHOME/web/WEB-INF/classes and download QBRWebServicesHelp.properties</li>
+</ul>
+</li>
+</ol>
+</li>
+</ul>
+
+
+<h2><a name="B">B How to deploy web services on Greenstone 3</a></h2> 
+We'll look at the example of deploying the "QBRSOAPServer" web service which is used by the GS3-webservices-democlient application.
+<ol>
+<li>Go into your $GSDLHOME folder and start tomcat by typing in an X-term or ms-dos prompt:
+<pre>ant start</pre>
+
+<p>(NOTE: Previously, only the fundamental SOAPServer class offered web services for Greenstone. And those web services could and can still be deployed with
+<pre>ant deploy-localsite</pre>
+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.)</p>
+
+<p>While "ant deploy-localsite" deploys the same default SOAPServer web service, we want to deploy another web service this time.</p>
+
+<p>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:
+<pre>ant soap-deploy-site</pre>
+<ol style="list-style-type:lower-alpha">
+<li>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). </li>
+<li>The next time, you need to type the name of the set of web services you wish to deploy. In this case, type 
+<pre>QBRSOAPServer</pre> 
+Note the use of caps and lowercase letters.</li>
+<li>Finally it will ask you want you want to call this set of web services. You can either accept the default name&mdash;which would be QBRSOAPServerlocalsite if you had chosen to deploy it for localsite&mdash;or you can type some other name for the web services. (For instance, GS3AccessWebServices.)<br />
+At present, just accept the default service name of QBRSOAPServerlocalsite.</li>
+</ol>
+If all went well, it would now have been deployed.
+</li>
+
+<li>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:
+<pre>http://localhost:8080/greenstone3/services</pre>
+And on this page, it will mention QBRSOAPServerlocalsite (or whatever name you chose for the web services) among the list of web services deployed.<br />
+There will be a link named <b>wsdl</b> 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.
+
+<p>For example, depending on the serviceName you chose and the host/port where the services have been deployed on, this might be
+<pre>
+http://localhost:8080/greenstone3/services/QBRSOAPServerlocalsite?wsdl
+</pre></p>
+</li>
+</ol>
+
+<h2><a name="C">C Undeploying web services from Greenstone 3</a></h2> 
+When you don't want the web services deployed anymore, you can undeploy them.
+<ol>
+<li>Go into $GSDLHOME folder. Make sure tomcat is running (if not, type "ant start").</li> 
+<li>Type in an X-term:
+<pre>ant soap-undeploy-site</pre>
+</li>
+<li>Type the name of the web services you wish to undeploy.<br /> 
+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:
+<pre>http://localhost:8080/greenstone3/services</pre>
+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.<br />
+For instance, if we had a web service with the name "QBRSOAPServerlocalsite" deployed and wanted it removed, we'd type that name.
+</li>
+</ol>
+
+</body>
+</html>
Index: other-projects/trunk/gs3-webservices-democlient/docs/HowToFiles/2RunningGS3DemoClientWithGs3.html
===================================================================
--- other-projects/trunk/gs3-webservices-democlient/docs/HowToFiles/2RunningGS3DemoClientWithGs3.html	(revision 15338)
+++ other-projects/trunk/gs3-webservices-democlient/docs/HowToFiles/2RunningGS3DemoClientWithGs3.html	(revision 15338)
@@ -0,0 +1,137 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+
+<html>
+<head>
+<title>Running the GS3 web services demo-client application</title>
+</head>
+<body>
+<a href="index.html">Back to index page</a>
+
+<h1>Running the GS3 web services demo-client application</h1>
+In this document,
+<ul>
+<li>GS3 refers to Greenstone 3.</li>
+<li>"client" refers to the "GS3 web services demo-client" application.</li>
+</ul>
+
+<h2>Sections</h2>
+<ul>
+<li><a href="#A">A What you need</a></li>
+<li><a href="#B">B Obtaining the GS3 web services demo-client</a></li>
+<li><a href="#C">C Compiling the client</a></li>
+<li><a href="#D">D Running the gs3-webservices-democlient</a></li>
+<li><a href="#E">E How To Use The Client - a brief description</a></li>
+<li><a href="#F">F General information on the GS3-webservices-democlient</a></li>
+<li><a href="#G">G Running the client on a remote machine</a></li>
+</ul>
+
+
+<h2><a name="A">A What you need</a></h2>
+<ul>
+<li>Java 5 (JDK1.5)</li>
+<li>Greenstone 3 installed and running on an accessible server with the QBRSOAPServer web services deployed on it. See
+<ul>
+<li>wiki pages for installing Greenstone</li>
+<li><a href="1GettingGS3WebServicesRunning.html">Getting web services running on the Greenstone 3 server</a> 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.)</li>
+</ul>
+</li>
+</ul>
+
+<h2><a name="B">B Obtaining the GS3 web services demo-client</a></h2>
+Choose one of the following three methods:
+<ul>
+<li><b>Easy:</b> 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 <b>LOCATION</b> and unzip it.</li>
+<li><b>Involves compiling:</b> 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.</li>
+<li><b>Involves compiling:</b> 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 <a href="http://wiki.greenstone.org/wiki/index.php/Walkthrough:_installing_Greenstone_3_from_SVN_source_on_Windows">Walkthrough: installing Greenstone 3 from SVN source on Windows</a>, section "Preparation: what you need" for more information on where to get an SVN command-line client and how to install it.)<br />
+The SVN repository location for the gs3-webservices-democlient is:
+<pre>http://svn.greenstone.org/other-projects/trunk/gs3-webservices-democlient
+</pre>
+Open a Linux x-term or Windows DOS-prompt and checkout the gs3-webservices-democlient by typing:
+<pre>svn checkout http://svn.greenstone.org/other-projects/trunk/gs3-webservices-democlient</pre>
+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.</li>
+</ul>
+
+<h2><a name="C">C Compiling the client</a></h2>
+<b>NOTE:</b> 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.
+
+<ol>
+<li>Open a Linux x-term or Windows DOS-prompt and navigate into the top-level folder of the gs3-webservices-democlient.</li> 
+
+<li>Now, if you've made changes to the code, type 
+<pre>ant build-demo-client</pre>
+to create the executable jar file.
+
+If you want to recompile it from scratch, type
+<pre>ant clean
+ant build-demo-client</pre>
+
+If you want a list of other available ant commands (targets), type
+<pre>ant</pre>
+or
+<pre>ant usage</pre>
+</li>
+<li>Run the client application as described below.</li>
+</ol>
+
+<h2><a name="D">D Running the gs3-webservices-democlient</a></h2>
+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.
+
+<ol>
+<li>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:
+<ul>
+<li>If you are on Linux, open an X-term and type:
+<pre>./gs3democlient.sh</pre>
+</li>
+<li>If you are on Windows, you can double-click the gs3democlient.bat to launch the application</li>
+<li>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:
+<pre>java -jar GS3democlient.jar</pre>
+</li>	
+</ul>
+</li>
+<li>Continue on with the section How To Use The Client, below.</li>
+</ol>
+
+<h2><a name="E">E How To Use The Client - a brief description</a></h2>
+Once you have the application running, the application window should open up.
+
+<ol>
+<li>At the top, select the Digital Library you want to connect to from the drop-down list.<br />
+(If you don't have Fedora installed, the choosing the Fedora option will not make the connection to a Fedora server. See <a href="3InstallingFedora.html">this page for details on installing Fedora</a> and for links to the official Fedora installation instructions page.)
+<ul>
+<li>Choose Greenstone. It will ask you for the "Wsdl" of the QBRSOAPServer web services.<br /> 
+This means you will need the QBRSOAPServer web services deployed on the Greenstone3 server you want to connect to. See the document <a href="1GettingGS3WebServicesRunning.html">Getting web services running on the Greenstone 3 server</a> 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 <pre>http://HOST:PORT/greenstone3/services</pre>
+For instance, 
+<pre>http://localhost:9090/greenstone3/services</pre>
+(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.)
+</li>
+<li>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, <a href="3InstallingFedora.html">see here for details on installing Fedora</a> and for links to the official Fedora installation instructions page.
+</li>
+</ul>
+</li>
+<li>Once you're connected to the digital library, the available collections can be viewed in the collection drop-down box. Select one you want.</li>
+<li>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.</li>
+</ol>
+
+<h2><a name="F">F General information on the GS3-webservices-democlient</a></h2>
+<p>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 <a href="4InstallingFedoraGSearch.html">Installing Fedora Generic Search</a> for installation steps.)<br /> 
+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.</p>
+<p>The search results are documents that you can click on. If they have a hierarchical structure then the documents can be expanded further.</p>
+<p>You can view the metadata associated with selected documents (or classifications) in both the Browse and Query tabs.</p>
+
+	
+<h2><a name="G">G Running the client on a remote machine</a></h2>
+This section is on how to run the client on one computer when the QBRSOAPServer web services have been deployed on a remote machine.</br>
+Assuming you have the QBRSOAPServer web services deployed on the Greenstone 3 server (as described in <a href="1GettingGS3WebServicesRunning.html">Getting web services running on the Greenstone 3 server</a>) on one machine, your gs3-webservices-democlient can access these services if you install this client application on another machine.
+
+<ol>
+<li>If you haven't already done so, deploy the QBRSOAPServer web services on one computer.</li>
+<li>Point your web browser to the http://HOST:PORT/greenstone3/services page (substitute the host and port on which your Greenstone server resides).</li>
+<li>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).</li>
+<li>Move to another computer.</li>
+<li>Download the client application as described in the section Obtaining The gs3-webservices-democlient above.</li>
+<li>Run the client as described in the section Running the gs3-webservices-democlient</li>
+<li>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.
+</li>
+</ol>
+</body>
+</html>
Index: other-projects/trunk/gs3-webservices-democlient/docs/HowToFiles/3InstallingFedora.html
===================================================================
--- other-projects/trunk/gs3-webservices-democlient/docs/HowToFiles/3InstallingFedora.html	(revision 15338)
+++ other-projects/trunk/gs3-webservices-democlient/docs/HowToFiles/3InstallingFedora.html	(revision 15338)
@@ -0,0 +1,186 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+
+<html>
+<head>
+<title>Installing Fedora</title>
+</head>
+<body>
+<a href="index.html">Back to index page</a>
+
+<h1>Installing Fedora 2.2.1 and Fedora-related information</h1>
+
+<p>Here, we're following <a href="http://www.fedora.info/download/2.2.1/userdocs/distribution/installation.html">the official Fedora instructions for installing Fedora 2.2.1</a></p>
+
+<p>(Installation instructions for other versions of Fedora: 
+<ul>
+<li><a href="http://www.fedora-commons.org/documentation/2.2.2/userdocs/distribution/installation.html">Fedora 2.2.2</a></li>
+<li><a href="http://www.fedora-commons.org/documentation/3.0b1/userdocs/distribution/installation.html">Fedora 3.0</a></li>
+</ul>
+We've not tried using these later versions with the GS3 web services demo-client application yet.)</p>
+
+<p>I've not installed Fedora on Windows, and I've only tried working with 2.2.1 so far. But Fedora's own installation instructions refer to how to get it working on Windows. The procedure seems to be pretty much similar.</p>
+
+
+<h2>Sections</h2>
+<ul>
+<li><a href="#A">A Preliminary Steps</a></li>
+<li><a href="#B">B Installing Fedora 2.2.1</a></li>
+<li><a href="#C">C How to run Fedora (and how to stop it)</a></li>
+<li><a href="#D">D Creating the custom Greenstone 3 pid prefix</a></li>
+<li><a href="#E">E Exporting Greenstone documents into Fedora's repository</a></li>
+<li><a href="#F">F Further Information</a></li>
+</ul>
+
+
+<h2><a name="A">A Preliminary Steps</a></h2>
+<ol>
+<li>You need Greenstone 3.<br />
+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.<br />
+(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.)</li>
+<li>Fedora 2.2.1 requires Java 5 (I used jdk1.5.0_10).<br /> 
+If you wish to compile it yourself, you will need Apache Ant 1.6.5 and put it on your PATH.</li>
+<li>Defining environment variables. See <a href="http://www.fedora.info/download/2.2.1/userdocs/distribution/installation.html#intro.env">the official instructions</a> for further details on this. 
+
+<p>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:
+<ul>
+<li>JAVA_HOME - set this to the path of your JDK folder</li>
+<li>FEDORA_HOME - set this to the full path to that "fedora" folder just mentioned</li>
+<li>CATALINA_HOME should be set to the /full/path/to/fedora/tomcat folder.</li>
+<li>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</li>
+<li>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.</li>
+</ul>
+
+<p>If you're on <b>Linux</b>, 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.<br />
+For example:
+<pre>
+export JAVA_HOME=/opt/jdk1.5.0_10/
+export FEDORA_HOME=/my/path/to/fedora
+export CATALINA_HOME=$FEDORA_HOME/tomcat
+
+PATH=/opt/jdk1.5.0_10/bin:/opt/jdk1.5.0_10/bin/javac:/my/path/to/apache-ant-1.6.5:$FEDORA_HOME/server/bin:$FEDORA_HOME/client/bin:$PATH
+</pre>
+</p>
+
+<p>On <b>Windows</b>, adjustments to your PATH variable, and creation of new variables (like FEDORA_HOME, CATALINA_HOME, JAVA_HOME) are made by going to: <blockquote>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 Path variable.</blockquote>
+Note that on Windows, you use the <b>;</b> sign to append new items to your path, and when referring to previously declared environment variables you have to surround them with <b>%</b> signs:
+E.g.
+<pre>PATH=&lt;whatever-was-on-your-path-before&gt;;%FEDORA_HOME%/server/bin</pre>
+</p>
+</li>
+</ol>
+
+<h2><a name="B">B Installing Fedora 2.2.1</a></h2>
+<ol>
+<li>Download Fedora 2.2.1 from <a href="http://www.fedora.info/download/">http://www.fedora.info/download/</a>.<br />
+(Although I've not tried it, you could also try Fedora 2.2.2 or even Fedora 3 which are available from <a href="http://www.fedora-commons.org/developers/index.php">the Fedora Commons main page</a>)
+</li>
+<li>Extract it.
+</li>
+<li>Make sure you have the environment variables set as described in Preliminary Steps above. 
+In an Linux x-term, move into extracted directory (e.g. fedora-2.2.1-src/) and type in xterm:
+<pre>ant installer</pre>
+Then go into the dist folder of the extraction directory (e.g. fedora-2.2.1-src/dist/) and type:
+<pre>java -jar fedora-2.2.1-installer.jar</pre>
+</li>
+<li>This will run the command-line installer. Choose "quick" installation.
+</li>
+<li>Accept everything as given and set a password for your Fedora Administrator account whose default username is "fedoraAdmin".
+By accepting the defaults, it will the server is set to run on localhost, port 8080 (with shutdown port 8005).
+</li>
+</ol>
+
+<b>You will need to remember the following details of your installation:</b>
+<ul>
+<li>the username for your Fedora account (default would be: fedoraAdmin)</li>
+<li>the password for it (?)</li>
+<li>the host (default would be: localhost)</li>
+<li>the port number (default would be: 8080)</li>
+</ul>
+
+
+<h2><a name="C">C How to run Fedora (and how to stop it)</a></h2> 
+<ol>
+<li>First <b>start</b> up fedora server by typing the following in xterm:
+<pre>$FEDORA_HOME/tomcat/bin/startup.sh</pre>
+
+<li>Point your browser to 
+<pre>http://localhost:8080/fedora/</pre> 
+(or 
+<pre>http://HOST:PORT/fedora</pre>
+with whatever host and port you chose to install it on).</li>
+
+<li>An authorization dialogue will pop up, asking you to enter the username and password you chose upon installation.</li>
+</ol>
+
+If you ever want to <b>stop</b> the Fedora server, you will need to type in the X-term
+<pre>$FEDORA_HOME/tomcat/bin/shutdown.sh</pre>
+
+
+<h2><a name="D">D Creating the custom Greenstone 3 pid prefix</a></h2>
+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".<br />
+To do this, you will need to:
+
+<ol>
+<li>Shutdown the fedora server
+<pre>$FEDORA_HOME/tomcat/bin/shutdown.sh</pre>
+</li>
+<li>Open up fedora's configuration file in a text editor
+<pre>$FEDORA_HOME/server/config/fedora.fcfg</pre>
+</li>
+<li>Go down to where it says:
+<pre>&lt;param name="retainPIDs" value="demo test changeme fedora-bdef fedora-bmech tutorial"&gt;</pre>
+And append greenstone to the list of values, so you get something like:
+<pre>&lt;param name="retainPIDs" value="demo test changeme fedora-bdef fedora-bmech tutorial greenstone"&gt;</pre>
+</li>
+<li>Restart the fedora server
+<pre>$FEDORA_HOME/tomcat/bin/startup.sh</pre>
+</li>
+</ol>
+
+<p>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".<br />
+For more information, you may want to look at the <a href="http://www.fedora.info/release/1.1/userdocs/distribution/release-notes.html">Fedora Release Notes</a>: 
+<blockquote>"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."</blockquote></p>
+
+
+<h2><a name="E">E Exporting Greenstone documents into Fedora's repository</a></h2>
+<p>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.</p>
+
+<div style="color:red"><b>!!!!fli.sh launches modified gli.sh. But fli.bat launches gli.bat which has yet to be edited to work for both gs3 and gs2.</b></div>
+<ul>
+<li>Go into your greenstone 3 installation's gli folder, and run FLI:<br />
+If you're on Windows, double-click on fli.bat.<br />
+On Linux, you would run FLI by typing in an x-term:
+<pre>cd $GSDLHOME/gli
+./fli.sh
+</pre>
+
+</li>
+<li>Enter the host and port on which you set the Fedora server to listen ("localhost" and "8080" by default) and the username and password you chose. </li>
+<li>Build a collection from within FLI in the same manner you would build it in GLI.</li>
+</ul>
+
+<div style="display:none">
+<p>http://trac.greenstone.org/browser/gsdl/trunk/bin/script/g2f-buildcol.pl<br />
+http://trac.greenstone.org/browser/gsdl/trunk/bin/script/g2f-import.pl<br />
+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.</p>
+</div>
+
+
+<h2><a name="F">F Further Information</a></h2>
+<ul>
+<li>To run the Fedora-client application, you would type
+<pre>cd $FEDORA_HOME/client
+fedora-admin.sh
+</pre>
+</li>
+<li>The location of the <b>Fedora Basic Search Interface</b> ("REST interface" as it uses Fedora's URL-based web services) is 
+<pre>http://HOST:PORT/fedora/search</pre>
+where HOST and PORT depend on what you chose when you installed it. E.g. http://localhost:8080/fedora/search<br />
+Note that the default search functionality that Fedora's own access web services (API-A) provide do not include full-text indexing and searching.
+</li>
+<li>To install <b>Fedora Generic Search</b>&mdash;which provides full-text indexing and search capabilities for content stored in a Fedora repository&mdash;see the document <a href="4InstallingFedoraGSearch.html">Installing Fedora Generic Search</a>.
+</li>
+</ul>
+
+</body>
+</html>
Index: other-projects/trunk/gs3-webservices-democlient/docs/HowToFiles/4InstallingFedoraGSearch.html
===================================================================
--- other-projects/trunk/gs3-webservices-democlient/docs/HowToFiles/4InstallingFedoraGSearch.html	(revision 15338)
+++ other-projects/trunk/gs3-webservices-democlient/docs/HowToFiles/4InstallingFedoraGSearch.html	(revision 15338)
@@ -0,0 +1,80 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+
+<html>
+<head>
+<title>Installing Fedora Generic Search</title>
+</head>
+<body>
+<a href="index.html">Back to index page</a>
+
+<h1>Installing Fedora Generic Search</h1>
+In this document,
+<ul>
+<li>$FEDORA_HOME refers to the full path to your Fedora installation directory.<br /> </li>
+<li>For a walkthrough on installing Fedora (and for links to the official Fedora instructions for installation) see <a href="3InstallingFedora.html">Installing Fedora</a>.</li>
+</ul>
+
+
+<ol>
+<li><a href="http://drama.ramp.org.au/cgi-bin/trac.cgi/wiki/InstallingFedoraGSearch">The detailed installation instructions</a> which I followed were written by the Muradora team.
+</li>
+
+<li>Once installed, the FedoraGSearch rest url will by default be at: 
+<pre>http://localhost:8080/fedoragsearch/rest</pre>
+</li>
+
+<li>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.
+<ol style="list-style-type:lower-alpha"> 
+<li>Open the file:
+<pre>$FEDORAHOME/tomcat/webapps/fedoragsearch/WEB-INF/classes/config/index/demoFoxmlToLucene.xslt</pre>
+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:
+<pre>	&lt;xsl:if test="starts-with($PID,'greenstone')"&gt;
+	...
+	&lt;/xsl:if&gt;
+</pre>
+So that now the file contains:
+<pre>&lt;xsl:if test="foxml:digitalObject/foxml:objectProperties/foxml:property[@NAME='http://www.w3.org/1999/02/22-rdf-syntax-ns#type' and @VALUE='FedoraObject']"&gt;
+  <b>&lt;xsl:if test="starts-with($PID,'greenstone')"&gt; // ADDED THIS</b>
+     &lt;!--    filter out annotations: --&gt;
+     &lt;!--
+     	&lt;xsl:choose&gt;
+       	&lt;xsl:when test="foxml:digitalObject/foxml:datastream/foxml:datastreamVersion[last()]/foxml:xmlContent/rdf:RDF/rdf:Description/rel:isMemberOf[@rdf:resource='info:fedora/mura:annotations']"&gt;
+        &lt;/xsl:when&gt; // CORRECTED typo in this comment
+        &lt;xsl:otherwise&gt;
+     --&gt;
+    &lt;xsl:apply-templates mode="activeDemoFedoraObject"/&gt;
+     &lt;!--
+        &lt;/xsl:otherwise&gt;
+        &lt;/xsl:choose&gt;
+     --&gt;
+  <b>&lt;/xsl:if&gt; // ADDED THIS</b>
+&lt;/xsl:if&gt;
+</pre>
+</li>
+
+<li>In the file
+<pre>
+$FEDORAHOME/tomcat/webapps/fedoragsearch/WEB-INF/classes/config/index/index.properties</pre> 
+we're going to add fulltext (and label) to the list of fields that are indexed and are therefore searchable. We do this by appending 
+<pre>
+ds.fulltext ds.label
+</pre> 
+So that it now becomes:
+<pre>fgsindex.defaultQueryFields = dc.description dc.title dc.creator dc.identifier ds.fulltext ds.label</pre>
+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.) 
+</li>
+
+<li>Finally, <b>an important note:</b> Fedora Generic Search only supports indexing and searching Fedora Digital Objects (Fedora repository contents) whose MIME-type is one of
+<ul>
+<li>text/html</li>
+<li>text/plain</li>
+<li>application/pdf</li>
+</ul>
+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.)  
+</li>
+</ol>
+</li>
+</ol>
+
+</body>
+</html>
Index: other-projects/trunk/gs3-webservices-democlient/docs/HowToFiles/5ExposingYourGS3WebServicesOnGS3Server.html
===================================================================
--- other-projects/trunk/gs3-webservices-democlient/docs/HowToFiles/5ExposingYourGS3WebServicesOnGS3Server.html	(revision 15338)
+++ other-projects/trunk/gs3-webservices-democlient/docs/HowToFiles/5ExposingYourGS3WebServicesOnGS3Server.html	(revision 15338)
@@ -0,0 +1,97 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+
+<html>
+<head>
+<title>How to expose custom Greenstone 3 web services on GS3's server</title>
+</head>
+<body>
+<a href="index.html">Back to index page</a>
+
+<h1>How to expose custom Greenstone 3 web services on GS3's server</h1>
+
+What you need:
+<ul>
+<li>Java JDK installed</li>
+<li>Greenstone 3</li>
+</ul>
+
+In this document, 
+<ul>
+<li>$GSDL3HOME refers to the full path to your Greenstone 3 installation.</li>
+<li>GS3 may be used as a shorthand to refer to Greenstone 3.</li>
+</ul>
+
+<h2>Sections</h2>
+<ul>
+<li><a href="#A">A Create your web service Java class</a></li>
+<li><a href="#B">B How to deploy your new web service using GS3'S ant build file</a></li>
+<li><a href="#C">C How to undeploy your web service from greenstone 3</a></li>
+</ul>
+
+
+<h2><a name="A">A Create your web service Java class</a></h2>
+In the steps below, I am assuming that your web service class will be passing either 
+<ul>
+<li>simple data types: strings, ints, floats, characters, boolean, arrays of simple data types, etc., or </li>
+<li>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.</li>
+</ul>
+If this is indeed the case, the default behaviour that will apply when the steps below are followed will be appropriate.<br />
+<b>DETAILS:</b> 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.
+
+<p>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.</p>
+
+<ol>
+<li>Write the Java class that will contain the methods you wish to expose as operations on Greenstone's "services" page.<br />
+Note that I haven't tried working with constructors other than the default constructors (the ones that take no parameters).</li>
+<li>Copy the contents of the java file into a new java file and name it &lt;someWebService&gt;SOAPServer.java.in. For example, this duplicate file would be called MyServicesSOAPServer.java.in</li>
+<li>Edit &lt;someWebService&gt;SOAPServer.java.in so that 
+<ul>
+<li>its class name is &lt;someWebService&gt;SOAPServer@sitename@ </li>
+<li>its constructor is similarly called &lt;someWebService&gt;SOAPServer@sitename@</li>
+<li>Any other explicit references in the file to the class name must similarly be renamed to &lt;someWebService&gt;SOAPServer@sitename@. For instance, a Logger object for the class or static references to the class must now refer to &lt;someWebService&gt;SOAPServer@sitename@.</li>
+</ul>
+</li>
+<li>Place the file &lt;someWebService&gt;SOAPServer.java.in into the folder $GSDL3HOME/resources/java, alongside the other <webservice>SOAPServer.java.in already in here.</li>
+<li>OPTIONAL STEP: Open $GSDL3HOME/build.xml and you can add your web service name (&lt;someWebService&gt;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.</li>
+</ol>
+
+<h2><a name="B">B How to deploy your new web service using GS3'S ant build file</a></h2>
+<ol>
+<li>Open an X-term or DOS-prompt and go into the $GSDL3HOME directory.</li>
+<li>Make sure that Greenstone 3's Tomcat server is running. If it's not running, do:
+<pre>ant start</pre>
+</li>
+<li>Deploy your site by typing:
+<pre>ant soap-deploy-site</pre>
+It will ask you 3 things:
+<ol style="list-style-type:lower-alpha">
+<li>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
+<pre>localsite</pre>
+</li>
+<li>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:
+<pre>&lt;someWebService&gt;SOAPServer</pre>
+</li>
+<li>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 <pre>&lt;someWebService&gt;SOAPServer&lt;NameOftheSiteYouDeployedItFor&gt;</pre>
+It's handy to remember the name of the web services you deployed in case you wish to undeploy it (see Section C below).
+</li>
+</ol>
+</li>
+<li>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 <b>services</b> page for the Site you deployed the web service for. This page will list all the web services deployed.<br />
+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
+</li>
+</ol>
+
+<h2><a name="C">C How to undeploy your web service from greenstone 3</a></h2>
+<ol>
+<li>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).
+</li>
+<li>Open an X-term or DOS prompt and go into the $GSDL3HOME folder.</li>
+<li>Type:
+<pre>soap-undeploy-site</pre>
+It will ask you for the name of the web service you wish to undeploy. Type the name.</li>
+<li>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.
+</li>
+</ol>
+
+</body>
+</html>
Index: other-projects/trunk/gs3-webservices-democlient/docs/HowToFiles/6WritingAWebServiceClient.html
===================================================================
--- other-projects/trunk/gs3-webservices-democlient/docs/HowToFiles/6WritingAWebServiceClient.html	(revision 15338)
+++ other-projects/trunk/gs3-webservices-democlient/docs/HowToFiles/6WritingAWebServiceClient.html	(revision 15338)
@@ -0,0 +1,496 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+
+<html>
+<head>
+<title>How to write a simple client for Greenstone 3 web services</title>
+</head>
+<body>
+<a href="index.html">Back to index page</a>
+
+<h1>How to write a simple client for Greenstone 3 web services</h1>
+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.
+
+<p>In this document,
+<ul>
+<li>$GSDLHOME is the full path to your greenstone 3 directory.</li>
+</ul>
+</p>
+
+<h2>Sections</h2>
+<ul>
+<li><a href="#A">A General information on writing a client for Greenstone 3 web services</a></li>
+<li><a href="#B">B An actual code example</a></li>
+</ul>
+
+<h2><a name="A">A General information on writing a client for Greenstone 3 web services</a></h2>
+<ol>
+<li>First we need Greenstone 3 to deploy the web services in order for our client to have access to its operations.<br />
+Go to $GSDLHOME and type in an X-term:
+<pre>ant soap-deploy-site</pre>
+
+It will ask you for the 
+<ul>
+<li>The greenstone Site you wish to deploy the services for.</li>
+<li>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.</li>
+<li>Give the web service a name.</li>
+</ul>
+
+If you go to the page
+<pre>http://HOST:PORT/greenstone3/services</pre>
+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 operation query, browse and retrieve operations as well as describe operations which will describe the details of these Greenstone 3 services.
+</li>
+<li>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 
+<ol style="list-style-type:lower-alpha">
+<li>import Axis' Call and Service objects:
+<pre>import org.apache.axis.client.Call;
+import org.apache.axis.client.Service;
+import javax.xml.namespace.QName;
+import javax.xml.rpc.ServiceException;
+</pre>
+</li>
+<li>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.
+<pre>try {
+    	service = new Service(wsdlURLName, new QName(namespace, serviceName));
+    } catch(ServiceException e) {
+    	System.err.println("Unable to connect to web services.\nExiting...");
+    	throw(e);
+    }
+</pre>
+</li>
+<li>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:
+<pre>Call call = (Call)this.service.createCall(
+		new QName(namespace, portName), 
+		new QName(namespace, OPERATION_NAME)
+		);
+<pre>
+</li>
+<li>Finally, invoke the operation using that call object by 
+<ul>
+<li>putting the operation's parameters in the right order into an array of Objects and passing that to Call's invoke() method.</li>
+<li>by casting the return value to the expected return type.
+<pre>MyReturnType response = (MyReturnType) call.invoke(new Object[]{
+	paramObj1, paramObj2, ..., paramObjN});
+</pre>
+</li>
+</ul>
+</li>
+</ol>
+
+
+<li>To get a Greenstone client (or web service) to compile or run, you may need to include some jar files in the compile/execution classpath. Look in
+<ul>
+<li>$GSDLHOME/web/WEB-INF/lib/</li>
+<li>$GSDLHOME/lib/</li>
+</ul>
+You may also need $GSDLHOME/web/applet/xml-apis.jar<br />
+If you ever need to use servlets, add in $GSDLHOME/packages/tomcat/common/lib/servlet-api.jar
+</li>
+</ol>
+
+<h2><a name="B">B An actual code example</a></h2>
+We're going to write a simple client for the QBRSOAPServer.
+
+<ol>
+<li>Deploy the QBRSOAPServer in order to have our client access it.
+Go to $GSDLHOME and type in an X-term:
+<pre>ant soap-deploy-site</pre>
+For our example:
+<ul>
+<li>type "localsite", to deploy the services locally.</li>
+<li>type "QBRSOAPServer", to deploy the Query, Browse and Retrieve services.</li>
+<li>press Enter to accept the default web service name of "QBRSOAPServerlocalsite".</li>
+</ul>
+</li>
+<li>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:
+<pre>
+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 invoking Greenstone 3's WebServices
+	 * using its WSDL file */
+	protected Service service; 
+	
+	// Inspect the wsdl file to find at the very bottom, the service name, port name and soap address
+	//endpoint locations:
+	// &lt;wsdl:service name="QBRSOAPServerlocalsiteService"&gt;
+	//	 &lt;wsdl:port binding="impl:QBRSOAPServerlocalsiteSoapBinding" name="QBRSOAPServerlocalsite"&gt;
+	//    &lt;wsdlsoap:address location="http://HOST:PORT/greenstone3/services/QBRSOAPServerlocalsite"/&gt;
+	//   &lt;/wsdl:port&gt;
+	// &lt;/wsdl:service&gt;
+	// 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 of 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.
+	 *	&lt;wsdl:message name="queryRequest"&gt;
+	 *	 &lt;wsdl:part name="collection" type="xsd:string"/&gt;
+	 *	 &lt;wsdl:part name="service" type="xsd:string"/&gt;
+	 *	 &lt;wsdl:part name="lang" type="xsd:string"/&gt;
+	 *	 &lt;wsdl:part name="nameToValsMap" type="apachesoap:Map"/&gt;
+	 *	 &lt;/wsdl:message&gt;
+	 *
+	 *	 From the wsdl file, we also know that the return type is String:
+	 *	 &lt;wsdl:message name="queryResponse"&gt;
+	 *	 &lt;wsdl:part name="queryReturn" type="xsd:string"/&gt;
+	 *	 &lt;/wsdl:message&gt;
+	*/
+	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);
+		}
+	}
+}
+<pre>
+</li>
+<li>In order to compile the above client code, the required jar files are
+<ul>
+<li>$GSDLHOME/web/WEB-INF/lib/axis.jar</li>
+<li>$GSDLHOME/web/WEB-INF/lib/jaxrpc.jar</li>
+</ul>
+</li>
+<li>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:
+<ul>
+<li>commons-logging-**.jar</li>
+<li>commons-discovery-**.jar</li>
+<li>saaj.jar</li>
+<li>wsdl4j-**.jar</li>
+<li>activation.jar</li>
+</ul>
+All of these can be found in the $GSDLHOME/web/WEB-INF/lib folder.
+</li>
+<li>Try executing the code in 2 above. My output is:
+<pre>
+THE DESCRIPTION RETURNED FOR THE FieldQuery SERVICE IS: 
+&lt;message&gt;
+  &lt;response from="gs2mgppdemo/FieldQuery" type="describe"&gt;
+    &lt;service name="FieldQuery" type="query"&gt;
+      &lt;displayItem name="name"&gt;Form Search&lt;/displayItem&gt;
+
+      &lt;displayItem name="submit"&gt;Search&lt;/displayItem&gt;
+
+      &lt;displayItem name="description"&gt;Simple fielded search&lt;/displayItem&gt;
+
+      &lt;paramList&gt;
+        &lt;param default="Sec" name="level" type="enum_single"&gt;
+          &lt;displayItem name="name"&gt;Granularity to search at&lt;/displayItem&gt;
+
+          &lt;option name="Sec"&gt;
+            &lt;displayItem name="name"&gt;Section&lt;/displayItem&gt;
+          &lt;/option&gt;
+
+          &lt;option name="Doc"&gt;
+            &lt;displayItem name="name"&gt;Document&lt;/displayItem&gt;
+          &lt;/option&gt;
+        &lt;/param&gt;
+
+        &lt;param default="1" name="case" type="boolean"&gt;
+          &lt;displayItem name="name"&gt;Turn casefolding &lt;/displayItem&gt;
+
+          &lt;option name="0"&gt;
+            &lt;displayItem name="name"&gt;off&lt;/displayItem&gt;
+          &lt;/option&gt;
+
+          &lt;option name="1"&gt;
+            &lt;displayItem name="name"&gt;on&lt;/displayItem&gt;
+          &lt;/option&gt;
+        &lt;/param&gt;
+
+        &lt;param default="1" name="stem" type="boolean"&gt;
+          &lt;displayItem name="name"&gt;Turn stemming &lt;/displayItem&gt;
+
+          &lt;option name="0"&gt;
+            &lt;displayItem name="name"&gt;off&lt;/displayItem&gt;
+          &lt;/option&gt;
+
+          &lt;option name="1"&gt;
+            &lt;displayItem name="name"&gt;on&lt;/displayItem&gt;
+          &lt;/option&gt;
+        &lt;/param&gt;
+
+        &lt;param default="1" name="accent" type="boolean"&gt;
+          &lt;displayItem name="name"&gt;Turn accentfolding &lt;/displayItem&gt;
+
+          &lt;option name="0"&gt;
+            &lt;displayItem name="name"&gt;off&lt;/displayItem&gt;
+          &lt;/option&gt;
+
+          &lt;option name="1"&gt;
+            &lt;displayItem name="name"&gt;on&lt;/displayItem&gt;
+          &lt;/option&gt;
+        &lt;/param&gt;
+
+        &lt;param default="some" name="matchMode" type="enum_single"&gt;
+          &lt;displayItem name="name"&gt;Match&lt;/displayItem&gt;
+
+          &lt;option name="some"&gt;
+            &lt;displayItem name="name"&gt;some&lt;/displayItem&gt;
+          &lt;/option&gt;
+
+          &lt;option name="all"&gt;
+            &lt;displayItem name="name"&gt;all&lt;/displayItem&gt;
+          &lt;/option&gt;
+        &lt;/param&gt;
+
+        &lt;param default="1" name="sortBy" type="enum_single"&gt;
+          &lt;displayItem name="name"&gt;Document display order&lt;/displayItem&gt;
+
+          &lt;option name="1"&gt;
+            &lt;displayItem name="name"&gt;ranked&lt;/displayItem&gt;
+          &lt;/option&gt;
+
+          &lt;option name="0"&gt;
+            &lt;displayItem name="name"&gt;natural&lt;/displayItem&gt;
+          &lt;/option&gt;
+        &lt;/param&gt;
+
+        &lt;param default="100" name="maxDocs" type="integer"&gt;
+          &lt;displayItem name="name"&gt;Maximum hits to return&lt;/displayItem&gt;
+        &lt;/param&gt;
+
+        &lt;param name="simpleField" occurs="4" type="multi"&gt;
+          &lt;displayItem name="name"&gt;&lt;/displayItem&gt;
+
+          &lt;param name="fqv" type="string"&gt;
+            &lt;displayItem name="name"&gt;Word or phrase &lt;/displayItem&gt;
+          &lt;/param&gt;
+
+          &lt;param default="ZZ" name="fqf" type="enum_single"&gt;
+            &lt;displayItem name="name"&gt;in field&lt;/displayItem&gt;
+
+            &lt;option name="ZZ"&gt;
+              &lt;displayItem name="name"&gt;all fields&lt;/displayItem&gt;
+            &lt;/option&gt;
+
+            &lt;option name="TX"&gt;
+              &lt;displayItem name="name"&gt;text&lt;/displayItem&gt;
+            &lt;/option&gt;
+
+            &lt;option name="DL"&gt;
+              &lt;displayItem name="name"&gt; titles&lt;/displayItem&gt;
+            &lt;/option&gt;
+
+            &lt;option name="DS"&gt;
+              &lt;displayItem name="name"&gt;subjects&lt;/displayItem&gt;
+            &lt;/option&gt;
+
+            &lt;option name="DO"&gt;
+              &lt;displayItem name="name"&gt;organisations&lt;/displayItem&gt;
+            &lt;/option&gt;
+          &lt;/param&gt;
+        &lt;/param&gt;
+      &lt;/paramList&gt;
+    &lt;/service&gt;
+  &lt;/response&gt;
+&lt;/message&gt;
+
+RESULT OF EXECUTING THE QUERY: 
+&lt;message&gt;
+  &lt;response from="gs2mgppdemo/FieldQuery" type="process"&gt;
+    &lt;metadataList&gt;
+      &lt;metadata name="numDocsMatched"&gt;140&lt;/metadata&gt;
+
+      &lt;metadata name="numDocsReturned"&gt;100&lt;/metadata&gt;
+
+      &lt;metadata name="query"&gt; snail water&lt;/metadata&gt;
+    &lt;/metadataList&gt;
+
+    &lt;documentNodeList&gt;
+      &lt;documentNode docType="hierarchy" nodeID="HASH011291f4f0794f8fcd324a43.13" nodeType="leaf" rank="74.75892" /&gt;
+      &lt;documentNode docType="hierarchy" nodeID="HASH0119e312094355aebcb59a77.7.1" nodeType="leaf" rank="40.254803" /&gt;
+      ...
+      &lt;documentNode docType="hierarchy" nodeID="HASH01e7ccf5c76312e6b4caaaab.7.5" nodeType="leaf" rank="0.01744299" /&gt;&lt;/documentNodeList&gt;
+
+    &lt;termList&gt;
+      &lt;term field="" freq="58" name="snail" numDocsMatch="21" stem="5"&gt;
+        &lt;equivTermList&gt;
+          &lt;term freq="" name="Snail" numDocsMatch="" /&gt;
+          &lt;term freq="" name="snail" numDocsMatch="" /&gt;&lt;/equivTermList&gt;
+      &lt;/term&gt;
+
+      &lt;term field="" freq="585" name="water" numDocsMatch="120" stem="5"&gt;
+        &lt;equivTermList&gt;
+          &lt;term freq="" name="Water" numDocsMatch="" /&gt;
+          &lt;term freq="" name="water" numDocsMatch="" /&gt;&lt;/equivTermList&gt;
+      &lt;/term&gt;
+    &lt;/termList&gt;
+  &lt;/response&gt;
+&lt;/message&gt;
+</pre>
+</li>
+</ol>
+
+</body>
+</html>
Index: other-projects/trunk/gs3-webservices-democlient/docs/HowToFiles/7BasicsOfWritingWebServices.html
===================================================================
--- other-projects/trunk/gs3-webservices-democlient/docs/HowToFiles/7BasicsOfWritingWebServices.html	(revision 15338)
+++ other-projects/trunk/gs3-webservices-democlient/docs/HowToFiles/7BasicsOfWritingWebServices.html	(revision 15338)
@@ -0,0 +1,98 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+
+<html>
+<head>
+<title>Writing web services in general - using Java and Apache Axis</title>
+</head>
+<body>
+<a href="index.html">Back to index page</a>
+
+<h1>Writing web services in general - using Java and Apache Axis</h1>
+<p>In this document,
+<ul>
+<li>$GSDLHOME is the full path to your greenstone 3 directory.</li>
+</ul>
+</p>
+
+<h2>Sections</h2>
+<ul>
+<li><a href="#A">A The basics of writing and deploying web services in general</a></li>
+<li><a href="#B">B Troubleshooting</a></li>
+</ul>
+
+<h2><a name="A">A The basics of writing and deploying web services in general</a></h2>
+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.
+
+<ol>
+<li>Write a Java class that will become the web service.<br />
+For example here's UsernameService.java:
+<pre>
+package org.greenstone;
+
+public class UsernameService {
+	public String getUsername() { return "pinky"; }
+}
+</pre>
+Compile it. (Say in Eclipse.)
+</li>
+<li>Copy the *.class file into the correct package structure inside web/WEB-INF/lib/classes folder of Apache axis.<br />
+Since we are using Greenstone 3, this is $GSDLHOME/web/WEB-INF/classes/<correct package structure>. Therefore, in our example, we would copy UsernameService.class into $GSDLHOME/web/WEB-INF/lib/classes/org.greenstone/
+</li>
+
+<li>Once you have deployed localsite (or other site) in Greenstone3 using
+<pre>ant deploy-localsite</pre>
+the file $GSDLHOME/web/WEB-INF/server-config.wsdd would have been generated.
+It would contain one or more &lt;service&gt; elements.
+
+Stop greenstone's tomcat:
+<pre>ant stop</pre>
+
+Copy an existing &lt;service&gt; element in order to create a &lt;service&gt; element for your web service.
+In our example case, you could have:
+<pre>
+ &lt;service name="UsernameService" provider="java:RPC"&gt;
+  &lt;parameter name="allowedMethods" value="getUsername"/&gt;
+  &lt;parameter name="className" value="org.greenstone.UsernameService"/&gt;
+ &lt;/service&gt;
+</pre>
+<b>NOTES:</b>
+<ul>
+<li>Set the service's provider attribute to "java:RPC"</li>
+<li>The serviceName is what you want appearing in the wsdl file (it need not be the same as the class name)</li>
+<li>the className value is your web service Java class with full-package structure.</li>
+<li>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:
+<pre>
+ &lt;service name="MyWebServices" provider="java:RPC"&gt;
+  &lt;parameter name="allowedMethods" value="*"/&gt;
+  &lt;parameter name="className" value="org.greenstone.WebServices"/&gt;
+ &lt;/service&gt;
+</pre>
+</li>
+</ul>
+</li>
+
+<li>We now need to deploy the web service.
+Start tomcat:
+<pre>ant start</pre>
+And now use Axis' AdminClient tool to deploy the web service by typing the following in the x-term from within the GSDLHOME folder:
+<pre>java -cp $AXISCLASSPATH org.apache.axis.client.AdminClient -lhttp://YOURCOMPUTER:YOURPORT/greenstone3/services/AdminService web/WEB-INF/server-config.wsdd</pre>
+Change the computer host and port to suite your situation. For example<br />
+<blockquote>
+java -cp $AXISCLASSPATH org.apache.axis.client.AdminClient -lhttp://harakeke:8080/greenstone3/services/AdminService web/WEB-INF/server-config.wsdd
+</blockquote>
+Check it says DONE PROCESSING or something like it.
+</li>
+
+<li>Stop Tomcat and restart it again.
+In a browser go to the "services" page of the Greenstone 3:
+http://localhost:8080/greenstone3/services
+and find the new service there. There will be a link to its WSDL file as well.
+</li>
+</ol>
+
+<h2><a name="B">B Troubleshooting</a></h2>
+Tried to run axis AdminClient on the server-config.wsdd (service descriptor) file and got an AxisFault Exception?<br />
+SOLUTION: You have to run tomcat (ant start) before running AdminClient.
+
+</body>
+</html>
Index: other-projects/trunk/gs3-webservices-democlient/docs/HowToFiles/index.html
===================================================================
--- other-projects/trunk/gs3-webservices-democlient/docs/HowToFiles/index.html	(revision 15338)
+++ other-projects/trunk/gs3-webservices-democlient/docs/HowToFiles/index.html	(revision 15338)
@@ -0,0 +1,28 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+
+<html>
+<head>
+<title>List of documents related to GS3 web services and the demo-client</title>
+</head>
+<body>
+<h1>List of documents related to GS3 web services and the demo-client application</h1>
+<p>Start with <a href="0InstallDemoClientInBrief.html">In brief: getting the GS3 web services demo-client to run</a></p>
+
+Details:<br />
+Running the GS3 web services demo-client application:
+<ol>
+<li><a href="1GettingGS3WebServicesRunning.html">Getting web services running on the Greenstone 3 server</a></li>
+<li><a href="2RunningGS3DemoClientWithGs3.html">Running the GS3 web services demo-client application</a></li>
+<li><a href="3InstallingFedora.html">Installing Fedora 2.2.1 and Fedora-related information</a></li>
+<li><a href="4InstallingFedoraGSearch.html">Installing Fedora Generic Search</a></li>
+</ol>
+
+Further information:
+<ol>
+<li><a href="5ExposingYourGS3WebServicesOnGS3Server.html">How to expose custom Greenstone 3 web services on GS3's server</a></li>
+<li><a href="6WritingAWebServiceClient.html">How to write a simple client for Greenstone 3 web services</a></li>
+<li><a href="7BasicsOfWritingWebServices.html">Writing web services in general - using Java and Apache Axis</a></li>
+</ol>
+
+</body>
+</html>
