Changeset 8472

Timestamp:

2004-11-05T15:30:24+13:00 (19 years ago)

Author:

kjdon

Message:

more changes, and added a table of contents

Location:

trunk/gsdl3/docs/manual

Files:

• manual.pdf (modified) ( previous)
• manual.tex (modified) (10 diffs)

trunk/gsdl3/docs/manual/manual.tex

@@ -59 +59 @@
 
 This documentation consists of several parts. Section~\ref{sec:install} is for administrators, and covers \gsiii\  installation, how to access the library, and some administration issues. Section~\ref{sec:user} is for users of the software, and looks at using the sample collections, creating new collections, and how to make small customisations to the interface. The remaining sections are aimed towards  the \gs\  developer. Section~\ref{sec:develop-runtime} describes the run-time system, including the structure of the software, and the message format, while Section~\ref{sec:develop-build} describes the collection building process. Section~\ref{sec:new-features} describes how to add new features to \gs, such as how to add new services, new page types, new plugins for different document formats.  Section~\ref{sec:distributed} describes how to make \gs\  run in a distributed fashion, using SOAP as an example communications protocol. Finally, there are several appendices, including how to install \gs\  from CVS, some notes on Tomcat and SOAP, and a comparison of \gsii\  and \gsiii\  format statements.
+\newpage
+\tableofcontents
 \newpage
 \section{\gs\  installation and administration}\label{sec:install}
@@ -402 +404 @@
 \begin{gsc}\begin{verbatim}
 <?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE DirectoryMetadata SYSTEM "http://greenstone.org/dtd/DirectoryMetadata/1.0/DirectoryMetadata.dtd">
+<!DOCTYPE DirectoryMetadata SYSTEM "http://greenstone.org/dtd/DirectoryMetadata
+         /1.0/DirectoryMetadata.dtd">
 <DirectoryMetadata>
   <FileSet>
@@ -2135 +2138 @@
 \section{Distributed \gs\ }\label{sec:distributed}
 
-\gs\  is designed to run in a distributed fashion. One \gs\  installation can talk to several sites on different computers. This requires some sort of communication protocol. Any protocol can be used, however we have only implemented a simple SOAP protocol.
+\gs\  is designed to run in a distributed fashion. One \gs\  installation can talk to several sites on different computers. This requires some sort of communication protocol. Any protocol can be used, currently we have a simple SOAP protocol.
 
 more explanation..
@@ -2146 +2149 @@
 \end{figure}
 
-We have used Apache SOAP for Java. This is run as a servlet in Tomcat. 
-If you have obtained \gs\  through CVS, you will need to install soap separately, describe in Appendix~\ref{app:soap-cvs}. Debugging soap is described in Appendix~\ref{app:soap-debug}.
+We have used Apache SOAP for Java. This is run as a servlet in Tomcat. Tomcat in Greenstone comes set up to use SOAP, but it is not enabled. To enable it, run \gst{gs3-enable-soap.sh/bat}. For more details about SOAP in Greenstone, see Appendix~\ref{app:soap}. Debugging soap is described in Appendix~\ref{app:soap-debug}.
 
 \subsection{Serving a site using soap}
@@ -2190 +2192 @@
 If you need it, the password for anonymous CVS access is \gst{anonymous}. Note that some older versions of CVS have trouble accessing this repository due to the port number being present. We are using version 1.11.1p1. 
 
-The software needs to be compiled and installed. The installation procedure has been semi-automated. The following sections describe installation under Linux and windows. The most up to date instructions may be found in the README.txt file in the top level gsdl3 directory.
-
-\subsection{Linux install}
-
-What you need to do is:
+The software needs to be compiled and installed. The installation procedure uses a shell script or batch file. The most up to date instructions may be found in the README.txt file in the top level gsdl3 directory.
+
+To install Greenstone once you have checked it out of CVS, do the following (alternatives for Linux or Windows):
 
 \begin{quote}\begin{gsc}
 cd gsdl3\\
-source gs3-setup.sh\\
-./gs3-prepare.sh\\
-./configure \\
-make \\
-make install \\
-\[make docs\] \\
-./gs3-finalise.sh\\
-source gs3-setup.sh \\
+./gs3-install.sh or gs3-install\\
+source gs3-setup.sh or gs3-setup
 \end{gsc}\end{quote}
 
-Note: \gst{source gs3-setup.sh} sets the environment variables \gst{CLASSPATH, PATH, JAVA\_HOME} and needs to be done in a shell before doing collection building etc. 
-
-To startup or shutdown the library (includes the Tomcat server and MYSQL server), the commands are:
+To recompile the code at any stage, you can use
 \begin{quote}\begin{gsc}
-./gs3-launch.sh
-./gs3-launch.sh -shutdown
+source gs3-setup.sh or gs3-setup\\
+make\\
+make install\\
 \end{gsc}\end{quote}
 
-\subsection{Windows install}
-
-[TODO: check that these are correct]
-Make sure that the following environment variables are set: JAVA\_HOME (where the JAva 2 SDK is installed); PATH (should include the CVS program, and \%JAVA\_HOME\%$\backslash$bin). The following commands should be run in a DOS prompt.
-
-Run gs3-setup.bat\\
-Run gs3-prepare.bat\\
-Using Wordpad, edit the gsdl3$\backslash$comms$\backslash$jakarta$\backslash$tomcat$\backslash$conf$\backslash$server.xml file. Add
-
+Note: \gst{gs3-setup} sets the environment variables \gst{CLASSPATH, PATH, JAVA\_HOME} and needs to be done in a shell before doing collection building etc. 
+
+To startup or shutdown the library (includes the Tomcat server and MYSQL server), the commands are (run from the gsdl3 directory):
 \begin{quote}\begin{gsc}
-<!-- GSDL3 Service -->\\
-<Context path='/gsdl3' docBase='@gsdl3home@$\backslash$web' debug='1'
-   reloadable='true'/>
+./gs3-launch.sh or gs3-launch
+./gs3-launch.sh -shutdown or close the window
 \end{gsc}\end{quote}
 
-above the line:
-\gst{<!-- Tomcat Root Context -->}
-
-Still using Wordpad, edit the gsdl3$\backslash$comms$\backslash$jakarta$\backslash$tomcat$\backslash$conf$\backslash$web.xml file. set the value of the 'listings' parameter to false.
-
-Run make.bat\\
-Run make.bat install.\\
-Run gs3-finalise.bat\\
-
-To run \gs\ , run gs3-launch.bat. This will start the Tomcat server in a new DOS window (stop it by closing the window), and open a broser window showing the \gsiii\  homepage.
 
 \newpage
@@ -2251 +2227 @@
 
 
-Tomcat runs by default on port 8080---this can be changed in server.xml, in the \gst{<!-- Define a non-SSL Coyote HTTP/1.1 Connector on port 8080 --><Connector>} element.  The siteConfig files also need changing if Tomcat's port is changed: \gst{<httpAddress>} for the site, and \gst{<address>} for a remote site both use this.
-
-Note: Tomcat must be shutdown and restarted any time you make changes in the following for those changes to take effect:\\
+Tomcat runs by default on port 8080---this can be changed in server.xml, in the \begin{quote}\begin{gsc}
+<!-- Define a non-SSL Coyote HTTP/1.1 Connector on port 8080 -->\\
+<Connector>
+\end{gsc}\end{quote}
+ element.  The siteConfig files also need changing if Tomcat's port is changed: \gst{<httpAddress>} for the site, and \gst{<address>} for a remote site both use this.
+
+Note: Tomcat must be shutdown and restarted any time you make changes in the following for those changes to take effect:
 \begin{bulletedlist}
 \begin{gsc}
@@ -2266 +2246 @@
 On startup, the servlet loads in its collections and services. If the site or collection configuration files are changed, these changes will not take effect until the site/collection is reloaded. This can be done through the reconfiguration messages (see Section~\ref{sec:runtime-config}), or by restarting Tomcat.
 
-We have set up Tomcat to follow symlinks. To disable this feature, remove the \gst{<Resources>} element from the gsdl3 context in \gst{\$GSDL3HOME/comms/jakarta/tomcat/conf/server.xml}:\\
+We have set up Tomcat to follow symlinks. To disable this feature, remove the \gst{<Resources>} element from the gsdl3 context in \\\gst{\$GSDL3HOME/comms/jakarta/tomcat/conf/server.xml}:
 
 \begin{quote}\begin{gsc}
@@ -2275 +2255 @@
 \end{gsc}\end{quote}
 
-We have set up Tomcat to disallow directory listings for everything in the docBase directory.  To turn this back on, you need to edit Tomcat's default web.xml file (\$GSDL3HOME/comms/jakarta/tomcat/conf/web.xml):
+We have set up Tomcat to disallow directory listings for everything in the docBase directory.  To turn this back on, you need to edit Tomcat's default web.xml file (\gst{\$GSDL3HOME/comms/jakarta/tomcat/conf/web.xml}):
 
 In the default servlet definition, change the 'listings' parameter to true.
 
-Tomcat uses a Manager to handle HTTP session information. This may be stored between restarts if possible. To use a persistent session handling manager, uncomment the \gst{<Manager>} element in \gst{\$GSDL3HOME/comms/jakarta/tomcat/conf/server.xml}. For the default manager, session information is stored in the work directory: \gst{\$GSDL3HOME/comms/jakarta/tomcat/work/Standalone/localhost/gsdl3/SESSIONS.ser}. Delete this file to clear the cached session info.
+Tomcat uses a Manager to handle HTTP session information. This may be stored between restarts if possible. To use a persistent session handling manager, uncomment the \gst{<Manager>} element in \\
+\gst{\$GSDL3HOME/comms/jakarta/tomcat/conf/server.xml}. For the default manager, session information is stored in the work directory:\\
+\gst{\$GSDL3HOME/comms/jakarta/tomcat/work/Standalone/localhost/gsdl3/SESSIONS.ser}. Delete this file to clear the cached session info.
 
 \subsection{Proxying Tomcat with apache}
@@ -2294 +2276 @@
 \end{gsc}\end{quote}
 
-In our example, the \gsiii\  servlet can be accessed at \gst{http://www.greenstone.org/greenstone3/library}, instead of at \gst{http://puka.cs.waikato.ac.nz:8080/gsdl3/library}, which is not publically accessible.
+In our example, the \gsiii\  servlet can be accessed at \\
+\gst{http://www.greenstone.org/greenstone3/library}, instead of at \\
+\gst{http://puka.cs.waikato.ac.nz:8080/gsdl3/library}, which is not publically accessible.
 
 \subsection{Running Tomcat behind a proxy}
@@ -2303 +2287 @@
 \section{SOAP}\label{app:soap}
 
-\subsection{Setting up SOAP from CVS}\label{app:soap-cvs}
-
-If you have obtained \gs\  through CVS, you will need to install the SOAP stuff by running:
+Grenstone uses Apache SOAP for distributed communications. This runs as a servlet inside Tomcat, and services can be deployed by the servlet. The SOAP servlet comes ready to run, but not enabled. To enable it, run:
 
 \begin{quote}\begin{gsc}
-install-soap.bash  
+gs3-enable-soap.[sh/bat]
 \end{gsc}\end{quote}
 
-This unpacks the soap distribution, adds a SOAP context to Tomcat's server.xml configuration file, and creates the file \gst{src/java/org/greenstone/gsdl3/SOAPServer.java} from \gst{src/java/org/greenstone/gsdl3/SOAPServer.java.in} (it has a place where gsdl3home needs to be added).
-It also tries to deploy the SOAP service, but this often doesn't work. You may need to run from a shell the following command:
+All this does is to rename the SOAP web.xml.disabled file to web.xml. 
+
+The SOAP service for localsite comes pre-deployed. To get the gateway servlet talking to the localsite SOAP server, you need to shutdown and restart Tomcat. You should now see more collections when you run the gateway servlet.
+
+To deploy a SOAP service for other sites, run
+\begin{quote}\begin{gsc}
+gs3-soap-deploy-site.[sh/bat] <sitename> <siteURI>
+\end{gsc}\end{quote}
+
+This creates a new SOAPServer class for the site (\gst{\$GSDL3HOME/src/java/org/greenstone/gsdl3/SOAPServer<sitename>.java}), creates a resource file for deployment (\gst{\$GSDL3HOME/resources/soap/<sitename>.xml}), and then tries to deploy the service. If the deployment doesn't work, you can run it from the command line like:
 
 \begin{gsc}\begin{verbatim}
 java org.apache.soap.server.ServiceManagerClient 
   http://localhost:8080/soap/servlet/rpcrouter deploy 
-  resources/soap/localsite.xml
+  resources/soap/<sitename>.xml
 \end{verbatim}\end{gsc} 
 
-You can also deploy a service through the website.  If Tomcat is not running, start it up (see \ref{subsec:runtomcat}).
+You can also deploy a service through the website.  If Tomcat is not running, start it up. 
 
 The SOAP servlet can be accessed at \begin{gsc}{\tt http://localhost:8080/soap}\end{gsc}. You should see a welcome page. Click on ``Run the admin client''. This enables you to list, deploy and undeploy SOAP services.
 
-To deploy the SOAPServer for localsite:
+To deploy the SOAPServer for siteX:
 
 Click on ``deploy'' and edit the following fields in the deploy form:
 
 \begin{tabular}{ll}
-ID: & org.greenstone.localsite\\
+ID: & <URI for siteX>\\
 Scope: (choose Session  & Request---new instantiation for each request\\
   or Application)   &    Session---same instantiation across a session\\
         &    Application---only uses one instantiation\\
 Methods: &process\\
-Java Provider / Provider Class: & org.greenstone.gsdl3.SOAPServer\\
+Java Provider / Provider Class: & org.greenstone.gsdl3.SOAPServersiteX\\
 \end{tabular}
 
 Now click the ``deploy'' button at the bottom of the page. If the service has been deployed, it should appear when you click on the left hand ``List'' button.
 
-Information about deployed services is maintained between Tomcat sessions---you only need to deploy it once. To get the gateway servlet talking to the SOAP server, you need to shutdown and restart Tomcat (see \ref{subsec:runtomcat}). You should see more collections when you run the gateway servlet.
+Information about deployed services is maintained between Tomcat sessions---you only need to deploy it once. 
 
 \subsection{Debugging SOAP}\label{app:soap-debug}