source: trunk/gsdl3/docs/manual/manual.tex@ 9445

Last change on this file since 9445 was 9445, checked in by kjdon, 17 years ago

small changes

  • Property svn:keywords set to Author Date Id Revision
File size: 166.3 KB
Line 
1\documentclass[a4paper,11pt]{article}
2\usepackage{isolatin1,times,epsfig}
3\hyphenation{Message-Router Text-Query}
4
5\newenvironment{gsc}% Greenstone text bits
6{\begin{footnotesize}\begin{tt}}%
7{\end{tt}\end{footnotesize}}
8
9\newcommand{\gst}[1]{{\footnotesize \tt #1}}
10\newcommand{\gsdlhome}{\$GSDL3HOME}
11
12\newcommand{\gsii}{Greenstone 2}
13\newcommand{\gsiii}{Greenstone 3}
14\newcommand{\gs}{Greenstone}
15
16\begin{document}
17
18\title{\gsiii\ : A modular digital library.}
19
20% if you work on this manual, add your name here
21\author{Katherine Don, George Buchanan and Ian H. Witten \\[1ex]
22 Department of Computer Science \\
23 University of Waikato \\ Hamilton, New Zealand \\
24 \{kjdon, grbuchan, ihw\}@cs.waikato.ac.nz}
25
26\date{}
27
28\maketitle
29
30\newenvironment{bulletedlist}%
31{\begin{list}{$\bullet$}{\setlength{\itemsep}{0pt}\setlength{\parsep}{0pt}}}%
32{\end{list}}
33
34\noindent
35Greenstone Digital Library Version 3 is a complete redesign and
36reimplementation of the \gs\ digital library software. The current
37version (\gsii) enjoys considerable success and is being widely used.
38\gsiii \ will capitalise on this success, and in addition it will
39\begin{bulletedlist}
40\item improve flexibility, modularity, and extensibility
41\item lower the bar for ``getting into'' the \gs\ code with a view to
42 understanding and extending it
43\item use XML where possible internally to improve the amount of
44 self-documentation
45\item make full use of existing XML-related standards and software
46\item provide improved internationalisation, particularly in terms of sort order,
47 information browsing, etc.
48\item include new features that facilitate additional ``content management''
49 operations
50\item operate on a scale ranging from personal desktop to corporate library
51\item easily permit the incorporation of text mining operations
52\item use Java, to encourage multilinguality, X-compatibility, and to permit
53 easier inclusion of existing Java code (such as for text mining).
54\end{bulletedlist}
55Parts of \gs\ will remain in other languages (e.g. MG, MGPP); JNI (Java
56Native Interface) will be used to communicate with these.
57
58A description of the general design and architecture of \gsiii\ is covered by the document {\em The design of Greenstone3: An agent based dynamic digital library} (design-2002.ps, in the gsdl3/docs/manual directory).
59
60This 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.
61\newpage
62\tableofcontents
63\newpage
64\section{\gs\ installation and administration}\label{sec:install}
65
66This section covers where to get \gsiii\ from, how to install it and how to run it. The standard method of running \gsiii\ is as a Java servlet. We provide the Tomcat servlet container to run the servlet. Standard web servers may be able to be configured to provide servlet support, and thereby remove the need to use Tomcat. Please see your web server documentation for this. This documentation assumes that you are using Tomcat. To access \gsiii, Tomcat must be started up, and then it can be accessed via a web browser.
67
68
69\subsection{Get and install \gs\ }
70
71\gsiii\ is available from \gst{http://www.greenstone.org/greenstone3}. There are currently two releases: one of Linux, one for Windows. They were built using InstallShieldX, a new multi-platform installer software. This uses Java and is quite slow.
72
73\gsiii\ is also available through CVS (Concurrent Versioning System). This provides the latest development version, and is not guaranteed to be stable. Appendix~\ref{app:cvs} describes how to download and install \gsiii\ from CVS.
74
75\subsubsection{Linux}
76
77Download the latest version of the installer, \gst{gsdl3-x.xx-linux}, and run it in a shell (\gst{./gsdl3-x.xx-linux}). The installation process will prompt you for the installation directory, the name of your computer and what port to run Tomcat on (the defaults being \gst{localhost} and \gst{8080}). Once \gsiii\ has been installed, you can start the library by running \gst{.gs3-launch.sh} from the gsdl3 directory, and opening up a browser pointing to \gst{http://localhost:8080/gsdl3} (substituting your chosen name and port if necessary).
78
79\subsubsection{Windows}
80
81Download the latest Windows installer, \gst{gsdl3-x.xx-win32.exe}, and double click it to start the installation. You will be prompted for the installation directory, installation type, your computer name and the port number to run Tomcat on (defaults are \gst{localhost} and \gst{8080}). Once \gsiii\ is installed, you can access the library by selecting \gst{Greenstone Digital Library 3} in the Start menu.
82
83\subsubsection{Accessing the library in a browser}\label{sec:browser-access}
84
85Once you have started up the library (see the previous sections for OS dependent instructions), you can access it in a browser at \gst{http://localhost:8080/gsdl3} (or \gst{http://your-computer-name:your-chosen-port/gsdl3}). This gets you to a welcome page containing links to four servlets: the \gst{test} servlet (this allows you to check that Tomcat is running properly); the standard \gst{library} servlet which serves \gst{localsite} site with the \gst{default} interface; the \gst{classic} servlet which serves \gst{localsite} using the \gst{classic} or \gsii-style interface; the \gst{gateway} servlet, which serves \gst{gateway} site with the \gst{default} interface. The \gst{gateway} site uses a SOAP connection to communicate with \gst{localsite}, and demonstrates the library working in a distributed fashion.
86
87\subsection{How the library works}
88
89The standard library program is a Java servlet. We use the Tomcat servlet container to present the servlets over the web. Tomcat takes CGI-style URLs and passes the arguments to the servlet, which processes these and returns a page of HTML. As far as an end-user is concerned, a servlet is a Java version of a CGI program. The interaction is similar: access is via a web browser, using arguments in a URL.
90
91Other types of interfaces can be used, such as Java GUI programs. See Section~\ref{sec:new-interfaces} for details about how to make these.
92
93\subsubsection{Restarting the library}
94
95The library program (actually Tomcat) can be restarted in Windows by closing the window, and restarting it from the Start menu. In Linux, you need to go to the gsdl3 directory, and run \gst{./gs3-launch.sh -shutdown}, then \gst{./gs3-launch.sh}.
96
97
98Tomcat must be restarted any time you make changes in the following for those changes to take effect:\\
99\begin{bulletedlist}
100\begin{gsc}
101\item \gsdlhome/web/WEB-INF/web.xml
102\item \gsdlhome/comms/jakarta/tomcat/conf/server.xml
103\end{gsc}
104\item any classes or jar files used by the servlets
105\end{bulletedlist}
106\noindent Note: stdout and stderr for the servlets both go to\\
107\gst{\gsdlhome/comms/jakarta/tomcat/logs/catalina.out}
108
109
110\subsection{Directory structure}
111
112Table~\ref{tab:dirs} shows the file hierarchy for \gsiii\ .
113The first part shows the common stuff which can be shared between
114\gs\ users---the source, libraries etc. The second part shows the file hierarchy for the gsdl3/web directory, which comprises the gsdl3 context for Tomcat, and is accessible via Tomcat. The main directories are for sites and interfaces: there can be several sites and interfaces per installation, and they are described in the following section.
115
116
117\begin{table}
118\caption{The \gs\ directory structure}
119\label{tab:dirs}
120{\footnotesize
121\begin{tabular}{l p{8cm}}
122\hline
123\bf directory & \bf description \\
124\hline
125gsdl3
126 & The main installation directory---gsdl3home can be changed to something more standard\\
127gsdl3/src
128 & Source code lives here \\
129gsdl3/src/java/
130 & java source code \\
131gsdl3/packages
132 & Imported packages from other systems e.g. MG, MGPP \\
133gsdl3/lib
134 & Shared library files\\
135gsdl3/lib/java
136 & Java jar files\\
137gsdl3/resources
138 & any resources that may be needed\\
139gsdl3/resources/java
140 & properties files for java resource bundles - used to handle all the language specific text This directory is on the class path, so any other Java resources can be placed here \\
141gsdl3/resources/soap
142 & soap service description files \\
143gsdl3/resources/dtd
144 & \gsiii\ has trouble locating DTD files sometimes. They can go here\\
145gsdl3/bin
146 & executable stuff lives here\\
147gsdl3/bin/script
148 & some Perl and/or shell building scripts\\
149gsdl3/comms
150 & Communication packages: Tomcat and SOAP\\
151gsdl3/docs
152 & Documentation\\
153\hline
154gsdl3/web
155 & This is where the web site is defined. Any static HTML files can go here. This directory is the Tomcat root directory.\\
156gsdl3/web/WEB-INF
157 & The web.xml file lives here (servlet configuration information for Tomcat)\\
158gsdl3/web/WEB-INF/classes
159 & Servlet classes go in here\\
160gsdl3/web/sites
161 & Contains directories for different sites---a site is a set of collections and services served by a single MessageRouter (MR). The MR may have connections (e.g. soap) to other sites\\
162gsdl3/web/sites/localsite
163 & An example site - the site configuration file lives here\\
164gsdl3/web/sites/localsite/collect
165 & The collections directory \\
166gsdl3/web/sites/localsite/images
167 & Site specific images \\
168gsdl3/web/sites/localsite/transforms
169 & Site specific transforms \\
170gsdl3/web/interfaces
171 & Contains directories for different interfaces - an interface is defined by its images and XSLT files \\
172gsdl3/web/interfaces/default
173 & The default interface\\
174gsdl3/web/interfaces/default/images
175 & The images for the default interface\\
176gsdl3/web/interfaces/default/transforms
177 & The XSLT files for the default interface\\
178\hline
179\end{tabular}}
180\end{table}
181
182
183\subsection{Sites and interfaces}\label{sec:sites-and-ints}
184
185[local gs stuff (sites and interfaces) vs installed stuff (code)\\
186where they live, whats the difference, what each contains.]\\
187Sites and interfaces contain the content and presentation information, respectively, for the digital library.
188A site is comprised of a set of collections and possibly some site-wide services. An interface (in this web-based servlet context) is a set of images along with a set of XSLT files used for translating xml output from the library into an appropriate form---HTML in general.
189
190One \gsiii\ installation can have many sites and interfaces, and these can be paired in different combinations. One instantiation of a servlet uses one site and one interface, so every specified pairing results in a new servlet instance. For example, a single site might be served with two different interfaces. This provides different modes of access to the same content. e.g. HTML vs WML, or perhaps providing a completely different look and feel for different audiences. Alternatively, a standard interface may be used with many different sites---providing a consistent mode of access to a lot of different content.
191
192Collections live in the \gst{collect} directory of a site. Any collections that are found in this directory when the servlet is initialised will be loaded up and presented to the user. Collections require valid configuration files, but apart from this, nothing needs to be done to the site to use new collections. Collections added while Tomcat is running will not be noticed automatically. Either the server needs to be restarted, or a configuration request may be sent to the library, triggering a (re)load of the collection (this is described in Section~\ref{sec:runtime-config}).
193
194There are two sites that come with the distribution: \gst{localsite}, and \gst{gateway}. \gst{localsite} has several demo collections, while \gst{gateway} has none. \gst{gateway} specifies that a SOAP connection should be made to \gst{localsite}. Getting this to work involves setting up a soap server for localsite: see Section~\ref{sec:distributed} for details.
195There are also two interfaces provided in the distribution: \gst{default} and \gst{classic}. The default interface is a generic \gsiii\ interface, while the \gst{classic} interface aims to look like the old \gsii\ interface.
196
197Each site and interface has a configuration file which specifies parameters for the site or interface---these are described in Section~\ref{sec:config}.
198
199\subsection{Configuring Tomcat}\label{sec:tomcat-config}
200
201The file \gst{\gsdlhome/web/WEB-INF/web.xml} contains the configuration information for Tomcat. It tells Tomcat what servlets to load, what initial parameters to pass them, and what web names map to the servlets.
202There are four servlets specified in web.xml (these correspond to the four servlet links in the welcome page for \gsiii): one is a test servlet that just prints ``hello greenstone'' to a web page. This is useful if you are having trouble getting Tomcat set up. The other three are the \gs\ library servlets described in Section~\ref{sec:browser-access}, \gst{library}, \gst{classic} and \gst{gateway}. Each servlet must specify which site and which interface to use. Having multiple servlets provides a way of serving different sites, or the same site with a different style of presentation. Site\_name and interface\_name are just two examples of initialisation parameters used by the library servlets. The full list is shown in Table~\ref{tab:serv-init}.
203
204For more details about Tomcat see Appendix~\ref{app:tomcat}.
205
206\begin{table}
207\caption{\gs\ servlet initialisation parameters}
208\label{tab:serv-init}
209{\footnotesize
210\begin{tabular}{llp{5cm}}
211\hline
212\bf name & \bf sample value & \bf description \\
213\hline
214gsdl3\_home & /research/kjdon/gsdl3 & the base directory of the gsdl3 installation \\
215site\_name & localsite & the name of the site to use \\
216interface\_name & default & the name of the interface to use\\
217library\_name & library & the web name of the servlet \\
218default\_lang & en & the default language for the interface\\
219receptionist\_class & NZDLReceptionist & (optional) specifies an alternative Receptionist to use\\
220messagerouter\_class & NewMessageRouter & (optional) specifies an alternative MessageRouter to use\\
221params\_class & NZDLParams & (optional) specifies an alternative GSParams class to use \\
222\hline
223\end{tabular}}
224\end{table}
225
226\subsection{Configuring a \gs\ library}\label{sec:config}
227
228Initial \gsiii\ system configuration is determined by a set of configuration files, all expressed in XML. Each site has a configuration file that binds parameters for the site, \gst{siteConfig.xml}. Each interface has a configuration file, \gst{interfaceConfig.xml}, that specifies Actions for the interface. Collections also have several configuration files; these are discussed in Section~\ref{sec:collconfig}.
229The configuration files are read in when the system is initialised, and their contents are cached in memory. This means that changes made to these files once the system is running will not take immediate effect. Tomcat needs to be restarted for changes to the interface configuration file to take effect. However, changes to the site configuration file can be incorporated sending a system command to the library. There are a series of system commands that can be sent to the library to induce reconfiguration of different modules, including reloading the whole site. This removes the need to restart the system to reflect these changes. These commands are described in Section~\ref{sec:runtime-config}.
230
231\subsubsection{Site configuration file}\label{sec:siteconfig}
232
233The file \gst{siteConfig.xml} specifies the URI for the site (\gst{localSiteName}), the HTTP address for site resources (\gst{httpAddress}), any ServiceClusters that the site provides (for example, collection building), any ServiceRacks that do not belong to a cluster or collection, and a list of
234known external sites to connect to. Collections are not specified in the site
235configuration file, but are determined by the contents of the site's
236collections directory.
237
238The HTTP address is used for retrieving resources from a site outside the XML protocol. Because a site is HTTP accessible through Tomcat, any files (e.g. images) belonging to that site or to its collections can be specified in the HTML of a page by a URL. This avoids having to retrieve these files from a remote site via the XML protocol\footnote{Currently, sites live inside the Tomcat gsdl3 root context, and therefore all their content is accessible over HTTP via the Tomcat address. We need to see if parts can be restricted. Also, if we use a different protocol, then resources from remote sites may need to come through the XML. Also, if we are running locally without using Tomcat, we may want to get them via file:// rather than http://.}.
239
240Figure~\ref{fig:siteconfig} shows two example site configuration files. The first example is for a rudimentary site with no site-wide services,
241which does not connect to any external sites. The second example is for a site with one site-wide service cluster - a collection building cluster. It also connects to the first site using SOAP.
242These two sites happen to be running on the same machine, which is why they can use \gst{localhost} in the address. For site \gst{gsdl1} to talk to site \gst{localsite}, a SOAP server must be run for \gst{localsite}. The address of the SOAP server, in this case, is \gst{http://localhost:8080/soap/servlet/rpcrouter}.
243
244
245\begin{figure}
246\begin{gsc}\begin{verbatim}
247<siteConfig>
248 <localSiteName value="org.greenstone.localsite"/>
249 <httpAddress value="http://localhost:8080/gsdl3/sites/localsite"/>
250 <serviceClusterList/>
251 <serviceRackList/>
252 <siteList/>
253</siteConfig>
254\end{verbatim}\end{gsc}
255
256\begin{gsc}\begin{verbatim}
257<siteConfig>
258 <localSiteName value="org.greenstone.gsdl1"/>
259 <httpAddress value="http://localhost:8080/gsdl3/sites/gsdl1"/>
260 <serviceClusterList>
261 <serviceCluster name="build">
262 <metadataList>
263 <metadata name="Title">Collection builder</metadata>
264 <metadata name="Description">Builds collections in a
265 gsdl2-style manner</metadata>
266 </metadataList>
267 <serviceRackList>
268 <serviceRack name="GS2Construct"/>
269 </serviceRackList>
270 </serviceCluster>
271 </serviceClusterList>
272 <siteList>
273 <site name="org.greenstone.localsite"
274 address="http://localhost:8080/soap/servlet/rpcrouter"
275 type="soap"/>
276 </siteList>
277</siteConfig>
278\end{verbatim}\end{gsc}
279\caption{Two sample site configuration files}
280\label{fig:siteconfig}
281\end{figure}
282
283\subsubsection{Interface configuration file}\label{sec:interfaceconfig}
284
285The interface configuration file \gst{interfaceConfig.xml} lists all the actions that the interface knows about at the start (other ones can be loaded dynamically). Actions create the web pages for the library: there is generally one Action per type of page. For example, a query action produces the pages for searching, while a document action displays the documents. The configuration file specifies what short name each action maps to (this is used in library URLs for the a (action) parameter) e.g. QueryAction should use a=q. If the interface uses XSLT, it specifies what XSLT file should be used for each action and possibly each subaction. This makes it easy for developers to implement and use different actions and/or XSLT files without recompilation. The server must be restarted, however.
286
287It also lists all the languages that the interface text files have been translated into. These have a \gst{name} attribute, which is the ISO code for the language, and a \gst{displayElement} which gives the language name in that language (note that this file should be encoded in UTF-8). This language list is used on the Preferences page to allow the user to change the interface language. Details on how to add a new language to a \gsiii\ library are shown in Section~\ref{sec:interface-customise}.
288
289\begin{figure}
290\begin{gsc}\begin{verbatim}
291<interfaceConfig>
292 <actionList>
293 <action name='p' class='PageAction'>
294 <subaction name='home' xslt='home.xsl'/>
295 <subaction name='about' xslt='about.xsl'/>
296 <subaction name='help' xslt='help.xsl'/>
297 <subaction name='pref' xslt='pref.xsl'/>
298 </action>
299 <action name='q' class='QueryAction' xslt='basicquery.xsl'/>
300 <action name='b' class='GS2BrowseAction' xslt='classifier.xsl'/>
301 <action name='a' class='AppletAction' xslt='applet.xsl'/>
302 <action name='d' class='DocumentAction' xslt='document.xsl'/>
303 <action name='xd' class='XMLDocumentAction'>
304 <subaction name='toc' xslt='document-toc.xsl'/>
305 <subaction name='text' xslt='document-content.xsl'/>
306 </action>
307 <action name='pr' class='ProcessAction' xslt='process.xsl'/>
308 <action name='s' class='SystemAction' xslt='system.xsl'/>
309 </actionList>
310 <languageList>
311 <language name="en">
312 <displayItem name='name'>English</displayItem>
313 </language>
314 <language name="fr">
315 <displayItem name='name'>Français</displayItem>
316 </language>
317 <language name='es'>
318 <displayItem name='name'>Español</displayItem>
319 </language>
320 </languageList>
321</interfaceConfig>
322\end{verbatim}\end{gsc}
323\caption{Default interface configuration file}
324\label{fig:ifaceconfig}
325\end{figure}
326
327
328\subsection{Run-time re-initialisation}\label{sec:runtime-config}
329
330When Tomcat is started up, the site and interface configuration files are read in, and actions/services/collections loaded as necessary. The configuration is then static unless Tomcat is restarted, or re-configuration commands issued.
331
332There are several commands that can be issued to Tomcat to avoid having to restart the server. These can reload the entire site, or just individual collections. Unfortunately at present there are no commands to reconfigure the interface, so if the interface configuration file has changed, Tomcat must be restarted for those changes to take effect. Similarly, if the Java classes are modified, Tomcat must be restarted then too.
333
334Currently, the runtime configuration commands can only be accessed by typing arguments into the URL; there is no nice web form yet to do this.
335
336The arguments are entered after the \gst{library?} part of the URL. There are three types of commands: configure, activate, deactivate\footnote{There is no security for these commands yet in \gs, so the deactivate/delete command is disabled}. These are specified by \gst{a=s\&sa=c}, \gst{a=s\&sa=a}, and \gst{a=s\&sa=d}, respectively (\gst{a} is action, \gst{sa} is subaction). By default, the requests are sent to the MessageRouter, but they can be sent to a collection/cluster by the addition of \gst{sc=xxx}, where \gst{xxx} is the name of the collection or cluster. Table~\ref{tab:run-time config} describes the commands and arguments in a bit more detail.
337
338\begin{table}
339\caption{Example run-time configuration arguments.}
340\label{tab:run-time config}
341{\footnotesize
342\begin{tabular}{lp{8cm}}
343\hline
344\gst{a=s\&sa=c} & reconfigures the whole site. Reads in siteConfig.xml, reloads all the collections. Just part of this can be specified with another argument \gst{ss} (system subset). The valid values are \gst{collectionList}, \gst{siteList}, \gst{serviceList}, \gst{clusterList}. \\
345\gst{a=s\&sa=c\&sc=XXX} & reconfigures the XXX collection or cluster. \gst{ss} can also be used here, valid values are \gst{metadataList} and \gst{serviceList}. \\
346\gst{a=s\&sa=a} & (re)activate a specific module. Modules are specified using two arguments, \gst{st} (system module type) and \gst{sn} (system module name). Valid types are \gst{collection}, \gst{cluster} \gst{site}.\\
347\gst{a=s\&sa=d} & deactivate a module. \gst{st} and \gst{sn} can be used here too. Valid types are \gst{collection}, \gst{cluster}, \gst{site}, \gst{service}. Modules are removed from the current configuration, but will reappear if Tomcat is restarted.\\
348\gst{a=s\&sa=d\&sc=XXX} & deactivate a module belonging to the XXX collection or cluster. \gst{st} and \gst{sn} can be used here too. Valid types are \gst{service}. \\
349\hline
350\end{tabular}}
351\end{table}
352\newpage
353\section{Using \gsiii\ }\label{sec:user}
354
355Once \gsiii\ is installed, the sample collections can be accessed. The installation comes with several example collections, and Section~\ref{sec:usecolls} describes these collections and how to use them. Section~\ref{sec:buildcol} describes how to build new collections.
356
357\subsection{Using a collection}\label{sec:usecolls}
358
359A collection typically consists of a set of documents, which could be text, HTML, word, PDF, images, bibliographic records etc, along with some access methods, or ``services''. Typical access methods include searching or browsing for document identifiers, and retrieval of content or metadata for those identifiers.
360Searching involves entering words or phrases and getting back lists of documents that contain those words. The search terms may be restricted to particular fields of the document.
361
362Browsing involves navigating pre-defined hierarchies of documents, following links of interest to find documents. The hierarchies may be constructed on different metadata fields, for example, alphabetical lists of Titles, or a hierarchy of Subject classifications. Clicking on a bookshelf icon takes you to a lower level in the hierarchy, while clicking on a book or page icon takes you to a document.
363
364In the standard interface that comes with \gsiii\ \footnote{of course, this is all customisable}, collections in a digital library are presented in the following manner. The 'home' page of the library shows a list of all the public collections in that library. Clicking on a collection link takes you to the home page for the collection, which we call the collection's 'about' page. The standard page banner looks something like that shown in Figure~\ref{fig:page-banner}.
365
366\begin{figure}[h]
367 \centering
368 \includegraphics[width=4in]{pagebanner} %5.8
369 \caption{A sample collection page banner}
370 \label{fig:page-banner}
371\end{figure}
372
373The image at the top left is a link to the collection's home page. The top right has buttons to link to the library home page, help and preferences pages. All the available services are arrayed along a navigation bar, along the bottom of the banner. Clicking on a name accesses that service.
374
375Search type services generally provide a form to fill in, with parameters including what field or granularity to search, and the query itself. Clicking the search button carries out the search, and a list of matching documents will be displayed. Clicking on the icons in the result list takes you to the document itself.
376
377Once you are looking at a document, clicking the open book icon at the top of the document, underneath the navigation bar, will take you back to the service page that you accessed the document from.
378
379\subsection{Building a collection}\label{sec:buildcol}
380
381There are three ways to get a new collection into \gsiii. The first is to build it using the \gsiii\ command line building process. The second way is to use the Greenstone Librarian Interface to build a new collection. This creates a collection in a \gsiii\ context, but uses the \gsii\ Perl collection building process. The third way is to import a pre-built \gsii\ collection.
382
383Collections live in the collect directory of a site. As described in Section~\ref{sec:sites-and-ints}, there can be several sites per \gsiii\ installation. The collect directory is at \gst{\$GSDL3HOME/web/sites/site-name/collect}, where site-name is the name of the site you want your new collection to belong to.
384
385The following three sections describe how to create a collection from scratch, using command line and GLI building, and how to import a \gsii\ collection. Once a collection has been built (and is located in the collect directory), the library server needs to be notified that there is a new collection. This can be accomplished in two ways\footnote{and eventually there will also probably be automatic polling for new collections}. If you are the library administrator, you can restart Tomcat. The library servlet will then be created afresh, and will discover the new collection when it scans the collect directory for the collection list. Alternatively, an activate collection command can be issued to the servlet, using the arguments \gst{a=s\&sa=a\&st=collection\&sn=collname}, where \gst{collname} should be replaced with the collection name---this tells the library program to (re)load the \gst{collname} collection.
386
387
388\subsubsection{Creating a collection from scratch}
389
390To create the director
391Building native \gsiii\ collections is done using the \gst{gs3-build.sh} script, with the \gst{collectionConfig.xml} file controlling how the building is done. There are a number of considerations in building a collection: what documents appear in the collection, how they are indexed for searching, which classifications are used for browsing, etc.
392
393Firstly, the documents that comprise the collection should be placed in the import subdirectory. At present, only documents in this directory will appear in the collection. Documents can be organised into sub folders inside the import directory.
394[TODO: describe the kinds of documents that can be added, something about METS files?]
395
396Metadata for documents can be added using metadata.xml files. These files have already been used in \gsii, and the format is the same in \gsiii. A metadata.xml file has a root element of \gst{<DirectoryMetadata>}. This encloses a series of \gst{<FileSet>} items. Neither of these tags has any attributes. Each \gst{<FileSet>} item includes two parts: firstly, one or more \gst{<FileName>} tags, each of which encloses a regular expression to identify the files which are to be assigned the metadata. Only files in the same directory as the metadata.xml, or in one of its child directories, will be selected. The filename tag encloses the regular expression as text, e.g.:
397
398\begin{gsc}\begin{verbatim}
399<FileName>example</FileName>
400\end{verbatim}\end{gsc}
401
402This would match any file containing the text 'example' in its name. The second part of the \gst{<FileSet>} item is a \gst{<Description>} item. The \gst{<Description>} tag has no attributes, but encloses one or more \gst{<Metadata>} tags. Each \gst{<Metadata>} tag contains one metadata item, i.e. a label to describe the metadata and a corresponding value. The \gst{<Metadata>} tag has one compulsory attribute: ``name''. This attribute gives the metadata label to add to the document. Each \gst{<Metadata>} tag also has an optional attribute: ``mode''. If this attribute is set to ``accumulate'' then the value is added to the document, and any existing values for that metadata item are retained. If the attribute is set to ``set'' or is omitted, then any existing value of the metadata item will be deleted.
403
404\begin{figure}
405\begin{gsc}\begin{verbatim}
406<?xml version="1.0" encoding="UTF-8"?>
407<!DOCTYPE DirectoryMetadata SYSTEM "http://greenstone.org/dtd/DirectoryMetadata
408 /1.0/DirectoryMetadata.dtd">
409<DirectoryMetadata>
410 <FileSet>
411 <FileName>ec160e</FileName>
412 <Description>
413 <Metadata name="Title">The Courier - No.160 - Nov - Dec 1996 -
414 Dossier Habitat - Country reports: Fiji , Tonga (ec160e)</Metadata>
415 <Metadata mode="accumulate" name="Language">English</Metadata>
416 <Metadata mode="accumulate" name="Subject">Settlements and housing:
417 general works incl. low- cost housing, planning techniques, surveying,
418 etc.</Metadata>
419 <Metadata mode="accumulate" name="Subject">The Courier ACP 1990 - 1996
420 Africa-Caribbean-Pacific - European Union</Metadata>
421 <Metadata mode="accumulate" name="Organization">EC Courier</Metadata>
422 <Metadata mode="accumulate" name="AZList">T.1</Metadata>
423 </Description>
424 </FileSet>
425 <FileSet>
426 <FileName>b22bue</FileName>
427 <Description>
428 <Metadata name="Title">Butterfly Farming in Papua New Guinea
429 (b22bue)</Metadata>
430 <Metadata mode="accumulate" name="Language">English</Metadata>
431 <Metadata mode="accumulate" name="Subject">Other animals (micro-
432 livestock, little known animals, silkworms, reptiles, frogs,
433 snails, game, etc.)</Metadata>
434 <Metadata mode="accumulate" name="Organization">BOSTID</Metadata>
435 <Metadata mode="accumulate" name="AZList">T.1</Metadata>
436 <Metadata mode="accumulate" name="Keyword">start a butterfly farm
437 </Metadata>
438 </Description>
439 </FileSet>
440</DirectoryMetadata>
441\end{verbatim}\end{gsc}
442\caption{Sample metadata.xml file}
443\label{fig:metadatafile}
444\end{figure}
445
446Figure~\ref{fig:metadatafile} shows an example metadata.xml file.
447Here, only one file pattern is found in each file set. However, the \gst{Description} tag contains a number of separate metadata items. Note that the \gst{Title} metadata does not have the \gst{mode=accumulate} attribute. This means that when the title is assigned to a document, its existing \gst{Title} information will be lost.
448
449The basic means of finding documents in \gs\ is search. Options for building the search indexes include which indexer to use, what granularity to use for the indexes (e.g. whether to index documents as a whole, or sections of documents), what content the index should have (the whole text of the document or one or many metadata fields). Section-level indexes allow a reader to recall part of a document (for instance, a chapter) rather than the entire document. However, \gsiii\ must be able to identify the internal structure of the document to achieve this. The degree to which structure can be found varies from file format to file format.
450
451An alternative means of finding documents is through browsing. Greenstone can create pre-defined browsing hierarchies based on document metadata. Each browsing structure is called a classifier. Options for building classifiers include what type of classifier to use (linear list or multi-level hierarchy), what metadata to build the classifier on, e.g. Title, Author etc.
452
453The collectionConfig.xml file controls the all of these options for collection building, and the format is described in Section~\ref{sec:collconfig}.
454
455To build a collection, place the source documents and optional metadata.xml file(s) in the import directory, place the \gst{collectionConfig.xml} file in the etc directory, and execute \gst{gs3build.sh/bat sitename collectionname}. The process will run, placing the new indexes in the \gst{building} subdirectory of the collection's directory. You must have mysql running before you start building---running \gst{gs3-launch.sh/bat} will start up the MySQL server as well as tomcat.
456
457Once the build process is complete, the building directory should be renamed to index (after deleting or renaming the existing index directory, if any), and Tomcat prompted to reload the collection---either by restarting the server, or by sending an activate collection command to the library servlet.
458
459\subsubsection{Using the Librarian Interface}
460
461The Greenstone Librarian Interface (GLI) can be used to create \gsii\ style collections for \gsiii. It can be started under Windows by selecting Greenstone Librarian Interface from the Greenstone 3 Digital Library menu in the Program Files section of the Start menu. On Linux, run \gst{./gli4gs3.sh} from the \gst{gsdl3/gli} directory.
462
463Currently, the GLI works almost exactly the same as for \gsii\footnote{Eventually the GLI will be modified to use native \gsiii\ config files and collection building}. Collection configuration is done in a \gsii\ manner. The main difference is that \gsiii\ has different sites and interfaces and servlets, whereas \gsii\ has a single collect directory, and a single runtime cgi program.
464
465The GLI for \gsiii\ has a couple of new configuration parameters: site and servlet. It operates within a single site---you can edit, delete, create new collections within this site. A servlet is also specified for that site---this is used when previewing a collection. While you are working in one site, you cannot edit collections from another site. However, you can base a collection on one from another site. To change the working site and/or servlet, go to Preferences-$>$Connection in the File menu. By default, the GLI will use site \gst{localsite}, and servlet \gst{library}.
466
467Collection building using the GLI will use the \gsii\ Perl scripts and plugins. At the conclusion of the \gsii\ build process, a conversion script will be run to create the \gsiii\ configuration files. This means that format statements are no longer 'live'---changing these will require changes to the \gsiii\ config files. You can either rebuild the collection through the GLI (may take a while), or run the conversion script directly (see following section).
468
469Detailed instructions about using the GLI can be found in Sections 3.1 and 3.2 of the Greenstone 2 User's Guide (\gst{GS2-User-en.pdf}. This can be found in your \gsii\ installation, or in the gsdl3/docs/manual directory if you have installed \gsiii\ from a distribution.
470
471
472\subsubsection{Importing a \gsii\ collection}
473
474
475Pre-built \gsii\ collections can also be used in \gsiii\footnote{For information about the \gsii\ software, and how to build collections using it, visit \gst{www.greenstone.org}}. The collection folder should be copied to the collect directory of the site it is to appear in (or a symbolic link may be used if possible).
476The \gsiii\ run time system requires different configuration files for a collection, so you need to run a conversion script. All this does is create the new collectionConfig.xml and buildConfig.xml from the old collect.cfg and build.cfg files. It does not change the collection in any way, so it can still be used by \gsii\ software.
477
478The conversion script is \gst{convert\_coll\_from\_gs2.pl}. To run it, make sure you have run \gst{source setup.bash} (or \gst{setup} in Windows) in your top-level gsdl directory of the \gsii\ installation (as well as running the standard \gst{gs3-setup} command). Then you need to specify the path to the collect directory and the collection name as parameters to the conversion script. For example,
479
480\begin{gsc}
481\begin{verbatim}
482convert_coll_from_gs2.pl -collectdir
483 $GSDL3HOME/web/sites/localsite/collect demo
484\end{verbatim}
485\end{gsc}
486%$
487The script attempts to create \gsiii\ format statements from the old \gsii\ ones. The conversion may not always work properly, so if the collection looks a bit strange under \gsiii\ , you should check the format statements. Format statements are described in Section~\ref{sec:formatstmt}.
488
489Once again, to have the collection recognised by the library servlet, you can either restart Tomcat, or load it dynamically.
490
491\subsection{Collection configuration files}\label{sec:collconfig}
492
493Each collection has two, or possibly three, configuration files, \gst{collectionConfig.xml} and \gst{buildConfig.xml}, and optionally \gst{collectionInit.xml}, that give metadata, display and other information for the
494collection.\footnote{For collections imported from \gsii, \gst{collectionConfig.xml} and \gst{buildConfig.xml}are generated from \gst{collect.cfg} and \gst{build.cfg}.} The first includes user-defined presentation metadata for the collection,
495such as its name and the {\em About this collection} text; gives formatting information for the collection display; and also gives
496instructions on how the collection is to be built. The second is produced by
497the build-time process and includes any metadata that can be determined
498automatically. It also includes configuration information for any ServiceRacks needed by the collection.
499
500All the configuration files should be encoded using UTF-8.
501
502\subsubsection{collectionInit.xml}
503
504This optional file is only used for non-standard, customised collections. It specifies the class name of the non-standard collection class. The only syntax so far is the class name:
505
506\begin{gsc}\begin{verbatim}
507<collectionInit class="XMLCollection"/>
508\end{verbatim}\end{gsc}
509
510Section~\ref{sec:new-coll-types} describes an example collection where this file is used. Depending on the type of collection that this is used for, one or both of the other config files may not be needed.
511
512\subsubsection{collectionConfig.xml}
513
514The collection configuration file is where the collection designer (e.g. a librarian) decides what form the collection should take. This includes the collection metadata such as title and description, and also includes what indexes and browsing structures should be built. The format of \gst{collectionConfig.xml} is still under consideration. However, Figure~\ref{fig:collconfig} shows the parts of it that have been defined so far.
515
516Display elements for a collection or metadata for a document can be entered in any language---use lang='en' attributes to metadata elements to specify which language they are in.
517
518\begin{figure}
519\begin{gsc}\begin{verbatim}
520<collectionConfig xmlns:gsf="http://www.greenstone.org/configformat"
521 xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
522 <metadataList>
523 <metadata name="creator">greenstone@cs.waikato.ac.nz</metadata>
524 </metadataList>
525 <displayItemList>
526 <displayItem name="name" lang="en">Greenstone 3 demo</displayItem>
527 <displayItem name="icon" lang="en">gs3demo.gif</displayItem>
528 <displayItem name="smallicon" lang="en">gs3demosm.gif</displayItem>
529 <displayItem name="description" lang="fr">Il s'agit d'une collection
530 de démonstration pour le logiciel Greenstone. Elle contient
531 seulement un petit échantillon des Bibliothèques humanitaires
532 pour le Développement (11 documents).</displayItem>
533 <displayItem name="description" lang="en">This is a demonstration
534 collection for the Greenstone digital library software. It contains
535 a small subset (11 books) of the Humanity Development Library. It
536 is built with mg using Greenstone 3 native building.</displayItem>
537 </displayItemList>
538 <search type='mg'>
539 <index name="i1">
540 <field>text</field>
541 <level>document</level>
542 <displayItem name='name' lang="en">entire documents</displayItem>
543 <displayItem name='name' lang="fr">documents entiers</displayItem>
544 <displayItem name='name' lang="es">documentos enteros</displayItem>
545 </index>
546 <index name="i2">
547 <field>text</field>
548 <level>section</level>
549 <displayItem name='name' lang="en">chapters</displayItem>
550 <displayItem name='name' lang="fr">chapitres</displayItem>
551 <displayItem name='name' lang="es">capítulos</displayItem>
552 </index>
553 <format>
554 <gsf:template match="documentNode">
555 <td valign='top'><gsf:link><gsf:icon/></gsf:link></td>
556 <td><gsf:metadata name='Title' /></td>
557 </gsf:template>
558 </format>
559 </search>
560 <browse>
561 <classifier name="CL1" type="AZList" horizontalAtTop='true'>
562 <field>Title</field>
563 <sort>Title</sort>
564 <displayItem name='name' lang='en'>Titles</displayItem>
565 </classifier>
566 <classifier name="CL2" type="Hierarchy">
567 <field>Organization</field>
568 <sort>Title</sort>
569 <displayItem name='name' lang='en'>Organizations</displayItem>
570 <file URL="/research/kjdon/home/gsdl3/web/sites/localsite/collect/
571 gs3test/etc/org.xml"/>
572 </classifier>
573 <classifier name="CLKeyword" type="Hierarchy">
574 <field>Keyword</field>
575 <sort>Title</sort>
576 <displayItem name='name' lang='en'>HowTo</displayItem>
577 <file URL="/research/kjdon/home/gsdl3/web/sites/localsite/collect/
578 gs3test/etc/keyword.xml"/>
579 <format>
580 <gsf:template match="documentNode">
581 <br /><gsf:link><gsf:metadata name='Keyword' />
582 </gsf:link></gsf:template>
583 </format>
584 </classifier>
585 </browse>
586 <display/>
587</collectionConfig>
588\end{verbatim}\end{gsc}
589[TODO: add in building instructions for the classifiers]
590\caption{Sample collectionConfig.xml file (gs3demo collection)}
591\label{fig:collconfig}
592\end{figure}
593
594The \gst{<metadataList>} element specifies some collection metadata, such as creator. The \gst{<displayItemList>} specifies some language dependent information that is used for collection display, such as collection name and short description. These displayItem elements can be specified in different languages.
595
596The \gst{<search>} element specifies what indexes should be built, and provides some display and formatting information for each one. Search has an attribute, \gst{type}, which specifies which indexer to be used for indexing. Currently, \gst{mg} and \gst{mgpp}[??] are available. If type is not specified, mg is used. Multiple search elements may be specified, if more than one indexer is to be used. (Note, this is not yet recognised by the run-time system.)
597
598Search indexes appear as individual \gst{<index>} elements within the \gst{<search>} element. Some choices for the index are made using attributes of the element itself, and some through child elements.
599
600Each index must have a unique name, which is used to identify it within \gsiii\ The name is given as an attribute of the \gst{<index>} element.
601
602The other choices are described using child elements of \gst{<index>}. The \gst{<level>} tag indicates the index level and the \gst{<field>} tag the text to be used. The \gst{<level>} tag can contain one of document, section or paragraph, while the \gst{<field>} tag can contain ``text'' or the name of a metadata field. If the \gst{<level>} tag is omitted, the default setting is to index by document, and if the \gst{<field>} tag is omitted, the default setting is to index the document text.
603
604Example index specifications include:
605
606[NOTE: I think we shouldn't have default level and field and that it must be specified--kjdon]
607
608To index only the title of each separate document in the collection:
609\begin{gsc}\begin{verbatim}
610<index name="dtt">
611 <level>document</level>
612 <field>dc:title</field>
613</index>
614\end{verbatim}\end{gsc}
615...in this case the \gst{<field>} tag refers to the ``title'' metadata item, found in the Dublin Core namespace. The mg search engine would be used on this index.
616
617Alternatively, to index the full document texts by section:
618\begin{gsc}\begin{verbatim}
619<index name="stx">
620 <level>section</level>
621</index>
622\end{verbatim}\end{gsc}
623...or...
624\begin{gsc}\begin{verbatim}
625<index name="stx">
626 <level>section</level>
627 <field>text</field>
628</index>
629\end{verbatim}\end{gsc}
630...in the first example, the \gst{<field>} tag is not explicitly defined, and would default to 'text', whereas it is explicitly set to 'text' in the second example. As they are of the same name, they should not appear in the same \gst{collectionConfig.xml} file.
631
632Moving onto \gst{<classifier>} items, the format is broadly similar to \gst{<index>} items, but with a couple of different choices. Firstly, each classifier should have ``name'' and ``type'' attributes. In the case of \gst{<classifier>} items the ``type'' attribute identifies the type of classifier it is. At present, this should either be ``Hierarchy'' or ``AZList''.
633
634The remaining choices for the classifier should follow as child elements of the \gst{<classifier>} element. The \gst{<file>} element should contain the name of the file that describes the classifier as its ``URL'' attribute. The format of this file varies from classifier type to classifier type. The \gst{<field>} element identifies the name of the field to index. More than one \gst{<field>} element may appear if two or more metadata fields are to be used with the classifier. Finally, the \gst{<sort>} item identifies another metadata field which the items within one classifier node are to be ordered. Unlike the \gst{<index>} element, the \gst{<classifier>} element does not have default, assumed values for its children.
635
636Figure~\ref{fig:hierarchyfile} shows the format of the file for a Hierarchy classifier. [TODO add a description]
637\begin{figure}
638\begin{gsc}\begin{verbatim}
639<Hierarchy>
640 <Classification>
641 <Name>ACCU</Name>
642 <Path>1</Path>
643 <Description>ACCU</Description>
644 </Classification>
645 <Classification>
646 <Name>Agenda 21</Name>
647 <Path>2</Path>
648 <Description>Agenda 21</Description>
649 </Classification>
650 <Classification>
651 <Name>FAO</Name>
652 <Path>3</Path>
653 <Description>FAO</Description>
654 <Children>
655 <Classification>
656 <Name>FAO Better Farming series</Name>
657 <Path>3.1</Path>
658 <Description>FAO Better Farming Series</Description>
659 </Classification>
660 </Children>
661 </Classification>
662</Hierarchy>
663\end{verbatim}\end{gsc}
664\caption{Sample Hierarchy classifier file}
665\label{fig:hierarchyfile}
666\end{figure}
667
668Inside the \gst{<search>} and \gst{<browse>} elements, \gst{<displayItem>} elements are used to provide titles for the indexes or classifiers, while \gst{<format>} elements provide formatting instructions, typically for a document or classifier node in a list of results. Placing the \gst{<format>} instructions at the top level in the search or browse element will apply the format to all the indexes or classifiers, while placing it inside an individual index or classifier element will restrict that formatting instruction to that item.
669
670The \gst{<display>} element contains optional formatting information for the display of documents. Templates that can be specified here include \gst{documentHeading}, \gst{DocumentContent}. Other formatting options may also be specified here, such as whether to display a table of contents and/or cover image for the documents.
671
672Format elements are described in Section~\ref{sec:formatstmt}.
673
674An optional \gst{<replaceList>} element can be included at the top level. This contains a list of strings and their replacements. This is particularly useful for Greenstone 2 collections that use macros.
675
676The format is like the following:
677\begin{gsc}\begin{verbatim}
678<replaceList>
679<replace scope='text' macro="xxx" text="yyy"/>
680<replace scope='metadata' macro="xxx" bundle="yyy" key="zzz"/>
681<replace scope='all' macro='xxx' metadata='yyy'/>
682</replaceList>
683\end{verbatim}\end{gsc}
684
685Scope determines on what text the replacements are carried out: text, metadata, or both (all). An empty scope attribute is equivalent to scope=all. Each replace type can be used with all scope values. Replacing uses Java's 'String.replaceAll' functionality, so macro and replacement text are actually regular expressions. The first example is a straight textual replacement. The second example uses dictionary lookups. xxx will be replaced with the (language-dependent) value for key zzz in resource bundle yyy. The third example uses metadata: xxx will be replaced by the value of the yyy metadata for that document.
686
687Appendix~\ref{app:gs2replace} gives some examples that have been used for Greenstone 2 collections.
688
689\subsubsection{buildConfig.xml}\label{sec:buildconfig}
690
691The file \gst{buildConfig.xml} is produced by the collection building process. Generally it is not necessary to look at this file, but it can be useful in determining what went wrong if the collection doesn't appear quite the way it was planned.
692
693It contains metadata and other information about the collection that can
694be determined automatically, such as the number of
695documents it contains. It also includes a list of ServiceRack classes that are
696required to provide the services that have been built into the
697collection. The serviceRack names are Java classes that are loaded
698dynamically at runtime. Any information inside the serviceRack element is
699specific to that service---there is no set format. Figure~\ref{fig:buildconfig} shows an example. This configuration file specifies that the collection should load up 3 ServiceRacks: \gst{GS2MGPPRetrieve}, \gst{GS2MGPPSearch}, and \gst{PhindPhraseBrowse}. The contents of each \gst{<serviceRack>} element are passed to the appropriate ServiceRack objects for configuration. The \gst{collectionConfig.xml} file content is also passed to the ServiceRack objects at configure time---the \gst{format} and \gst{displayItem} information is used directly from the \gst{collectionConfig.xml} file rather than added into \gst{buildConfig.xml} during building. This enables formatting and metadata changes in \gst{collectionConfig.xml} to take effect in the collection without rebuilding being necessary. However, as these files are cached, the collection needs to be reloaded for the changes to appear in the library.
700
701
702\begin{figure}
703\begin{gsc}\begin{verbatim}
704<buildConfig xmlns:gsf="http://www.greenstone.org/configformat">
705 <metadataList>
706 <metadata name="numDocs">11</metadata>
707 </metadataList>
708 <serviceRackList>
709 <serviceRack name="GS2MGPPRetrieve">
710 <defaultLevel name="Sec" />
711 <classifierList>
712 <classifier name="CL1" content="Subject" />
713 <classifier name="CL2" content="Title" horizontalAtTop="true" />
714 <classifier name="CL3" content="Organization" />
715 <classifier name="CL4" content="Keyword" />
716 </classifierList>
717 </serviceRack>
718 <serviceRack name="PhindPhraseBrowse" />
719 <serviceRack name="GS2MGPPSearch">
720 <defaultLevel name="Sec" />
721 <levelList>
722 <level name="Doc" />
723 <level name="Sec" />
724 <level name="Para" />
725 </levelList>
726 <fieldList>
727 <field shortname="ZZ" name="allfields" />
728 <field shortname="TX" name="text" />
729 <field shortname="TI" name="Title" />
730 <field shortname="SU" name="Subject" />
731 <field shortname="ORG" name="Organization" />
732 <field shortname="SO" name="Source" />
733 </fieldList>
734 <searchTypeList>
735 <searchType name="plain" />
736 <searchType name="form" />
737 </searchTypeList>
738 <defaultIndex name="idx" />
739 <indexList>
740 <index name="idx" />
741 </indexList>
742 </serviceRack>
743 </serviceRackList>
744</buildConfig>
745\end{verbatim}\end{gsc}
746\caption{Sample buildConfig.xml file (mgppdemo collection)}
747\label{fig:buildconfig}
748\end{figure}
749
750\subsection{Formatting the collection}\label{sec:formatstmt}
751
752Part of collection design involves deciding how the collection should look. \gsiii\ has a default 'look' for a collection, so this is optional. However, the default may not suit the purposes of some collections, so many parts to the look of a collection can be determined by the collection designer.
753
754In standard \gsiii\ , the library is served to a web browser by a servlet, and the HTML is generated using XSLT. XSLT templates are used to format all the parts of the pages. These templates can be overridden by including them in the \gst{collectionConfig.xml} file. Some commonly overridden templates are those for formatting lists: search results list, classifier browsing hierarchies, and for parts of the document display.
755
756Real XSLT templates for formatting search results or classifier lists are quite complicated, and not at all easy for a new user to write. For example, the following is a sample template for formatting a classifier list, to show Keyword metadata as a link to the document.
757
758\begin{gsc}\begin{verbatim}
759<xsl:template match="documentNode" priority="2"
760 xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
761 <xsl:param name="collName"/>
762 <td><a href="{\$library_name}?a=d&amp;c={\$collName}&amp;
763 d={@nodeID}&amp;dt={@docType}"><xsl:value-of
764 select="metadataList/metadata[@name='Keyword']"/></a>
765 </td>
766</xsl:template>
767 \end{verbatim}\end{gsc}
768
769To write this, the user would need to know that:
770\begin{bulletedlist}
771\item the variable \gst{\$library\_name} exists,
772\item the collection name is passed in as a parameter called \gst{collName}
773\item metadata for a document is found in a \gst{<metadataList>} and that its form is \gst{<metadata name="Keyword">the value</metadata>}
774\item the arguments needed for the link to the document are \gst{a, sa, c, d, a, dt}.
775\end{bulletedlist}
776
777Since XSLT is written in XML, we can use XSLT to transform XML into XSLT. \gsiii\ provides a simplified set of formatting commands, written in XML, which will be transformed into proper XSLT. The user specifies a \gst{<gsf:template>} for what they want to format---these typically match \gst{documentNode} or \gst{classifierNode} (for node in a classification hierarchy).
778
779The template at the start of this section can be represented as:
780
781\begin{gsc}\begin{verbatim}
782<gsf:template match='documentNode'>
783 <td><gsf:link><gsf:metadata name='Keyword'/></gsf:link></td>
784</gsf:template>
785\end{verbatim}\end{gsc}
786
787Table~\ref{tab:gsf-format} shows the set of 'gsf' (Greenstone Format) elements. If you have come from a \gsii\ background, Appendix~\ref{app:gs2format} shows \gsii\ format elements and their equivalents in \gsiii\ .
788
789\begin{table}
790\caption{Format elements for GSF format language}
791\label{tab:gsf-format}
792{\footnotesize
793\begin{tabular}{p{6.5cm}p{6.5cm}}
794\hline
795\bf Element & \bf Description \\
796\hline
797\gst{<gsf:text/>} & The document's text\\
798\hline
799\gst{<gsf:link>...</gsf:link>} & The HTML link to the document itself \\
800\gst{<gsf:link type='document'>...
801</gsf:link>} & Same as above\\
802\gst{<gsf:link type='classifier'>...
803</gsf:link>} & A link to a classification node (use in classifierNode templates)\\
804\gst{<gsf:link type='source'>...
805</gsf:link>} & The HTML link to the original file---set for documents that have been converted from e.g. Word, PDF, PS \\
806\hline
807\gst{<gsf:icon/>} & An appropriate icon\\
808\gst{<gsf:icon type='document'/>} & same as above\\
809\gst{<gsf:icon type='classifier'/>} & bookshelf icon for classification nodes\\
810\gst{<gsf:icon type='source'/>} & An appropriate icon for the original file e.g. Word, PDF icon\\
811\hline
812\gst{<gsf:metadata name='Title'/>} & The value of a metadata element for the current document or section, in this case, Title\\
813\gst{<gsf:metadata name='Title' select='select-type' [separator='y' multiple='true']/>} & A more extended selection of metadata values. The select field can be one of those shown in Table~\ref{tab:gsf-select-types}. There are two optional attributes: separator gives a String that will be used to separate the fields, default is ``, ``, and if multiple is set to true, looks for multiple values at each section.\\
814\gst{<gsf:metadata name='Date' format='formatDate'/>} & The value of a metadata element for the current document, formatted in some way. Current formatting options available are formatDate: turns '20040201' into '01 February 2004', and formatLanguage: turns 'en' into 'English', both in a language dependent manner. \\
815\hline
816\gst{<gsf:choose-metadata>
817 <gsf:metadata name='metaA'/>
818 <gsf:metadata name='metaB'/>
819 <gsf:metadata name='metaC'/>
820</gsf:choose-metadata>}
821 & A choice of metadata. Will select the first existing one. the metadata elements can have the select, separator and multiple attributes like normal.\\
822\hline
823\gst{<gsf:switch preprocess=
824'preprocess-type'>
825<gsf:metadata name='Title'/>
826<gsf:when test='test-type'
827test-value='xxx'>...</gsf:when>
828<gsf:when test='test-type'
829test-value='yyy'>...</gsf:when>
830<gsf:otherwise>...</gsf:otherwise>
831</gsf:switch>} & switch on the value of a particular metadata - the metadata is specified in gsf:metadata, has the same attributes as normal.\\
832\hline
833\end{tabular}}
834\end{table}
835
836The \gst{<gsf:metadata>} elements are used to output metadata values. The simplest case is \gst{<gsf:metadata name='Title'/>}---this outputs the Title metadata for the current document or section. Namespaces are important here: if the Title metadata is in the Dublin Core (dc) namespace, then the element should look like \gst{<gsf:metadata name='dc.Title'/>}. There are three other attributes for this element. The attribute \gst{multiple} is used when there may be more than one value for the selected metadata.
837For instance, one document may fall into several classification categories, and therefore may have multiple Subject metadata values. Adding \gst{multiple='true'} to the \gst{<gsf:metadata>} element will retrieve all values, not just the first one. Multiple values are separated by commas by default. The \gst{separator} attribute is used to change the separating string. For example, adding \gst{separator=':~'} to the element will separate all values by a colon and a space.
838
839Sometimes you may want to display metadata values for sections other than the current one. For example, in the mgppdemo collection, in a search list we display the Titles of all the enclosing sections, followed by the Title of the current section, all separated by semi-colons. The display ends up looking something like:
840\emph{Farming snails 2; Starting out; Selecting your snails}
841where \emph{Selecting your snails} is the Title of the section in the results list, and \emph{Farming snails 2} and \emph{Starting out} are the Titles of the enclosing sections. The \gst{select} attribute is used to display metadata for sections other than the current one. Table~\ref{tab:gsf-select-types} shows the options available for this attribute. The \gst{separator} attribute is used here also, to specify the separating text.
842
843To get the previous metadata, the format statement would have the following in it:
844
845\begin{gsc}
846\begin{verbatim}
847<gsf:metadata name='Title' select='ancestors' separator='; '/>;
848 <gsf:metadata name='Title'/>
849\end{verbatim}
850\end{gsc}
851
852\begin{table}
853\caption{Select types for metadata format elements}
854\label{tab:gsf-select-types}
855{\footnotesize
856\begin{tabular}{ll}
857\hline
858\bf Select Type & \bf Description\\
859\hline
860current & The current section \\
861parent & The immediate parent section\\
862ancestors & All the parents back to the root (topmost) section\\
863root & The root or topmost section \\
864siblings & All the sibling sections\\
865children & The immediate child sections of the current section\\
866descendents & All the descendent sections\\
867\hline
868\end{tabular}}
869\end{table}
870
871The \gst{<gsf:choose-metadata} element selects the first available metadata value from the list of options.
872\begin{gsc}
873\begin{verbatim}
874<gsf:choose-metadata>
875 <gsf:metadata name='dc.Title'/>
876 <gsf:metadata name='dls.Title'/>
877 <gsf:metadata name='Title'/>
878</gsf:choose-metadata>
879\end{verbatim}
880\end{gsc}
881
882This will display the dls.Title metadata if available, otherwise it will use the dc.Title metadata if available, otherwise it will use the Title metadata. If there are no values for any of these metadata elements, then nothing will be displayed.
883
884The \gst{<gsf:switch>} element allows different formatting depending on the value of a specified metadata element. For example, the following switch statement could be used to display a different icon for each document in a list depending on which organisation it came from.
885
886\begin{gsc}
887\begin{verbatim}
888<gsf:switch preprocess='toLower;stripSpace'>
889 <gsf:metadata name='Organization'/>
890 <gsf:when test='equals' test-value='bostid'>
891 <!-- output BOSTID image --></gsf:when>
892 <gsf:when test='equals' test-value='worldbank'>
893 <!-- output world bank image --></gsf:when>
894 <gsf:otherwise><!-- output default image--></gsf:otherwise>
895</gsf:switch>
896\end{verbatim}
897\end{gsc}
898
899Preprocessing of the metadata value is optional. The preprocess types are \gst{toLower} (make the value lowercase), \gst{toUpper} (make the value uppercase), \gst{stripSpace} (removes any whitespace from the value). These operations are carried out on the value of the selected metadata before the test is carried out. Multiple processing types can be specified, separated by ; and they will be applied in the order specified (from left to right).
900
901Each option specifies a test and a test value. Test values are just text. Tests include \gst{startsWith}, \gst{contains}, \gst{exists}, \gst{equals}, \gst{endsWith}. Exists doesn't need a test value. Having an otherwise option ensures that something will be displayed even when none of the tests match.
902
903If none of the gsf elements meets your needs for formatting, XSLT can be entered directly into the format element, giving the collection designer full flexibility over how the collection appears.
904
905The collection specific templates are added into the configuration file \gst{collectionConfig.xml}. Any templates found in the XSLT files can be overridden.
906The important part to adding templates into the configuration file is determining where to put them. Formatting templates cannot go just anywhere---there are standard places for them. Figure~\ref{fig:format-places} shows the positions that templates can occur.
907
908\begin{figure}
909\begin{gsc}\begin{verbatim}
910<collectionConfig>
911 <metadataList/>
912 <displayItemList/>
913 <search>
914 <format> <!--Put here templates related to searching and
915 the query page. The common one is the documentNode
916 template -->
917 <gsf:template match='documentNode'>...</gsf:template>
918 </format>
919 </search>
920 <browse>
921 <classifier name='xx'>
922 <format><!-- put here templates related to formating a
923 particular classifier page. Common ones are documentNode
924 and classifierNode templates-->
925 <gsf:template match='documentNode'>...</gsf:template>
926 <gsf:template match='classifierNode'>...</gsf:template>
927 <gsf:template match='classifierNode' mode='horizontal'>...
928 </gsf:template>
929 </format>
930 </classifier>
931 <classifier>...</classifier>
932 <format><!-- formatting for all the classifiers. these will
933 be overridden by any classifier specific formatting
934 instructions --></format>
935 </browse>
936 <display>
937 <format><!-- here goes any formatting relating to the display
938 of the documents. These are generally named templates,
939 and format options -->
940 <gsf:template name='documentContent'>...</gsf:template>
941 <gsf:option name='TOC' value='true'/>
942 </format>
943 </display>
944</collectionConfig>
945\end{verbatim}\end{gsc}
946\caption{Places for format statements}
947\label{fig:format-places}
948\end{figure}
949
950
951There are also formatting instructions that are not templates but are options.
952These are described in Table~\ref{tab:format_options}. They are entered into the configuration file like \gst{<gsf:option name='coverImages' value='false'/>}
953
954\begin{table}
955\caption{Formatting options}
956\label{tab:format_options}
957{\footnotesize
958\begin{tabular}{llp{5cm}}
959\hline
960\bf option name & \bf values & \bf description \\
961\hline
962coverImages & true, false & whether or not to display cover images for documents \\
963TOC & true, false & whether or not to display the table of contents for the document\\
964\hline
965\end{tabular}}
966\end{table}
967
968Note, format templates are added into the XSLT files before transforming, while the options are added into the page source, and used in tests in the XSLT.
969\subsubsection{Changing the service text strings}
970
971Each collection has a set of services which are the access points for the information in the collection. Each service has a set of text strings which are used to display it. These include name, description, the text on the submit button, and names and descriptions of all the parameters to the service.
972
973These text strings are found in .properties files, in gsdl3/resources/java. The names of the files are based on class names. Subclasses can defined their own properties, or can use their parent class ones. For example, AbstractSearch defines strings for the TextQuery service, in AbstractSearch.properties. GS2MGSearch just uses these default ones, so doesn't need its own property file.
974
975A particular collection can override the properties for any service. For example, if a collection uses the GS2MGSearch service rack (look in the buildConfig.xml file for a list of service racks used), and the collection builder wants to change the text associated with this service, they can put a GS2MGSearch.properties file in the resources directory of the collection.
976This will be used in preference to one in the default resources directory.
977Note that while changes in the default properties files seem to require a tomcat restart to take effect, changes in the colleciton specific properties files take effect immediately.
978
979\subsection{Customising the interface}\label{sec:interface-customise}
980
981Format statements in the collection configuration files provide a way to change small parts of the collection display. For large scale customisations to a collection, or ones that apply to a site as a whole, a second mechanism is available. The interface is defined by a set of XSLT files that transform the page data into HTML. Any of these files can be overridden to provide specialised display, on a site or collection basis.
982
983The first section looks at customizing the existing interface, while the second section looks at defining a whole new interface. The last section describes how to add a new language translation of an interface.
984
985\subsubsection{Modifying an existing interface}
986
987Most of an interface is defined by XSLT files, which are stored in \gst{\$GSDL3HOME/\-web/\-interfaces/\-interface-name/\-transform}. These can be changed and the changes will take effect straight away. If changes only apply to certain collections or sites, not everything that uses the interface, you can override some of the files by putting new ones in a different place. XSLT files are looked for in the following order: collection, site, interface, default interface. (This currently only apples to sites, and therefore collections, that reside in the same \gs\ installation as the interface.)
988
989Sites and collections can have a transform directory, which is where customised XSLT files should go. Any XSLT files in here will be used in preference to the interface files when using this collection. For example, if you want to have a completely different layout for the about page of a collection, you can put a new \gst{about.xsl} file into the collection's \gst{transform} directory, and this will be used instead. This is what we do for the Gutenberg sample collection.
990
991This also applies to files that are included from other XSLT files. For example the query.xsl for the query pages includes a file called querytools.xsl. To have a particular site show a different query interface either of these files may need to be modified. Creating a new version of either of these and putting it in the site transform directory will work. Either the new query.xsl will include the default querytools, or the default query.xsl will include the new querytools.xsl. The xsl:include directives are preprocessed by the java code and full paths added based on availability of the files, so that the correct one is used.
992
993Note that you cannot include a file with the same name as the including file. For example query.xsl cannot include query.xsl (it is tempting to want to do this if you just want to change one template for a particular file, and then include the default. but you cant).
994
995\subsubsection{Defining a new interface}
996
997A new interface may be needed if different instantiations of the library require different interfaces, or different developers want their own look and feel. Creating a new interface will allow modifications to be made while leaving the original one intact.
998
999A new interface needs a directory in \gst{\$GSDL3HOME/web/interfaces}, the name of this directory becomes the interface name. Inside, it needs images and transform directories, and an interfaceConfig.xml file. Any XSLT may be overridden for a new interface by putting the replacement in the new transform directory. If the appropriate XSLT file is not there, the one from the default interface will be used - this enables just overriding a few XSLT files as needed.
1000
1001To use a new interface, the Tomcat web.xml must be edited: either change the interface that a current servlet instance is using, or add another servlet instantiation to the file (see Section~\ref{sec:sites-and-ints} or Appendix~\ref{app:tomcat}). The Tomcat server must be restarted for this to take effect.
1002
1003\subsubsection{Changing the interface language}
1004
1005The interface language can be changed by going to the preferences page, and choosing a language from the list, which includes all languages into which the interface has been translated.
1006
1007It is easy to add a new interface language to \gs\ . Language specific text strings are separated out from the rest of the system to allow for easy incorporation of new languages. These text strings are contained in Java resource bundle properties files. These are plain text files consisting of key-value pairs, located in \gst{resources/java}. Each interface has one named \gst{interface\_name.properties} (where `name' is the interface name). Each service class has one with the same name as the class (e.g. \gst{GS2Search.properties}). To add another language all of the base .properties files must be translated. The translated files keep the same names, but with a language extension added. For example, a French version of \gst{interface\_default.properties} would be named \gst{interface\_default\_fr.properties}.
1008
1009Keys will be looked up in the properties file closest to the specified language. For example, if language \gst{fr\_CA} was specified (French language, country Canada), and the default locale was \gst{en\_GB}, Java would look at properties files in the following order, until it found the key: \gst{XXX\_fr\_CA.properties}, \gst{XXX\_fr.properties}, \gst{XXX\_en\_GB.properties}, then \gst{XXX\_en.properties}, and finally the default \gst{XXX.properties}.
1010
1011These new files are available straight away---to use the new language, add e.g. \gst{l=fr} to the arguments in the URL. To get \gs\ to add it in to the list of languages on the preferences page, an entry needs to be added into the languages list in the \gst{interfaceConfig.xml} file (see Section~\ref{sec:interfaceconfig}). Modification of this file requires a restart of the Tomcat server for the changes to be recognised.
1012
1013\newpage
1014\section{Developing \gsiii : Run-time system}\label{sec:develop-runtime}
1015
1016[TODO: rewrite this!!]
1017runtime object structure diagram. describe the modules.\\
1018class hierarchy,\\
1019directory structure and where everything lives\\
1020message format.\\
1021overall description of message passing sequence.\\
1022configuration process - start up and runtime\\
1023\\
1024page generation\\
1025accessing the javadoc\\
1026
1027\subsection{Overview of modules??}
1028
1029A \gsiii\ 'library' system consists of many components: MessageRouter, Receptionist, Actions, Collections, ServiceRacks etc. Figure~\ref{fig:local} shows how they fit together in a stand-alone system. The top left part is concerned with displaying the data, while the bottom right part is the collection data serving part. The two sides communicate through the MessageRouter. There is a one-to-one correspondence between modules and Java classes, with the exception of services: for coding and/or run-time efficiency reasons, several Service modules may be grouped together into one ServiceRack class.
1030
1031\begin{figure}[t]
1032 \centering
1033 \includegraphics[width=4in]{newlocal} %5.8
1034 \caption{A simple stand-alone site.}
1035 \label{fig:local}
1036\end{figure}
1037
1038
1039{\em MessageRouter}: this is the central module for a site. It controls the site, loading up all the collections, clusters, communicators needed. All messages pass through the MessageRouter. Communication between remote sites is always done between MessageRouters, one for each site.
1040
1041{\em Collection and ServiceCluster}: these are very similar, and group a set of services into a conceptual group.. They both provide some metadata about the collection/cluster, and a list of services. The services are provided by ServiceRack objects that the collection/cluster loads up. A Collection is a specific type of ServiceCluster. A ServiceCluster groups services that are related conceptually, e.g. all the building services may be part of a cluster. What is part of a cluster is specified by the site configuration file. A Collection's services are grouped by the fact that they all operate on some common data---the documents in the collection.
1042Functionally Collection and ServiceCluster are very similar, but conceptually, and to the user, they are quite different.
1043
1044{\em Service}: these provide the core functionality of the system e.g. searching, retrieving documents, building collections etc. One or more may be grouped into a single Java class (ServiceRack) for code reuse, or to avoid instantiating the same objects several times. For example, MGPP searching services all need to have the index loaded into memory.
1045
1046{\em Communicator/Server}: these facilitate communication between remote modules. For example, if you want MR1 to talk to MR2, you need a Communicator-Server pair. The Server sits on top of MR2, and MR1 talks to the Communicator. Each communication type needs a new pair. So far we have only been using SOAP, so we have a SOAPCommunicator and a SOAPServer.
1047
1048{\em Receptionist}: this is the point of contact for the 'front end'. Its core functionality involves routing requests to the Actions, but it may do more than that. For example, a Receptionist may: modify the request in some way before sending it to the appropriate Action; add some data to the page responses that is common to all pages; transform the response into another form using XSLT. There is a hierarchy of different Receptionist types, which is described in Section~\ref{sec:recepts}.
1049
1050{\em Actions}: these do the job of creating the 'pages'. There is a different action for each type of page, for example PageAction handles semi-static pages, QueryAction handles queries, DocumentAction displays documents. They know a little bit about specific service types. Based on the 'CGI' arguments passed in to them, they construct requests for the system, and put together the responses into data for the page. This data is returned to the Receptionist, which may transform it to HTML. The various actions are described in more detail in Section~\ref{sec:pagegen}.
1051
1052
1053\subsection{Start up configuration}\label{sec:startup-config}
1054
1055We use the Tomcat web server, which operates either stand-alone in a test mode
1056or in conjunction with the Apache web server. The \gs\ LibraryServlet
1057class is loaded by Tomcat and the servlet's \gst{init()} method is called. Each time a
1058\gst{get/put/post} (etc.) is used, a new thread is started and
1059\gst{doGet()/doPut()/doPost()} (etc.) is called.
1060
1061The \gst{init()} method creates a new Receptionist and a new
1062MessageRouter. Default classes (DefaultReceptionist, MessageRouter) are used unless subclasses have been specified in the servlet initiation parameters (see Section~\ref{sec:sites-and-ints}). The appropriate system variables are set for each object (interface
1063name, site name, etc.) and then \gst{configure()} is called on both. The MessageRouter handle
1064is passed to the Receptionist. The servlet then communicates only with
1065the Receptionist, not with the MessageRouter.
1066
1067The Receptionist reads in the \gst{interfaceConfig.xml} file (see Section~\ref{sec:interfaceconfig}), and loads up all the different Action classes. Other Actions may be loaded on the fly as needed. Actions are added to a map, with shortnames for keys. Eg the QueryAction is added with key 'q'. The Actions are passed the MessageRouter reference too.
1068If the Receptionist is a TransformingReceptionist, a mapping between shortnames and XSLT file names is also created.
1069
1070The MessageRouter reads in its site configuration file \gst{siteConfig.xml} (see Section~\ref{sec:siteconfig}). It creates a module map that maps names to objects. This is used for routing the messages. It also keeps small chunks of XML---serviceList, collectionList, clusterList and siteList. These are part of what get returned in response to a describe request (see Section~\ref{sec:describe}.).
1071
1072Each ServiceRack specified in the configuration file is created, then queried for its list of services. Each service name is added to the map, pointing to the ServiceRack object. Each service is also added to the serviceList. After this stage, ServiceRacks are transparent to the system, and each service is treated as a separate module.
1073
1074ServiceClusters are created and passed the \gst{<serviceCluster>} element for configuration. They are added to the map as is, with the cluster name as a key. A serviceCluster is also added to the serviceClusterList.
1075
1076For each site specified, the MessageRouter creates an appropriate type of Communicator object. Then it tries to get the site description. If the server for the remote site is up and running, this should be successful. The site will be added to the mapping with its site name as a key. The site's collections, services and clusters will also be added into the static xml lists. If the server for the remote site is not running, the site will not be included in the siteList or module map. To try again to access the site, either Tomcat must be restarted, or a run-time reconfigure-site command must be sent (see Section~\ref{sec:runtime-config}).
1077
1078The MessageRouter also looks inside the site's \gst{collect} directory, and loads up a Collection object for each valid collection found. If a \gst{collectionInit.xml} file is present, a subclass of Collection may be used.
1079The Collection object reads its \gst{buildConfig.xml} and \gst{collectionConfig.xml}
1080files, determines the metadata, and loads ServiceRack classes based on the
1081names specified in \gst{buildConfig.xml\/}. The \gst{<serviceRack>} XML element is passed to the object to be used in configuration. The \gst{collectionConfig.xml} contents are also passed in to the ServiceRacks. Any format or display information that the services need must be extracted from the collection configuration file.
1082Collection objects are added to the module map with their name as a key, and also a collection element is added into the collectionList XML.
1083
1084\subsection{Message passing}
1085
1086There are two types of messages used by the system: external and internal messages. All messages have an enclosing \gst{<message>} element, which contains either one or more requests, or one or more responses. In the following descriptions, the message element is not shown, but is assumed to be present.
1087Action in \gsiii\ is originated by a request coming in from the outside. In the standard web-based \gs, this comes from a servlet and is passed into the Receptionist. This ``external'' type request is a request for a page of data, and contains a representation of the CGI style arguments. A page of XML is returned, which can be in HTML format or other depending on the output parameter of the request.
1088
1089Messages inside the system (``internal'' messages) all follow the same basic format: message elements contain multiple request elements, or multiple response elements. Messaging is all synchronous. The same number of responses as requests will be returned. Currently all requests are independent, so any requests can be combined into the same message, and they will be answered separately, with their responses being sent back in a single message.
1090
1091When a page request (external request) comes in to the Receptionist, it looks at the action attribute and passes the request to the appropriate Action module. The Action will fire one or more internal requests to the MessageRouter, based on the arguments. The data is gathered into a response, which is returned to the Receptionist. The page that the receptionist returns contains the original request, the response from the action and other info as needed (depends on the type of Receptionist). The data may be transformed in some way --- for the \gs\ servlet we transform using XSLT to generate html pages.
1092
1093Actions send internal style messages to the MessageRouter. Some can be answered by it, others are passed on to collections, and maybe on to services. Internal requests are for simple actions, such as search, retrieve metadata, retrieve document text
1094There are different internal request types: describe, process, system, format, status. Process requests do the actual work of the system, while the other types get auxiliary information. The format of the requests and responses for each internal request type are described in the following sections. External style requests, and their page responses are described in the Section about page generation (Section~\ref{sec:pagegen}).
1095
1096\subsection{'describe'-type messages}\label{sec:describe}
1097
1098The most basic of the internal standard requests is ``describe-yourself'', which can be sent to any module in the system. The module responds with a semi-predefined piece of XML, making these requests very efficient. The response is predefined apart from any language-specific text strings, which are put together as each request comes in, based on the language attribute of the request.
1099\begin{quote}\begin{gsc}\begin{verbatim}
1100<request lang='en' type='describe' to=''/>
1101\end{verbatim}\end{gsc}\end{quote}
1102If the \gst{to} field is empty, a request is answered by the MessageRouter.
1103An example response from a MessageRouter might look like this:
1104\begin{quote}\begin{gsc}\begin{verbatim}
1105<response lang='en' type='describe'>
1106 <serviceList/>
1107 <siteList>
1108 <site name='org.greenstone.gsdl1'
1109 address='http://localhost:8080/soap/servlet/rpcrouter'
1110 type='soap' />
1111 </siteList>
1112 <serviceClusterList>
1113 <serviceCluster name="build" />
1114 </serviceClusterList>
1115 <collectionList>
1116 <collection name='org.greenstone.gsdl1/
1117 org.greenstone.gsdl2/fao' />
1118 <collection name='org.greenstone.gsdl1/demo' />
1119 <collection name='org.greenstone.gsdl1/fao' />
1120 <collection name='myfiles' />
1121 </collectionList>
1122</response>
1123\end{verbatim}\end{gsc}\end{quote}
1124This MessageRouter has no individual site-wide services (an empty \gst{<serviceList>}), but has a service cluster called build (which provides collection importing and building functionality). It
1125communicates with one site, \gst{org.greenstone.gsdl1}. It is aware of four
1126collections. One of these, \gst{myfiles}, belongs to it; the other three are
1127available through the external site. One of those collections is actually from
1128a further external site.
1129
1130It is possible to ask just for a specific part of the information provided by a
1131describe request, rather than the whole thing. For example, these two
1132messages get the \gst{collectionList} and the \gst{siteList} respectively:
1133\begin{quote}\begin{gsc}\begin{verbatim}
1134<request lang='en' type='describe' to=''>
1135 <paramList>
1136 <param name='subset' value='collectionList'/>
1137 </paramList>
1138</request>
1139
1140<request lang='en' type='describe' to=''>
1141 <paramList>
1142 <param name='subset' value='siteList'/>
1143 </paramList>
1144</request>
1145\end{verbatim}\end{gsc}\end{quote}
1146
1147Subset options for the MessageRouter include \gst{collectionList}, \gst{serviceClusterList}, \gst{serviceList}, \gst{siteList}.
1148
1149When a collection or service cluster is asked to describe itself, what is returned is a list of metadata, some display elements, and a list of services. For example, here is such a message, along with a sample response.
1150
1151\begin{quote}\begin{gsc}\begin{verbatim}
1152<request lang='en' type='describe' to='mgppdemo'/>
1153
1154<response from="mgppdemo" type="describe">
1155 <collection name="mgppdemo">
1156 <displayItem lang="en" name="name">greenstone mgpp demo
1157 </displayItem>
1158 <displayItem lang="en" name="description">This is a
1159 demonstration collection for the Greenstone digital
1160 library software. It contains a small subset (11 books)
1161 of the Humanity Development Library. It is built with
1162 mgpp.</displayItem>
1163 <displayItem lang="en" name="icon">mgppdemo.gif</displayItem>
1164 <serviceList>
1165 <service name="DocumentStructureRetrieve" type="retrieve" />
1166 <service name="DocumentMetadataRetrieve" type="retrieve" />
1167 <service name="DocumentContentRetrieve" type="retrieve" />
1168 <service name="ClassifierBrowse" type="browse" />
1169 <service name="ClassifierBrowseMetadataRetrieve"
1170 type="retrieve" />
1171 <service name="TextQuery" type="query" />
1172 <service name="FieldQuery" type="query" />
1173 <service name="AdvancedFieldQuery" type="query" />
1174 <service name="PhindApplet" type="applet" />
1175 </serviceList>
1176 <metadataList>
1177 <metadata name="creator">greenstone@cs.waikato.ac.nz</metadata>
1178 <metadata name="numDocs">11</metadata>
1179 <metadata name="buildType">mgpp</metadata>
1180 <metadata name="httpPath">http://kanuka:8090/gsdl3/sites/
1181 localsite/collect/mgppdemo</metadata>
1182 </metadataList>
1183 </collection>
1184</response>
1185\end{verbatim}\end{gsc}\end{quote}
1186
1187Subset options for a collection or serviceCluster include \gst{metadataList}, \gst{serviceList}, and \gst{displayItemList}.
1188
1189This collection provides many typical services. Notice how this response lists the services available, while the collection configuration file for this collection (Figure~\ref{fig:collconfig}) described serviceRacks. Once the service racks have been configured, they become transparent in the system, and only services are referred to.
1190There are three document retrieval services, for structural information, metadata, and content. The Classifier services retrieve classification structure and metadata. These five services were all provided by the GS2MGPPRetrieve ServiceRack. The three query services were provided by GS2MGPPSearch serviceRack, and provide different kinds of query interface. The last service, PhindApplet, is provided by the PhindPhraseBrowse serviceRack and is an applet service.
1191
1192A \gst{describe} request sent to a service returns a list of parameters that
1193the service accepts and some display information, (and in future may describe the content type for the request and response). Subset options for the request include \gst{paramList} and \gst{displayItemList}.
1194
1195Parameters can be in the following formats:
1196\begin{quote}\begin{gsc}\begin{verbatim}
1197<param name='xxx' type='integer|boolean|string|invisible' default='yyy'/>
1198<param name='xxx' type='enum_single|enum_multi' default='aa'/>
1199 <option name='aa'/><option name='bb'/>...
1200</param>
1201<param name='xxx' type='multi' occurs='4'>
1202 <param .../>
1203 <param .../>
1204</param>
1205\end{verbatim}\end{gsc}\end{quote}
1206
1207If no default is specified, the parameter is assumed to be mandatory.
1208Here are some examples of parameters:
1209\begin{quote}\begin{gsc}\begin{verbatim}
1210<param name='case' type='boolean' default='0'/>
1211
1212<param name='maxDocs' type='integer' default='50'/>
1213
1214<param name='index' type='enum' default='dtx'>
1215 <option name='dtx'/>
1216 <option name='stt'/>
1217 <option name='stx'/>
1218<param>
1219
1220<!-- this one is for the text box and field list for the
1221simple field query-->
1222<param name='simpleField' type='multi' occurs='4'>
1223 <param name='fqv' type='string'/>
1224 <param name='fqf' type='enum_single'>
1225 <option name='TI'/><option name='AU'/><option name='OR'/>
1226 </param>
1227</param>
1228
1229\end{verbatim}\end{gsc}\end{quote}
1230The type attribute is used to determine how to display the parameters on a web page or interface. For example, a string parameter may result in a text entry box, a boolean an on/off button, enum\_single/enum\_multi a drop-down menu, where one or many items, respectively, can be selected.
1231A multi-type parameter indicates that two or more parameters are associated, and should be displayed appropriately. For example, in a field query, the text box and field list should be associated. The occurs attribute specifies how many times the parameter should be displayed on the page.
1232Parameters also come with display information: all the text strings needed to present them to the user. These include the name of the parameter and the display values for any options. These are included in the above parameter descriptions in the form of \gst{<displayItem>} elements.
1233
1234A service description also contains some display information---this includes the name of the service, and the text for the submit button.
1235
1236Here is a sample describe request to the FieldQuery service of collection mgppdemo, along with its response. The parameters in this example include their display information. Figure~\ref{fig:query-display} shows an example html search form that may be generated from this describe response.
1237
1238\begin{quote}\begin{gsc}\begin{verbatim}
1239<request lang="en" to="mgppdemo/FieldQuery" type="describe" />
1240
1241<response from="mgppdemo/FieldQuery" type="describe">
1242 <service name="FieldQuery" type="query">
1243 <displayItem name="name">Form Query</displayItem>
1244 <displayItem name="submit">Search</displayItem>
1245 <paramList>
1246 <param default="Doc" name="level" type="enum_single">
1247 <displayItem name="name">Granularity to search at</displayItem>
1248 <option name="Doc">
1249 <displayItem name="name">Document</displayItem>
1250 </option>
1251 <option name="Sec">
1252 <displayItem name="name">Section</displayItem>
1253 </option>
1254 <option name="Para">
1255 <displayItem name="name">Paragraph</displayItem>
1256 </option>
1257 </param>
1258 <param default="1" name="case" type="boolean">
1259 <displayItem name="name">Turn casefolding </displayItem>
1260 <option name="0">
1261 <displayItem name="name">off</displayItem>
1262 </option>
1263 <option name="1">
1264 <displayItem name="name">on</displayItem>
1265 </option>
1266 </param>
1267 <param default="1" name="stem" type="boolean">
1268 <displayItem name="name">Turn stemming </displayItem>
1269 <option name="0">
1270 <displayItem name="name">off</displayItem>
1271 </option>
1272 <option name="1">
1273 <displayItem name="name">on</displayItem>
1274 </option>
1275 </param>
1276 <param default="10" name="maxDocs" type="integer">
1277 <displayItem name="name">Maximum documents to return
1278 </displayItem>
1279 </param>
1280 <param name="simpleField" occurs="4" type="multi">
1281 <displayItem name="name"></displayItem>
1282 <param name="fqv" type="string">
1283 <displayItem name="name">Word or phrase </displayItem>
1284 </param>
1285 <param default="ZZ" name="fqf" type="enum_single">
1286 <displayItem name="name">in field</displayItem>
1287 <option name="ZZ">
1288 <displayItem name="name">allfields</displayItem>
1289 </option>
1290 <option name="TX">
1291 <displayItem name="name">text</displayItem>
1292 </option>
1293 <option name="TI">
1294 <displayItem name="name">Title</displayItem>
1295 </option>
1296 <option name="SU">
1297 <displayItem name="name">Subject</displayItem>
1298 </option>
1299 <option name="ORG">
1300 <displayItem name="name">Organization</displayItem>
1301 </option>
1302 <option name="SO">
1303 <displayItem name="name">Source</displayItem>
1304 </option>
1305 </param>
1306 </param>
1307 </paramList>
1308 </service>
1309</response>
1310\end{verbatim}\end{gsc}\end{quote}
1311
1312\begin{figure}[t]
1313 \centering
1314 \includegraphics[width=3.5in]{query2.ps}
1315 \caption{The previous query service describe response as displayed on the search page.}
1316 \label{fig:query-display}
1317\end{figure}
1318
1319A describe request to an applet type service returns the applet html element: this will be embedded into a web page to run the applet.
1320\begin{quote}\begin{gsc}\begin{verbatim}
1321<request type='describe' to='mgppdemo/PhindApplet'/>
1322
1323<response type='describe'>
1324 <service name='PhindApplet' type='query'>
1325 <applet ARCHIVE='phind.jar, xercesImpl.jar, gsdl3.jar,
1326 jaxp.jar, xml-apis.jar'
1327 CODE='org.greenstone.applet.phind.Phind.class'
1328 CODEBASE='lib/java'
1329 HEIGHT='400' WIDTH='500'>
1330 <PARAM NAME='library' VALUE=''/>
1331 <PARAM NAME='phindcgi' VALUE='?a=a&amp;sa=r&amp;sn=Phind'/>
1332 <PARAM NAME='collection' VALUE='mgppdemo' />
1333 <PARAM NAME='classifier' VALUE='1' />
1334 <PARAM NAME='orientation' VALUE='vertical' />
1335 <PARAM NAME='depth' VALUE='2' />
1336 <PARAM NAME='resultorder' VALUE='L,l,E,e,D,d' />
1337 <PARAM NAME='backdrop' VALUE='interfaces/default/>
1338 images/phindbg1.jpg'/>
1339 <PARAM NAME='fontsize' VALUE='10' />
1340 <PARAM NAME='blocksize' VALUE='10' />
1341 The Phind java applet.
1342 </applet>
1343 <displayItem name="name">Browse phrase hierarchies</displayItem>
1344 </service>
1345</response>
1346\end{verbatim}\end{gsc}\end{quote}
1347
1348Note that the library parameter has been left blank. This is because library refers to the current servlet that is running and the name is not necessarily known in advance. So either the applet action or the Receptionist must fill in this parameter before displaying the html.
1349
1350\subsection{'system'-type messages}\label{sec:system}
1351
1352``System'' requests are used to tell a MessageRouter, Collection or ServiceCluster to update its cached information and activate or deactivate other modules. For example, the MessageRouter has a set of Collection modules that it can talk to. It also holds some XML information about those collections---this is returned when a request for a collection list comes in. If a collection is deleted or modified, or a new one created, this information may need to change, and the list of available modules may also change. Currently these requests are initiated by particular CGI requests (see Section~\ref{sec:runtime-config}).
1353
1354The basic format of a system request is as follows:
1355
1356\begin{quote}\begin{gsc}\begin{verbatim}
1357<request type='system' to=''>
1358 <system .../>
1359</request>
1360\end{verbatim}\end{gsc}\end{quote}
1361
1362One or more actual requests are specified in system elements. The following are examples:
1363\begin{quote}\begin{gsc}\begin{verbatim}
1364<system type='configure' subset=''/>
1365<system type='configure' subset='collectionList'/>
1366<system type='activate' moduleType='collection' moduleName='demo'/>
1367<system type='deactivate' moduleType='site' moduleName='site1'/>
1368\end{verbatim}\end{gsc}\end{quote}
1369
1370The first request reconfigures the whole site---the MessageRouter goes through its whole configure process again. The second request just reconfigures the collectionList---the MessageRouter will delete all its collection information, and re-look through the collect directory and reload all the collections again.
1371The third request is to activate collection demo. This could be a new collection, or a reactivation of an old one. If a collection module already exists, it will be deleted, and a new one loaded. The final request deactivates the site site1---this removes the site from the siteList and module map, and also removes any of that sites collections/services from the static lists.
1372
1373A response just contains a status message\footnote{TODO: add in error/status codes}, for example:
1374\begin{quote}\begin{gsc}\begin{verbatim}
1375<status>MessageRouter reconfigured successfully</status>
1376<status>Error on reconfiguring collectionList</status>
1377<status>collection:demo activated</status>
1378<status>site:site1 deactivated</status>
1379\end{verbatim}\end{gsc}\end{quote}
1380
1381System requests are mainly answered by the MessageRouter. However, Collections and ServiceClusters will respond to a subset of these requests.
1382
1383\subsection{'format'-type messages}\label{sec:format}
1384
1385Collection designers are able to specify how their collection looks to a certain degree. They can specify format statements for display that will apply to the results of a search, the display of a document, entries in a classification hierarchy, for example. This info is generally service specific. All services respond to a format request, where they return any service specific formatting information. A typical request and response looks like this:
1386\begin{quote}\begin{gsc}\begin{verbatim}
1387<request lang="en" to="mgppdemo/FieldQuery" type="format" />
1388
1389<response from="mgppdemo/FieldQuery" type="format">
1390 <format>
1391 <gsf:template match="documentNode"><td><gsf:link>
1392 <gsf:metadata name="Title" />(<gsf:metadata name="Source" />)
1393 </gsf:link></td>
1394 </gsf:template>
1395 </format>
1396</response>
1397\end{verbatim}\end{gsc}\end{quote}
1398
1399The actual format statements are described in Section~\ref{sec:formatstmt}. They are templates written directly in XSLT, or in GSF (GreenStone Format) which is a simple XML representation of the more complicated XSLT templates.
1400GSF-style format statements need to be converted to proper XSLT. This is currently done by the Receptionist (but may be moved to an ActionHelper): the format XML is transformed to XSLT using XSLT with the config\_format.xsl stylesheet.
1401
1402\subsection{'status'-type messages}\label{sec:status}
1403
1404These are only used with process-type services, which are those where a request is sent to start some type of process (see Section~\ref{sec:process}). An initial 'process' request to a 'process' service generates a response which states whether the process had successfully started, and whether its still continuing. If the process is not finished, status requests can be sent repeatedly to the service to poll the status, using the pid to identify the process. Status codes are used to identify the state of a process. The values used at the moment are listed in Table~\ref{tab:status codes}\footnote{A more standard set of codes should probably be used, for example, the HTTP codes}.
1405
1406\begin{table}
1407\caption{Status codes currently used in \gsiii\ }
1408\label{tab:status codes}
1409{\footnotesize
1410\begin{tabular}{llp{8cm}}
1411\hline
1412\bf code name & \bf code & \bf meaning \\
1413& \bf value & \\
1414\hline
1415SUCCESS & 1 & the request was accepted, and the process was completed \\
1416ACCEPTED & 2 & the request was accepted, and the process has been started, but it is not completed yet \\
1417ERROR & 3 & there was an error and the process was stopped \\
1418CONTINUING & 10 & the process is still continuing \\
1419COMPLETED & 11 & the process has finished \\
1420HALTED & 12 & the process has stopped \\
1421INFO & 20 & just an info message that doesn't imply anything \\
1422\hline
1423\end{tabular}}
1424\end{table}
1425
1426 The following shows an example status request, along with two responses, the first a 'OK but continuing' response, and the second a 'successfully completed' response. The content of the status elements in the two responses is the output from the process since the last status update was sent back.
1427
1428\begin{quote}\begin{gsc}\begin{verbatim}
1429<request lang="en" to="build/ImportCollection" type="status">
1430 <paramList>
1431 <param name="pid" value="2" />
1432 </paramList>
1433</request>
1434
1435<response from="build/ImportCollection">
1436 <status code="2" pid="2">Collection construction: import collection.
1437command = import.pl -collectdir /research/kjdon/home/gsdl3/web/sites/
1438 localsite/collect test1
1439starting
1440 </status>
1441</response>
1442
1443<response from="build/ImportCollection">
1444 <status code="11" pid="2">RecPlug: getting directory
1445/research/kjdon/home/gsdl3/web/sites/localsite/collect/test1/import
1446WARNING - no plugin could process /.keepme
1447
1448*********************************************
1449Import Complete
1450*********************************************
1451* 1 document was considered for processing
1452* 0 were processed and included in the collection
1453* 1 was rejected. See /research/kjdon/home/gsdl3/web/sites/
1454 localsite/collect/test1/etc/fail.log for a list of rejected documents
1455Success
1456 </status>
1457</response>
1458\end{verbatim}\end{gsc}\end{quote}
1459
1460\subsection{'process'-type messages}
1461
1462Process requests and responses provide the major functionality of the system---these are the ones that do the actual work. The format depends on the service they are for, so I'll describe these by service.
1463
1464Query type services TextQuery, FieldQuery, AdvancedFieldQuery (GS2MGSearch, GS2MGPPSearch), TextQuery (LuceneSearch)
1465The main type of requests in the system are for services. There are different types of services, currently: \gst{query}, \gst{browse}, \gst{retrieve}, \gst{process}, \gst{applet}, \gst{enrich}. Query services do some kind of search and return a list of document identifiers. Retrieve services can return the content of those documents, metadata about the documents, or other resources. Browse is for browsing lists or hierarchies of documents. Process type services are those where the request is for a command to be run. A status code will be returned immediately, and then if the command has not finished, an update of the status can be requested. Applet services are those that run an applet. Enrich services take a document and return the document with some extra markup added.
1466
1467 Other possibilities include transform, extract, accrete. These types of service generally enhance the functionality of the first set. They may be used during collection formation: 'accrete' documents by adding them to a collection, 'transform' the documents into a different format, 'extract' information or acronyms from the documents, 'enrich' those documents with the information extracted or by adding new information. They may also be used during querying: 'transform' a query before using it to query a collection, or 'transform' the documents you get back into an appropriate form.
1468
1469The basic structure of a service 'process' request is as follows:
1470\begin{quote}\begin{gsc}\begin{verbatim}
1471
1472<request lang='en' type='process' to='demo/TextQuery'>
1473 <paramList/>
1474 other elements...
1475</request>
1476
1477\end{verbatim}\end{gsc}\end{quote}
1478
1479The parameters are name-value pairs corresponding to parameters that were specified in the service description sent in response to a describe request.
1480
1481\begin{quote}\begin{gsc}\begin{verbatim}
1482<param name='case' value='1'/>
1483<param name='maxDocs' value='34'/>
1484<param name='index' value='dtx'/>
1485\end{verbatim}\end{gsc}\end{quote}
1486
1487Some requests have other content---for document retrieval, this would be a list of document identifiers to retrieve. For metadata retrieval, the content is the list of documents to retrieve metadata for.
1488
1489Responses vary depending on the type of request. The following sections look at the process type requests and responses for each type of service.
1490
1491\subsubsection{'query'-type services}
1492Responses to query requests contain a list of document identifiers, along with some other information, dependent on the query type. For a text query, this includes term frequency information, and some metadata about the result. For instance, a text query on 'snail farming', with the parameter 'maxDocs=10' might return the first 10 documents, and one of the query metadata items would be the total number of documents that matched the query.\footnote{no metadata about the query result is returned yet.}
1493
1494The following shows an example query request and its response.
1495
1496Find at most 10 Sections in the mgppdemo collection, containing the word snail (stemmed), returning the results in ranked order:
1497\begin{quote}\begin{gsc}\begin{verbatim}
1498<request lang='en' to="mgppdemo/TextQuery" type="process">
1499 <paramList>
1500 <param name="maxDocs" value="10"/>
1501 <param name="queryLevel" value="Section"/>
1502 <param name="stem" value="1"/>
1503 <param name="matchMode" value="some"/>
1504 <param name="sortBy" value="1"/>
1505 <param name="index" value="t0"/>
1506 <param name="case" value="0"/>
1507 <param name="query" value="snail"/>
1508 </paramList>
1509</request>
1510
1511<response from="mgppdemo/TextQuery" type="process">
1512 <metadataList>
1513 <metadata name="numDocsMatched" value="59" />
1514 </metadataList>
1515 <documentNodeList>
1516 <documentNode nodeID="HASHac0a04dd14571c60d7fbfd.4.2"
1517 docType='hierarchy' nodeType="leaf" />
1518 <documentNode nodeID="HASH010f073f22033181e206d3b7.2.12"
1519 docType='hierarchy' nodeType="leaf" />
1520 <documentNode nodeID="HASH010f073f22033181e206d3b7.1"
1521 docType='hierarchy' nodeType="interior" />
1522 <documentNode nodeID="HASHac0a04dd14571c60d7fbfd.2.2"
1523 docType='hierarchy' nodeType="leaf" />
1524 ...
1525 </documentNodeList>
1526 <termList>
1527 <term field="" freq="454" name="snail" numDocsMatch="58" stem="3">
1528 <equivTermList>
1529 <term freq="" name="Snail" numDocsMatch="" />
1530 <term freq="" name="snail" numDocsMatch="" />
1531 <term freq="" name="Snails" numDocsMatch="" />
1532 <term freq="" name="snails" numDocsMatch="" />
1533 </equivTermList>
1534 </term>
1535 </termList>
1536</response>
1537\end{verbatim}\end{gsc}\end{quote}
1538
1539The list of document identifiers includes some information about document type and node type. Currently, document types include \gst{simple}, \gst{paged} and \gst{hierarchy}. \gst{simple} is for single section documents, i.e. ones with no sub-structure. \gst{paged} is documents that have a single list of sections, while \gst{hierarchy} type documents have a hierarchy of nested sections. For \gst{paged} and \gst{hierarchy} type documents, the node type identifies whether a section is the root of the document, an internal section, or a leaf.
1540
1541The term list identifies, for each term in the query, what its frequency in the collection is, how many documents contained that term, and a list of its equivalent terms (if stemming or casefolding was used).
1542
1543\subsubsection{'browse'-type services}
1544
1545Browse type services are used for classification browsing. The request consists of a list of classifier identifiers, and some structure parameters listing what structure to retrieve.
1546
1547\begin{quote}\begin{gsc}\begin{verbatim}
1548<request lang="en" to="mgppdemo/ClassifierBrowse" type="process">
1549 <paramList>
1550 <param name="structure" value="ancestors" />
1551 <param name="structure" value="children" />
1552 </paramList>
1553 <classifierNodeList>
1554 <classifierNode nodeID="CL1.2" />
1555 </classifierNodeList>
1556</request>
1557
1558<response from="mgppdemo/ClassifierBrowse" type="process">
1559 <classifierNodeList>
1560 <classifierNode nodeID="CL1">
1561 <nodeStructure>
1562 <classifierNode nodeID="CL1">
1563 <classifierNode nodeID="CL1.2">
1564 <classifierNode nodeID="CL1.2.1" />
1565 <classifierNode nodeID="CL1.2.2" />
1566 <classifierNode nodeID="CL1.2.3" />
1567 <classifierNode nodeID="CL1.2.4" />
1568 <classifierNode nodeID="CL1.2.5" />
1569 </classifierNode>
1570 </classifierNode>
1571 </nodeStructure>
1572 </classifierNode>
1573 </classifierNodeList>
1574</response>
1575\end{verbatim}\end{gsc}\end{quote}
1576
1577Possible values for structure parameters are \gst{ancestors}, \gst{parent}, \gst{siblings}, \gst{children}, \gst{descendents}. The response gives, for each identifier in the request, a \gst{<nodeStructure>} element with all the requested structure put together into a hierarchy. The structure may include classifier and document nodes.
1578
1579
1580\subsubsection{'retrieve'-type services}
1581
1582Retrieval services are special in that requests are not explicitly initiated by a user from a form on a web page, but are called from actions in response to other things. This means that their names are hard-coded into the Actions. DocumentContentRetrieve, DocumentStructureRetrieve and DocumentMetadataRetrieve are the standard names for retrieval services for content, structure, and metadata of documents. Requests to each of these include a list of document identifiers. Because these generally refer to parts of documents, the elements are called \gst{<documentNode>}. For the content, that is all that is required. For the metadata retrieval service, the request also needs parameters specifying what metadata is required. For structure retrieval services, requests need parameters specifying what structure or structural info is required.
1583
1584Some example requests and responses follow.
1585
1586Give me the Title metadata for these documents:
1587\begin{quote}\begin{gsc}\begin{verbatim}
1588
1589<request lang="en" to="mgppdemo/DocumentMetadataRetrieve" type="process">
1590 <paramList>
1591 <param name="metadata" value="Title" />
1592 </paramList>
1593 <documentNodeList>
1594 <documentNode nodeID="HASHac0a04dd14571c60d7fbfd.4.2"/>
1595 <documentNode nodeID="HASH010f073f22033181e206d3b7.2.12"/>
1596 <documentNode nodeID="HASH010f073f22033181e206d3b7.1"/>
1597 ...
1598 </documentNodeList>
1599</request>
1600
1601<response from="mgppdemo/DocumentMetadataRetrieve" type="process">
1602 <documentNodeList>
1603 <documentNode nodeID="HASHac0a04dd14571c60d7fbfd.4.2">
1604 <metadataList>
1605 <metadata name="Title">Putting snails in your second pen</metadata>
1606 </metadataList>
1607 </documentNode>
1608 <documentNode nodeID="HASH010f073f22033181e206d3b7.2.12">
1609 <metadataList>
1610 <metadata name="Title">Now you must decide</metadata>
1611 </metadataList>
1612 </documentNode>
1613 <documentNode nodeID="HASH010f073f22033181e206d3b7.1">
1614 <metadataList>
1615 <metadata name="Title">Introduction</metadata>
1616 </metadataList>
1617 </documentNode>
1618 </documentNodeList>
1619</response>
1620\end{verbatim}\end{gsc}\end{quote}
1621
1622One or more parameters specifying metadata may be included in a request. Also, ametadata value of \gst{all} will retrieve all the metadata for each document.
1623
1624Any browse-type service must also implement a metadata retrieval service to provide metadata for the nodes in the classification hierarchy. The name of it is the browse service name plus \gst{MetadataRetrieve}. For example, the ClassifierBrowse service described in the previous section should also have a ClassifierBrowseMetadataRetrieve service. The request and response format is exactly the same as for the DocumentMetadataRetrieve service, except that \gst{<documentNode>} elements are replaced by \gst{<classifierNode>} elements (and the corresponding list element is also changed).
1625
1626Give me the text (content) of this document:
1627\begin{quote}\begin{gsc}\begin{verbatim}
1628<request lang="en" to="mgppdemo/DocumentContentRetrieve" type="process">
1629 <paramList />
1630 <documentNodeList>
1631 <documentNode nodeID="HASHac0a04dd14571c60d7fbfd.4.2" />
1632 </documentNodeList>
1633</request>
1634
1635<response from="mgppdemo/DocumentContentRetrieve" type="process">
1636 <documentNodeList>
1637 <documentNode nodeID="HASHac0a04dd14571c60d7fbfd.4.2">
1638 <nodeContent>&lt;Section&gt;
1639 &lt;/B&gt;&lt;P ALIGN=&quot;JUSTIFY&quot;&gt;&lt;/P&gt;
1640 &lt;P ALIGN=&quot;JUSTIFY&quot;&gt;190. When the plants in
1641 your second pen have grown big enough to provide food and
1642 shelter, you can put in the snails.&lt;/P&gt;
1643 </nodeContent>
1644 </documentNode>
1645 </documentNodeList>
1646</response>
1647\end{verbatim}\end{gsc}\end{quote}
1648
1649The content of a node is returned in a \gst{<nodeContent>} element. In this case it is escaped HTML.
1650
1651Give me the ancestors and children of the specified node, along with the number of siblings it has:
1652\begin{quote}\begin{gsc}\begin{verbatim}
1653<request lang="en" to="mgppdemo/DocumentStructureRetrieve" type="process">
1654 <paramList>
1655 <param name="structure" value="ancestors" />
1656 <param name="structure" value="children" />
1657 <param name="info" value="numSiblings" />
1658 </paramList>
1659 <documentNodeList>
1660 <documentNode nodeID="HASHac0a04dd14571c60d7fbfd.4.2" />
1661 </documentNodeList>
1662</request>
1663
1664<response from="mgppdemo/DocumentStructureRetrieve" type="process">
1665 <documentNodeList>
1666 <documentNode nodeID="HASHac0a04dd14571c60d7fbfd.4.2">
1667 <nodeStructureInfo>
1668 <info name="numSiblings" value="2" />
1669 </nodeStructureInfo>
1670 <nodeStructure>
1671 <documentNode nodeID="HASHac0a04dd14571c60d7fbfd"
1672 docType='hierarchy' nodeType="root">
1673 <documentNode nodeID="HASHac0a04dd14571c60d7fbfd.4"
1674 docType='hierarchy' nodeType="interior">
1675 <documentNode nodeID="HASHac0a04dd14571c60d7fbfd.4.2"
1676 docType='hierarchy' nodeType="leaf" />
1677 </documentNode>
1678 </documentNode>
1679 </nodeStructure>
1680 </documentNode>
1681 </documentNodeList>
1682</response>
1683\end{verbatim}\end{gsc}\end{quote}
1684
1685Structure is returned inside a \gst{<nodeStructure>} element, while structural info is returned in a \gst{<nodeStructureInfo>} element. Possible values for structure parameters are as for browse services: \gst{ancestors}, \gst{parent}, \gst{siblings}, \gst{children}, \gst{descendents}, \gst{entire}. Possible values for info parameters are \gst{numSiblings}, \gst{siblingPosition}, \gst{numChildren}.
1686
1687\subsubsection{'process'-type services}\label{sec:process}
1688Requests to process-type services are not requests for data---they request some action to be carried out, for example, create a new collection, or import a collection. The response is a status or an error message. The import and build commands may take a long time to complete, so a response is sent back after a successful start to the command. The status may be polled by the requester to see how the process is going.
1689
1690Process requests generally contain just a parameter list. Like for any service, the parameters used by a process-type service can be obtained by a describe request to that service.
1691
1692Here are two example requests for process-services that are part of the build service cluster (hence the addresses all begin with 'build/'), followed by an example response:
1693
1694\begin{quote}\begin{gsc}\begin{verbatim}
1695<request lang='en' type='process' to='build/NewCollection'>
1696 <paramList>
1697 <param name='creator' value='me@home.com'/>
1698 <param name='collName' value='the demo collection'/>
1699 <param name='collShortName' value='demo'/>
1700 </paramlist>
1701</request>
1702
1703<request lang='en' type='process' to='build/ImportCollection'>
1704 <paramList>
1705 <param name='collection' value='demo'/>
1706 </paramlist>
1707</request>
1708
1709<response from="build/ImportCollection">
1710 <status code="2" pid="2">Starting process...</status>
1711</response>
1712\end{verbatim}\end{gsc}\end{quote}
1713
1714The \gst{code} attribute in the response specifies whether the command has been successfully stated, whether its still going, etc (see Table~\ref{tab:status codes} for a list of currently used codes). The pid attribute specifies a process id number that can be used when querying the status of this process. The content of the status element is (currently) just the output from the process so far. Status messages, which were described in Section~\ref{sec:status}, are used to find out how the process is going, and whether it has finished or not.
1715
1716\subsubsection{'applet'-type services}
1717
1718Applet-type services are those that process the data for an applet. A request consists only of a list of parameters, and the response contains an \gst{<appletData>} element that contains the XML data to be returned to the applet. The format of this is entirely specific to the applet---there is no set format to the applet data.
1719
1720Here is an example request and response, used by the Phind applet:
1721\begin{quote}\begin{gsc}\begin{verbatim}
1722 <request type='query' to='mgppdemo/PhindApplet'>
1723 <paramList>
1724 <param name='pc' value='1'/>
1725 <param name='pptext' value='health'/>
1726 <param name='pfe' value='0'/>
1727 <param name='ple' value='10'/>
1728 <param name='pfd' value='0'/>
1729 <param name='pld' value='10'/>
1730 <param name='pfl' value='0'/>
1731 <param name='pll' value='10'/>
1732 </paramList>
1733 </request>
1734
1735 <response type='query' from='mgppdemo/PhindApplet'>
1736 <appletData>
1737 <phindData df='9' ef='46' id='933' lf='15' tf='296'>
1738 <expansionList end='10' length='46' start='0'>
1739 <expansion df='4' id='8880' num='0' tf='59'>
1740 <suffix> CARE</suffix>
1741 </expansion>
1742 ...
1743 </expansionList>
1744 <documentList end='10' length='9' start='0'>
1745 <document freq='78' hash='HASH4632a8a51d33c47a75c559' num='0'>
1746 <title>The Courier - N??159 - Sept- Oct 1996 Dossier Investing
1747 in People Country Reports: Mali ; Western Samoa
1748 </title>
1749 </document>
1750 ...
1751 </documentList>
1752 <thesaurusList end='10' length='15' start='0'>
1753 <thesaurus df='7' id='12387' tf='15' type='RT'>
1754 <phrase>PUBLIC HEALTH</phrase>
1755 </thesaurus>...
1756 </thesaurusList>
1757 </phindData>
1758 </appletData>
1759 </response>
1760
1761\end{verbatim}\end{gsc}\end{quote}
1762
1763\subsubsection{'enrich'-type services}
1764
1765Enrich services typically take some text of documents (inside \gst{<nodeContent>} tags) and returns the text marked up in some way. One example of this is the GatePOSTag service: this identifies Dates, Locations, People and Organizations in the text, and annotates the text with the labels. In the following example, the request is for Location and Dates to be identified.
1766
1767\begin{quote}\begin{gsc}\begin{verbatim}
1768<request lang="en" to="GatePOSTag" type="process">
1769 <paramList>
1770 <param name="annotationType" value="Date,Location" />
1771 </paramList>
1772 <documentNodeList>
1773 <documentNode nodeID="HASHac0a04dd14571c60d7fbfd">
1774 <nodeContent>
1775 FOOD AND AGRICULTURE ORGANIZATION OF THE UNITED NATIONS
1776 Rome 1986
1777 P-69
1778 ISBN 92-5-102397-2
1779 FAO 1986
1780 </nodeContent>
1781 </documentNode>
1782 </documentNodeList>
1783</request>
1784
1785<response from="GatePOSTag" type="process">
1786 <documentNodeList>
1787 <documentNode nodeID="HASHac0a04dd14571c60d7fbfd">
1788 <nodeContent>
1789 FOOD AND AGRICULTURE ORGANIZATION OF THE UNITED NATIONS
1790 <annotation type="Location">Rome</annotation>
1791 <annotation type="Date">1986</annotation>
1792 P-69
1793 ISBN 92-5-102397-2
1794 FAO <annotation type="Date">1986</annotation>
1795 </nodeContent>
1796 </documentNode>
1797 </documentNodeList>
1798</response>
1799\end{verbatim}\end{gsc}\end{quote}
1800
1801\subsection{Page generation}\label{sec:pagegen}
1802
1803A 'page' is some XML or HTML (or other?) data returned in response to an
1804external 'page'-type request. These requests originate from outside \gs\ , for example from a servlet, or java application, and are received by the Receptionist. As described below in Section~\ref{sec:page-requests}, the requests are XML representations of \gs\ URLs. One of the arguments is action (a). This tells the Receptionist which Action module to pass the request to.
1805
1806Action modules decode the rest of the arguments to determine what requests need to be made to the system. One or more internal requests may be made to the MessageRouter. A request for format information from the Collection/Service may also be made. The resulting data is gathered together into a single XML response, \gst{<page>}, and returned to the Receptionist.
1807
1808The page format is described in Section~\ref{sec:page-format}. The XML may be returned as is, or may be modified by the Receptionist. The various Receptionists are described in Section~\ref{sec:recepts}. The default receptionist used by a servlet transforms the XML into HTML using XSL stylesheets. Section~\ref{sec:collformat} looks at collection specific formatting, in particular for HTML output.
1809Sections~\ref{sec:pageaction} to \ref{sec:systemaction} look at the various actions and what kind of data they gather.
1810
1811\subsubsection{'page'-type requests and their arguments}\label{sec:page-requests}
1812
1813These are requests for a 'page' of data---for example, the home page for a site; the query page for a collection; the text of a document. They contain, in XML, a list of arguments specifying what type of page is required. If the external context is a servlet, the arguments represent the 'CGI' arguments in a \gs\ URL. The two main arguments are \gst{a} (action) and \gst{sa} (subaction). All other arguments are encoded as parameters.
1814
1815Here are some examples of requests\footnote{In a servlet context, these correspond to the arguments \gst{a=p\&sa=about\&c=demo\&l=fr}, and \gst{a=q\&l=en\&s=TextQuery\&c=demo\&rt=r\&ca=0\&st=1\&m=10\&q=snail}.}:
1816
1817\begin{quote}\begin{gsc}\begin{verbatim}
1818<request type='page' action='p' subaction='about'
1819 lang='fr' output='html'>
1820 <paramList>
1821 <param name='c' value='demo'/>
1822 </paramList>
1823</request>
1824\end{verbatim}\end{gsc}\end{quote}
1825
1826\begin{quote}\begin{gsc}\begin{verbatim}
1827<request type='page' action='q' lang='en' output='html'>
1828 <paramList>
1829 <param name='s' value='TextQuery'/>
1830 <param name='c' value='demo'/>
1831 <param name='rt' value='r'/>
1832 <!-- the rest are the service specific params -->
1833 <param name='ca' value='0'/> <!-- casefold -->
1834 <param name='st' value='1'/> <!-- stem -->
1835 <param name='m' value='10'/> <!-- maxdocs -->
1836 <param name='q' value='snail'/> <!-- query string -->
1837 </paramList>
1838</request>
1839\end{verbatim}\end{gsc}\end{quote}
1840
1841There are some standard arguments used in Greenstone, and they are described in Table~\ref{tab:args}. These are used by Receptionists and Actions. The GSParams class specifies all the general basic arguments, and whether they should be saved or not (Some arguments need to be saved during a session, and this needs to be implemented outside \gs\ proper --- currently we do this in the servlet, using servlet session handling). The servlet has an init parameter \gst{params\_class} which specifies which params class to use: GSParams can be subclassed if necessary. The Receptionist and Actions must not have conflicting argument names.
1842
1843Other arguments are used dynamically and come from the Services. Service arguments must always be saved during a session. Services may be created by different people, and may reside on a different site. There is no guarantee that there is no conflict with argument names between services and actions. Therefore service parameters are namespaced when they are put on the page, whereas interface (receptionist and action) parameters have no namespace. The default namespace is s1 (service1) --- any parameters that are for the service will be prefixed by this. For example, the case parameter for a search will be put in the page as s1.case, and the resulting argument in a search URL will be s1.case. When actions are deciding which parameters need to be sent in a request to a service, they can use the namespace information.
1844
1845If there are two or more services combined on a page with a single submit button, they will use namespaces s1, s2, s3 etc as needed. The s (service) parameter will end up with a list of services. For example, \gst{s=TextQuery,MusicQuery,} and the order of these determines the mapping order of the namespaces, i.e. s1 will map to TextQuery, s2 to MusicQuery.
1846
1847\begin{table}
1848{\footnotesize
1849\begin{tabular}{lll}
1850\hline
1851\bf Argument & \bf Meaning &\bf Typical values \\
1852\hline
1853a & action & a (applet), q (query), b (browse), p (page), pr (process) \\
1854& & s (system)\\
1855sa & subaction & home, about (page action)\\
1856c & collection or & demo, build \\
1857& service cluster \\
1858s & service name & TextQuery, ImportCollection \\
1859rt & request type & d (display), r (request), s (status) \\
1860ro & response only & 0 or 1 - if set to one, the request is carried out \\
1861& & but no processing of the results is done \\
1862& & currently only used in process actions \\
1863o & output type & XML, html, WML \\
1864l & language & en, fr, zh ...\\
1865d & document id & HASHxxx \\
1866r & resource id & ???\\
1867pid & process handle & an integer identifying a particular process request \\
1868\hline
1869\end{tabular}}
1870\caption{Generic arguments that can appear in a \gs\ URL}
1871\label{tab:args}
1872\end{table}
1873
1874\subsubsection{page format}\label{sec:page-format}
1875
1876The basic page format is:
1877\begin{quote}\begin{gsc}\begin{verbatim}
1878<page lang='en'>
1879 <pageRequest/>
1880 <pageResponse/>
1881</page>
1882\end{verbatim}\end{gsc}\end{quote}
1883
1884* show configuration and describe whats its used for
1885
1886There are two main elements in the page: pageRequest, pageResponse. The pageRequest is the original request that came into the Receptionist---this is included so that any parameters can be preset to their previous values, for example, the query options on the query form. The pageResponse contains all the data that has been gathered from the system by the action. The other two elements contain extra information needed by XSLT. Config contains run-time variables such as the location of the gsdl home directory, the current site name, the name of the executable that is running (e.g. library)---these are needed to allow the XSLT to generate correct HTML URLs. Display contains some of the text strings needed in the interface---these are separate from the XSLT to allow for internationalization.
1887
1888The following subsections outline, for each action, what data is needed and what requests are generated to send to the system.
1889
1890
1891Once the XML page has been put together, the page to return to the user is created by transforming the XML using XSLT. The output is HTML at this stage, but it will be possible to generate alternative outputs, such as XML, WML etc. A set of XSLT files defines an 'interface'. Different users can change the look of their web pages by creating new XSLT files for a new 'interface'. Just as we have a sites directory where different sites 'live' (ie where their configuration file and collections are located), we have an interfaces directory where the different interfaces 'live' (ie their transforms and images are located there). The default XSLT files are
1892located in interfaces/default/transforms. Collections, sites and other interfaces
1893can override these files by having their own copy of the appropriate
1894files. New interfaces have their own directory inside interfaces/. Sites and collections can have a transform directory containing XSLT files. The order in which the XSLT files are looked for is collection, site, current
1895interface, default interface.\footnote{this currently breaks down for remote sites - need to rethink it a bit.}
1896***TODO*** describe a bit more?? currently only can get this locally
1897
1898\subsubsection{Receptionists}\label{sec:recepts}
1899
1900The receptionist is the controlling module for the page generation part of \gs\ . It has the job of loading up all the actions, and it knows about the message router it and the actions are supposed to talk to. It routes messages received to the appropriate action (page-type messages) or directly to the message router (all other types). Receptionists also do other things, for example, adding to the page received back from the action any information that is common to all pages.
1901
1902There are different ways of providing an interface to \gs\ , from web based CGI style (using servlets) to Java GUI applications. These different interfaces require slightly different responses from a receptionist, so we provide several standard types of receptionist.
1903
1904Receptionist: This is the most basic receptionist. The page it returns consists of the original request, and the response from the action it was sent to. Methods preProcessRequest, and postProcessPage are called on the request and page, respectively, but in this basic receptionist, they don't do anything.
1905
1906TransformingReceptionist: This extends Receptionist, and overwrites postProcessPage to transform the page using XSLT. An XSLT is listed for each action in the receptionists configuration file, and this is used to transform the page. First, some display information, and configuration information is added to the page. Then it is transformed using the specified XSLT for the action, and returned.
1907
1908WebReceptionist: The WebReceptionist extends TransformingReceptionist. It doesn't do much else except some argument conversion. To keep the URLs short, parameters from the services are given shortnames, and these are used in the web pages.
1909
1910DefaultReceptionist: This extends WebReceptionist, and is the default one for \gsiii\ servlets. Due to the page design, some extra information is needed for each page: some metadata about the current collection. The receptionist sends a describe request to the collection to get this, and appends it to the page before transformation using XSLT.
1911
1912NZDLReceptionist: (do we want to talk about this?) This is an example of a custom receptionist. For a look-alike nzdl.org system, even more information is needed for each page, namely the list of classifiers available from the ClassifierBrowse service.
1913
1914By default, the LibraryServlet uses DefaultReceptionist. However, there is a servlet init-param called \gst{receptionist} which can be set to make the servlet use a different one.
1915
1916\subsubsection{Collection specific formatting}\label{sec:collformat}
1917get format info, transform gsf->xsl. transfrom xml->html
1918
1919config params are passed in to the transformation
1920\subsubsection{CGI arguments}
1921
1922
1923\subsubsection{Page action}\label{sec:pageaction}
1924
1925PageAction is responsible for displaying kinds of information pages, such as the home page of the library, or the home page of a collection, or the help and preferenecs pages. These pages are not associated with specific services like the other page types. In general, the data comes from describe requests to various modules.
1926The different pages are requested using the subaction argument. For the 'home' page, a 'describe' request is sent to the MessageRouter---this returns a list of all the collections, services, serviceClusters and sites known about. For each collection, its metadata is retrieved via a 'describe' request. This metadata is added into the previous result, which is then added into the page. For the 'about' page, a \gst{describe} request is sent to the module that the about page is about: this may be a collection or a service cluster. This returns a list of metadata
1927and a list of services.
1928
1929
1930\subsubsection{Query action}\label{sec:queryaction}
1931
1932The basic URL is \gst{a=q\&s=TextQuery\&c=demo\&rt=d/r}.
1933There are three query services which have been implemented: TextQuery, FieldQuery, and AdvancedFieldQuery. These are all handled in the same way by query action.
1934For each page, the service description is requested from the service of the current collection (via a describe request). This is currently done every time the query page is
1935displayed, but should be cached. The description includes a list of the parameters available for the query, such as case/stem, max num docs to return, etc. If the request type (rt) parameter is set to d for display, the action only needs to display the form, and this is the only request to the service. Otherwise, the submit button has been pressed, and a query request to the TextQuery service is sent. This has all the parameters from the URL put into the parameter list. A list of document identifiers
1936is returned. A followup query is sent to the MetadataRetrieve service of the collection: the content includes the list of
1937documents, with a request for some of their metadata. Which metadata to retrieve is determined by looking through the XSLT that will be used to transform the page. The service description and query result are combined into a page of XML, which is returned to the Receptionist.
1938
1939\subsubsection{Applet action}\label{sec:appletaction}
1940
1941There are two types of request to the applet action: \gst{a=a \& rt=d\/} and
1942\gst{a=a \& rt=r\/}. The value \gst{rt=d\/} means ``display the applet.'' A
1943\gst{describe} request is sent to the service, which returns the \gst{<applet>} HTML element. The transformation file \gst{applet.xsl} embeds this
1944into the page, and the servlet returns the HTML.
1945
1946The value \gst{rt=r} signals a request from the applet. A process request containing all the parameters is sent to the applet service. The result contains an appletData element, which contains a single element - this element is returned
1947directly to the applet, in XML. No transformation is done.
1948Because the AppletAction doesn't know or care anything about the applet data, it can work with any applet-service pair.
1949
1950Note that the applet HTML may need to know the name of the \gst{library}
1951program. However, that name is chosen by the person who installed the software
1952and will not necessarily be ``library''. To get around this, the applet can
1953put a parameter called ``library'' into the applet data with a null value:
1954\begin{quote}\begin{gsc}\begin{verbatim}
1955<PARAM NAME='library' VALUE=''/>
1956\end{verbatim}\end{gsc}\end{quote}
1957When the AppletAction encounters this parameter it inserts the name of the
1958current library servlet as its value.
1959
1960\subsubsection{Document action}\label{sec:documentaction}
1961
1962DocumentAction is responsible for displaying a document to the user. The display might involve some metadata and/or text for a document or part of a document. For hierarchical documents, a table of contents may be shown, while for paged documents (those with a single linear list of sections), next and previous page buttons may be shown. These different display types require different information about the document. Depending on the arguments, DocumentAction will send requests to several services: DocumentMetadataRetrieve, DocumentStructureRetrieve and DocumentContentRetrieve.
1963
1964A basic display, for example, Title and text, involves a metadata request to get the Title, and a content request to get the text. Hierarchical table of contents display requires a structure request. If the entire contents is to be displayed, the parameter \gst{structure=entire} would be sent in the request. Otherwise, parameters \gst{structure=ancestors}, \gst{structure=children} and possibly \gst{structure=siblings} may be used, depending in the position of the current node in the document. These return a hierarchical structure of nodes, containing ancestor nodes, child nodes and sibling nodes, respectively.
1965For paged display, the structure is not actually needed. A structure request is still sent, but this time it requests some information, rather the structure itself. The information requested includes the number of siblings and the current position of the current node, or the number of children (if the current node is the root of the document).
1966
1967Metadata may be requested for the current node, or for any nodes in the structure, and content also. The metadata and content are added into the appropriate nodes in the structure hierarchy, and this is returned as the page data.
1968
1969\subsubsection{XML Document action}\label{sec:xmldocumentaction}
1970
1971XMLDOcumentAction is a little different to the standard DocumentAction. It operates in two modes, \gst{text} and \gst{toc}. In \gst{text} mode, it will retrieve the content of the current document node using a DocumentContentRetrieve request. In \gst{toc} mode, it retrieves the entire table of contents for the document using a DocumentStructureRetrieve request. Either mode may also retrieve metadata for the current section or each section in the table of contents.
1972
1973\subsubsection{GS2Browse action}\label{sec:browseaction}
1974
1975GS2BrowseAction is for displaying Greenstone 2 style classifiers.
1976\subsubsection{System action}\label{sec:systemaction}
1977
1978SystemAction allows for manual reconfiguration of various components at run-time. There is no interactive web-page displaying the options, it merely turns a set of CGI arguments into an XML system request. The response from a system request is a message which is displayed to the user.
1979
1980\begin{table}
1981\caption{Configure CGI arguments}
1982\label{tab:system-cgi}
1983{\footnotesize
1984\begin{tabular}{ll}
1985\hline
1986\bf arg & \bf description\\
1987\hline
1988a=s & system action\\
1989sa=c$|$a$|$d & type of system request: c (configure), a (add/activate), \\
1990& d (delete/deactivate) \\
1991c=demo & the request will go to this collection/servicecluster \\
1992& instead of the message router\\
1993ss=collectionList & subset for configure: only reconfigure this part.\\
1994& For the MessageRouter, can be serviceClusterList, serviceList, \\
1995& collectionList, siteList.\\
1996& For a collection/cluster, can be metadataList or serviceList.\\
1997sn=demo & \\
1998st=collection& \\
1999\hline
2000\end{tabular}}
2001\end{table}
2002
2003
2004\subsection{Other code information}
2005
2006Greenstone has a set of Utility classes, which are briefly described in Table~\ref{tab:utils}.
2007
2008\begin{table}[h]
2009\caption{The utility classes in org.greenstone.gsdl3.util}
2010\label{tab:utils}
2011{\footnotesize
2012\begin{tabular}{lp{3.75in}}
2013\hline
2014\bf Utility class & \bf Description\\
2015\hline
2016Dictionary & wrapper around a Resource Bundle, providing strings with parameters\\
2017GSConstants & holds some constants used for servlet arguments and configuration variables\\
2018GSEntityResolver & an EntityResolver which can be used to find resources such as DTDs\\
2019GSFile & class to create all \gs\ file paths e.g. used to locate configuration files, XSLT files and collection data. \\
2020GSHTML & provides convenience methods for dealing with HTML, e.g. making strings HTML safe\\
2021GSParams & contains names and default values for interface parameters\\
2022NZDLParams & a subclass of GSParams which holds default service parameters too, necessary for the classic style interface.\\
2023GSPath & used to create, examine and modify message address paths\\
2024GSSQL & contains static strings for all the SQL table/field names\\
2025GSStatus & some static codes for status messages\\
2026GSXML & lots of methods for extracting information out of \gs\ XML, and creating some common types of elements. Also has static Strings for element and attribute names used by \gs\ .\\
2027GSXSLT & some manipulation functions for \gs\ XSLT\\
2028Misc & miscellaneous functions\\
2029OID & class to handle \gs\ (2) OIDs\\
2030GS3OID & subclass of OID to handle \gsiii\ OIDs\\
2031SQLQuery & contains a connection to a SQL database, along with some methods for accessing the data, such as converting MG numbers to and from Greenstone OIDs.\\
2032XMLConverter & provides methods to create new Documents, parse Strings or Files into Documents, and convert Nodes to Strings\\
2033XMLTransformer & methods to transform XML using XSLT \\
2034XSLTUtil & contains static methods to be called from within XSLT \\
2035\hline
2036\end{tabular}}
2037\end{table}
2038
2039\newpage
2040\section{Collection building architecture}\label{sec:develop-build}
2041**** GEORGE ****
2042how building actually works\\
2043the building structure/architecture\\
2044modules API\\
2045
2046\newpage
2047\section{Developing \gsiii\ : Adding new features}\label{sec:new-features}
2048
2049\subsection{Creating new services}\label{sec:new-services}
2050
2051*inherit from ServiceRack - abstract base class. this handles the main process method, determines the service name and request type. if request type is describe, and to is empty, it returns a list of services (short\_service\_info) which is initialised in the configure method. a describe request to a particular service results in getServiceDescription being called, which must be supplied by the subclass.
2052other request types (process) get sent to processXXX methods, where XXX is the service name.
2053
2054* what methods are expected
2055
2056*service type responses expected
2057
2058*a browse type service must also implement servicenameMetadataRetrieve service.
2059
2060* should a metadata retrieval service advertise what metadata is available??
2061
2062standard service type vs new service type - standard needs some xml response syntax.
2063
2064\subsection{creating new actions/pages}\label{sec:new-pages}
2065
2066\subsection{new interfaces}\label{sec:new-interfaces}
2067
2068It is easy to create new interfaces to \gsiii. Here we are talking about interfaces other than those to display in typical browser.
2069
2070Handheld devices: Use the standard servlet setup, but with a different set of XSLT files to format the pages for small screens, or use WML.
2071
2072Java GUI Interface: There are couple of alternatives. Depending on what you want to display in the GUI, you could talk to either a Receptionist or a MessageRouter. The library classes can be set up and compiled into the GUI program.
2073Talking to a Receptionist will give you access to pages of XML. It is likely that the standard Receptionist class would be used - this doesn't transform the data to HTML. Queries such as ``give me the home page of a collection'' and ``do the following search'' can be issued. All teh data needed for the result view is returned. Queries are quite simple, but are limited to what kinds of Actions are available in the library.
2074Talking to a MessageRouter requires a bit more effort on the part of the GUI program, but results in greater flexibility. The kinds of queries that can be issued are individual units of action, such as ``describe yourself'', ``search'', ``retrieve the content for this document''. More than one request may need to be made for a particular feature of the GUI. However you can ask for any combination of data available in the system, you are not relying on Actions. What you will implemenet though, may be a lot like the Action code in terms of request sequences.
2075
2076Interfaces in other programming languages: Because the communication is all XML based, other interfaces can talk to the Java library if a communication protocol is set up. This could be done using SOAP for example. LIke for Java GUI interfaces, the program could talk to a Receptionist or to a MessageRouter.
2077e.g. java interface. where you can interface to. MR vs Receptionist. diff receptionists. egs, handheld - using servlet, transforming recpt, but new set of XSLT java program other program - talk to recpt but just get back XML data for pages. java gui - just talk to MR, do all processing itself.
2078
2079Remote interfaces: remote interfaces can be set up in the same way as above, using a communication protocol between the interface, and the library program.
2080
2081\subsection{Adding new classifiers}\label{sec:new-classifiers}
2082*** GEORGE ***
2083\subsection{Adding new plugins}\label{sec:new-plugins}
2084*** GEORGE ***
2085
2086\subsection{New types of collections}\label{sec:new-coll-types}
2087
2088There are two types of standard \gs\ collections: collections built with the \gsiii\ building system, and collections that are imported from \gsii\ . There are many options to collection building but it is conceivable that these options don't meet the needs of all collection builders. \gsiii\ has an ability to use any type of collection you can come up with, assuming some java code is provided.
2089
2090There are four levels of customisation that may be needed with new collections: service, collection, interface XSLT, and action levels. We will use the example collections that come with \gs\ to describe these different levels.
2091
2092Firstly, new service classes need to be written to provide the functionality to search/browse/whatever the collection. If the services have similar interfaces and functionality to the standard services, this may be all that is needed. For example, the \gsii\ MGPP collections were the first to be served in \gsiii\ . When we came to do \gsii\ MG collections, all we had to do was write some new service classes that interacted with MG instead of MGPP. Because these collections used the same type of services, this was all we had to do. The format of the configuration files was similar, they just specified MG serviceRack classes rather than MGPP ones.
2093
2094The XML Sample Texts (gberg) collection, however, was done quite differently to the standard collections. New services were provided to search the database (built with Lucene) and to provide the documents and parts of documents (using XSLT to transform the raw XML files). The collectionConfig file had some extra information in it: a list of the documents in the collection along with their Titles. Because the standard collection class has no notion of document lists, a new class was created (org.greenstone.gsdl3.collection.XMLCollection). This class is basically the same as a standard collection class except that it looks for and stores in memory the documentList from the collectionConfig file.
2095
2096To tell \gs\ to load up a different type of collection class, we use another configuration file: etc/collectionInit.xml. This specifies the name of the collection class to use.
2097Currently, this is all that is specified in that file, but you may want to add parameters for the class etc.
2098
2099\gst{<collectionInit class="XMLCollection"/>}
2100
2101The display for the collection is also quite different. The home page for the collection displays the list of documents. To achieve this, the describe response from the collection had to include the list, and a new XSLT was written for the collection that displayed this. Collection XSLT should be put in the transform directory of the collection\footnote{These are currently only used when running \gs\ in a non-distributed fashion, but it will be added in properly at some stage}.
2102
2103Document display is significantly different to standard \gs\ . There are two modes of display: table of contents mode, and content mode. Clicking on a document link from the collection home page takes the user to the table of contents for the collection. Clicking on one of the sections in the table of contents takes them to a display of that section. To facilitate this, not only do we need new XSLT files , we also needed a new action. XMLDocumentAction was created, that used two subactions, toc and text, for the different modes of display.
2104
2105The Receptionist was told about this new action by the addition of the following element to the interfaceConfig.xml file:
2106
2107\begin{gsc}\begin{verbatim}
2108<action name='xd' class='XMLDocumentAction'>
2109 <subaction name='toc' xslt='document-toc.xsl'/>
2110 <subaction name='text' xslt='document-content.xsl'/>
2111</action>
2112\end{verbatim}\end{gsc}
2113
2114XSLT files are linked to subactions rather than the action as a whole. The collection supplies the two XSLT files written appropriately for the data it contains.
2115
2116All links that link to the documents have to be changed to use the xd action rather than the standard d action. These include the links from the home page, and the links from query results.
2117
2118Querying of the collection is almost the same as usual. The query service provides a list of parameters, does the query and then sends back a list of document identifiers. The standard query action was fine for this collection. The change occurs in the way that the results are displayed---this is accomplished using a format statement supplied in the collectionConfig file inside the search node.
2119
2120\begin{gsc}\begin{verbatim}
2121<search>
2122 <format>
2123 <gsf:template match="documentNode">
2124 <xsl:param name="collName"/>
2125 <xsl:param name="serviceName"/>
2126 <td>
2127 <b><a href="{$library_name}?a=xd&amp;sa=text&amp;c={$collName}&
2128 amp;d={@nodeID}&amp;p.a=q&amp;p.s={$serviceName}">
2129 <xsl:choose>
2130 <xsl:when test="metadataList/metadata[@name='Title']">
2131 <gsf:metadata name="Title"/>
2132 </xsl:when>
2133 <xsl:otherwise>(section)</xsl:otherwise>
2134 </xsl:choose>
2135 </a>
2136 </b> from <b><a href="{$library_name}?a=xd&amp;sa=toc&amp;
2137 c={$collName}&amp;d={@nodeID}.rt&amp;p.a=q&amp;p.s={$serviceName}">
2138 <gsf:metadata name="Title" select="root"/></a></b>
2139 </td>
2140 </gsf:template>
2141 </format>
2142</search>
2143\end{verbatim}\end{gsc}
2144
2145Instead of displaying an icon and the Title, it displays the Title of the section and the title of the document. Both of these are linked to the document: the section title to the content of that section, the document title to the table of contents for the document. Because these require non-standard arguments to the library, these parts of the template are written in XSLT not \gs\ format language. As is shown here it is perfectly feasible to write a format statement that includes XSLT mixed in with \gs\ format elements.
2146
2147The document display uses CSS to format the output---these are kept in the collection and specified in the collections XSLT files. The documents also specify DTD files. Due to the way we read in the XML files, Tomcat sometimes has trouble locating the DTDs. One option is to make all the links absolute links to files in the collection folder, the other option is to put them in \gs\ 's DTD folder gsdl3/resources/dtd.
2148
2149\subsection{The Classic Interface}
2150
2151The library seen at \gst{http://www.greenstone.org/greenstone3/nzdl} is like a mirror to \gst{http://www.nzdl.org}---it aims to present the same collections, in the same way but using \gsiii\ instead of \gsii\ . It uses a new site (nzdl) with the classic interface. The web.xml file had a new servlet entry in it to specify the combination of nzdl site and classic interface.
2152
2153The site was created by making a directory called nzdl in the sites folder. A siteConfig file was created. Because it is running on Linux, we were able to link to all the collections in the old \gs\ installation. The convert\_coll\_from\_gs2.pl script was run over all the collections to produce the new XML configuration files.
2154
2155The classic interface was created to be used by this site (and is now a standard part of Greenstone).
2156In many cases, creating a new interface just requires the new images and XSLT to be added to the new directory(see Sections~\ref{sec:sites-and-ints} and \ref{sec:interface-customise}). This classic interface required a bit more customisation.
2157
2158The standard \gsiii\ navigation bar lists all the services available for the collection. In \gsii\ , the navigation bar provides the search option, and the different classifiers. This is not service specific, but hard coded to the search and classifiers. The XSLT that produces the navigation bar needed to be altered to produce this. But also, a new Receptionist was needed.
2159The standard receptionist (DefaultReceptionist) gathers a little bit of extra information for each page of XML before transforming it: this is the list of services for the collection and their display information, allowing the services to be listed along the navigation bar. This is information that is needed by every page (except for the library home page) and therefore is obtained by the receptionist instead of by each action. The nzdl interface needed a bit more information than this: for the ClassifierBrowse service, if there was one, the list of classifiers and their display elements must be obtained. So a new Receptionist (NZDLReceptionist) was written that inherited from DefaultReceptionist, and added this new info into the page.
2160
2161One of the servlet initialisation parameters is the receptionist class: this was added to the servlet definition in the web.xml file so that the LibraryServlet would load up the right receptionist class.
2162
2163
2164\newpage
2165\section{Distributed \gs\ }\label{sec:distributed}
2166
2167\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.
2168
2169more explanation..
2170
2171\begin{figure}[h]
2172 \centering
2173 \includegraphics[width=4in]{remote} %5.8
2174 \caption{A distributed digital library configuration running over several servers}
2175 \label{fig:remote}
2176\end{figure}
2177
2178We 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}.
2179
2180\subsection{Serving a site using soap}
2181
2182A script has been created to setup a SOAP server for a site. On Linux, from the gsdl3 directory, run
2183\gst{./gs3-soap-deploy-site.sh <sitename> <siteuri>}
2184
2185Sitename is the name of the site's directory, e.g. localsite. The siteuri is the identifier that will be used for the SOAP resource, e.g. org.greenstone.localsite. It should be a unique name amongst all the SOAP services that you want to connect to.
2186
2187The script deploys the service for the site specified. A resource file (\gst{sitename.xml}) is created which is used to specify the service. It can be found in \gst{gsdl3/resources/soap}, and is generated from \gst{site.xml.in}.
2188
2189To get siteA to talk to siteB, you need to deploy a SOAP server on siteB, then add a \gst{<site>} element to the \gst{<siteList>} of siteA's \gst{siteConfig.xml} file (in \gst{gsdl3/web/sites/siteA/siteConfig.xml}).
2190
2191In the \gst{<siteList>} element, add the following (substituting the chosen site uri for siteAuri):
2192
2193\begin{gsc}\begin{verbatim}
2194<site name="siteAuri"
2195 address="http://localhost:8080/soap/servlet/rpcrouter"
2196 type="soap"/>
2197\end{verbatim}\end{gsc}
2198
2199(Note that localhost and 8080 should be changed to the values you entered when installing \gsiii).
2200
2201\appendix
2202
2203\newpage
2204\section{Using \gsiii\ from CVS}\label{app:cvs}
2205
2206[TODO: need to make sure building stuff is in here]
2207
2208\gsiii\ is also available via CVS. You can download the latest version of the code. This is not guaranteed to be stable, in fact it is likely to be unstable. The advantage of using CVS is that you can update the code and get the latest fixes.
2209
2210Note that you will need the Java 2 SDK, version 1.4.0 or higher.
2211
2212To check out the \gs\ code, use:
2213
2214\begin{quote}\begin{gsc}\begin{verbatim}
2215cvs -d :pserver:cvs\_anon@cvs.scms.waikato.ac.nz:2402/usr/local/
2216 global-cvs/gsdl-src co -P gsdl3
2217\end{verbatim}\end{gsc}\end{quote}
2218
2219If 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.
2220
2221The 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.
2222
2223To install Greenstone once you have checked it out of CVS, do the following (alternatives for Linux or Windows):
2224
2225\begin{quote}\begin{gsc}
2226cd gsdl3\\
2227./gs3-install.sh or gs3-install\\
2228source gs3-setup.sh or gs3-setup
2229\end{gsc}\end{quote}
2230
2231To recompile the code at any stage, you can use
2232\begin{quote}\begin{gsc}
2233source gs3-setup.sh or gs3-setup\\
2234make\\
2235make install\\
2236\end{gsc}\end{quote}
2237
2238Note: \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.
2239
2240To startup or shutdown the library (includes the Tomcat server and MYSQL server), the commands are (run from the gsdl3 directory):
2241\begin{quote}\begin{gsc}
2242./gs3-launch.sh or gs3-launch \\
2243./gs3-launch.sh -shutdown or close the window
2244\end{gsc}\end{quote}
2245
2246
2247\newpage
2248\section{Tomcat}\label{app:tomcat}
2249
2250Tomcat is a servlet container. It is used to serve a \gs\ site using a servlet.
2251
2252The file \gst{\gsdlhome/comms/jakarta/tomcat/conf/server.xml} is the Tomcat configuration file. The installation process adds a context for \gsiii\ servlets (\gst{\gsdlhome/web})---this tells Tomcat where to find the web.xml file, and what URL (\gst{/gsdl3}) to give it. Anything inside the context directory is accessible via Tomcat\footnote{can we use .htaccess files to restrict access??}. For example, the index.html file that lives in \gst{\gsdlhome/web} can be accessed through the URL \gst{localhost:8080/gsdl3/index.html}. The demo collection's images can be accessed through \\
2253\gst{localhost:8080/gsdl3/sites/localsite/collect/demo/images/}.
2254
2255
2256Tomcat runs by default on port 8080---this can be changed in server.xml, in the \begin{quote}\begin{gsc}
2257<!-- Define a non-SSL Coyote HTTP/1.1 Connector on port 8080 -->\\
2258<Connector>
2259\end{gsc}\end{quote}
2260 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.
2261
2262Note: Tomcat must be shutdown and restarted any time you make changes in the following for those changes to take effect:
2263\begin{bulletedlist}
2264\begin{gsc}
2265\item \gsdlhome/web/WEB-INF/web.xml
2266\item \gsdlhome/comms/jakarta/tomcat-tomcat-4.0.1/conf/server.xml
2267\end{gsc}
2268\item any classes or jar files used by the servlets
2269\end{bulletedlist}
2270\noindent Note: stdin and stdout for the servlets both go to\\
2271\gst{\gsdlhome/comms/jakarta/tomcat/logs/catalina.out}
2272
2273On 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.
2274
2275We 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}:
2276
2277\begin{quote}\begin{gsc}
2278<Context path="/gsdl3" docBase="\$GSDL3HOME/web" debug="1" \\
2279reloadable="true">\\
2280 <Resources allowLinking='true'/>\\
2281</Context>\\
2282\end{gsc}\end{quote}
2283
2284We 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}):
2285
2286In the default servlet definition, change the 'listings' parameter to true.
2287
2288Tomcat 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 \\
2289\gst{\$GSDL3HOME/comms/jakarta/tomcat/conf/server.xml}. For the default manager, session information is stored in the work directory:\\
2290\gst{\$GSDL3HOME/comms/jakarta/tomcat/work/Standalone/localhost/gsdl3/SESSIONS.ser}. Delete this file to clear the cached session info. Note that Tomcat needs to be shutdown to delete this file.
2291
2292\subsection{Proxying Tomcat with apache}
2293
2294Instead of incorporating servlet support into your existing web server, an easy alternative is to proxy Tomcat. The \gst{http://www.greenstone.org/greenstone3} site uses apache to proxy Tomcat. ProxyPass and ProxyPassReverse directives need to be added to the Virtualhost description for the www.greenstone.org server.
2295
2296\begin{quote}\begin{gsc}
2297<VirtualHost xx.xx.xx.xx>\\
2298ServerName www.greenstone.org\\
2299...\\
2300ProxyPass /greenstone3 http://puka.cs.waikato.ac.nz:8080/gsdl3\\
2301ProxyPassReverse /greenstone3 http://puka.cs.waikato.ac.nz:8080/gsdl3\\
2302</VirtualHost>\\
2303\end{gsc}\end{quote}
2304
2305In our example, the \gsiii\ servlet can be accessed at \\
2306\gst{http://www.greenstone.org/greenstone3/library}, instead of at \\
2307\gst{http://puka.cs.waikato.ac.nz:8080/gsdl3/library}, which is not publically accessible.
2308
2309\subsection{Running Tomcat behind a proxy}
2310
2311Almost everything works fine when Tomcat is running behind a proxy. The only time this causes trouble is if the servlet itself needs to make external http connections. We do this in the infomine demo collection for example. One of the service classes sends http requests to the infomine database at riverside. Since this is going through the proxy, a username and password is needed. It is not sufficient to prompt the user for a password because they are unlikely to have a password for the particular proxy that Tomcat is using. What we have done at present is to put a proxy element in the siteConfig.xml file. Here you have to enter a suitable username and password for the proxy server. Unfortunately these are entered in plain text. And the file is viewable via the servlet. So we need a better solution.
2312
2313\newpage
2314\section{SOAP}\label{app:soap}
2315
2316Grenstone 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:
2317
2318\begin{quote}\begin{gsc}
2319gs3-enable-soap.[sh/bat]
2320\end{gsc}\end{quote}
2321
2322All this does is to rename the SOAP web.xml.disabled file to web.xml.
2323
2324The 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.
2325
2326To deploy a SOAP service for other sites, run
2327\begin{quote}\begin{gsc}
2328gs3-soap-deploy-site.[sh/bat] <sitename> <siteURI>
2329\end{gsc}\end{quote}
2330
2331This 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:
2332
2333\begin{gsc}\begin{verbatim}
2334java org.apache.soap.server.ServiceManagerClient
2335 http://localhost:8080/soap/servlet/rpcrouter deploy
2336 resources/soap/<sitename>.xml
2337\end{verbatim}\end{gsc}
2338
2339You can also deploy a service through the website. If Tomcat is not running, start it up.
2340
2341The 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.
2342
2343To deploy the SOAPServer for siteX:
2344
2345Click on ``deploy'' and edit the following fields in the deploy form:
2346
2347\begin{tabular}{ll}
2348ID: & <URI for siteX>\\
2349Scope: (choose Session & Request---new instantiation for each request\\
2350 or Application) & Session---same instantiation across a session\\
2351 & Application---only uses one instantiation\\
2352Methods: &process\\
2353Java Provider / Provider Class: & org.greenstone.gsdl3.SOAPServersiteX\\
2354\end{tabular}
2355
2356Now 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.
2357
2358Information about deployed services is maintained between Tomcat sessions---you only need to deploy it once.
2359
2360\subsection{Debugging SOAP}\label{app:soap-debug}
2361
2362If you need to debug the SOAP stuff for some reason, or just want to look at the SOAP messages that are being passed back and forth, use a program called TcpTunnelGui. This intercepts messages coming in to one port, displays them, and passes them to another port.
2363To run it, type:
2364
2365\begin{quote}\gst{java org.apache.soap.util.net.TcpTunnelGui 8070 localhost 8080}
2366\end{quote}
2367
23688070 is the port that TcpTunnelGui listens on, and 8080 is the port that it sends the messages onto---the port that Tomcat is using. You need to modify \gs\ to talk to port 8070 when it wants to talk to Tomcat, so that the messages go through TcpTunnelGui. This is specified in the \gst{<site>} element of the gateway site configuration file (\gst{\gsdlhome/web/sites/gateway/siteConfig.xml}).
2369\begin{quote}\begin{gsc}\begin{verbatim}
2370<site name="org.greenstone.localsite"
2371 address="http://localhost:8080/soap/servlet/rpcrouter"
2372 type="soap"/>
2373\end{verbatim}\end{gsc}\end{quote}
2374
2375Note that \gst{http://localhost:8080/soap/servlet/rpcrouter} is the
2376address for talking to the Tomcat SOAP servlet services.
2377
2378
2379\newpage
2380\section{Tidying up the formatting for imported Greenstone 2 collections}\label{app:gs2tidy}
2381
2382\subsection{Format statements: \gsii\ vs \gsiii\ }\label{app:gs2format}
2383The following table shows the \gsii\ format elements, and their equivalents in \gsiii\
2384\begin{table}[h]
2385\caption{\gsiii\ equivalents of \gsii\ format statements}
2386{\footnotesize
2387\begin{tabular}{ll}
2388\hline
2389\bf \gsii\ & \bf \gsiii\ \\
2390\hline
2391\gst{[Text]} & \gst{<gsf:text/>} \\
2392\gst{[num]} & \gst{<gsf:metadata name='docnum'/>}\\
2393\gst{[link][/link]} & \gst{<gsf:link></gsf:link>} or \\
2394& \gst{<gsf:link type='document'></gsf:link>}\\
2395\gst{[srclink][/srclink]} & \gst{<gsf:link type='source'></gsf:link>}\\
2396\gst{[icon]} & \gst{<gsf:icon/>} or \\
2397& \gst{<gsf:icon type='document'/>}\\
2398\gst{[srcicon]} & \gst{<gsf:icon type='source'/>}\\
2399\gst{[Title]} (metadata) & \gst{<gsf:metadata name='Title'/>} or \\
2400& \gst{<gsf:metadata name='Title' select='current'/>}\\
2401\gst{[parent:Title]} & \gst{<gsf:metadata name='Title' select='parent' />}\\
2402\gst{[parent(All):Title]} & \gst{<gsf:metadata name='Title' select='ancestors'/>}\\
2403\gst{[parent(Top):Title]} & \gst{<gsf:metadata name='Title' select='root' />}\\
2404\gst{[parent(All': '):Title]} & \gst{<gsf:metadata name='Title' select='ancestors'}\\
2405& \gst{ separator=': ' />}\\
2406\gst{[sibling(All': '):Title]} & \gst{<gsf:metadata name='Title' multiple='true'} \\
2407& \gst{ separator=': ' />}\\
2408\gst{\{Or\}\{[dc.Title],} & \gst{<gsf:choose-metadata>}\\
2409\gst{ [dls.Title], [Title]\}}& \gst{ <gsf:metadata name='dc.Title'/>}\\
2410& \gst{ <gsf:metadata name='dls.Title'/>}\\
2411& \gst{ <gsf:metadata name='Title'/>}\\
2412& \gst{</gsf:choose-metadata>}\\
2413\gst{\{If\}\{[parent:Title],} & \gst{<gsf:choose-metadata>}\\
2414\gst{ [parent:Title], [Title]\}}& \gst{ <gsf:metadata name='Title' select='parent'/>}\\
2415& \gst{ <gsf:metadata name='Title'/>}\\
2416& \gst{</gsf:choose-metadata>}\\
2417\gst{\{If\}\{[Subject],} & \gst{<gsf:switch>}\\
2418\gst{ <td>[Subject]</td>\}}& \gst{ <gsf:metadata name='Subject'/>}\\
2419& \gst{ <gsf:when test='exists'>} \\
2420& \gst{ <td><gsf:metadata name='Subject'/></td>}\\
2421& \gst{ </gsf:when></gsf:switch>}\\
2422\hline
2423\end{tabular}}
2424\end{table}
2425\subsection{Cleaning up macros}\label{app:gs2replace}
2426
2427Here we show some of the replace items that have been used for Greenstone 2 collections.
2428
2429Getting rid of silly backslashes:
2430\begin{gsc}\begin{verbatim}
2431<replace scope='text' macro="\\?\\\(" text="\("/>
2432\end{verbatim}\end{gsc}
2433
2434Macro resolving using resource bundles and metadata:
2435\begin{gsc}\begin{verbatim}
2436<replace scope='metadata' macro="_magazines_" bundle="NZDLMacros"
2437 key="Magazines"/>
2438<replace scope='all' macro='_thisOID_' metadata='archivedir'/>
2439<replace macro="_httpcollimg_"
2440 text="sites/localsite/collect/folktale/index/assoc"/>
2441\end{verbatim}\end{gsc}
2442
2443Fixing up broken external links:
2444\begin{gsc}\begin{verbatim}
2445<replace macro="_httpextlink_&amp;rl=1&amp;href="
2446 text="?a=d&amp;c=folktale&amp;s0.ext=1&amp;d="/>
2447<replace macro="_httpextlink_&amp;rl=0&amp;href="
2448 text="?a=p&amp;sa=html&amp;c=folktale&amp;url="/>
2449\end{verbatim}\end{gsc}
2450
2451These two examples show how to deal with Greenstone 2's external link macros. The first one is for a 'relative' external link. In this case, the links are like URL's but they actually refer to Greenstone internal documents. So the Greensotne 3 link is to the document, but with parameter s0.ext signifying that the d argument will need translating before retrieving the content.
2452The second example is a truly external link. This is translated into a html type page action, where the url is presented as a frame along with the collection header in a separate frame.
2453
2454Sometimes we need to add in macros to be resolved in a second step:
2455\begin{gsc}\begin{verbatim}
2456<replace macro="_iconpdf_" scope="metadata"
2457 text="&lt;img title='_texticonpdf_' src='interfaces/default/images/ipdf.gif'/&gt;"/>
2458<replace macro="_texticonpdf_" scope="metadata" bundle="interface_classic"
2459 key="texticonpdf"/>
2460\end{verbatim}\end{gsc}
2461
2462\end{document}
Note: See TracBrowser for help on using the repository browser.