WPSClient (deegree-core 3.0.3 API)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.deegree.protocol.wps.client
Class WPSClient

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

public class WPSClient
extends java.lang.Object
extends java.lang.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 processUrl = new URL( "http://...?service=WPS&version=1.0.0&request=GetCapabilities" );
   WPSClient wpsClient = new WPSClient( processUrl );
 ...

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: 26579 $, $Date: 2010-09-06 15:36:20 +0200 (Mo, 06. Sep 2010) $
Author:: Georg Walenciak, Christian Kiehle, Andrei Ionita, Markus Schneider, last edited by: $Author: lbuesching $
See Also:: Process, ProcessExecution

Constructor Summary
`WPSClient(java.net.URL capabilitiesURL)` Creates a new `WPSClient` instance.

Method Summary
`java.net.URL`	`getDescribeProcessURL(boolean post)` Returns the URL announced by the service for issuing `DescribeProcess` requests.
`java.net.URL`	`getExecuteURL(boolean post)` Returns the URL announced by the service for issuing `Execute` requests.
`ServiceMetadata`	`getMetadata()` Returns the metadata (ServiceIdentification, ServiceProvider) of the service.
`Process`	`getProcess(java.lang.String id)` Returns the specified process instance (ignoring the codespace of the identifier).
`Process`	`getProcess(java.lang.String id, java.lang.String idCodeSpace)` Returns the specified process instance.
`Process[]`	`getProcesses()` Returns all processes offered by the service.
`java.lang.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(java.net.URL capabilitiesURL)
          throws java.io.IOException,
                 OWSException

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:: java.io.IOException - if a communication/network problem occured; OWSException - if the server replied with an exception

Method Detail

getServiceVersion

public java.lang.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 ServiceMetadata 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(java.lang.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(java.lang.String id,
                          java.lang.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 java.net.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 java.net.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)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.deegree.protocol.wps.client Class WPSClient

Initialization

Accessing service metadata

Getting process information

Executing a process

Providing input

Controlling output

Executing a process: raw output mode

Executing a process: asynchronous mode

Implementation notes

TODOs

WPSClient

getServiceVersion

getMetadata

getProcesses

getProcess

getProcess

getDescribeProcessURL

getExecuteURL

org.deegree.protocol.wps.client
Class WPSClient