org.deegree.protocol.wps.client
Class WPSClient

java.lang.Object
  org.deegree.protocol.wps.client.WPSClient

public class WPSClient
extends Object

API-level client for accessing services that implement the WebProcessingService (WPS) 1.0.0 protocol.

Initialization

In the initial step, one constructs a new WPSClient instance by invoking the constructor with a URL to a WPS capabilities document. In most cases, this will be a GetCapabilities request (including necessary parameters) to a WPS service.

 ...
   URL capabilitiesUrl = new URL( "http://...?service=WPS&version=1.0.0&request=GetCapabilities" );
   WPSClient wpsClient = new WPSClient( capabilitiesUrl );
 ...
 

Afterwards, the WPSClient instance is bound to the specified service and allows to access announced service metadata, process information as well as the execution of processes.

Accessing service metadata

The method getMetadata() allows to access the metadata announced by the service, such as title, abstract, provider etc.

Getting process information

The method getProcesses() allows to find out about the processes offered by the service. Additionally (if one knows the identifier of a process beforehand), one can use getProcess(String) or getProcess(String, String) to retrieve a specific process. The Process class allows to execute a process and offers methods to access detail information such as title, abstract, input parameter types and output parameters types:

 ...
   Process buffer = wpsClient.getProcess ("Buffer");
   System.out.println ("Abstract for Buffer process: " + buffer.getAbstract());
   System.out.println ("Number of input parameters: " + buffer.getInputTypes().length);
   System.out.println ("Number of output parameters: " + buffer.getOutputTypes().length);
 ...
 

Executing a process

When executing a request, the method Process.prepareExecution() must be used to create a ProcessExecution context first. This context provides methods for setting the input parameters, controlling the desired output parameter behaviour and invoking the execution.

 ...
   Process buffer = wpsClient.getProcess ("Buffer");
 
   // get execution context
   ProcessExecution execution = buffer.prepareExecution();
   
   // add input parameters
   execution.addLiteralInput( "BufferDistance", null, "0.1", "double", "unity" );
   execution.addXMLInput( "GMLInput", null, gmlFileUrl, "text/xml", null, null );
   
   // perform execution
   ExecutionOutputs outputs = execution.execute();
   
   // access individual output values
   ComplexOutput bufferedGeometry = outputs.getXML ("BufferedGeometry", null);
   XMLStreamReader xmlStream = bufferedGeometry.getAsXMLStream();
 ...
 

Providing input

Input is straightforwardly specified for the literal and bbox cases:

AbstractProcessExecution.addLiteralInput(String, String, String, String, String) respectively

AbstractProcessExecution.addBBoxInput(String, String, double[], double[], String)

 ...
   execution.addLiteralInput( "BufferDistance", null, "0.1", "double", "unity" );
   execution.addBBoxInput( "BBOXInput", null, new double[] { 0, 0 }, new double[] { 90, 180 }, "EPSG:4326" );
 ...
 

For complex data however, the are methods that provide XML and binary data separately. One can provide the input as reference by giving an URL and whether it is external (using http, ftp, etc. protocols) or local (file protocol).
AbstractProcessExecution.addXMLInput(String, String, URL, boolean, String, String, String) and respectively

AbstractProcessExecution.addBinaryInput(String, String, URL, boolean, String, String)

 ...
   URL externalURL = new URL( "http://..." );
   execution.addXMLInput( "XMLInput1", null, externalURL, true, "text/xml", null, null );
   URL localURL = new URL( "file:/home/musterman/xmlInput.xml" );
   execution.addXMLInput( "XMLInput2", null, localURL, false, "text/xml", null, null );
   
   // and for binary data, as local file
   execution.addBinaryInput( "BinaryInput1", null, localBinaryURL, false, "image/png", null );
   // OR, from the web
   execution.addBinaryInput( "BinaryInput2", null, externalBinaryURL, true, "image/png", null );
 ...
 

Alternatively, one can simply provide the input inline as stream. In the case of XML it will be a XMLStreamReader, while for the binary data expected will be an InputStream.

AbstractProcessExecution.addXMLInput(String, String, XMLStreamReader, String, String, String) respectively

AbstractProcessExecution.addBinaryInput(String, String, java.io.InputStream, String, String)

 ...
   execution.addXMLInput( "XMLInput", null, reader, "text/xml", null, null );
   // respectively, in the case of binary input
   execution.addBinaryInput( "BinaryInput", null, is, "image/png", null );
 ...
 

Controlling output

By omitting to set the outputs, the process will generate the default ones, as specified in the process definition. However, the user can take control on precisely what outputs he/she wants by using ProcessExecution.addOutput(String, String, String, boolean, String, String, String) and specifying the id of the respective wanted output. Among the parameters there is the possibility of specifying to retrieve the output as reference or inline.

 ...
      // BBOXOutput will be returned inline
      execution.addOutput( "BBOXOutput", null, null, false, null, null, null );
      // BinaryOutput will be returned as reference 
      execution.addOutput( "BinaryOutput", null, null, true, null, null, null );
      // the other (not specified) outputs will be skipped.
 ...
 

Executing a process: raw output mode

There is also the possibility of selecting the WPS RawOutput mode, where the (single) output parameter is not going to be wrapped in an ExecuteResponse XML document, but directly returned as a resource. For this one must set Process.prepareRawExecution() to retrieve a suitable execution context. The server shall respond with this sole output resource.

 ...
   Process buffer = wpsClient.getProcess ("Buffer");
 
   // get raw execution context
   RawProcessExecution execution = buffer.prepareRawExecution();
   
   // add input parameters
   execution.addLiteralInput( "BufferDistance", null, "0.1", "double", "unity" );
   execution.addXMLInput( "GMLInput", null, gmlFileUrl, "text/xml", null, null );
   
   // invoke RawOutput mode execution (returns a single output parameter)
   ComplexOutput output = execution.execute("GMLOutput", null, "text/xml", null, null);
 ...
 

Executing a process: asynchronous mode

Instead of using ProcessExecution.execute(), one can also request asynchronous execution via the ProcessExecution.executeAsync() method. In the latter case, the call will return immediately, but the result is not necessarily available yet. In order to check for completion, the ProcessExecution.getState() is available, that will poll the server for the current status (if it wasn't finished anyway). Additionally, the method ProcessExecution.getPercentCompleted() is available to check the execution progress (if the process supports it).

 ...
   Process buffer = wpsClient.getProcess ("Buffer");
 
   // get execution context
   ProcessExecution execution = buffer.prepareExecution();
   
   // add input parameters
   execution.addLiteralInput( "BufferDistance", null, "0.1", "double", "unity" );
   execution.addXMLInput( "GMLInput", null, gmlFileUrl, "text/xml", null, null );
   
   // invoke asynchronous execution (returns immediately)
   execution.executeAsync();
   
   // do other stuff
   ...
   
   // check execution state
   if (execution.getState() == SUCCEEDED) {
       ExecutionOutputs outputs = execution.getOutputs();
       ...
       // access the outputs as in synchronous case
       ComplexOutput bufferedGeometry = outputs.getXML ("BufferedGeometry", null);
       XMLStreamReader xmlStream = bufferedGeometry.getAsXMLStream();
   }
 ...
 

Implementation notes

• Supported protocol versions: WPS 1.0.0
• The implementation is thread-safe, a single WPSClient instance can be shared among multiple threads.

TODOs

• Implement input parameter passing for POST-references.
• Cope with exceptions reports that are returned for GetCapabilities and DescribeProcess requests.
• Determine the correct XML encoding for HTTP-requests/responses, see http://www.ietf.org/rfc/rfc2376.txt
• Clean up exception handling.
• Enable/document a way to set connection parameters (timeout, proxy settings, ...)
• Support metadata in multiple languages (as mandated by the WPS spec).
• Check validity (cardinality, order) of input and output parameters in ProcessExecution.

Version:

$Revision: 31815 $, $Date: 2011-09-07 17:26:03 +0200 (Wed, 07 Sep 2011) $

Author:

Georg Walenciak, Johannes Wilden, Andrei Ionita, Markus Schneider, last edited by: $Author: mschneider $

See Also:

Process, ProcessExecution

Constructor Summary

WPSClient(URL capabilitiesURL)
Creates a new WPSClient instance.

Method Summary

URL	getDescribeProcessURL(boolean post) Returns the URL announced by the service for issuing DescribeProcess requests.
URL	getExecuteURL(boolean post) Returns the URL announced by the service for issuing Execute requests.
OWSCapabilities	getMetadata() Returns the metadata (ServiceIdentification, ServiceProvider) of the service.
Process	getProcess(String id) Returns the specified process instance (ignoring the codespace of the identifier).
Process	getProcess(String id, String idCodeSpace) Returns the specified process instance.
Process[]	getProcesses() Returns all processes offered by the service.
String	getServiceVersion() Returns the WPS protocol version in use.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

WPSClient

public WPSClient(URL capabilitiesURL)
          throws OWSExceptionReport,
                 IOException

Creates a new WPSClient instance.

Parameters:

capabilitiesURL - url of a WPS capabilities document, usually this is a GetCapabilities request to a WPS service, must not be null

Throws:

OWSException - if the server replied with an exception

IOException - if a communication/network problem occured

OWSExceptionReport

Method Detail

getServiceVersion

public String getServiceVersion()

Returns the WPS protocol version in use.

NOTE: Currently, this is always "1.0.0" (as the client only supports this version).

Returns:

the WPS protocol version in use, never null

getMetadata

public OWSCapabilities getMetadata()

Returns the metadata (ServiceIdentification, ServiceProvider) of the service.

Returns:

the metadata of the service, never null

getProcesses

public Process[] getProcesses()

Returns all processes offered by the service.

Returns:

all processes offered by the service, may be empty, but never null

getProcess

public Process getProcess(String id)

Returns the specified process instance (ignoring the codespace of the identifier).

NOTE: This is a convenience method that ignores the optional codespace that a process identifier may have. If a server actually offers two processes with the same identifier, but different codespace, let's say 'Buffer' (codespace: 'Sextante') and 'Buffer' (codespace: 'GRASS'), then it's not defined which of the ones will be returned, when this method is called with parameter 'Buffer'. To be on the safe side, use getProcess(String, String).

Parameters:

id - process identifier, never null

Returns:

process instance, can be null (if no process with the specified identifier and code space is offered by the services)

getProcess

public Process getProcess(String id,
                          String idCodeSpace)

Returns the specified process instance.

Parameters:

id - process identifier, never null

idCodeSpace - codespace of the process identifier, may be null (for identifiers that don't use a code space)

Returns:

process instance, can be null (if no process with the specified identifier and code space is offered by the services)

getDescribeProcessURL

public URL getDescribeProcessURL(boolean post)

Returns the URL announced by the service for issuing DescribeProcess requests.

Parameters:

post - if set to true, the URL for POST requests will be returned, otherwise the URL for GET requests will be returned

Returns:

the DescribeProcess URL, may be null (if the server doesn't provide a binding for the specified request method)

getExecuteURL

public URL getExecuteURL(boolean post)

Returns the URL announced by the service for issuing Execute requests.

Parameters:

post - if set to true, the URL for POST requests will be returned, otherwise the URL for GET requests will be returned

Returns:

the Execute URL, may be null (if the server doesn't provide a binding for the specified request method)