com.luciad.ogc.wfs.client

LuciadLightspeedClass TLcdWFSClient

java.lang.Object

com.luciad.ogc.wfs.client.TLcdWFSClient

public class TLcdWFSClient
extends Object

The TLcdWFSClient class represents a client interface to an OpenGIS WFS server. The supported WFS versions are 1.0.0, 1.1.0 and 2.0.0.

A new TLcdWFSClient instance can be created by invoking one of the static factory methods, given a URI of the server or an TLcdWFSCapabilities object representing the server's capabilities. To customize the communication between client and server, an ILcdOWSTransport can optionally be provided. This interface represents the transport layer, and can be used to choose the communication protocol (HTTP GET, HTTP POST, ...), add authentication, or configure any other parameter that relates to the communication channel. By default, an instance of TLcdOWSHttpTransport is used.

Once a TLcdWFSClient instance is initialized, the following requests can be created:

• GetCapabilities: createGetCapabilitiesRequest()
• GetFeature: createGetFeatureRequest()
• DescribeFeatureType: createDescribeFeatureTypeRequest()
• LockFeature: createLockFeatureRequest()
• GetFeatureWithLock: createGetFeatureWithLockRequest()
• Transaction: createTransactionRequest()

To send requests to the server and receive the response, the following methods can be used:

• GetCapabilities: getCachedCapabilities() or getCapabilities(TLcdWFSGetCapabilitiesRequest)
• GetFeature: getFeature(TLcdWFSGetFeatureRequest)
• DescribeFeatureType: describeFeatureType(TLcdWFSDescribeFeatureTypeRequest)
• LockFeature: lockFeature(TLcdWFSLockFeatureRequest)
• GetFeatureWithLock: getFeatureWithLock(TLcdWFSGetFeatureWithLockRequest)
• Transaction: transaction(TLcdWFSTransactionRequest)

Upon initialization, TLcdWFSClient automatically performs a version negotiation process with the server to agree on the version number. All created requests are initialized with the agreed version number, and should therefore only be used by the TLcdWFSClient instance that created them.

Since:

8.2

See Also:

TLcdOWSHttpTransport, TLcdWFSGetCapabilitiesRequest, TLcdWFSGetFeatureRequest, TLcdWFSDescribeFeatureTypeRequest, TLcdWFSLockFeatureRequest, TLcdWFSGetFeatureWithLockRequest, TLcdWFSTransactionRequest

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	TLcdWFSClient(TLcdWFSCapabilities aCapabilities, ILcdOWSTransport aTransport) Creates a new TLcdWFSClient with the given parameters.
protected	TLcdWFSClient(URI aURI, ILcdOWSTransport aTransport, Object aTransportData) Creates a new TLcdWFSClient with the given parameters.

Method Summary

Modifier and Type	Method and Description
TLcdWFSDescribeFeatureTypeRequest	createDescribeFeatureTypeRequest() Creates a new 'DescribeFeatureType' request object which is compatible with the WFS version implemented by the WFS server this client communicates with.
TLcdWFSGetCapabilitiesRequest	createGetCapabilitiesRequest() Creates a new 'GetCapabilities' request object which is compatible with the WFS version implemented by the WFS server this client communicates with.
TLcdWFSGetFeatureRequest	createGetFeatureRequest() Creates a new 'GetFeature' request object which is compatible with the WFS version implemented by the WFS server this client communicates with.
TLcdWFSGetFeatureWithLockRequest	createGetFeatureWithLockRequest() Creates a new 'GetFeatureWithLock' request object which is compatible with the WFS version implemented by the WFS server this client communicates with.
TLcdWFSLockFeatureRequest	createLockFeatureRequest() Creates a new 'LockFeature' request object which is compatible with the WFS version implemented by the WFS server this client communicates with.
TLcdWFSTransactionRequest	createTransactionRequest() Creates a new 'Transaction' request object which is compatible with the WFS version implemented by the WFS server this client communicates with.
static TLcdWFSClient	createWFSClient(TLcdWFSCapabilities aCapabilities, ILcdOWSTransport aTransport) Creates a new WFS client using the specified capabilities.
static TLcdWFSClient	createWFSClient(URI aURI) Creates a new WFS client using the specified URI.
static TLcdWFSClient	createWFSClient(URI aURI, ILcdOWSTransport aTransport, Object aTransportData) Creates a new WFS client using the specified URI.
protected List	decodeOperations(TLcdWFSCapabilities aCapabilities) Returns a list of TLcdOWSOperation instances based on the contents of the provided TLcdWFSCapabilities instance.
TLcdOWSInputStream	describeFeatureType(TLcdWFSDescribeFeatureTypeRequest aRequest) Performs the 'DescribeFeatureType' request.
TLcdWFSCapabilities	getCachedCapabilities() Returns the most recent capabilities object that was requested by this client.
TLcdWFSCapabilities	getCapabilities(TLcdWFSGetCapabilitiesRequest aRequest) Performs the 'GetCapabilities' request.
TLcdOWSInputStream	getFeature(TLcdWFSGetFeatureRequest aRequest) Performs the 'GetFeature' request.
TLcdOWSInputStream	getFeatureWithLock(TLcdWFSGetFeatureWithLockRequest aRequest) Performs the 'GetFeatureWithLock' request.
protected TLcdOWSOperation	getOperation(String aOperationName) Retrieves an operation based on the operation name.
URI	getURI() Returns the URI of the WFS server.
TLcdWFSLockFeatureResponse	lockFeature(TLcdWFSLockFeatureRequest aRequest) Performs the 'LockFeature' request.
protected TLcdOWSInputStream	performRequest(String aOperationName, ILcdOWSRequest aRequest) Performs a WFS request.
String	toString()
TLcdWFSTransactionResponse	transaction(TLcdWFSTransactionRequest aRequest) Performs the 'Transaction' request.

Methods inherited from class java.lang.Object

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

Constructor Detail

TLcdWFSClient

protected TLcdWFSClient(TLcdWFSCapabilities aCapabilities,
                        ILcdOWSTransport aTransport)
                 throws TLcdOWSDecodingException,
                        TLcdOWSTransportException,
                        TLcdOWSServerException,
                        TLcdOWSUnsupportedVersionException

Creates a new TLcdWFSClient with the given parameters.

Parameters:

aCapabilities - the capabilities of the WFS server

aTransport - the transport to use

Throws:

TLcdOWSDecodingException - if an error occurs while decoding the initial WFS response

TLcdOWSServerException - if an exception report is received from the server

TLcdOWSTransportException - if an error occurs in the transport layer while negotiation the version

TLcdOWSUnsupportedVersionException - if the specified WFS server does not support any of the WFS versions implemented by this client

TLcdWFSClient

protected TLcdWFSClient(URI aURI,
                        ILcdOWSTransport aTransport,
                        Object aTransportData)
                 throws TLcdOWSDecodingException,
                        TLcdOWSTransportException,
                        TLcdOWSServerException,
                        TLcdOWSUnsupportedVersionException

Creates a new TLcdWFSClient with the given parameters.

Parameters:

aURI - the URI of the WFS server

aTransport - the transport to use

aTransportData - the transport data to use for the initial capabilities requests (may be null)

Throws:

IllegalArgumentException - if the specified URI is not compatible with the specified transport

TLcdOWSDecodingException - if an error occurs while decoding the initial WFS response

TLcdOWSServerException - if an exception report is received from the server

TLcdOWSTransportException - if an error occurs in the transport layer while negotiation the version

TLcdOWSUnsupportedVersionException - if the specified WFS server does not support any of the WFS versions implemented by this client

Method Detail

createWFSClient

public static TLcdWFSClient createWFSClient(URI aURI)
                                     throws TLcdOWSTransportException,
                                            TLcdOWSServerException,
                                            TLcdOWSDecodingException,
                                            TLcdOWSUnsupportedVersionException

Creates a new WFS client using the specified URI. The WFS client will use the default transport (HTTP).

Parameters:

aURI - the URI of the WFS server

Returns:

a new WFS client

Throws:

NullPointerException - if the URI is null

IllegalArgumentException - if the specified URI is not compatible with the default transport

TLcdOWSDecodingException - if an error occurs while decoding the intial WFS response

TLcdOWSServerException - if an exception report is received from the server

TLcdOWSTransportException - if an error occurs in the transport layer while negotiation the version

TLcdOWSUnsupportedVersionException - if the specified WFS server does not support any of the WFS versions implemented by this client

See Also:

createWFSClient(java.net.URI, ILcdOWSTransport, Object)

createWFSClient

public static TLcdWFSClient createWFSClient(TLcdWFSCapabilities aCapabilities,
                                            ILcdOWSTransport aTransport)
                                     throws TLcdOWSUnsupportedVersionException,
                                            TLcdOWSDecodingException,
                                            TLcdOWSServerException,
                                            TLcdOWSTransportException

Creates a new WFS client using the specified capabilities. The WFS client will use the specified transport. If the version number of the capabilities is supported, a WFS client is initiated with the given capabilities. If the version number is not supported, this method performs the version negotiation process described in the WFS specification. The WFS client returned by this method is guaranteed to be compatible with the WFS version supported by the WFS server.

Parameters:

aCapabilities - the capabilities of the WFS server

aTransport - the transport to use

Returns:

a new WFS client

Throws:

NullPointerException - if either the capabilities or the transport is null

TLcdOWSDecodingException - if an error occurs while decoding the intial WFS response

TLcdOWSServerException - if an exception report is received from the server

TLcdOWSTransportException - if an error occurs in the transport layer while negotiation the version

TLcdOWSUnsupportedVersionException - if the specified WFS server does not support any of the WFS versions implemented by this client

createWFSClient

public static TLcdWFSClient createWFSClient(URI aURI,
                                            ILcdOWSTransport aTransport,
                                            Object aTransportData)
                                     throws TLcdOWSUnsupportedVersionException,
                                            TLcdOWSDecodingException,
                                            TLcdOWSServerException,
                                            TLcdOWSTransportException

Creates a new WFS client using the specified URI. The WFS client will use the specified transport. This method will retrieve the capabilities description from the WFS server at the specified URI. Depending on the response of the WFS server this method will then perform the version negotiation process described in the WFS specification. These initial capabilities requests will use the specified transport data, if not null. Transport data can for example be used to supply authentication information, if required by the server. The WFS client returned by this method is guaranteed to be compatible with the WFS version supported by the WFS server.

Parameters:

aURI - the URI of the WFS server

aTransport - the transport to use

aTransportData - the transport data to use for the initial capabilities requests (may be null)

Returns:

a new WFS client

Throws:

NullPointerException - if either the URI or the transport is null

IllegalArgumentException - if the specified URI is not compatible with the specified transport

TLcdOWSDecodingException - if an error occurs while decoding the intial WFS response

TLcdOWSServerException - if an exception report is received from the server

TLcdOWSTransportException - if an error occurs in the transport layer while negotiation the version

TLcdOWSUnsupportedVersionException - if the specified WFS server does not support any of the WFS versions implemented by this client

getURI

public URI getURI()

Returns the URI of the WFS server. If no URI was specified at construction, the URI is determined from the capabilities: as each OGC Web Service should support a GetCapabilities request, the address associated with this request is used. If the GET request method is supported, the corresponding address is used; otherwise, it is assumed that the POST request method is supported and the corresponding address is used; if this check also fails, null is returned and the client will not be able to connect with the WFS server.

Returns:

the URI of the WFS server.

getOperation

protected final TLcdOWSOperation getOperation(String aOperationName)

Retrieves an operation based on the operation name.

Parameters:

aOperationName - the name of the operation

Returns:

the operation or null if the requested operation is not supported by the WFS server

decodeOperations

protected List decodeOperations(TLcdWFSCapabilities aCapabilities)

Returns a list of TLcdOWSOperation instances based on the contents of the provided TLcdWFSCapabilities instance. By default, this method will return a list of operations that are read from the 'Capability/Request' section of the WFS capabilities object.

Parameters:

aCapabilities - the capabilities from which to derive the list of operations

Returns:

a list of TLcdOWSOperation instances or an empty list if no operations are available

createGetCapabilitiesRequest

public TLcdWFSGetCapabilitiesRequest createGetCapabilitiesRequest()

Creates a new 'GetCapabilities' request object which is compatible with the WFS version implemented by the WFS server this client communicates with.

Returns:

a new 'GetCapabilities' request

createDescribeFeatureTypeRequest

public TLcdWFSDescribeFeatureTypeRequest createDescribeFeatureTypeRequest()

Creates a new 'DescribeFeatureType' request object which is compatible with the WFS version implemented by the WFS server this client communicates with.

Returns:

a new 'DescribeFeatureType' request

createGetFeatureRequest

public TLcdWFSGetFeatureRequest createGetFeatureRequest()

Creates a new 'GetFeature' request object which is compatible with the WFS version implemented by the WFS server this client communicates with.

Returns:

a new 'GetFeature' request

createTransactionRequest

public TLcdWFSTransactionRequest createTransactionRequest()

Creates a new 'Transaction' request object which is compatible with the WFS version implemented by the WFS server this client communicates with.

Returns:

a new 'Transaction' request

Since:

10.0

createLockFeatureRequest

public TLcdWFSLockFeatureRequest createLockFeatureRequest()

Creates a new 'LockFeature' request object which is compatible with the WFS version implemented by the WFS server this client communicates with.

Returns:

a new 'LockFeature' request

Since:

10.0

createGetFeatureWithLockRequest

public TLcdWFSGetFeatureWithLockRequest createGetFeatureWithLockRequest()

Creates a new 'GetFeatureWithLock' request object which is compatible with the WFS version implemented by the WFS server this client communicates with.

Returns:

a new 'GetFeatureWithLock' request

Since:

10.0

getCachedCapabilities

public TLcdWFSCapabilities getCachedCapabilities()

Returns the most recent capabilities object that was requested by this client. The client will update the capabilities when it is first created and every time getCapabilities(TLcdWFSGetCapabilitiesRequest) is called.

Returns:

the capabilities of the WFS service

getCapabilities

public TLcdWFSCapabilities getCapabilities(TLcdWFSGetCapabilitiesRequest aRequest)
                                    throws TLcdOWSServerException,
                                           TLcdOWSDecodingException,
                                           TLcdOWSTransportException,
                                           TLcdOWSUnsupportedVersionException

Performs the 'GetCapabilities' request.

Parameters:

aRequest - the request object containing the parameters to pass to the WFS server

Returns:

the capabilities of the WFS service

Throws:

TLcdOWSServerException - if the server returned an OpenGIS Web Service exception

TLcdOWSDecodingException - if an error occurred while decoding the 'GetCapabilities' response

TLcdOWSTransportException - if an error occurred in the transport while accessing the web service

TLcdOWSUnsupportedVersionException - if the server only supports WFS specification versions that are not supported by this client

describeFeatureType

public TLcdOWSInputStream describeFeatureType(TLcdWFSDescribeFeatureTypeRequest aRequest)
                                       throws TLcdOWSServerException,
                                              TLcdOWSDecodingException,
                                              TLcdOWSTransportException

Performs the 'DescribeFeatureType' request.

Parameters:

aRequest - the request object containing the parameters to pass to the WFS server

Returns:

a description of the feature types specified in the request object

Throws:

TLcdOWSServerException - if the server returned an OpenGIS Web Service exception

TLcdOWSDecodingException - if an error occurred while decoding the 'DescribeFeatureType' response

TLcdOWSTransportException - if an error occurred in the transport while accessing the web service

getFeature

public TLcdOWSInputStream getFeature(TLcdWFSGetFeatureRequest aRequest)
                              throws TLcdOWSServerException,
                                     TLcdOWSDecodingException,
                                     TLcdOWSTransportException

Performs the 'GetFeature' request.

If GML is used as exchange format (default), the returned stream can be decoded into an ILcdModel using a TLcdWFSModelDecoderDecorator. Next to supporting the GML output from a WFS, this class also supports the handling of service exception reports.

Parameters:

aRequest - the request object containing the parameters to pass to the WFS server

Returns:

an inputstream containing the data returned by the WFS server

Throws:

TLcdOWSServerException - if the server returned an OpenGIS Web Service exception

TLcdOWSDecodingException - if an error occurred while decoding the 'GetFeature' response

TLcdOWSTransportException - if an error occurred in the transport while accessing the web service

See Also:

TLcdWFSModelDecoderDecorator

getFeatureWithLock

public TLcdOWSInputStream getFeatureWithLock(TLcdWFSGetFeatureWithLockRequest aRequest)
                                      throws TLcdOWSServerException,
                                             TLcdOWSDecodingException,
                                             TLcdOWSTransportException

Performs the 'GetFeatureWithLock' request.

If GML is used as exchange format (default), the returned stream can be decoded into an ILcdModel using a TLcdWFSModelDecoderDecorator. Next to supporting the GML output from a WFS, this class also supports the handling of service exception reports.

Parameters:

aRequest - the request object containing the parameters to pass to the WFS server

Returns:

an inputstream containing the data returned by the WFS server

Throws:

TLcdOWSServerException - if the server returned an OpenGIS Web Service exception

TLcdOWSDecodingException - if an error occurred while decoding the 'GetFeature' response

TLcdOWSTransportException - if an error occurred in the transport while accessing the web service

See Also:

TLcdWFSModelDecoderDecorator

lockFeature

public TLcdWFSLockFeatureResponse lockFeature(TLcdWFSLockFeatureRequest aRequest)
                                       throws TLcdOWSDecodingException,
                                              TLcdOWSTransportException,
                                              TLcdOWSServerException

Performs the 'LockFeature' request.

Parameters:

aRequest - the request object containing the parameters to pass to the WFS server

Returns:

a TLcdWFSLockFeatureResponse containing the response from the server.

Throws:

TLcdOWSServerException - if the server returned an OpenGIS Web Service exception

TLcdOWSDecodingException - if an error occurred while decoding the 'LockFeature' response

TLcdOWSTransportException - if an error occurred in the transport while accessing the web service

transaction

public TLcdWFSTransactionResponse transaction(TLcdWFSTransactionRequest aRequest)
                                       throws TLcdOWSDecodingException,
                                              TLcdOWSTransportException,
                                              TLcdOWSServerException

Performs the 'Transaction' request.

Parameters:

aRequest - the request object containing the parameters to pass to the WFS server

Returns:

a TLcdWFSTransactionResponse containing the response from the server.

Throws:

TLcdOWSServerException - if the server returned an OpenGIS Web Service exception

TLcdOWSDecodingException - if an error occurred while decoding the 'Transaction' response

TLcdOWSTransportException - if an error occurred in the transport while accessing the web service

performRequest

protected final TLcdOWSInputStream performRequest(String aOperationName,
                                                  ILcdOWSRequest aRequest)
                                           throws TLcdOWSTransportException,
                                                  TLcdOWSServerException,
                                                  TLcdOWSDecodingException

Performs a WFS request.

Parameters:

aOperationName - the name of the operation to invoke

aRequest - the request object that should be sent

Returns:

the response input stream

Throws:

TLcdOWSServerException - if the server returned an OpenGIS Web Service exception

TLcdOWSDecodingException - if an error occurred while decoding the processing the response

TLcdOWSTransportException - if an error occurred in the transport while accessing the web service

toString

public String toString()

Overrides:

toString in class Object