org.geotools.data.ows

Class AbstractOpenWebService<C extends Capabilities,R>

Object

AbstractOpenWebService<C,R>

Direct Known Subclasses:

WebMapServer, WebMapTileServer, WFSClient

public abstract class AbstractOpenWebService<C extends Capabilities,R>
extends Object

This abstract class provides a building block for one to implement an Open Web Service (OWS) client. Each OWS is usually defined by an OGC specification, available at http://www.opengeospatial.org.

This class provides version negotiation, Capabilities document retrieval, and a request/response infrastructure. Implementing subclasses need to provide their own Specifications (representing versions of the OWS to be implemented) and their own request/response instances.

Author:

Richard Gould

Field Summary

Fields

Modifier and Type	Field and Description
protected C	capabilities
protected Map<String,Object>	hints Hints, now used for the XML parsing *
protected ServiceInfo	info
protected static Logger	LOGGER
protected Map<R,ResourceInfo>	resourceInfo
protected URL	serverURL
protected Specification	specification
protected Specification[]	specs Contains the specifications that are to be used with this service

Constructor Summary

Constructors

Constructor and Description
AbstractOpenWebService(URL serverURL) Set up the specifications used and retrieve the Capabilities document given by serverURL.
AbstractOpenWebService(URL serverURL, HTTPClient httpClient, C capabilities)
AbstractOpenWebService(URL serverURL, HTTPClient httpClient, C capabilities, Map<String,Object> hints)

Method Summary

Modifier and Type	Method and Description
protected abstract ServiceInfo	createInfo() Implemented by a subclass to describe service
protected abstract ResourceInfo	createInfo(R resource)
abstract C	getCapabilities() Get the getCapabilities document.
Map<String,Object>	getHints() Returns the hints affecting the service operations
HTTPClient	getHTTPClient()
ServiceInfo	getInfo() Description of this service.
ResourceInfo	getInfo(R resource)
protected Response	internalIssueRequest(Request request) Issues a request to the server and returns that server's response.
GetCapabilitiesResponse	issueRequest(GetCapabilitiesRequest request)
protected C	negotiateVersion() Version number negotiation occurs as follows (credit OGC): 1) If the server implements the requested version number, the server shall send that version.
void	setHints(Map<String,Object> hints) Sets the hints affecting the service operations
void	setHttpClient(HTTPClient httpClient)
void	setLoggingLevel(Level newLevel)
protected abstract void	setupSpecifications() Sets up the specifications/versions that this server is capable of communicating with.

Methods inherited from class Object

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

Field Detail

serverURL

protected final URL serverURL

capabilities

protected C extends Capabilities capabilities

info

protected ServiceInfo info

resourceInfo

protected Map<R,ResourceInfo> resourceInfo

specs

protected Specification[] specs

Contains the specifications that are to be used with this service

specification

protected Specification specification

hints

protected Map<String,Object> hints

Hints, now used for the XML parsing *

LOGGER

protected static final Logger LOGGER

Constructor Detail

AbstractOpenWebService

public AbstractOpenWebService(URL serverURL)
                       throws IOException,
                              ServiceException

Set up the specifications used and retrieve the Capabilities document given by serverURL.

Parameters:

serverURL - a URL that points to the capabilities document of a server

Throws:

IOException - if there is an error communicating with the server

ServiceException - if the server responds with an error

AbstractOpenWebService

public AbstractOpenWebService(URL serverURL,
                              HTTPClient httpClient,
                              C capabilities)
                       throws ServiceException,
                              IOException

Throws:

ServiceException

IOException

AbstractOpenWebService

public AbstractOpenWebService(URL serverURL,
                              HTTPClient httpClient,
                              C capabilities,
                              Map<String,Object> hints)
                       throws ServiceException,
                              IOException

Throws:

ServiceException

IOException

Method Detail

setHttpClient

public void setHttpClient(HTTPClient httpClient)

getHTTPClient

public HTTPClient getHTTPClient()

getCapabilities

public abstract C getCapabilities()

Get the getCapabilities document. If there was an error parsing it during creation, it will return null (and it should have thrown an exception during creation).

Returns:

a Capabilities object, representing the Capabilities of the server

getInfo

public ServiceInfo getInfo()

Description of this service.

Provides a very quick description of the service, for more information please review the capabilitie document.

Returns:

description of this service.

createInfo

protected abstract ServiceInfo createInfo()

Implemented by a subclass to describe service

Returns:

ServiceInfo

getInfo

public ResourceInfo getInfo(R resource)

createInfo

protected abstract ResourceInfo createInfo(R resource)

setupSpecifications

protected abstract void setupSpecifications()

Sets up the specifications/versions that this server is capable of communicating with.

negotiateVersion

protected C negotiateVersion()
                      throws IOException,
                             ServiceException

Version number negotiation occurs as follows (credit OGC):

• 1) If the server implements the requested version number, the server shall send that version.
• 2a) If a version unknown to the server is requested, the server shall send the highest version less than the requested version.
• 2b) If the client request is for a version lower than any of those known to the server, then the server shall send the lowest version it knows.
• 3a) If the client does not understand the new version number sent by the server, it may either cease communicating with the server or send a new request with a new version number that the client does understand but which is less than that sent by the server (if the server had responded with a lower version).
• 3b) If the server had responded with a higher version (because the request was for a version lower than any known to the server), and the client does not understand the proposed higher version, then the client may send a new request with a version number higher than that sent by the server.

The OGC tells us to repeat this process (or give up). This means we are actually going to come up with a bit of setup cost in figuring out our GetCapabilities request. This means that it is possible that we may make multiple requests before being satisfied with a response.

Also, if we are unable to parse a given version for some reason, for example, malformed XML, we will request a lower version until we have run out of versions to request with. Thus, a server that does not play nicely may take some time to parse and might not even succeed.

Returns:

a capabilities object that represents the Capabilities on the server

Throws:

IOException - if there is an error communicating with the server, or the XML cannot be parsed

ServiceException - if the server returns a ServiceException

internalIssueRequest

protected Response internalIssueRequest(Request request)
                                 throws IOException,
                                        ServiceException

Issues a request to the server and returns that server's response. It asks the server to send the response gzipped to provide a faster transfer time.

Parameters:

request - the request to be issued

Returns:

a response from the server, which is created according to the specific Request

Throws:

IOException - if there was a problem communicating with the server

ServiceException - if the server responds with an exception or returns bad content

issueRequest

public GetCapabilitiesResponse issueRequest(GetCapabilitiesRequest request)
                                     throws IOException,
                                            ServiceException

Throws:

IOException

ServiceException

setLoggingLevel

public void setLoggingLevel(Level newLevel)

getHints

public Map<String,Object> getHints()

Returns the hints affecting the service operations

setHints

public void setHints(Map<String,Object> hints)

Sets the hints affecting the service operations