com.luciad.wms.client.model

LuciadLightspeedClass TLcdWMSClient

java.lang.Object

com.luciad.wms.client.model.TLcdWMSClient

public class TLcdWMSClient
extends Object

The TLcdWMSClient class represents a client interface to an OpenGIS WMS server. The supported WMS versions are 1.1.0, 1.1.1 and 1.3.0.

A new TLcdWMSClient instance can be created by invoking one of the static factory methods, given a URI of the server or an ALcdOGCWMSCapabilities 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 TLcdWMSClient instance is initialized, the following requests can be created:

• GetCapabilities: createGetCapabilitiesRequest()
• GetMap: createGetMapRequest()
• GetFeatureInfo: createGetFeatureInfoRequest()
• DescribeLayer: createDescribeLayerRequest()
• GetLegendGraphic: createGetLegendGraphicRequest()

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

• GetCapabilities: getCachedCapabilities() or getCapabilities(TLcdWMSGetCapabilitiesRequest)
• GetMap: getMap(TLcdWMSGetMapRequest)
• GetFeatureInfo: getFeatureInfo(TLcdWMSGetFeatureInfoRequest)
• DescribeLayer: describeLayer(TLcdWMSDescribeLayerRequest)
• GetLegendGraphic: getLegendGraphic(TLcdWMSGetLegendGraphicRequest)

Upon initialization, TLcdWMSClient 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 TLcdWMSClient instance that created them.

Since:

9.1

See Also:

TLcdOWSHttpTransport, TLcdWMSGetCapabilitiesRequest, TLcdWMSGetMapRequest, TLcdWMSGetFeatureInfoRequest, TLcdWMSDescribeLayerRequest, TLcdWMSGetLegendGraphicRequest

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
TLcdWMSDescribeLayerRequest	createDescribeLayerRequest() Creates a new 'DescribeLayer' request object which is compatible with the WMS version implemented by the WMS server this client communicates with.
TLcdWMSGetCapabilitiesRequest	createGetCapabilitiesRequest() Creates a new 'GetCapabilities' request object which is compatible with the WMS version implemented by the WMS server this client communicates with.
TLcdWMSGetFeatureInfoRequest	createGetFeatureInfoRequest() Creates a new 'GetFeatureInfo' request object which is compatible with the WMS version implemented by the WMS server this client communicates with.
TLcdWMSGetLegendGraphicRequest	createGetLegendGraphicRequest() Creates a new 'GetLegendGraphic' request object which is compatible with the WMS version implemented by the WMS server this client communicates with.
TLcdWMSGetMapRequest	createGetMapRequest() Creates a new 'GetMap' request object which is compatible with the WMS version implemented by the WMS server this client communicates with.
static TLcdWMSClient	createWMSClient(ALcdOGCWMSCapabilities aCapabilities, ILcdOWSTransport aTransport) Creates a new WMS client using the specified capabilities.
static TLcdWMSClient	createWMSClient(URI aURI) Creates a new WMS client using the specified URI.
static TLcdWMSClient	createWMSClient(URI aURI, ILcdOWSTransport aTransport, Object aTransportData) Creates a new WMS client using the specified URI.
protected List	decodeOperations(ALcdOGCWMSCapabilities aCapabilities) Returns a list of TLcdOWSOperation instances based on the contents of the provided ALcdOGCWMSCapabilities instance.
TLcdOWSInputStream	describeLayer(TLcdWMSDescribeLayerRequest aRequest) Performs the 'DescribeLayer' request.
ALcdOGCWMSCapabilities	getCachedCapabilities() Returns the most recent capabilities object that was requested by this client.
ALcdOGCWMSCapabilities	getCapabilities(TLcdWMSGetCapabilitiesRequest aRequest) Performs the 'GetCapabilities' request.
TLcdOWSInputStream	getFeatureInfo(TLcdWMSGetFeatureInfoRequest aRequest) Performs the 'GetFeatureInfo' request.
TLcdOWSInputStream	getLegendGraphic(TLcdWMSGetLegendGraphicRequest aRequest) Performs the 'GetLegendGraphic' request.
TLcdOWSInputStream	getMap(TLcdWMSGetMapRequest aRequest) Performs the 'GetMap' request.
protected TLcdOWSOperation	getOperation(String aOperationName) Retrieves an operation based on the operation name.
URI	getURI() Returns the URI of the WMS server.
protected TLcdOWSInputStream	performRequest(String aOperationName, ILcdOWSRequest aRequest) Performs a WMS request.

Methods inherited from class java.lang.Object

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

Constructor Detail

TLcdWMSClient

protected TLcdWMSClient(ALcdOGCWMSCapabilities aCapabilities,
                        ILcdOWSTransport aTransport)
                 throws TLcdOWSDecodingException,
                        TLcdOWSTransportException,
                        TLcdOWSUnsupportedVersionException

Creates a new TLcdWMSClient with the given parameters.

Parameters:

aCapabilities - the capabilities of the WMS server

aTransport - the transport to use

Throws:

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

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

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

TLcdWMSClient

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

Creates a new TLcdWMSClient with the given parameters.

Parameters:

aURI - the URI of the WMS 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 WMS response

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

TLcdOWSTransportException - if an error occurred in the transportation layer

TLcdOWSServerException - if the server returned a WMS service exception

Method Detail

createWMSClient

public static TLcdWMSClient createWMSClient(URI aURI)
                                     throws TLcdOWSServerException,
                                            TLcdOWSDecodingException,
                                            TLcdOWSTransportException,
                                            TLcdOWSUnsupportedVersionException

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

Parameters:

aURI - the URI of the WMS server

Returns:

a new WMS 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 initial WMS response

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

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

TLcdOWSServerException

createWMSClient

public static TLcdWMSClient createWMSClient(ALcdOGCWMSCapabilities aCapabilities,
                                            ILcdOWSTransport aTransport)
                                     throws TLcdOWSUnsupportedVersionException,
                                            TLcdOWSDecodingException,
                                            TLcdOWSTransportException

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

Parameters:

aCapabilities - the capabilities of the WMS server; both the version (ALcdOGCWMSCapabilities#getVersion) and the URL of the GET access point of the GetCapabilities request (ALcdOGCWMSCapabilities#getOperationsMetadata()#getOperationByName("GetCapabilities").getDCP(0).getHTTP().getGet(0).getHref()) need to be filled in.

aTransport - the transport to use

Returns:

a new WMS client

Throws:

NullPointerException - if either the capabilities or the transport is null

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

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

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

createWMSClient

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

Creates a new WMS client using the specified URI. The WMS client will use the specified transport. This method will retrieve the capabilities description from the WMS server at the specified URI. Depending on the response of the WMS server this method will then perform the version negotiation process described in the WMS 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 WMS client returned by this method is guaranteed to be compatible with the WMS version supported by the WMS server.

Parameters:

aURI - the URI of the WMS server

aTransport - the transport to use

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

Returns:

a new WMS 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 initial WMS response

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

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

TLcdOWSServerException

See Also:

TLcdOGCWMSProxyModelDecoder.setEntityLocation(String, java.net.URL)

getURI

public URI getURI()

Returns the URI of the WMS 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 WMS server.

Returns:

the URI of the WMS server.

getCachedCapabilities

public ALcdOGCWMSCapabilities 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(TLcdWMSGetCapabilitiesRequest) is called.

Returns:

the capabilities of the WMS service

getCapabilities

public ALcdOGCWMSCapabilities getCapabilities(TLcdWMSGetCapabilitiesRequest aRequest)
                                       throws TLcdOWSTransportException,
                                              TLcdOWSServerException,
                                              TLcdOWSDecodingException,
                                              TLcdOWSUnsupportedVersionException

Performs the 'GetCapabilities' request.

Parameters:

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

Returns:

the capabilities of the WMS service

Throws:

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 WMS specification versions that are not supported by this client

TLcdOWSServerException - if the server returned a service exception

getMap

public TLcdOWSInputStream getMap(TLcdWMSGetMapRequest aRequest)
                          throws TLcdOWSDecodingException,
                                 TLcdOWSTransportException,
                                 TLcdOWSServerException

Performs the 'GetMap' request.

Parameters:

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

Returns:

an inputstream containing the data returned by the WMS server

Throws:

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

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

TLcdOWSServerException - if the server returned a service exception

getFeatureInfo

public TLcdOWSInputStream getFeatureInfo(TLcdWMSGetFeatureInfoRequest aRequest)
                                  throws TLcdOWSDecodingException,
                                         TLcdOWSTransportException,
                                         TLcdOWSServerException

Performs the 'GetFeatureInfo' request.

Parameters:

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

Returns:

an inputstream containing the data returned by the WMS server

Throws:

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

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

TLcdOWSServerException - if the server returned a service exception

getLegendGraphic

public TLcdOWSInputStream getLegendGraphic(TLcdWMSGetLegendGraphicRequest aRequest)
                                    throws TLcdOWSDecodingException,
                                           TLcdOWSTransportException,
                                           TLcdOWSServerException

Performs the 'GetLegendGraphic' request.

Parameters:

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

Returns:

an inputstream containing the data returned by the WMS server

Throws:

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

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

TLcdOWSServerException - if the server returned a service exception

describeLayer

public TLcdOWSInputStream describeLayer(TLcdWMSDescribeLayerRequest aRequest)
                                 throws TLcdOWSDecodingException,
                                        TLcdOWSTransportException,
                                        TLcdOWSServerException

Performs the 'DescribeLayer' request.

Parameters:

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

Returns:

an inputstream containing the data returned by the WMS server

Throws:

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

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

TLcdOWSServerException - if the server returned a service exception

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 WMS server.

performRequest

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

Performs a WMS request.

Parameters:

aOperationName - the name of the operation to invoke

aRequest - the request object that should be sent

Returns:

the response input stream

Throws:

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

TLcdOWSServerException - if the server returned a WMS Service exception

TLcdOWSDecodingException - if a decoding error occurred while performing the request

decodeOperations

protected List decodeOperations(ALcdOGCWMSCapabilities aCapabilities)

Returns a list of TLcdOWSOperation instances based on the contents of the provided ALcdOGCWMSCapabilities instance. By default, this method will return a list of operations that are read from the 'Capability/Request' section of the WMS 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

createGetMapRequest

public TLcdWMSGetMapRequest createGetMapRequest()

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

Returns:

a new 'GetMap' request

createGetFeatureInfoRequest

public TLcdWMSGetFeatureInfoRequest createGetFeatureInfoRequest()

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

Returns:

a new 'GetFeatureInfo' request

createGetCapabilitiesRequest

public TLcdWMSGetCapabilitiesRequest createGetCapabilitiesRequest()

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

Returns:

a new 'GetCapabilities' request

createDescribeLayerRequest

public TLcdWMSDescribeLayerRequest createDescribeLayerRequest()

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

Returns:

a new 'DescribeLayer' request

createGetLegendGraphicRequest

public TLcdWMSGetLegendGraphicRequest createGetLegendGraphicRequest()

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

Returns:

a new 'GetLegendGraphic' request