WPS

The WPS module provides a “WPS client” API so programmers can easily build Web Process Service requests and parse the responses. This module allows developers to create getCapabilities, describeProcess and execute requests for WPS servers send requests and parse responses into objects

Maven:

<dependency>
  <groupId>org.geotools</groupId>
  <artifactId>gt-wps</artifactId>
  <version>${geotools.version}</version>
</dependency>

A main design goal of this module is to make the process of building a request and handling the response quick and easy for programmers. By using Process Plugin wrapper classes, developers can easily build and create process requests with just a few lines of code.

The following sections will show the design of this module and some examples of how to use it.

Internally the design of this module is similar to the WMS module with the client code taking care of creating requests, sending requests, and parsing responses.

The following are some of the core objects for this module:

• WebProcessingService

  The main object of the design is the WebProcessingService class. WebProcessingService acts as a proxy for a remote WPS Server and can be used to examine and retrieve information from the server, and to execute processes the server provides. To begin communicating with a server, pass in a URL pointing to a WPS Capabilities document (view examples below).

• WPSFactory

  This class wraps around an AbstractProcessFactory from the Process Plugin. By providing it a ProcessDescriptionType bean (which can be fetched from a WebProcessingService describeProcess request) it will build a Process Factory based on that process definition.

  This factory can then build processes which can be executed (view examples below).

• WPSProcess

  After creating a WPSFactory, you can build processes from it. This class wraps around a AbstractProcess from the Process Plugin. By calling its execute method, it will build up a request object, send it, then parse and return the results.

  By using these wrapper classes, a programmer can quickly build process requests and get results with only a few lines of code (view examples below).

WPS with custom HTTPClient Example

The following example shows how to create a WebProcessingService using a custom implementation of org.geotools.data.ows.HTTPClient:

public class MyWpsHTTPClient implements HTTPClient
{
   @Override
   public abstract org.geotools.data.ows.HTTPResponse post(java.net.URL arg0, java.io.InputStream arg1, java.lang.String arg2) throws java.io.IOException;

   @Override
   public abstract org.geotools.data.ows.HTTPResponse get(java.net.URL arg0) throws java.io.IOException
   {
      //csutom method implementation here...
   }

   @Override
   public abstract java.lang.String getUser();
   {
      //csutom method implementation here...
   }

   @Override
   public abstract void setUser(java.lang.String arg0);
   {
      //csutom method implementation here...
   }

   @Override
   public abstract java.lang.String getPassword();
   {
      //csutom method implementation here...
   }

   @Override
   public abstract void setPassword(java.lang.String arg0);
   {
      //csutom method implementation here...
   }

   @Override
   public abstract int getConnectTimeout();
   {
      //csutom method implementation here...
   }

   @Override
   public abstract void setConnectTimeout(int arg0);
   {
      //csutom method implementation here...
   }

   @Override
   public abstract int getReadTimeout();
   {
      //csutom method implementation here...
   }

   @Override
   public abstract void setReadTimeout(int arg0);
   {
      //csutom method implementation here...
   }
}

It’s possible now to allow the WebProcessingService make use of MyWpsHTTPClient by simply passing it to the class Constructor.:

wps = new WebProcessingService(url, new MyWpsHTTPClient(), null);

Notice also that GeoTools already has an available implementation of HTTPClient which may be used for the most common cases, allowing also Basic authentication.:

org.geotools.data.ows.SimpleHttpClient

WPS getCapabilties Example

The following example shows how to create a WebProcessingService and use it to retrieve a getCapabilities document.:

URL url = new URL("http://localhost:8080/geoserver/ows?service=WPS&request=GetCapabilities");
WebProcessingService wps = new WebProcessingService(url);
WPSCapabilitiesType capabilities = wps.getCapabilities();

// view a list of processes offered by the server
ProcessOfferingsType processOfferings = capabilities.getProcessOfferings();
EList processes = processOfferings.getProcess();

You can now iterate over the list of processes the server offers.

WPS describeProcess Example

This example shows how to do a full describeProcess request from a WebProcessingService.:

// create a WebProcessingService as shown above, then do a full describeprocess on my process
DescribeProcessRequest descRequest = wps.createDescribeProcessRequest();
descRequest.setIdentifier("DoubleAddition"); // describe the double addition process

// send the request and get the ProcessDescriptionType bean to create a WPSFactory
DescribeProcessResponse descResponse = wps.issueRequest(descRequest);
ProcessDescriptionsType processDesc = descResponse.getProcessDesc();
ProcessDescriptionType pdt = (ProcessDescriptionType) processDesc.getProcessDescription().get(0);
WPSFactory wpsfactory = new WPSFactory(pdt, url);

// create a process
Process process = wpsfactory.create();

You now have a process built from the describeProcess description, which can be executed as shown below.

WPS Execute Example

This example builds from the previous ones and shows how to send a request to execute a simple “double addition” process.:

// create a WebProcessingService, WPSFactory and WPSProcess as shown above and execute it
Process process = wpsfactory.create();

// setup the inputs
Map<String, Object> map = new TreeMap<String, Object>();
Double d1 = 77.5;
Double d2 = 22.3;
map.put("input_a", d1);
map.put("input_b", d2);

// you could validate your inputs against what the process expected by checking
// your map against the Parameters in wpsfactory.getParameterInfo(), but
// to keep this simple let's just try sending the request without validation
Map<String, Object> results = process.execute(map, null);

Double result = (Double) results.get("result");

Now you you have a result that was calculated on the WPS server.

WPS getExecutionResponse Example

This example shows how to ask to the WPS for the status of a process request and handle the different status codes.:

WebProcessingService wps = new WebProcessingService(
    new URL(storedRequestURL),
    this.wpsHTTPClient,
    null);

GetExecutionStatusRequest execRequest = wps.createGetExecutionStatusRequest();
execRequest.setIdentifier(this.wpsProcessIdentifier);

GetExecutionStatusResponse response = wps.issueRequest(execRequest);

// Checking for Exceptions and Status...
if ((response.getExceptionResponse() == null) && (response.getExecuteResponse() != null))
{
    if (response.getExecuteResponse().getStatus().getProcessSucceeded() != null)
    {
        // Process complete ... checking output
        for (Object processOutput : response.getExecuteResponse().getProcessOutputs().getOutput())
        {
            OutputDataType wpsOutput = (OutputDataType) processOutput;
            // retrieve the value of the output ...
            wpsOutput.getData().getLiteralData().getValue();
        }
        else if (response.getExecuteResponse().getStatus().getProcessFailed() != null)
        {
            // Process failed ... handle failed status
        }
        else if (response.getExecuteResponse().getStatus().getProcessStarted() != null)
        {
            // Updating status percentage...
            int percentComplete =
                response.getExecuteResponse().getStatus().getProcessStarted().getPercentCompleted().intValue();
        }
    }
    else
    {
        // Retrieve here the Exception message and handle the errored status ...
    }