Class TLcdWMSClient
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()
orgetCapabilities(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:
-
Constructor Summary
ModifierConstructorDescriptionprotected
TLcdWMSClient
(ALcdOGCWMSCapabilities aCapabilities, ILcdOWSTransport aTransport) Creates a newTLcdWMSClient
with the given parameters.protected
TLcdWMSClient
(URI aURI, ILcdOWSTransport aTransport, Object aTransportData) Creates a newTLcdWMSClient
with the given parameters. -
Method Summary
Modifier and TypeMethodDescriptionCreates a new 'DescribeLayer' request object which is compatible with the WMS version implemented by the WMS server this client communicates with.Creates a new 'GetCapabilities' request object which is compatible with the WMS version implemented by the WMS server this client communicates with.Creates a new 'GetFeatureInfo' request object which is compatible with the WMS version implemented by the WMS server this client communicates with.Creates a new 'GetLegendGraphic' request object which is compatible with the WMS version implemented by the WMS server this client communicates with.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 ofTLcdOWSOperation
instances based on the contents of the providedALcdOGCWMSCapabilities
instance.describeLayer
(TLcdWMSDescribeLayerRequest aRequest) Performs the 'DescribeLayer' request.Returns the most recent capabilities object that was requested by this client.getCapabilities
(TLcdWMSGetCapabilitiesRequest aRequest) Performs the 'GetCapabilities' request.getFeatureInfo
(TLcdWMSGetFeatureInfoRequest aRequest) Performs the 'GetFeatureInfo' request.Performs the 'GetLegendGraphic' request.getMap
(TLcdWMSGetMapRequest aRequest) Performs the 'GetMap' request.protected final TLcdOWSOperation
getOperation
(String aOperationName) Retrieves an operation based on the operation name.getURI()
Returns the URI of the WMS server.protected final TLcdOWSInputStream
performRequest
(String aOperationName, ILcdOWSRequest aRequest) Performs a WMS request.
-
Constructor Details
-
TLcdWMSClient
protected TLcdWMSClient(ALcdOGCWMSCapabilities aCapabilities, ILcdOWSTransport aTransport) throws TLcdOWSDecodingException, TLcdOWSTransportException, TLcdOWSUnsupportedVersionException Creates a newTLcdWMSClient
with the given parameters.- Parameters:
aCapabilities
- the capabilities of the WMS serveraTransport
- the transport to use- Throws:
TLcdOWSDecodingException
- if an error occurs while decoding the initial WMS responseTLcdOWSTransportException
- if an error occurs in the transport layer while negotiation the versionTLcdOWSUnsupportedVersionException
- 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 newTLcdWMSClient
with the given parameters.- Parameters:
aURI
- the URI of the WMS serveraTransport
- the transport to useaTransportData
- 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 transportTLcdOWSDecodingException
- if an error occurs while decoding the initial WMS responseTLcdOWSUnsupportedVersionException
- if the specified WMS server does not support any of the the WMS versions implemented by this clientTLcdOWSTransportException
- if an error occurred in the transportation layerTLcdOWSServerException
- if the server returned a WMS service exception
-
-
Method Details
-
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 nullIllegalArgumentException
- if the specified URI is not compatible with the default transportTLcdOWSDecodingException
- if an error occurs while decoding the initial WMS responseTLcdOWSTransportException
- if an error occurs in the transport layer while negotiation the versionTLcdOWSUnsupportedVersionException
- if the specified WMS server does not support any of the the WMS versions implemented by this clientTLcdOWSServerException
-
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 nullTLcdOWSDecodingException
- if an error occurs while decoding the initial WMS responseTLcdOWSTransportException
- if an error occurs in the transport layer while negotiation the versionTLcdOWSUnsupportedVersionException
- 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 serveraTransport
- the transport to useaTransportData
- 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 nullIllegalArgumentException
- if the specified URI is not compatible with the specified transportTLcdOWSDecodingException
- if an error occurs while decoding the initial WMS responseTLcdOWSTransportException
- if an error occurs in the transport layer while negotiation the versionTLcdOWSUnsupportedVersionException
- if the specified WMS server does not support any of the the WMS versions implemented by this clientTLcdOWSServerException
- See Also:
-
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 aGetCapabilities
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
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 timegetCapabilities(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' responseTLcdOWSTransportException
- if an error occurred in the transport while accessing the web serviceTLcdOWSUnsupportedVersionException
- if the server only supports WMS specification versions that are not supported by this clientTLcdOWSServerException
- 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' responseTLcdOWSTransportException
- if an error occurred in the transport while accessing the web serviceTLcdOWSServerException
- 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' responseTLcdOWSTransportException
- if an error occurred in the transport while accessing the web serviceTLcdOWSServerException
- 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' responseTLcdOWSTransportException
- if an error occurred in the transport while accessing the web serviceTLcdOWSServerException
- 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' responseTLcdOWSTransportException
- if an error occurred in the transport while accessing the web serviceTLcdOWSServerException
- if the server returned a service exception
-
getOperation
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 invokeaRequest
- 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 serviceTLcdOWSServerException
- if the server returned a WMS Service exceptionTLcdOWSDecodingException
- if a decoding error occurred while performing the request
-
decodeOperations
Returns a list ofTLcdOWSOperation
instances based on the contents of the providedALcdOGCWMSCapabilities
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
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
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
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
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
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
-