====== Greenstone 3 Web services and servlets======


===== Servlets =====
The standard method of running Greenstone3 is as a [[http://www.oracle.com/technetwork/java/index-jsp-135475.html|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 [[en:user:sites|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 [[en:user:interfaces|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//):



<code xml>
	<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>
</code>

\\

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


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

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: 
    * [[http://trac.greenstone.org/browser/other-projects/gs3-webservices-java-client/trunk/docs/HowToFiles/7BasicsOfWritingWebServices.html?format=raw|Basics of Writing web services]]
    * [[http://trac.greenstone.org/browser/other-projects/gs3-webservices-java-client/trunk/docs/HowToFiles/6WritingAWebServiceClient.html?format=raw|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  [[http://trac.greenstone.org/browser/other-projects/trunk/gs3-webservices-democlient/dist|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:
    * [[http://trac.greenstone.org/browser/other-projects/gs3-webservices-java-client/trunk/docs/HowToFiles/0InstallDemoClientInBrief.html?format=raw|Installing the demo client]]
    * [[http://trac.greenstone.org/browser/other-projects/gs3-webservices-java-client/trunk/docs/HowToFiles/1GettingGS3WebServicesRunning.html?format=raw|Getting the QBR services running]]
    * [[http://trac.greenstone.org/browser/other-projects/gs3-webservices-java-client/trunk/docs/HowToFiles/2RunningGS3DemoClientWithGs3.html?format=raw|Running the demo client]]