NOTE: This page is outdated. If you are looking for up-to-date information, please refer to the official documentation on the deegree homepage.

HowTo: Write processes for deegree 3 processingService in Java

This is an introduction on how to write custom processes for the deegree 3 processingService in Java. For information on setting up a processingService or other ways of injecting processes, please have a look at the WPS documentation.

Contents

Set up a process development environment
Creating a custom process
Advanced topics
1. Other input and output parameters
  1. Accessing the input parameter values
  2. Setting the output parameters values
2. Asynchronous execution
  1. Providing execution status information

1. Set up a process development environment

If you want to develop your own WPS processes, these are the recommended steps for preparing a development environment (make sure that you have installed the system requirements on your machine):

1.1. Checkout the deegree WPS demo module from SVN

You may use your favorite SVN client (e.g. TortoiseSVN) or just use the SVN command line client:

svn co https://svn.wald.intevation.org/svn/deegree/deegree3/tags/3.0.4/deegree-demos/deegree-wps-demo

Make sure to checkout out into a reasonable work directory. If you want to work with Eclipse, it's usually best to check out into Eclipse's workspace folder.

1.2. Build / start the WPS module

For these steps, it's required to have Maven 2 (2.2.1 is tested/recommended) installed. On the command line, switch to the checkout directory.

For building the WAR, execute the following command:

mvn package

Afterwards, you will find the WAR in the target folder.

You may now deploy the WAR into your web servlet container installation, or just fire it up using Maven's Tomcat plugin (in this case, shut down any running web servlet containers beforehand, so the default port 8080 is available):

```
mvn tomcat:run
```

Point your web browser to the start page of the WPS webapp: http://localhost:8080/deegree-wps-demo You may stop the embedded Tomcat by pressing CTRL+C on the command line.

1.3. Set up the WPS module in Eclipse (tested with 3.5 EE version)

On the command line (in the checkout directory}:

mvn -Dwtpversion=2.0 eclipse:eclipse -DdownloadSources=true -DdownloadJavadocs=true

This will create the necessary build path and project information needed by Eclipse. Afterwards (in Eclipse), create a new project (simply choose "Java Project", and enter deegree-wps-demo as the project name. Click "Finish". If you checked out into the Eclipse's workspace folder, the project will be set up correctly and should compile fine (if this is the first time your using a Maven project inside this Eclipse installation, you will need to set the M2_REPO variable.

Note that Eclipse recognizes the project as a "Dynamic web project", and thus you may just right-click on the project name and select "Run As" -> "Run on Server". This allows to start up the deegree WPS inside Eclipse, using it's embedded server configurations. HINT: To add a suitable server configuration, go to "Window" -> "Preferences" -> "Server" -> "Runtime Environment".

2. Creating a custom process

In the deegree 3 processingService, a Java-based process consists of two files:

A Java process class that implements the Processlet interface and contains the processing logic. These classes are called processlets in deegree3. An example is src/main/java/org/deegree/wps/ParameterDemoProcesslet.java.
The process definition containing a thorough description of the process. In this file you specify a unique identifier for your process, the processlet (see above), a title and an abstract description of your process. Furthermore you specify all the input and output parameters of your process. See src/main/webapp/WEB-INF/workspace/processes/ParameterDemoProcess.xml for an example.

The process created in this tutorial implements a really simple operation for adding two integer input parameters. It assumes that you have set up a process development environment in Eclipse as described above.

2.1. Create a process definition file

In the folder src/main/webapp/client/WEB-INF/workspace/processes, create a process definition file AdditionProcess.xml with the following content.

<?xml version="1.0" encoding="UTF-8"?>
<ProcessDefinition configVersion="3.0.0" processVersion="1.0.0" storeSupported="true" statusSupported="false"
  xmlns="http://www.deegree.org/processes/java" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.deegree.org/processes/java http://schemas.deegree.org/processes/java/3.0.0/java.xsd">
  <Identifier>Addition</Identifier>
  <JavaClass>org.deegree.wps.AdditionProcesslet</JavaClass>
  <Title>Process for adding two integer values.</Title>
  <Abstract>The purpose of this process is to provide new users with a simple example process.</Abstract>
  <InputParameters>
    <LiteralInput>
      <Identifier>SummandA</Identifier>
      <Title>First summand </Title>
      <Abstract>This parameter specifies the first summand for a simple addition.</Abstract>
      <DataType reference="http://www.w3.org/TR/xmlschema-2/#integer">integer</DataType>
      <DefaultUOM>meters</DefaultUOM>
      <OtherUOM>centimeters</OtherUOM>
    </LiteralInput>
    <LiteralInput>
      <Identifier>SummandB</Identifier>
      <Title>Second summand </Title>
      <Abstract>This parameter specifies the second summand for a simple addition.</Abstract>
      <DataType reference="http://www.w3.org/TR/xmlschema-2/#integer">integer</DataType>
      <DefaultUOM>meters</DefaultUOM>
      <OtherUOM>centimeters</OtherUOM>
    </LiteralInput>
  </InputParameters>
  <OutputParameters>
    <LiteralOutput>
      <Identifier>Sum</Identifier>
      <Title>The result of the addition operation</Title>
      <DataType reference="http://www.w3.org/TR/xmlschema-2/#integer">integer</DataType>
      <DefaultUOM>meters</DefaultUOM>
      <OtherUOM>centimeters</OtherUOM>
    </LiteralOutput>
  </OutputParameters>
</ProcessDefinition>

HINT: After you copied the content into Eclipse (and you have the EE version or installed Eclipse WTP plugins), you may right-click and select "Validate" in order to check the syntactical correctness of your configuration. This is very helpful for finding configuration errors.

Note that process definitions in deegree 3 are very similar to process descriptions in the OGC WPS 1.0.0 specification. The root element of the file is ProcessDefinition.

2.1.1. Parameter configVersion

NOTE: Don't confuse the configVersion or processVersion with the version of the WPS protocol (which is 1.0.0 for the deegree 3 processingService). configVersion is a deegree-specific parameter standing for the version of the process definition's schema and currently has to be set at "3.0.0".

2.1.2. Parameter processVersion

The processVersion has to be set by the process developer and stands for the version of the process implementation. This parameter is usually increased when changes to the implementation of a process apply.

2.1.3. Parameter storeSupported

When storeSupported is set to "true", asynchronous process execution will be available. Note that this doesn't add any requirements to the actual process code, this is taken care of by the deegree processingService. See the advanced topics section for more information.

2.1.4. Parameter statusSupported

If statusSupported is set to true, then the process is declared to provide status information, i.e. execution percentage. See the advanced topics section for more information.

2.1.5. Element Identifier

The Identifier element must contain an appropriate unambiguous identifier. This is the name that the WPS will use for publishing the process.

2.1.6. Element JavaClass

The element JavaClass carries the fully qualified name of the java class that implements the process logic.

2.1.7. Element Title/Abstract

Title is used to give the process a short and meaningful title, while abstract may contain a short, human readable description of the functionality of the process.

2.1.8. Element InputParameters / OutputParameters

The largest part of the process definition is made up of the description of the input and output parameters of the process. For the sake of simplicity, only literal inputs and outputs are considered in this example process (see the advanced topics section for information on other input / output types). Literal inputs and outputs consist of an identifier, a title, an abstract as well as the specification of the datatype with default units of measurement and optionally other supported units of measurement:

  <InputParameters>
    <LiteralInput>
      <Identifier>SummandA</Identifier>
      <Title>First summand </Title>
      <Abstract>This parameter specifies the first summand for a simple addition.</Abstract>
      <DataType reference="http://www.w3.org/TR/xmlschema-2/#integer">integer</DataType>
      <DefaultUOM>meters</DefaultUOM>
      <OtherUOM>centimeters</OtherUOM>
    </LiteralInput>
    <LiteralInput>
      ...
    </LiteralInput>
  </InputParameters>
  <OutputParameters>
    <LiteralOutput>
      <Identifier>Sum</Identifier>
      <Title>The result of the addition operation</Title>
      <DataType reference="http://www.w3.org/TR/xmlschema-2/#integer">integer</DataType>
      <DefaultUOM>meters</DefaultUOM>
      <OtherUOM>centimeters</OtherUOM>
    </LiteralOutput>
  </OutputParameters>

2.2. Create the Java process code (processlet)

Next the process logic has to be implemented. Therefore, create a java class with name AdditionProcesslet in src/main/java/org/deegree/wps with the following content. Note: It is of course possible to create your process class in another package. You just need to make sure that it matches the the value of the JavaClass parameter in the process definition.

package org.deegree.wps;

import org.deegree.services.wps.Processlet;
import org.deegree.services.wps.ProcessletException;
import org.deegree.services.wps.ProcessletExecutionInfo;
import org.deegree.services.wps.ProcessletInputs;
import org.deegree.services.wps.ProcessletOutputs;
import org.deegree.services.wps.input.LiteralInput;
import org.deegree.services.wps.output.LiteralOutput;

public class AdditionProcesslet implements Processlet {

    public void process( ProcessletInputs in, ProcessletOutputs out, ProcessletExecutionInfo info )
                            throws ProcessletException {
        int summandA = Integer.parseInt( ( (LiteralInput) in.getParameter( "SummandA" ) ).getValue() );
        int summandB = Integer.parseInt( ( (LiteralInput) in.getParameter( "SummandB" ) ).getValue() );
        int sum = summandA + summandB;

        LiteralOutput output = (LiteralOutput) out.getParameter( "Sum" );
        output.setValue( "" + sum );
    }

    public void destroy() {}

    public void init() {}
}

2.2.1. Processlet details

The class has to implement the interface org.deegree.services.wps.Processlet that declares the methods process(...), init(), destroy(). init() is called once, when the process is deployed. destroy() is called once when the process is shut down.

process(...) is called whenever an Execute request is sent to the WPS that targets this process. With the method getParameter(String parameterId) and the unambiguous identifier of a parameter it is possible to retrieve the corresponding parameter object and by calling its getValue() method, the value of the parameter (see code example AdditionProcesslet). Below you see the source code for the AdditionProcesslet class, that basically just calculates the sum of two parameters from the WPS Execute request and returns the result in the parameter called "Sum" inside the WPS response.

2.3. Running and testing the process

2.3.1. Starting the web servlet container

Make sure that you have saved the Java processlet and the process definition files. Then (re-) start your dynamic web project in Eclipse (e.g. right-click on the project in package explorer, "Run As" -> "Run On Server").

The log of your application container should now mention the AdditionProcess (e.g. in Console view of Eclipse).

...
[12:20:50]  INFO: [JavaProcessProviderProvider] Loading process definition from file 'AdditionProcess.xml'
[12:20:50]  INFO: [JavaProcessProvider] Initializing process with id 'Addition'
[12:20:50]  INFO: [JavaProcessProvider] - process class: org.deegree.wps.AdditionProcesslet
[12:20:50]  INFO: [ProcessManager] - input parameter: SummandA
[12:20:50]  INFO: [ProcessManager] - input parameter: SummandB
[12:20:50]  INFO: [ProcessManager] - output parameter: Sum
...

2.3.2. Sending test requests to the WPS

You may now use the simple client supplied with the WPS (http://localhost:8080/deegree-wps-demo/console/client/client.xhtml) to see that the process is actually served and works:

<?xml version="1.0" encoding="UTF-8"?>
<wps:GetCapabilities service="WPS" xmlns:wps="http://www.opengis.net/wps/1.0.0" xmlns:ows="http://www.opengis.net/ows/1.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opengis.net/wps/1.0.0
http://schemas.opengis.net/wps/1.0.0/wpsGetCapabilities_request.xsd" language="en"/>

<?xml version="1.0" encoding="UTF-8"?>
<DescribeProcess xmlns="http://www.opengis.net/wps/1.0.0" xmlns:ows="http://www.opengis.net/ows/1.1" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opengis.net/wps/1.0.0 http://schemas.opengis.net/wps/1.0.0/wpsDescribeProcess_request.xsd" service="WPS" version="1.0.0" language="en">
    <ows:Identifier>Addition</ows:Identifier>
</DescribeProcess>

<?xml version="1.0" encoding="UTF-8"?>
<wps:Execute service="WPS" version="1.0.0"
  xmlns:wps="http://www.opengis.net/wps/1.0.0" xmlns:ows="http://www.opengis.net/ows/1.1"
  xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.opengis.net/wps/1.0.0 http://schemas.opengis.net/wps/1.0.0/wpsExecute_request.xsd">
  <ows:Identifier>Addition</ows:Identifier>
  <wps:DataInputs>
    <wps:Input>
      <ows:Identifier>SummandA</ows:Identifier>
      <wps:Data>
        <wps:LiteralData>21</wps:LiteralData>
      </wps:Data>
    </wps:Input>
    <wps:Input>
      <ows:Identifier>SummandB</ows:Identifier>
      <wps:Data>
        <wps:LiteralData>21</wps:LiteralData>
      </wps:Data>
    </wps:Input>
  </wps:DataInputs>
</wps:Execute>

3. Advanced topics

3.1. Other input and output parameters

The most complex topic of process implementation is dealing with inputs and outputs. The deegree 3 processingService supports every parameter variant that is defined by the WPS 1.0.0 specification. The specification permits three different types of input and output parameters:

LiteralInput,
BoundingBoxInput,
ComplexInput and the corresponding outputs.

LiteralInput is used for simple input parameters with literal values, that are given as a simple string e.g. "red", "42", "highway 101" (no nested XML fragments or similarly complex inputs). A BoundingBoxInput specifies a certain bounding box given in a specified or a default CRS. The content of a ComplexInput can be a complex XML structure as well as binary data (must be base64-encoded when given as an inline value).

Here's the process definition from the ParameterDemo process:

<?xml version="1.0" encoding="UTF-8"?>
<ProcessDefinition configVersion="3.0.0" processVersion="1.0.0" storeSupported="true" statusSupported="false"
  xmlns="http://www.deegree.org/processes/java" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.deegree.org/processes/java http://schemas.deegree.org/processes/java/3.0.0/java.xsd">
  <Identifier>ParameterDemoProcess</Identifier>
  <JavaClass>org.deegree.wps.ParameterDemoProcesslet</JavaClass>
  <Title>Process for demonstrating the use of different types of input and output parameters.</Title>
  <Abstract>The purpose of this process is to provide a demonstration for the use of different input and output
    parameter types in a deegree 3 WPS process.</Abstract>
  <InputParameters>
    <LiteralInput>
      <Identifier>LiteralInput</Identifier>
      <Title>Example literal input </Title>
      <Abstract>This parameter specifies how long the execution of the process takes (the process sleeps for this time).
        May be specified in seconds or minutes.</Abstract>
      <DataType reference="http://www.w3.org/TR/xmlschema-2/#integer">integer</DataType>
      <DefaultUOM>seconds</DefaultUOM>
      <OtherUOM>minutes</OtherUOM>
    </LiteralInput>
    <BoundingBoxInput>
      <Identifier>BBOXInput</Identifier>
      <Title>BBOXInput</Title>
      <DefaultCRS>EPSG:4326</DefaultCRS>
    </BoundingBoxInput>
    <ComplexInput>
      <Identifier>XMLInput</Identifier>
      <Title>XMLInput</Title>
      <DefaultFormat mimeType="text/xml" />
    </ComplexInput>
    <ComplexInput>
      <Identifier>BinaryInput</Identifier>
      <Title>BinaryInput</Title>
      <DefaultFormat mimeType="image/png" encoding="base64" />
    </ComplexInput>
  </InputParameters>
  <OutputParameters>
    <LiteralOutput>
      <Identifier>LiteralOutput</Identifier>
      <Title>A literal output parameter</Title>
      <DataType reference="http://www.w3.org/TR/xmlschema-2/#integer">integer</DataType>
      <DefaultUOM>seconds</DefaultUOM>
    </LiteralOutput>
    <BoundingBoxOutput>
      <Identifier>BBOXOutput</Identifier>
      <Title>A bounding box output parameter</Title>
      <DefaultCRS>EPSG:4326</DefaultCRS>
    </BoundingBoxOutput>
    <ComplexOutput>
      <Identifier>XMLOutput</Identifier>
      <Title>An XML output parameter</Title>
      <DefaultFormat mimeType="text/xml" />
    </ComplexOutput>
    <ComplexOutput>
      <Identifier>BinaryOutput</Identifier>
      <Title>A binary output parameter</Title>
      <DefaultFormat mimeType="image/png" encoding="base64" />
    </ComplexOutput>
  </OutputParameters>
</ProcessDefinition>

Please have a look at the corresponding example requests. These demonstrate parameter passing (inline / by reference) and execution variants (asynchronous, storing of documents, etc.)

3.1.1. Accessing the input parameter values

Please refer to src/main/java/org/deegree/wps/ParameterDemoProcesslet.java for an example. Also see http://download.deegree.org/deegree3/nightly/services/javadoc/org/deegree/services/wps/package-summary.html for JavaDoc.

The central interface is org.deegree.services.wps.Processlet. This interface declares the methods init, destroy and process. While init and destroy provide life-cycle hooks for initializing and destroying of processes, the process method hosts the process logic called for Execute requests.

To handle input values, the API provides five interfaces within the org.deegree.services.wps.input package:

ProcessletInputs (note the 's') encapsulates all input parameters for the execution.
ProcessletInput is the base type for a single input parameter. Instances are always of type BoundingBoxInput, ComplexInput or LiteralInput.
BoundingBoxInput is a ProcessletInput that holds a bounding box value.
ComplexInput is a ProcessletInput that can hold any kind of complex input parameters like objects encoded in XML or raw binary streams.
LiteralInput is a ProcessletInput that encapsulates a parameter of a simple quantity (e.g. a number) and optional units of measure (e.g. 'meter').

3.1.2. Setting the output parameters values

Please refer to src/main/java/org/deegree/wps/ParameterDemoProcesslet.java for an example. Also see http://download.deegree.org/deegree3/api/deegree-services-3.0.3/org/deegree/services/wps/Processlet.html for JavaDoc.

The corresponding output interfaces are ProcessletOutputs, ProcessletOutput, BoundingBoxOutput, ComplexOutput, LiteralOutput.

3.2. Asynchronous execution

The parameter storeSupported is used to specify whether it should be possible to execute the process asynchronously. Actually, it means that storing of response documents is enabled, which is necessary for asynchronous execution using the WPS protocol. When storeSupported is set to "true", asynchronous process execution will be available. Note that this doesn't add any requirements to the actually process code, this is all taken care of by the deegree processingService.

3.2.1. Providing execution status information

Please refer to src/main/java/org/deegree/wps/ParameterDemoProcesslet.java for an example on setting the percent completed information exposed by the WPS.

Refer to the JavaDoc for additional information on setting or getting status information from a process (ProcessletExecutionInfo) or access to exception codes (ProcessletException).

CategoryDeegree3 CategoryHowTo