Table of Contents

Greenstone 3 Web services and servlets

Servlets

The standard method of running Greenstone3 is as a Java servlet. There are several different classes of servlets in GS3 – and you can also create your own – but the most important is the class for libraries. In Greenstone3, a library is the combination of a site (which contains mostly content) and an interface (which contains presentation information). Servlets are defined in the web.xml file located in Greenstone3 → web → WEB-INF.

The table below presents some of the important servlet parameters and descriptions.

Servlets Parameters
ParameterDescription
servlet-name Name of the servlet. Only used in the web.xml file. Each servlet needs a unique name, and this name must be the same for both the <servlet> and the corresponding <servlet-mapping>
servlet-class The servlet's class (i.e. the type of servlet). The class for Greenstone3 libraries is org.greenstone.gsdl3.LibraryServlet.
descriptionA description of the servlet.
library_nameThe name of the library, which is this specific combination of site and interface. Greenstone3 uses this value to build the url, so this must match the value of the url-pattern.
site_name The name of the site to use. This must be a name of one of the folders in Greenstone3/web/sites. (The default site is localsite.)
interface_name The name of the interface to use. This must be a name of one of the folders in Greenstone3/web/interfaces. (The default interface is default.)
receptionist_class
default_lang The default language of the servlet. (Use en for English.)
url-pattern Specifies the url path to the servlet, i.e. the library. Since Greenstone3 actually uses the library_name value to build the url, not this value, the value of library_name must match the value of the url-pattern.
SOAPMonitorPort

There are two parts to defining a new servlet. In the first part, you supply parameter values (this library is called mylibrary and uses the localsite and an interface called althor):

	<servlet>
		<servlet-name>mylibrary</servlet-name>
		<description>My new GS3 interface</description>
		<servlet-class>org.greenstone.gsdl3.LibraryServlet</servlet-class>
		<init-param>
			<param-name>library_name</param-name>
			<param-value>mylibrary</param-value>
		</init-param>
		<init-param>
			<param-name>site_name</param-name>
			<param-value>localsite</param-value>
		</init-param>
		<init-param>
			<param-name>interface_name</param-name>
			<param-value>althor</param-value>
		</init-param>
		<init-param>
			<param-name>receptionist_class</param-name>
			<param-value>DefaultReceptionist</param-value>
		</init-param>
		<init-param>
			<param-name>default_lang</param-name>
			<param-value>en</param-value>
		</init-param>
	</servlet>


Then, you supply the relative URL where the servlet (in this case the library) will be located:

    <servlet-mapping>
	<servlet-name>mylibrary</servlet-name>
	<url-pattern>/mylibrary/*</url-pattern>
    </servlet-mapping>

In this example – assuming default settings have not been changed – the library would be be located at localhost:8383/greenstone3/mylibrary.

A few things to remember when defining new servlets:

  • the interface must be located in Greenstone3 → web → interfaces
  • the site must be located in Greenstone3 → web → sites
  • if your Greenstone3 server is already running, you must restart the server before any changes will take effect

Web services

  • There is an example client-application created to make use of Greenstone's "Query, Browse and Retrieve" (QBR) web services. This client-application can be obtained by downloading one of the two compressed files from here