source: other-projects/gs3-webservices-java-client/trunk/README.txt@ 21027

***********************************************************
            README
***********************************************************
Application: Greenstone 3 (QBR) web services demo-client

Summary: Demo-client application in Java for the QBR (Query, 
Browse and Retrieve) web services of Greenstone 3. Also 
provides similar access to a Fedora repository of Greenstone 
collections created by Greenstone's FLI application.

This is a Java demonstration application for Greenstone 3 
that presents a graphical user interface to Greenstone 3's 
Query, Browsing and Retrieval functionality.

The application allows one to search collections and browse 
them by classifiers, displaying the results.
 
It uses the new QBRSOAPServer web services of Greenstone 3 
to access its search and (document and metadata) retrieval 
operations, thereby demonstrating the use of Greenstone 
3's QBR web services.

It also lets you browse Greenstone collections exported by 
the FLI application into a Fedora repository. If Fedora 
Generic Search is installed and if your "Fedora-Greenstone" 
collections are indexed, some basic querying features will 
be available in the demo-client's interface. A tool to help 
install Fedora Generic Search once you have Fedora (2.2.1 or
greater) installed is included.

Documentation on how to use the application, as well as 
related matters like deploying the QBR web services and 
using FLI can be found in the docs/HowToFiles folder when 
the distribution is unzipped.


***********************************************************
        What you need and how to run
***********************************************************
- It runs on Windows XP (not tested on Vista yet) and Linux.
- You need Java 1.5 or higher installed and JAVA_HOME set.
- The Greenstone 3 server the demo-client is to communicate
with must be up-to-date with the latest source code from
the Greenstone SVN repository. The Greenstone 3 server must
have the new QBRSOAPServer web services deployed on it. See
section C.

A. If you've downloaded the zip file:
1. Unzip it into a folder.
2. Open an xterm and go into the folder where you extracted
it and type:
    ./gs3democlient.sh
(If you don't have execute permissions, type
    chmod u+x gs3democlient.sh
    ./gs3democlient.sh
)
If you're on Windows, you can double-click on 
gs3democlient.bat or otherwise open a DOS prompt, navigate
into the folder where you extracted the zip folder and type
    gs3democlient.bat
3. From the drop-down box at the top choose "greenstone"
and type the WSDL URL of the QBRSOAPServer deployed on the
Greenstone 3 server you wish to connect to. See section C.


B. If you've checked out the code and application from SVN, 
you'll need JDK 5 as it is used to compile the code. To get
the application running from SVN:
1. Go into the folder where you've checked it out into.
2. (You'll need an internet connection for this step because
it will download the file CheckJavaVersion.java)
Open an x-term when on Linux or a DOS prompt when on windows
and type:
    ant build-demo-client
This will generate the executable.
To run, type 
    ./gs3democlient.sh 
on Linux and 
    gs3democlient.bat
if you're on windows. (If you've got JAVA_HOME pointing to
JDK 1.5, you can also double-click on gs3democlient.bat to
get it running.) 
3. From the drop-down box at the top choose "greenstone"
and type the WSDL URL of the QBRSOAPServer deployed on the
Greenstone 3 server you wish to connect to. See section C.


C. Deploying the QBRSOAPServer web services on the up-to-
date Greenstone 3 server
1. Go the Greenstone 3 installation folder
2. Type
    ant soap-deploy-site
Then it will prompt you for 3 things. Press Enter to accept
localsite, type "QBRSOAPServer" and Press Enter again to
accept QBRSOAPServerlocalsite. Then point your browser to
http://HOST:PORT/greenstone3/services to see if the QBRSOAP-
Server web services are deployed and to get the link to its
WSDL URL needed by the demo-client application.


For detailed instructions, please refer to the html files 
in the folder docs/HowToFiles