Navigation

14. Process providers

Process provider resources define geospatial processes that can be accessed via the Web Processing Service (WPS).

The remainder of this chapter describes some relevant terms and the process provider configuration files in detail. You can access this configuration level by clicking on the processes link in the administration console. The corresponding resource files are located in the processes/ subdirectory of the active deegree workspace directory.

_images/workspace-overview-process.png

Process providers plug geospatial processes into the WPS

14.1. Java process provider

The Java process provider is a well-defined container for processes written in the Java programming language. In order to set up a working Java process provider resource, two things are required:

  • A Java process provider configuration file
  • A Processlet: Java class with the actual process code

The first item is an XML resource configuration file like any other deegree resource configuration. The second is special to this kind of resource. It provides the byte code with the process logic and has to be accessible by deegree’s classloader. There are several options to make custom Java code available to deegree webservices (see Java code and the classpath for details), but the most common options are:

  • Putting class files into the classes/ directory of the workspace
  • Putting JAR files into the modules/ directory of the workspace

14.1.1. Minimal configuration example

A very minimal valid configuration example looks like this:

Java process provider: Minimal example (resource configuration)

<ProcessDefinition configVersion="3.0.0" processVersion="1.0.0" 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>Process42</Identifier>
  <JavaClass>Processlet42</JavaClass>
  <Title>Calculates the answer to life, the universe and everything</Title>
  <OutputParameters>
    <LiteralOutput>
      <Identifier>Answer</Identifier>
      <Title>The universal answer</Title>
    </LiteralOutput>
  </OutputParameters>
</ProcessDefinition>

This example defines a bogus process with the following properties:

  • Identifier: Process42
  • Bound to Java code from class Processlet42
  • Title Calculates the answer to life, the universe and everything (returned in WPS responses)
  • No input parameters
  • Single output parameter with identifier Answer and title The universal answer

In order to make this configuration work, a matching Processlet class is required:

Java process provider: Minimal example (Java code)

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.output.LiteralOutput;

public class Processlet42 implements Processlet {

    @Override
    public void process( ProcessletInputs in, ProcessletOutputs out, ProcessletExecutionInfo info )
                            throws ProcessletException {
        LiteralOutput output = (LiteralOutput) out.getParameter( "Answer" );
        output.setValue( "42" );
    }

    @Override
    public void init() {
        // nothing to initialize
    }

    @Override
    public void destroy() {
        // nothing to destroy
    }
}

14.1.2. More complex configuration example

A more complex configuration example looks like this:

Java process provider: More complex example (resource configuration)

<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>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>

This example defines a demonstration process with the following properties:

  • Identifier: AdditionProcess
  • Bound to Java code from class AdditionProcesslet
  • Title Process for adding two integer values. (returned in WPS responses)
  • Two integer input parameters SummandA and SummandB with title, abstract and unit of measure
  • Single integer output parameter with identifier Sum, title and unit of measure

In order to make this configuration work, a matching Processlet class is required:

Java process provider: Minimal example (Java code)

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() {}
}

14.1.3. Configuration options

The configuration format for the Java process provider is defined by schema file http://schemas.deegree.org/processes/java/3.0.0/java.xsd. The following table lists all available configuration options. When specifiying them, their order must be respected.

Option Cardinality Value Description
@processVersion 1 String Release version of this process (metadata)
@storeSupported 0..1 Boolean If set to true, asynchronous execution will become available
@statusSupported 0..1 Boolean If set to true, process code provides status information
Identifier 1 String Identifier of the process
JavaClass 1 String Fully qualified name of a Processlet that implements the process logic
Title 1 String Short and meaningful title (metadata)
Abstract 0..1 String Short, human readable description (metadata)
Metadata 0..n String Additional metadata
Profile 0..n String Profile to which the WPS process complies (metadata)
WSDL 0..1 String URL of a WSDL document which describes this process (metadata)
InputParameters 0..1 Complex Definition and metadata of the input parameters
OutputParameters 1 Complex Definition and metadata of the output parameters

The following sections describe these options and their sub-options in detail, as well as the Processlet API.

14.1.4. General options

All general options just provide metadata that the WPS reports to client. They don’t affect the behaviour of the configured process.

  • processVersion: The processVersion attribute has to be managed by the process developer and describes the version of the process implementation. This parameter is usually increased when changes to the implementation of a process apply.
  • Identifier: An unambiguous identifier
  • Title: Short and meaningful title
  • Abstract: Short, human readable description
  • Metadata: Additional metadata
  • Profile: Profile to which the WPS process complies
  • WSDL: URL of a WSDL document which describes this process

Hint

These options directly relate to metadata defined in the WPS 1.0.0 specification.

14.1.5. The Processlet API

Option JavaClass specifies the fully qualified name of a Java class that implement deegree’s Processlet Java interface. This interface is part of an API that hides the complexity of the WPS protocol while providing efficient and scalable handling of input and output parameters. By using this API, the process developer can focus on implementing the process logic without having to care of the details of the protocol:

  • Request encoding (KVP, XML, SOAP)
  • Input parameter passing variants (inline, by reference)
  • Output parameter representation (inline, by reference)
  • Storing of response documents
  • Synchronous/asynchronous execution

The interface looks like this:

Java process provider: Processlet interface

package org.deegree.services.wps;

public interface Processlet {

    /**
     * Called by the {@link ProcessManager} to perform an execution of this {@link Processlet}.
     * <p>
     * The typical workflow is:
     * <ol>
     * <li>Get inputs from <code>in</code> parameter</li>
     * <li>Parse inputs into the required format (e.g. GML)</li>
     * <li>Do computation.</li>
     * <li>Transform computational results into required format (e.g. GML)</li>
     * <li>Write results to <code>out</code> parameter</li>
     * </ol>
     * 
     * @param in
     *            input arguments to be processed, never <code>null</code>
     * @param out
     *            used to store the process outputs, never <code>null</code>
     * @param info
     *            can be used to provide execution information, i.e. percentage completed and start/success messages
     *            that it wants to make known to clients, never <code>null</code>
     * @throws ProcessletException
     *             may be thrown by the processlet to indicate a processing exception
     */
    public void process( ProcessletInputs in, ProcessletOutputs out, ProcessletExecutionInfo info )
                            throws ProcessletException;

    /**
     * Called by the {@link ProcessManager} to indicate to a {@link Processlet} that it is being placed into service.
     */
    public void init();

    /**
     * Called by the {@link ProcessManager} to indicate to a {@link Processlet} that it is being taken out of service.
     * <p>
     * This method gives the {@link Processlet} an opportunity to clean up any resources that are being held (for
     * example, memory, file handles, threads) and make sure that any persistent state is synchronized with the
     * {@link Processlet}'s current state in memory.
     * </p>
     */
    public void destroy();
}

As you can see, the interface defines three methods:

  • init(): Called once when the workspace initializes the Java process provider resource that references the class.
  • destroy(): Called once when the workspace destroys the Java process provider resource that references the class.
  • process(...): Called every time an Execute request is sent to the WPS that targets this Processlet. The method usually reads the input parameters, performs the actual computation and writes the output parameters.

Hint

The Processlet interface mimics the well-known Java Servlet interface (hence the name). A Servlet developer does not need to care of the details of HTTP. Similarly, a Processlet developer does not need to care of the details of the WPS protocol.

Hint

The Java process provider instantiates the Processlet class only once. However, multiple simultaneous executions of a Processlet are possible (in case parallel Execute-requests are sent to a WPS), and therefore, the Processlet code must be implemented in a thread-safe manner (just like Servlets).

14.1.5.1. Processlet compilation

In order to succesfully compile a Processlet implementation, you will need to make the Processlet API available to the compiler. Generally, this means that the Java module deegree-services-wps (and it’s dependencies) have to be on the build path. We suggest to use Apache Maven for this. Here’s an example POM for your convenience:

Java process provider: Example Maven POM for compiling processlets

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <artifactId>processlet-examples</artifactId>
  <packaging>jar</packaging>
  <name>processlet-examples</name>
  <description>Maven project for compiling Processlets</description>

  <parent>
    <groupId>org.deegree</groupId>
    <artifactId>deegree</artifactId>
    <version>3.2.0</version>
  </parent>

  <repositories>
    <repository>
      <id>deegree-repo</id>
      <url>http://repo.deegree.org/content/groups/public</url>
      <releases>
        <updatePolicy>never</updatePolicy>
      </releases>
      <snapshots>
        <enabled>true</enabled>
      </snapshots>
    </repository>
  </repositories>

  <dependencies>
    <dependency>
      <groupId>org.deegree</groupId>
      <artifactId>deegree-services-wps</artifactId>
      <version>3.2.0</version>
    </dependency>
  </dependencies>

</project>

Tip

You can use this POM to compile the example Processlets above. Just create an empty directory somewhere and save the example POM as pom.xml. Place the Processlet Java files into subdirectory src/main/java/ (as files Processlet42.java / AdditionProcesslet.java). On the command line, change to the project directory and use mvn package (Apache Maven 3.0 and a compatible Java JDK have to be installed). Subdirectory target should now contain a JAR file that you can copy into the modules/ directory of the deegree workspace.

14.1.5.2. Testing Processlets using raw WPS requests

Hint

In order to perform WPS request to access your process provider/Processlet, you need to have an active Web Processing Service (WPS) resource in your workspace (which handles the WPS protocol and forwards the request to the process provider and the processlet).

The general idea of the WPS specification is that a client connects to a WPS server and invokes processes offered by the server to perform a computation. However, in some cases, you may just want to send raw WPS requests to a server and check the response yourself (e.g. for testing the behaviour of your processlet). The WPS 1.0.0 specification defines KVP, XML and SOAP-encoded requests. All encodings are supported by the deegree WPS, so you can choose the most appropriate one for your use-case. For sending KVP-requests, you can simply use your web browser (or a command line tools like wget or curl). XML or SOAP requests can be send using deegree’s generic client.

Some KVP GetCapabilities/DescribeProcess request examples for checking the metadata of processes:

  • http://127.0.0.1:8080/services/wps?service=WPS&request=GetCapabilities
  • http://127.0.0.1:8080/services/wps?service=WPS&version=1.0.0&request=DescribeProcess&identifier=Process42
  • http://127.0.0.1:8080/services/wps?service=WPS&version=1.0.0&request=DescribeProcess&identifier=AdditionProcess

Some simple KVP Execute request examples for invoking processes:

  • http://127.0.0.1:8080/services/wps?service=WPS&version=1.0.0&request=Execute&identifier=Process42
  • http://127.0.0.1:8080/services/wps?service=WPS&version=1.0.0&request=Execute&identifier=Addition&datainputs=SummandA=21;SummandB=21

Tip

The WPS 1.0.0 specification (and the deegree WPS) support many features with regard to process invocation, such as input parameter passing (inline or by reference), return parameters (inline or by reference), response variants and asynchronous execution. Example workspace 4: Web Processing Service demo contains XML example requests which demonstrate most of these features.

14.1.6. Input and output parameters

Besides the process logic, the most crucial topic of WPS process implementation is the standard-compliant definition and handling of input and output parameters. The deegree WPS and the Java process provider support all parameter types that are defined by the WPS 1.0.0 specification:

  • LiteralInput/LiteralOutput: Literal values, e.g. “red”, “42” or “highway 66”
  • BoundingBoxInput/BoundingBoxOutput: A geo-referenced bounding box
  • ComplexInput/ComplexOutput: Either an XML structure (e.g. GML encoded features) or binary data (e.g. coverage data as GeoTIFF)

In order to create your own process, first find out which input and output parameters you want it to have. During implementation, each parameter has to be considered twice:

  • It has to be defined in the resource configuration file
  • It has to be read or written in the Processlet

The definition in the resource configuration is mostly to specify metadata (identifier, title, abstract, datatype) of the parameter. The WPS will report it in response to DescribeProcess requests. When performing Execute requests, the deegree WPS will also perform a basic check of the validity of the input parameters (identifier, number of occurences, type) and respond with an ExceptionReport if the constraints are not met.

14.1.6.1. Basics of defining input and output parameters

In order to define a parameter of a process, create a new child element in your process provider configuration:

  • Input: Add a LiteralInput, BoundingBoxInput or ComplexInput element to section InputParameters
  • Output: Add a LiteralOutput, BoundingBoxOutput or ComplexOutput element to section OutputParameters

Here’s an InputParameters example that defines four parameters:

Java process provider: Example for InputParameters section

<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>

Here’s an OutputParameters example that defines four parameters:

Java process provider: Example for OutputParameters section

<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>

Each parameter definition element has the following common options:

Option Cardinality Value Description
Identifier 1 String Identifier of the parameter
Title 1 String Short and meaningful title (metadata)
Abstract 0..1 String Short, human readable description (metadata)
Metadata 0..n String Additional metadata

Besides the identifier of the parameter, these parameters just define metadata that the WPS reports. Additionally, each input parameter definition element supports the following two attributes:

Option Cardinality Value Description
@minOccurs 0..n Integer Minimum number of times the input has to be present in a request, default: 1
@maxOccurs 0..n String Maximum number of times the input has to be present in a request, default: 1

The differences and special options of the individual parameter types (Literal, Bounding Box, Complex) are described in the following sections.

14.1.6.2. Basics of accessing input and output parameters

The first two arguments of Processlet#process(..) provide access to the input parameter values and output parameter sinks. The first argument is of type ProcessletInputs and encapsulates the process input parameters. Here’s an example snippet that shows how to access the input parameter with identifier LiteralInput:

public void process( ProcessletInputs in, ProcessletOutputs out, ProcessletExecutionInfo info )
                     throws ProcessletException {

    ProcessletInput literalInput = in.getParameter( "LiteralInput" );
    [...]
}

The getParameter(...) method of ProcessletInputs takes the identifier of the process parameter as an argument and returns a ProcessletInput (without the s) object that provides access to the actual value of the process parameter. Here’s the ProcessletInput interface:

public interface ProcessletInput {

    /**
     * Returns the identifier or name of the input parameter as defined in the process description.
     *
     * @return the identifier of the input parameter
     */
    public CodeType getIdentifier();

    /**
     * Returns the title that has been supplied with the input parameter, normally available for display to a human.
     *
     * @return the title provided with the input, may be null
     */
    public LanguageString getTitle();

    /**
     * Returns the narrative description that has been supplied with the input parameter, normally available for display
     * to a human.
     *
     * @return the abstract provided with the input, may be null
     */
    public LanguageString getAbstract();
}

This interface does not provide access to the passed value, but ProcessletInput is the parent of three Java types that directly correspond to three input parameter types of the process provider configuration:

_images/java_processprovider_inputtypes.png

ProcessletInput interface and sub types for each parameter type

For example, if your input parameter definition “A” is a BoundingBoxInput, then the Java type for this parameter will be BoundingBoxInput as well. In your Java code, use a type cast to narrow the return type (and gain access to the passed value):

public void process( ProcessletInputs in, ProcessletOutputs out, ProcessletExecutionInfo info )
                     throws ProcessletException {

    BoundingBoxInput inputA = (BoundingBoxInput) in.getParameter( "A" );
    [...]
}

Tip

If an input parameter can occur multiple times (maxOccurs > 1 in the definition), use method getParameters(...) instead of getParameter(...). The latter method returns a List of ProcessletInput objects.

Output parameters are treated in a similar manner. The second parameter of Processlet#process(..) provides to output parameter sinks. It is of type ProcessletOutputs. Here’s a basic usage example:

public void process( ProcessletInputs in, ProcessletOutputs out, ProcessletExecutionInfo info )
                     throws ProcessletException {

    ProcessletOutput literalOutput = out.getParameter( "LiteralOutput" );
    [...]
}

Here’s the ProcessletOutput interface:

public interface ProcessletOutput {

    /**
     * Returns the identifier or name of the output parameter as defined in the process description.
     *
     * @return the identifier of the output parameter
     */
    public CodeType getIdentifier();

    /**
     * Returns the title that has been supplied with the request of the output parameter, normally available for display
     * to a human.
     *
     * @return the title provided with the output, may be null
     */
    public LanguageString getSubmittedTitle();

    /**
     * Returns the narrative description that has been supplied with the request of the output parameter, normally
     * available for display to a human.
     *
     * @return the abstract provided with the output, may be null
     */
    public LanguageString getSubmittedAbstract();

    /**
     * Returns whether this output parameter has been requested by the client, i.e. if it will be present in the result.
     * <p>
     * NOTE: If the parameter is requested, the {@link Processlet} must set a value for this parameter, if not, it may
     * or may not do so. However, for complex output parameters that are not requested, it is advised to omit them for
     * more efficient execution of the {@link Processlet}.
     * </p>
     *
     * @return true, if the {@link Processlet} must set the value of this parameter (in this execution), false otherwise
     */
    public boolean isRequested();

    /**
     * Sets the parameter title in the response sent to the client.
     *
     * @param title
     *            the parameter title in the response sent to the client
     */
    public void setTitle( LanguageString title );

    /**
     * Sets the parameter abstract in the response sent to the client.
     *
     * @param summary
     *            the parameter abstract in the response sent to the client
     */
    public void setAbstract( LanguageString summary );
}

Again, there are three subtypes. Each subtype of ProcessletOutput corresponds to one output parameter type:

_images/java_processprovider_outputtypes.png

ProcessletOutput interface and sub types for each parameter type

14.1.6.3. Literal parameters

Literal input and output parameter definitions have the following additional options:

Option Cardinality Value Description
DataType 0..1 String Data Type of this input (or output), default: unspecified (string)
DefaultUOM 0..1 String Default unit of measure, default: unspecified
OtherUOM 0..n String Alternative unit of measure
DefaultValue 0..1 String Default value of this input (only for inputs)
AllowedValues 0..1 Complex Constraints based on value sets and ranges (only for inputs)
ValidValueReference 0..1 Complex References to externally defined value sets and ranges (only for inputs)

These options basically define metadata that the WPS publishes to clients. For the sub-options of the AllowedValues and ValidValueReference options, please refer to the WPS 1.0.0 specification or the XML schema for the Java process provider configuration format (http://schemas.deegree.org/processes/java/3.0.0/java.xsd).

In order to work with a LiteralInput parameter in the Processlet code, the corresponding Java type offers the following methods:

/**
 * Returns the literal value.
 *
 * @see #getUOM()
 * @return the literal value (has to be in the correct UOM)
 */
public String getValue();

/**
 * Returns the UOM (unit-of-measure) for the literal value, it is guaranteed that the returned UOM is supported for
 * this parameter (according to the process description).
 *
 * @return the requested UOM (unit-of-measure) for the literal value, may be null if no UOM is specified in the
 *         process description
 */
public String getUOM();

/**
 * Returns the (human-readable) literal data type from the process definition, e.g. <code>integer</code>,
 * <code>real</code>, etc).
 *
 * @return the data type, or null if not specified in the process definition
 */
public String getDataType();

Similarly, the LiteralOutput type offers the following methods:

/**
 * Sets the value for this output parameter of the {@link Processlet} execution.
 *
 * @see #getRequestedUOM()
 * @param value
 *            value to be set (in the requested UOM)
 */
public void setValue( String value );

/**
 * Returns the requested UOM (unit-of-measure) for the literal value, it is guaranteed that this UOM is supported
 * for this parameter (according to the process description).
 *
 * @return the requested UOM (unit-of-measure) for the literal value, may be null
 */
public String getRequestedUOM();

/**
 * Returns the announced literal data type from the process definition (e.g. integer, real, etc) as an URI, such as
 * <code>http://www.w3.org/TR/xmlschema-2/#integer</code>.
 *
 * @return the data type, or null if not specified in the process definition
 */
public String getDataType();

14.1.6.4. BoundingBox parameters

BoundingBox input and output parameter definitions have the following additional options:

Option Cardinality Value Description
DefaultCRS 1 String Identifier of the default coordinate reference system
OtherCRS 0..n String Additionally supported coordinate reference system

In order to work with a BoundingBoxInput parameter in the Processlet code, the corresponding Java type offers the following methods:

/**
 * Returns the lower corner point of the bounding box.
 *
 * @return the lower corner point
 */
public double[] getLower();

/**
 * Returns the upper corner point of the bounding box.
 *
 * @return the upper corner point
 */
public double[] getUpper();

/**
 * Returns the CRS (coordinate reference system) name of the bounding box.
 *
 * @return the CRS (coordinate reference system) name or null if unspecified
 */
public String getCRSName();

/**
 * Returns the bounding box value, it is guaranteed that the CRS (coordinate reference system) of the returned
 * {@link Envelope} is supported for this parameter (according to the process description).
 *
 * @return the value
 */
public Envelope getValue();

Similarly, the BoundingBoxOutput type offers the following methods:

/**
 * Sets the value for this output parameter of the {@link Processlet} execution.
 *
 * @param lowerX
 * @param lowerY
 * @param upperX
 * @param upperY
 * @param crsName
 */
public void setValue( double lowerX, double lowerY, double upperX, double upperY, String crsName );

/**
 * Sets the value for this output parameter of the {@link Processlet} execution.
 *
 * @param lower
 * @param upper
 * @param crsName
 */
public void setValue( double[] lower, double[] upper, String crsName );

/**
 * Sets the value for this output parameter of the {@link Processlet} execution.
 *
 * @param value
 *            value to be set
 */
public void setValue( Envelope value );

14.1.6.5. Complex parameters

Complex input and output parameter definitions have the following additional options:

Option Cardinality Value Description
@maximumMegabytes 0..n Integer Maximum file size, in megabytes (only for inputs)
DefaultFormat 1 Complex Definition of the default XML or binary format
OtherFormats 0..n Complex Definition of an alternative XML or binary format

A complex format (DefaultFormat/OtherFormat) is defined via three attributes (compare with the WPS 1.0.0 specification):

Option Cardinality Value Description
@mimeType 0..1 String Mime type of the content, default: unspecified
@encoding 0..1 String Encoding of the content, default: unspecified
@schema 0..1 String XML schema of the content, default: unspecified

In order to work with a ComplexInput parameter in the Processlet code, the corresponding Java type offers the following methods:

/**
 * Returns the mime type of the input.
 *
 * @return the mime type of the input, may be <code>null</code>
 */
public String getMimeType();

/**
 * Returns the encoding information supplied with the input.
 *
 * @return the encoding information supplied with the input, may be <code>null</code>
 */
public String getEncoding();

/**
 * Returns the schema URL supplied with the input.
 *
 * @return the schema URL supplied with the input, may be <code>null</code>
 */
public String getSchema();

/**
 * Returns an {@link InputStream} for accessing the complex value as a raw stream of bytes (usually for binary
 * input).
 * <p>
 * NOTE: Never use this method if the input parameter is encoded in XML -- use {@link #getValueAsXMLStream()}
 * instead. Otherwise erroneous behaviour has to be expected (if the input value is given embedded in the execute
 * request document).
 * </p>
 *
 * @see #getValueAsXMLStream()
 * @return the input value as a raw stream of bytes
 * @throws IOException
 *             if accessing the value fails
 */
public InputStream getValueAsBinaryStream()
                        throws IOException;

/**
 * Returns an {@link XMLStreamReader} for accessing the complex value as an XML event stream.
 * <p>
 * NOTE: Never use this method if the input parameter is a binary value -- use {@link #getValueAsBinaryStream()}
 * instead.
 * </p>
 * The returned stream will point at the first START_ELEMENT event of the data.
 *
 * @return the input value as an XML event stream, current event is START_ELEMENT (the root element of the data
 *         object)
 * @throws IOException
 *             if accessing the value fails
 * @throws XMLStreamException
 */
public XMLStreamReader getValueAsXMLStream()
                        throws IOException, XMLStreamException;

Similarly, the ComplexOutput type offers the following methods:

/**
 * Returns a stream for writing binary output.
 *
 * @return stream for writing binary output, never <code>null</code>
 */
public OutputStream getBinaryOutputStream();

/**
 * Returns a stream for for writing XML output. The stream is already initialized with a
 * {@link XMLStreamWriter#writeStartDocument()}.
 *
 * @return a stream for writing XML output, never <code>null</code>
 * @throws XMLStreamException
 */
public XMLStreamWriter getXMLStreamWriter()
                        throws XMLStreamException;

/**
 * Returns the requested mime type for the complex value, it is guaranteed that the mime type is supported for this
 * parameter (according to the process description).
 *
 * @return the requested mime type, never <code>null</code> (as each complex output format has a default mime type)
 */
public String getRequestedMimeType();

/**
 * Returns the requested XML format for the complex value (specified by a schema URL), it is guaranteed that the
 * format is supported for this parameter (according to the process description).
 *
 * @return the requested schema (XML format), may be <code>null</code> (as a complex output format may omit schema
 *         information)
 */
public String getRequestedSchema();

/**
 * Returns the requested encoding for the complex value, it is guaranteed that the encoding is supported for this
 * parameter (according to the process description).
 *
 * @return the requested encoding, may be <code>null</code> (as a complex output format may omit encoding
 *         information)
 */
public String getRequestedEncoding();

14.1.7. Asynchronous execution and status information

The WPS protocol offers support for asynchronous execution of processes as well as providing status information for long running processes. The following two options of the Java process provider deal with this:

  • @storeSupported: If the storeSupported attribute is set to true, asynchronous execution of the process will be possible. A WPS client can then choose between synchronous execution (default) and asynchronous execution. Note that this doesn’t add any requirements to the implementation of the Processlet code, this is taken care of automatically by the deegree WPS.
  • @statusSupported: If statusSupported is set to true, the WPS will announce that the process can provide status information, i.e. execution percentage. In order for this to work, the Processlet code has to provide status information.

14.1.7.1. Providing status information in the Processlet code

The third parameter that’s passed to the execute(...) method is of type ProcessletExecutionInfo. This type provides the following methods:

/**
 * Allows the {@link Processlet} to indicate the percentage of the process that has been completed, where 0 means
 * the process has just started, and 99 means the process is almost complete. This value is expected to be accurate
 * to within ten percent.
 *
 * @param percentCompleted
 *            the percentage value to be set, a number between 0 and 99
 */
public void setPercentCompleted( int percentCompleted );

/**
 * Allows the {@link Processlet} to provide a custom started message for the client.
 *
 * @param message
 */
public void setStartedMessage( String message );

/**
 * Allows the {@link Processlet} to provide a custom finished message for the client.
 *
 * @param message
 */
public void setSucceededMessage( String message );

Tip

Depending on the type of computation that a Processlet performs, it may or may not be trivial to provide correct progress information via setPercentCompleted(...).

Table Of Contents

Previous topic

13. Server connections

Next topic

15. Coordinate reference systems

This Page

Navigation

© Copyright 2013, The deegree project. Created using Sphinx 1.1.3.