Changeset 7635


Ignore:
Timestamp:
2004-06-23T16:43:16+12:00 (20 years ago)
Author:
kjdon
Message:

* empty log message *

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/gsdl3/docs/manual/manual.tex

    r6930 r7635  
    379379The 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 pages and preference pages. All the available services are arrayed along a navigation bar, along the bottom of the banner. Clicking on a name accesses that service.
    380380
    381 Search type services generally provide a form to fill in, with parameters including what field or granularity to index, 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 results list takes you to the document itself.
     381Search 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.
    382382
    383383Once 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.
    … …  
    391391\subsection{Building a collection}\label{sec:buildcol}
    392392
    393 There are two ways to get a new collection into \gsiii\ . The first is to build it using the \gsiii\  building process. The second way is to import a \gsii\  collection.
     393There 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 build process. The third way is to import a pre-built \gsii\  collection.
    394394
    395395Collections 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 \$GSDL3HOME/web/sites/site-name/collect, where site-name is the name of the site you want your new collection to belong to.
    396396
    397 The following two sections describe how to create a collection from scratch, 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{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.
     397The 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{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.
    398398
    399399
    400400\subsubsection{Creating a collection from scratch}
    401401
    402 Building \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: including what documents appear in the collection, how they are indexed for searching, which classifications are used for browsing, etc.
    403 
    404 Firstly, 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.
     402Building 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.
     403
     404Firstly, 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.
    405405[TODO: describe the kinds of documents that can be added, something about METS files?]
    406406
    407 Metadata 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, file will be selected.  The filename tag encloses the regular expression as text, eg:
     407Metadata 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, eg:
    408408
    409409\begin{gsc}\begin{verbatim}
    … …  
    413413This 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 the existing value of the metadata item will be deleted.
    414414
    415 A sample \gst{metadata.xml} file can be found in the gs3test collection.  However, here is an example fragment of that \gst{metadata.xml} file:
    416 
     415\begin{figure}
    417416\begin{gsc}\begin{verbatim}
    418 <FileSet>
    419   <FileName>ec160e</FileName>
    420   <Description>
    421     <Metadata name="Title">The Courier - No.160 - Nov - Dec 1996 -
    422        Dossier Habitat - Country reports: Fiji , Tonga (ec160e)</Metadata>
    423     <Metadata mode="accumulate" name="Language">English</Metadata>
    424     <Metadata mode="accumulate" name="Subject">Settlements and housing:
    425       general works incl. low- cost housing, planning techniques, surveying,
    426       etc.</Metadata>
    427     <Metadata mode="accumulate" name="Subject">The Courier ACP 1990 - 1996
    428       Africa-Caribbean-Pacific - European Union</Metadata>
    429     <Metadata mode="accumulate" name="Organization">EC Courier</Metadata>
    430     <Metadata mode="accumulate" name="AZList">T.1</Metadata>
    431   </Description>
    432 </FileSet>
     417<?xml version="1.0" encoding="UTF-8"?>
     418<!DOCTYPE DirectoryMetadata SYSTEM "http://greenstone.org/dtd/DirectoryMetadata/1.0/DirectoryMetadata.dtd">
     419<DirectoryMetadata>
     420  <FileSet>
     421    <FileName>ec160e</FileName>
     422    <Description>
     423      <Metadata name="Title">The Courier - No.160 - Nov - Dec 1996 -
     424         Dossier Habitat - Country reports: Fiji , Tonga (ec160e)</Metadata>
     425      <Metadata mode="accumulate" name="Language">English</Metadata>
     426      <Metadata mode="accumulate" name="Subject">Settlements and housing:
     427        general works incl. low- cost housing, planning techniques, surveying,
     428        etc.</Metadata>
     429      <Metadata mode="accumulate" name="Subject">The Courier ACP 1990 - 1996
     430        Africa-Caribbean-Pacific - European Union</Metadata>
     431      <Metadata mode="accumulate" name="Organization">EC Courier</Metadata>
     432      <Metadata mode="accumulate" name="AZList">T.1</Metadata>
     433    </Description>
     434  </FileSet>
     435  <FileSet>
     436    <FileName>b22bue</FileName>
     437    <Description>
     438      <Metadata name="Title">Butterfly Farming in Papua New Guinea (b22bue)</Metadata>
     439      <Metadata mode="accumulate" name="Language">English</Metadata>
     440      <Metadata mode="accumulate" name="Subject">Other animals (micro-livestock, little known animals, silkworms, reptiles, frogs, snails, game, etc.)</Metadata>
     441      <Metadata mode="accumulate" name="Organization">BOSTID</Metadata>
     442      <Metadata mode="accumulate" name="AZList">T.1</Metadata>
     443      <Metadata mode="accumulate" name="Keyword">start a butterfly farm</Metadata>
     444    </Description>
     445  </FileSet>
     446</DirectoryMetadata>
    433447\end{verbatim}\end{gsc}
    434 
    435 Here, only one file pattern is found in the file set.  However, the \gst{Description} tag contains a number of separate metadata items.  Note that the \gst{Title} metadata does not have the mode=accumulate attribute.  This means that when the title is assigned to a document, its existing \gst{Title} information will be lost.
     448\caption{Sample metadata.xml file}
     449\label{fig:metadatafile}
     450\end{figure}
     451
     452Figure~\ref{fig:metadatafile} shows an example metadata.xml file.
     453Here, 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 mode=accumulate attribute.  This means that when the title is assigned to a document, its existing \gst{Title} information will be lost.
    436454
    437455The 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.
    438456
     457An 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, eg Title, Author etc.
     458
    439459The collectionConfig.xml file controls the all of these options for collection building, and the format is described in Section~\ref{sec:collconfig}.
    440460
    441 If a collectionConfig.xml file is not found, the \gsiii\  build process will import and use options, wherever possible, from a \gsii\  \gst{collect.cfg} file.  However, it is strongly recommended that a proper \gst{collectionConfig.xml} file is used wherever possible. [NOTE: I think we should require a proper config file for gs3  building--kjdon]
    442 
    443 To build a collection, execute \gst{gs3build.sh 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} will start up the mysql server as well as tomcat.
     461To 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 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} will start up the mysql server as well as tomcat.
    444462
    445463Once 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.
    … …  
    447465[TODO: need to describe namespaces somewhere? ]
    448466
     467\subsubsection{Using the Librarian Interface}
     468
     469[TODO: check that this is true with the new installer]
     470
     471The 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 .. menu in the Program Files section of the Start menu. On linux, run ./gli4gs3.sh from the gsdl3/gli directory.
     472
     473Currently, 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.
     474
     475The GLI for \gsiii\ has a couple of new configuration parameters: site and servlet. It operates using one site---you can edit, delete, create new collections within a single 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}.
     476
     477Collection building using the GLI will use the \gsii\ perl scripts and plugins. At the conclusing 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).
     478 
     479Detailed instructions about using the GLI can be found in Sections 3.1 and 3.2 of the Greenstone 2 User's Guide. This can be found in your \gsii\ installation, or in... if you have installed the ... installer.
     480
     481
    449482\subsubsection{Importing a \gsii\  collection}
    450483
    451 \gsiii\  can also serve \gsii\  collections. If you have a \gsii\  collection\footnote{For information about the \gsii\  software, and how to build collections using it, visit \gst{www.greenstone.org}}, you can copy it into the collect directory of the site you are using. Or make a link to it from the collect directory if your OS supports that.
     484
     485Pre-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).
    452486The \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.
    453487
    454 The conversion script is \gst{convert\_coll\_from\_gs2.pl}. To run it, make sure you have run \gst{source setup.bash} (or run 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,
     488The 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,
    455489
    456490\begin{gsc}
    … …  
    468502
    469503Each 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
    470 collection.\footnote{\gst{collectionConfig.xml} and \gst{buildConfig.xml} replace \gst{collect.cfg} and \gst{build.cfg} in
    471 \gsii.}  The first includes user-defined presentation metadata for the collection,
     504collection.\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,
    472505such as its name and the {\em About this collection} text; gives formatting information for the collection display; and also gives
    473506instructions on how the collection is to be built.  The second is produced by
    … …  
    536569  </search>
    537570  <browse>
    538     <classifier name="CL1"/>
    539     <classifier name="CL2"/>
    540     <classifier name="CL3"/>
    541     <classifier name="CL4">
     571    <classifier name="CL1" type="AZList" horizontalAtTop='true'>
     572      <field>Title</field>
     573      <sort>Title</sort>
     574      <displayItem name='name' lang='en'>Titles</displayItem>
     575    </classifier>
     576    <classifier name="CL2" type="Hierarchy">
     577      <field>Organization</field>
     578      <sort>Title</sort>
     579      <displayItem name='name' lang='en'>Organizations</displayItem>
     580      <file URL="/research/kjdon/home/gsdl3/web/sites/localsite/collect/
     581         gs3test/etc/org.xml"/>
     582    </classifier>
     583    <classifier name="CLKeyword" type="Hierarchy">
     584      <field>Keyword</field>
     585      <sort>Title</sort>
     586      <displayItem name='name' lang='en'>HowTo</displayItem>
     587      <file URL="/research/kjdon/home/gsdl3/web/sites/localsite/collect/
     588         gs3test/etc/keyword.xml"/>
    542589      <format>
    543590        <gsf:template match="documentNode">
    … …  
    557604The \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.
    558605 
    559 The \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.)
     606The \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.)
    560607
    561608Search 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. 
    … …  
    595642Moving 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''. 
    596643
    597 The 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 will be described later - it will vary 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.
     644The 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.
     645
     646Figure~\ref{fig:hierarchyfile} shows the format of the file for a Hierarchy classifier. [TODO add a  description]
     647\begin{figure}
     648\begin{gsc}\begin{verbatim}
     649<Hierarchy>
     650  <Classification>
     651    <Name>ACCU</Name>
     652    <Path>1</Path>
     653    <Description>ACCU</Description>
     654  </Classification>
     655  <Classification>
     656    <Name>Agenda 21</Name>
     657    <Path>2</Path>
     658    <Description>Agenda 21</Description>
     659  </Classification>
     660  <Classification>
     661    <Name>FAO</Name>
     662    <Path>3</Path>
     663    <Description>FAO</Description>
     664    <Children>
     665      <Classification>
     666        <Name>FAO Better Farming series</Name>
     667        <Path>3.1</Path>
     668        <Description>FAO Better Farming Series</Description>
     669      </Classification>
     670    </Children>
     671  </Classification>
     672</Hierarchy>
     673\end{verbatim}\end{gsc}
     674\caption{Sample Hierarchy classifier file}
     675\label{fig:hierarchyfile}
     676\end{figure}
    598677
    599678Inside 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.
    … …  
    886965Format 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.
    887966
    888 The 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 ad a new language translation of an interface.
     967The 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.
    889968
    890969\subsubsection{Modifying an existing interface}
    … …  
    9321011\subsection{Overview of modules??}
    9331012
    934 A \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.
     1013A \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. There is a one-to-one correspondance 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.
    9351014
    9361015\begin{figure}[t]
    … …  
    9471026Functionally Collection and ServiceCluster are very similar, but conceptually, and to the user, they are quite different.
    9481027
    949 {\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 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. Services provide the core functionality for the system, e.g. searching, retrieving documents, building collections etc.
     1028{\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. Services provide the core functionality for the system, e.g. searching, retrieving documents, building collections etc.
    9501029
    9511030{\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.
    … …  
    9701049the Receptionist, not with the MessageRouter.
    9711050
    972 The Receptionist reads in the \gst{interfaceConfig.xml} file, 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.
     1051The 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.
    9731052If the Receptionist is a TransformingReceptionist, a mapping between shortnames  and XSLT file names is also created.
    9741053
    975 The MessageRouter reads in its site configuration file \gst{siteConfig.xml}. 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 what get returned in response to a describe request (see Section~\ref{sec:describe}.).
     1054The 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 what get returned in response to a describe request (see Section~\ref{sec:describe}.).
    9761055Each 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.
    9771056ServiceClusters 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.
    978 For 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-sites commands must be sent (see next section).
     1057For 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-sites commands must be sent (see Section~\ref{sec:runtime-config}).
    9791058
    9801059The MessageRouter also looks inside the site's \gst{collect} directory, and  loads up a Collection object for each valid collection found.
    … …  
    9851064Collection objects are added to the module map with their name as a key, and also a collection element is added into the collectionList XML.
    9861065
    987 
    988 
    9891066\subsection{Message passing}
    9901067
    991 Action in \gsiii\  is originated by a request coming in from the outside. In the standard web-based \gs\ , this comes from a servlet 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 to the request. Messages inside the system 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.
    992 
    993 When a page request comes in to the Receptionist, it looks at the action attribute to determine which action to send it to. The response is returned from the action.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 servlet \gs\  we transform using XSLT to generate html pages which get returned to the servlet.
     1068There 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. 
     1069Action in \gsiii\  is originated by a request coming in from the outside. In the standard web-based \gs\ , this comes from a servlet 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 to the request.
     1070
     1071Messages 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 individual, 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.
     1072
     1073When a page request comes in to the Receptionist, it looks at the action attribute to determine which action to send it to. The response is returned from the action. 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 servlet \gs\  we transform using XSLT to generate html pages which get returned to the servlet.
    9941074
    9951075Actions 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
    … …  
    10051085These are the special 'external'-style messages. Requests originate from outside \gs\ , for example from a servlet, or java application. They 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.
    10061086
    1007 Here are some examples of  requests\footnote{In a servlet context, these correspond to the URLs \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}.}:
     1087Here 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}.}:
    10081088
    10091089\begin{quote}\begin{gsc}\begin{verbatim}
Note: See TracChangeset for help on using the changeset viewer.