Class AbstractOpenWebService<C extends Capabilities,​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 Detail

      • serverURL

        protected final URL serverURL
      • headers

        protected final Map<String,​String> headers
      • specs

        protected Specification[] specs
        Contains the specifications that are to be used with this service
      • 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,
                                      Map<String,​Object> hints)
                               throws ServiceException,
                                      IOException
        Throws:
        ServiceException
        IOException
      • AbstractOpenWebService

        public AbstractOpenWebService​(URL serverURL,
                                      HTTPClient httpClient,
                                      C capabilities,
                                      Map<String,​Object> hints,
                                      Map<String,​String> headers)
                               throws ServiceException,
                                      IOException
        Throws:
        ServiceException
        IOException
    • Method Detail

      • setHttpClient

        @Deprecated
        public void setHttpClient​(HTTPClient httpClient)
        Deprecated.
        httpClient should be treated as a final
        Parameters:
        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
      • 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
      • 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