| 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|---|
| 2 |
|
|---|
| 3 | <html>
|
|---|
| 4 | <head>
|
|---|
| 5 | <title>Running the GS3 web services demo-client application</title>
|
|---|
| 6 | </head>
|
|---|
| 7 | <body>
|
|---|
| 8 | <a href="index.html">Back to index page</a>
|
|---|
| 9 |
|
|---|
| 10 | <h1>Running the GS3 web services demo-client application</h1>
|
|---|
| 11 | In this document,
|
|---|
| 12 | <ul>
|
|---|
| 13 | <li>GS3 refers to Greenstone 3.</li>
|
|---|
| 14 | <li>"client" refers to the "GS3 web services demo-client" application.</li>
|
|---|
| 15 | </ul>
|
|---|
| 16 |
|
|---|
| 17 | <h2>Sections</h2>
|
|---|
| 18 | <ul>
|
|---|
| 19 | <li><a href="#A">A What you need</a></li>
|
|---|
| 20 | <li><a href="#B">B Obtaining the GS3 web services demo-client</a></li>
|
|---|
| 21 | <li><a href="#C">C Compiling the client</a></li>
|
|---|
| 22 | <li><a href="#D">D Running the gs3-webservices-democlient</a></li>
|
|---|
| 23 | <li><a href="#E">E How To Use The Client - a brief description</a></li>
|
|---|
| 24 | <li><a href="#F">F General information on the GS3-webservices-democlient</a></li>
|
|---|
| 25 | <li><a href="#G">G Running the client on a remote machine</a></li>
|
|---|
| 26 | </ul>
|
|---|
| 27 |
|
|---|
| 28 |
|
|---|
| 29 | <h2><a name="A">A What you need</a></h2>
|
|---|
| 30 | <ul>
|
|---|
| 31 | <li>Java 5 (JDK1.5)</li>
|
|---|
| 32 | <li>Greenstone 3 installed and running on an accessible server with the QBRSOAPServer web services deployed on it. See
|
|---|
| 33 | <ul>
|
|---|
| 34 | <li>wiki pages for installing Greenstone</li>
|
|---|
| 35 | <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>
|
|---|
| 36 | </ul>
|
|---|
| 37 | </li>
|
|---|
| 38 | </ul>
|
|---|
| 39 |
|
|---|
| 40 | <h2><a name="B">B Obtaining the GS3 web services demo-client</a></h2>
|
|---|
| 41 | Choose one of the following three methods:
|
|---|
| 42 | <ul>
|
|---|
| 43 | <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>
|
|---|
| 44 | <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>
|
|---|
| 45 | <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 />
|
|---|
| 46 | The SVN repository location for the gs3-webservices-democlient is:
|
|---|
| 47 | <pre>http://svn.greenstone.org/other-projects/trunk/gs3-webservices-democlient
|
|---|
| 48 | </pre>
|
|---|
| 49 | Open a Linux x-term or Windows DOS-prompt and checkout the gs3-webservices-democlient by typing:
|
|---|
| 50 | <pre>svn checkout http://svn.greenstone.org/other-projects/trunk/gs3-webservices-democlient</pre>
|
|---|
| 51 | 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>
|
|---|
| 52 | </ul>
|
|---|
| 53 |
|
|---|
| 54 | <h2><a name="C">C Compiling the client</a></h2>
|
|---|
| 55 | <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.
|
|---|
| 56 |
|
|---|
| 57 | <ol>
|
|---|
| 58 | <li>Open a Linux x-term or Windows DOS-prompt and navigate into the top-level folder of the gs3-webservices-democlient.</li>
|
|---|
| 59 |
|
|---|
| 60 | <li>Now, if you've made changes to the code, type
|
|---|
| 61 | <pre>ant build-demo-client</pre>
|
|---|
| 62 | to create the executable jar file.
|
|---|
| 63 |
|
|---|
| 64 | If you want to recompile it from scratch, type
|
|---|
| 65 | <pre>ant clean
|
|---|
| 66 | ant build-demo-client</pre>
|
|---|
| 67 |
|
|---|
| 68 | If you want a list of other available ant commands (targets), type
|
|---|
| 69 | <pre>ant</pre>
|
|---|
| 70 | or
|
|---|
| 71 | <pre>ant usage</pre>
|
|---|
| 72 | </li>
|
|---|
| 73 | <li>Run the client application as described below.</li>
|
|---|
| 74 | </ol>
|
|---|
| 75 |
|
|---|
| 76 | <h2><a name="D">D Running the gs3-webservices-democlient</a></h2>
|
|---|
| 77 | 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.
|
|---|
| 78 |
|
|---|
| 79 | <ol>
|
|---|
| 80 | <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:
|
|---|
| 81 | <ul>
|
|---|
| 82 | <li>If you are on Linux, open an X-term and type:
|
|---|
| 83 | <pre>./gs3democlient.sh</pre>
|
|---|
| 84 | </li>
|
|---|
| 85 | <li>If you are on Windows, you can double-click the gs3democlient.bat to launch the application</li>
|
|---|
| 86 | <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:
|
|---|
| 87 | <pre>java -jar GS3democlient.jar</pre>
|
|---|
| 88 | </li>
|
|---|
| 89 | </ul>
|
|---|
| 90 | </li>
|
|---|
| 91 | <li>Continue on with the section How To Use The Client, below.</li>
|
|---|
| 92 | </ol>
|
|---|
| 93 |
|
|---|
| 94 | <h2><a name="E">E How To Use The Client - a brief description</a></h2>
|
|---|
| 95 | Once you have the application running, the application window should open up.
|
|---|
| 96 |
|
|---|
| 97 | <ol>
|
|---|
| 98 | <li>At the top, select the Digital Library you want to connect to from the drop-down list.<br />
|
|---|
| 99 | (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.)
|
|---|
| 100 | <ul>
|
|---|
| 101 | <li>Choose Greenstone. It will ask you for the "Wsdl" of the QBRSOAPServer web services.<br />
|
|---|
| 102 | 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>
|
|---|
| 103 | For instance,
|
|---|
| 104 | <pre>http://localhost:9090/greenstone3/services</pre>
|
|---|
| 105 | (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.)
|
|---|
| 106 | </li>
|
|---|
| 107 | <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.
|
|---|
| 108 | </li>
|
|---|
| 109 | </ul>
|
|---|
| 110 | </li>
|
|---|
| 111 | <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>
|
|---|
| 112 | <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>
|
|---|
| 113 | </ol>
|
|---|
| 114 |
|
|---|
| 115 | <h2><a name="F">F General information on the GS3-webservices-democlient</a></h2>
|
|---|
| 116 | <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 />
|
|---|
| 117 | 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>
|
|---|
| 118 | <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>
|
|---|
| 119 | <p>You can view the metadata associated with selected documents (or classifications) in both the Browse and Query tabs.</p>
|
|---|
| 120 |
|
|---|
| 121 |
|
|---|
| 122 | <h2><a name="G">G Running the client on a remote machine</a></h2>
|
|---|
| 123 | 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>
|
|---|
| 124 | 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.
|
|---|
| 125 |
|
|---|
| 126 | <ol>
|
|---|
| 127 | <li>If you haven't already done so, deploy the QBRSOAPServer web services on one computer.</li>
|
|---|
| 128 | <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>
|
|---|
| 129 | <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>
|
|---|
| 130 | <li>Move to another computer.</li>
|
|---|
| 131 | <li>Download the client application as described in the section Obtaining The gs3-webservices-democlient above.</li>
|
|---|
| 132 | <li>Run the client as described in the section Running the gs3-webservices-democlient</li>
|
|---|
| 133 | <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.
|
|---|
| 134 | </li>
|
|---|
| 135 | </ol>
|
|---|
| 136 | </body>
|
|---|
| 137 | </html>
|
|---|
