Log in Help
Print
Home 〉 projects 〉 neon 〉 gas.html
 

GATEService (aka GaS)

A GATEService is defined here as a pipeline of GATE PR's which is available via a WebService. In the GLEAM architecture, it is called from an Executive. A GATEService can be a front-end to a set of GATE engines running on different servers in order to gain in scalability. The configuration of the GATEService will specify this behaviour. It is transparent to the external user of the GATEService how many machines are actually used to produce an annotation.

A GaS can declare required and optional parameters whose values are provided by the caller. The parameter values are mapped onto either feature values on the document being processed by the embedded GATE PRs, or runtime parameter values of the various PRs that make up the application. The mapping is defined in a service definition, an XML file supplied by the GaS creator:

<parameters>
  <param name="depth">
    <runtimeParameter prName="MyAnnotator" prParam="maxDepth" />
  </param>
  <param name="annotatorName">
    <documentFeature name="annotator" />
  </param>
</parameters>

Parameter values are all strings, but when mapping to PR parameters the usual GATE Resource.setParameterValue() is used, which can convert strings into other types (e.g. URL, Integer, etc.).

The service definition also specifies what annotation sets the service requires as input and populates as output:

<annotationSets>
  <annotationSet name="Original markups" in="true" />
  <annotationSet name="" out="true" />
  <annotationSet name="Key" in="true" out="true" />
</annotationSets>

Note that a service can use the same set for both input and output, and can use the default annotation set (the second example above).

The traditional GATE environment will have a plugin to connect to a GATEService as to a normal GATE Application, in that case a GATEService should be able to take as input the content of a document and not only a reference to it in a DocumentService. The GaS parameters would translate to runtime parameters on the GATEServicePR.

Therefore we can distinguish 2 types of Gas :

1.0.1. GATE mode

In this mode the GaS behaves roughly like a current GATE application, i-e it takes a document and a set of parameters as input and returns a modified document. This mode is required in order to incorporate a GaS in a GATE application, like any other PR.

1.0.2. Remote DataStore

In this mode a GaS does not expect the document as input but only a task, i-e the location of a document on a remote DocService, taskID, location of an executive service and a set of parameter values. When the document is annotated (or processing fails), the GaS communicates directly to the executive to tell it that the task is complete (or failed). This mode is required in GLEAM.

A new functionality should be created in GATE in order to be able to generate a simple service deployment (with everything running on a single server) with a couple of clicks. The result of this operation will be a WAR file, ready to be unpacked in a web application server. If you need a more advanced deployment, e.g. on a cluster, then more administrative intervention will be required.

2. Web-Service interface

A GATEService has the following query operations (returning string arrays):

The main meat of the service is in the following two operations:

processDocument provides the "GATE mode" described above:

XMLcontent : a GATE document in GATE XML format. This is expected to contain at least the annotation sets required as input by the service.

parameters : an array of name/value pairs giving String values for the parameters expected by this GaS. It is an error if the parameter list does not specify a value for each required parameter name, though the value specified may be null.

It returns an array of name/value pairs where the name is an annotation set name and the value is the XML representation of that annotation set (as per DocumentStaxUtils.writeAnnotationSet), one entry per output annotation set name (possibly zero if, for example, the service is training a classifier and doesn't need to return any output). It is expected that the caller would replace the content of each annotation set on the original document with the content returned from the service.

processRemoteDocument provides the "GLEAM mode":

execLocation : a URL (xsd:anyURI) giving the location of the executive which should be informed when the process completes (successfully or unsuccessfully)

taskID : task identifier that identifies this task to an Executive.

dsLocation : a URL giving the location of the document service in which the document to be processed resides.

docID : the ID of the document in the doc service.

parameters : as above

asMappings : an array of name/value pairs mapping the annotation sets expected by the GaS to annotation sets on the document in the doc service. A mapping is required for each input and output annotation set name the service uses. It is permitted for the same doc-service annotation set name to map to more than one GaS asName, but there is no guarantee as to the order in which output sets are written back to the doc service, so don't map two output sets onto the same set in the doc service. The purpose of this mapping is to allow the same service to operate over different annotation sets, for example the results of different human annotators.

processRemoteDocument does not return anything directly - the success or failure of the operation is communicated out-of-band to the executive.

3. Detailed User Guide

This section is copied from safe/gate-service/server/doc/userguide.yam.

3.1. Architecture

The GATE Service platform consists of two principal components:

The two sides communicate using the Java Messaging System (JMS), a framework for reliable messaging between (possibly distributed) Java components. The standard implementation uses Apache ActiveMQ as the message broker, but the code is not tied to any particular JMS provider.

In the simplest (and probably most frequent) case, the endpoint, messge broker and the workers can run in the same JVM, but it is also possible to run each component separately, either in several JVMs on the same physical machine, or distributed over the network. If a particular service is heavily loaded it is a simple matter to add extra worker nodes to spread the load, and workers can be added or removed dynamically without needing to shut down the web service.

The configuration and wiring together of these components is handled using the Spring framework. A number of standard configurations are available but with a little knowledge of Spring you can wire together complex combinations of workers and endpoints in a few XML files.

3.2. Defining a GATE Service

The Java code making up the GaS is completely generic and will work for any GATE application you wish to expose as a service. A specific service is configured with two files, first the .xgapp file defining the pipeline as produced by saving the application state from GATE, and second a service definition defining the input and output annotation sets required by the service and any parameters the service takes. These files are described in this section.

3.2.1. The saved application state

The GATE pipeline run by a service is typically defined by an .xgapp file, created in the GATE GUI using "Save application state"If you are a Spring guru it is technically possible to define the application in other ways. The application should be fully configured before saving, i.e. all required runtime parameters should be set (except possibly those that will be mapped to required service parameters, as described in the next section).

The saved application should be as self-contained as possible, i.e. the plugins used by the application should be in subdirectories under the saved application location. This is particularly important when the service is to be run in all-in-one mode, as read permission on parent directories may be restricted by the servlet container.

3.2.2. The service definition

A GaS can declare required and optional parameters whose values are provided by the caller. The parameter values are mapped onto either feature values on the document being processed by the embedded GATE PRs (useful in the case of a conditional controller), or runtime parameter values of the various PRs that make up the application. The mapping is defined in a service definition, an XML file supplied by the GaS creator:

<parameters>
  <param name="depth">
    <runtimeParameter prName="MyAnnotator" prParam="maxDepth" />
  </param>
  <param name="annotatorName">
    <documentFeature name="annotator" />
  </param>
</parameters>

Parameter values are all strings, but when mapping to PR parameters the usual GATE Resource.setParameterValue() is used, which can convert strings into other types (e.g. URL, Integer, etc.).

The service definition also specifies what annotation sets the service requires as input and populates as output:

<annotationSets>
  <annotationSet name="Original markups" in="true" />
  <annotationSet name="" out="true" />
  <annotationSet name="Key" in="true" out="true" />
</annotationSets>

Note that a service can use the same set for both input and output, and can use the default annotation set (the second example above).

3.3. Standard Configurations

The Ant build file provided with the GaS can build several standard configurations of GaS:

3.3.1. All-in-one WAR file

The war.complete Ant target creates a WAR file that will run a message broker, service endpoint and one or more workers all within the same web application context in a servlet container (e.g. Tomcat or Jetty). Despite the name, the WAR file generated is not quite complete, the following files must be inserted to complete the deployment:

Once these files have been added to the WAR it should be deployable on any Servlet 2.4 container (e.g. Tomcat 5.5, Jetty 6, etc.)

In addition, you may wish to edit /WEB-INF/gate-service.properties if you want to run more than one worker to allow for parallel processing of requests.

Finally, /WEB-INF/classes/log4j.properties defines the logging configuration for the service. The default file logs all informative, warning and error messages - when debugging you may wish to enable debug messages too.

3.3.2. Endpoint only

The war.endpointonly target creates a WAR file that runs just the web service endpoint for a service. It expects to post jobs to a remote message broker, and you will need to run one or more standalone workers to process the jobs. The endpoint-only WAR file requires the addition of just /WEB-INF/serviceDefinition.xml as described above. In addition, you will need to edit /WEB-INF/gate-service.properties and set the correct brokerURL (typically failover:tcp://hostname:61616), and you may wish to configure logging as above.

3.3.3. Standalone worker

The dist.worker target creates a ZIP file which is a suitable installation from which to run a set of standalone workers for a GaS. You will need to add the following files to the distribution:

You may also wish to edit gate-service.properties and log4j.properties in the conf directory to set the broker location, number of workers and logging configuration for the workers.

The workers are run using Ant - a build.xml file is provided in the gate-service-worker directory, just run ant in this directory to run the workers.

3.4. Advanced configuration

This section assumes some knowledge of the Spring framework, and in particular the Inversion of Control container and the format of bean definition XML files.

The various components of a GaS are configured using Spring. The standard configurations described above are simply pre-defined Spring contexts containing the relevant beans, which require minimal additional configuration to be useable.

3.4.1. Endpoints

The web service endpoint object for a particular GaS is instantiated by Axis. However, the endpoint object itself is simply a thin wrapper around a Spring bean, called the endpoint handler, that does the actual work.

When the GaS web application starts up it uses the standard Spring ContextLoaderListener to load an ApplicationContext from a number of bean definition files, typically stored in /WEB-INF/spring. The Axis-managed endpoint object then looks up the endpoint handler bean in this context under the ID endpointHandler. The endpointHandler bean is a prototype (non-singleton) bean, of which several instances will be created by the Axis service object to allow for multiple concurrent requests.

The usual endpoint handler is an instance of the class gleam.gateservice.endpoint.GateWebServiceHandler, and takes the following properties:

Creation of the connection factory and destination are JMS provider specific. In a JEE application server they would come from JNDI but for ActiveMQ they can simply be created as singleton beans in Spring. See /WEB-INF/spring/commonBeans.xml in a generated WAR file for an example.

3.4.2. Workers

Workers are started by gleam.gateservice.worker.WorkerRunner, which takes a Spring application context and looks for all beans of type gleam.gateservice.worker.WorkerConfig. Each WorkerConfig bean defines a set of workers to run, and has the following properties:

3.4.3. Running workers in a web application

To run workers in a web application, for example in the all-in-one case where the workers run in the same webapp as the endpoint, there is a ServletContextListener provided which creates a WorkerRunner and starts workers defined by all the WorkerConfig beans in the Spring web application context. The listener must be declared in web.xml, after the Spring ContextLoaderListener, as follows:

<listener>
  <listener-class>
    gleam.gateservice.worker.WorkerRunnerListener
  </listener-class>
<listener>

The spring context must of course include all the beans required by the WorkerConfigs...

3.5. Complex configurations - more than one service

There is nothing to stop you running endpoints and/or workers for more than one GaS in the same web application or JVM. However, some additional configuration is necessary.

3.5.1. Multiple endpoints in one webapp

To run endpoints for multiple services in the same web application, you must first create your Spring bean definitions such that the two independent endpoint handlers are defined correctly under different bean IDs (say serviceOneHandler and serviceTwoHandler). In particular, the two handlers must post their jobs to different JMS queues - either two different queues in the same broker or two independent brokers.

Once this is done you must modify the Axis server-config.wsdd file in WEB-INF and duplicate the service section defining the GATEService, changing the service name attributes to distinguish between the two services. Then you must add a parameter to each service to tell it which handler bean to use:

<service name="ServiceOne" provider="java:RPC" ...>
 ...
 <parameter name="scope" value="Application"/>
 <!-- Use a different bean name for the handler -->
 <parameter name="endpointHandlerBeanName" value="serviceOneHandler"/>
 ...
</service>

3.5.2. Multiple workers in one JVM

This case is very simple - just define multiple independent WorkerConfig beans in your Spring configuration, and all the defined workers will be run automatically by the WorkerRunner.