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
Parameter	Description
`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`.
`description`	A description of the servlet.
`library_name`	The 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

General Help in writing web services:
- Basics of Writing web services
- Writing a web services client

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

The following documents explain how to get your Greenstone's QBR web services running and how to run the demo client-application against them:

Greenstone Wiki

Table of Contents

Greenstone 3 Web services and servlets

Servlets

Web services