Package com.luciad.ogc.ows.model

Class TLcdOWSHttpTransport

java.lang.Object
com.luciad.ogc.ows.model.TLcdOWSHttpTransport
All Implemented Interfaces:
ILcdOWSTransport
public class TLcdOWSHttpTransport extends Object implements ILcdOWSTransport
An OpenGIS Web Service transport that uses HTTP as its transport protocol.

This implementation supports both HTTP GET and POST requests. For POST requests, the MIME types text/xml and application/x-www-form-urlencoded are supported.

By default, a maximum HTTP GET query length of 2048 characters is enforced; if the query length is larger, the communication automatically switches to HTTP POST if supported by the server. The maximum HTTP GET query length can be customized through the System property com.luciad.ogc.ows.model.TLcdOWSHttpTransport.maxGetQueryLength.

This implementation also supports connecting with servers that require authentication according to the HTTP Basic Authentication mechanism. Credentials can be supplied through the constructors of this class.

Based on the supported request methods at the service, performRequest(TLcdOWSOperation, ILcdOWSRequest) tries different requests in case of failure. By default, POST requests are tried before GET requests, if both are available. This behavior can be configured at construction time.

Instances of this class are thread safe and may be reused by multiple client classes. In other words, a single HTTP transport may be used concurrently by multiple OWS client implementations. This provides a convenient mechanism to centralize HTTP parameters such as authentication data in an application. Subclasses of this class should take this type of usage into account.
Since:
8.2

  • Constructor Details

    • TLcdOWSHttpTransport

      public TLcdOWSHttpTransport()
      Creates a new HTTP transport.

      By default, performRequest(TLcdOWSOperation, ILcdOWSRequest) first tries GET requests instead of POST requests.

    • TLcdOWSHttpTransport

      public TLcdOWSHttpTransport(String aUsername, String aPassword)
      Creates a new HTTP transport with the given username and password. These credentials will be used to authenticate at the server using HTTP Basic Authentication.

      By default, performRequest(TLcdOWSOperation, ILcdOWSRequest) first tries GET requests instead of POST requests.

      Parameters:
      aUsername - username to authenticate at the server; this is only used if the password is also set
      aPassword - password to authenticate at the server; this is only used if the username is also set
      Since:
      2015.1

    • TLcdOWSHttpTransport

      public TLcdOWSHttpTransport(boolean aPreferPOST)
      Creates a new HTTP transport with the given request type preference.
      Parameters:
      aPreferPOST - indicates whether POST requests are preferred above GET

    • TLcdOWSHttpTransport

      public TLcdOWSHttpTransport(String aUsername, String aPassword, boolean aPreferPOST)
      Creates a new HTTP transport with the given credentials and request type preference. The credentials will be used to authenticate at the server using HTTP Basic Authentication.
      Parameters:
      aUsername - username to authenticate at the server; this is only used if the password is also set
      aPassword - password to authenticate at the server; this is only used if the username is also set
      aPreferPOST - indicates whether POST requests are preferred above GET
      Since:
      2015.1

  • Method Details

    • canPerformRequest

      public boolean canPerformRequest(TLcdOWSOperation aOperation, ILcdOWSRequest aRequest)
      Description copied from interface: ILcdOWSTransport

      Fast check to see whether or not this transport is capable of performing the request.

      When this method returns false, ILcdOWSTransport.performRequest(TLcdOWSOperation, ILcdOWSRequest) will not be capable of performing the request and throw an error. When this method returns true, it is still possible that calling ILcdOWSTransport.performRequest(TLcdOWSOperation, ILcdOWSRequest) throws an error (for example when the server is offline).

      The default implementation returns true.

      Specified by:
      canPerformRequest in interface ILcdOWSTransport
      Parameters:
      aOperation - The operation
      aRequest - The request parameters
      Returns:
      false when this transport cannot perform the request, true when this transport probably can perform the request.

    • performRequest

      public TLcdOWSInputStream performRequest(TLcdOWSOperation aOperation, ILcdOWSRequest aRequest) throws TLcdOWSTransportException
      Performs the specified operation passing in the parameters defined in the request object.

      Request properties to be used for the connection can be specified through the transport data of the request, ILcdOWSRequest.getTransportData(), represented by a Map object (see URLConnection.getRequestProperties()).

      The returned TLcdOWSInputStream contains, next to the MIME type and input stream, the response headers of the connection, represented as a Map object (see URLConnection.getHeaderFields()).

      Specified by:
      performRequest in interface ILcdOWSTransport
      Parameters:
      aOperation - the operation to perform
      aRequest - the request parameters
      Returns:
      a typed inputstream
      Throws:
      TLcdOWSTransportException - if an error occurs in the transport layer

    • isCompatibleURI

      public boolean isCompatibleURI(URI aUri)
      Determines whether the specified URI is compatible with this transport implementation. An URI is considered compatible if it has a scheme (see URI.getScheme()) that equals "http" or "https".
      Specified by:
      isCompatibleURI in interface ILcdOWSTransport
      Parameters:
      aUri - the URI to test
      Returns:
      true if the specified URI is compatible; false otherwise

    • createDCP

      public TLcdOWSDCP createDCP(URI aURI)
      Creates an OpenGIS Web Service DCP that can be used to access the specified URI using this transport.

      This method can be used to create a TLcdOWSOperation object that is needed to perform initial requests (in other words, requests that need to be performed before web service metadata has been retrieved).

      By default, a TLcdOWSDCP is returned that is configured with a TLcdOWSHTTP object consisting of a GET request method.

      Specified by:
      createDCP in interface ILcdOWSTransport
      Parameters:
      aURI - the URI
      Returns:
      an OWS DCP object
      Throws:
      NullPointerException - if the specified URI is null
      IllegalArgumentException - if the specified URI is not compatible with this transport

    • openConnection

      protected HttpURLConnection openConnection(URL aUrl) throws IOException
      Opens a connection to the specified URL. This method can be overridden in order to redirect a URL to an HTTP proxy.
      Parameters:
      aUrl - the URL to which a connection should be opened
      Returns:
      an HttpURLConnection to the specified URL
      Throws:
      IOException - if an error occurs while opening the connection

    • handleResponse

      protected TLcdOWSInputStream handleResponse(URI aURI, ILcdOWSRequest aRequest, int aResponse, String aResponseMessage, Map aHeaderFields) throws TLcdOWSHttpTransportException
      This method is called if an error response code is received from the HTTP server and if the content of response is not a service exception.

      By default, this method fails by throwing a TLcdOWSHttpTransportException, initialized with the details of the error response (response code, message and header fields). Subclasses can override this method to take other actions (for instance use a proxy, retrieve authentication information, etc.), and still try to return a valid TLcdOWSInputStream.

      Parameters:
      aURI - the URI that was requested and triggered the error
      aRequest - the OWS request
      aResponse - the HTTP response code
      aResponseMessage - the HTTP response message
      aHeaderFields - the HTTP header fields
      Returns:
      a typed inputstream
      Throws:
      TLcdOWSHttpTransportException - in all cases

    • configureConnection

      protected void configureConnection(URI aURI, ILcdOWSRequest aRequest, HttpURLConnection aConnection) throws IOException
      Configures the specified connection. This method allows subclasses to set specific request properties.

      The default implementation sets the following properties, in this order:

      • A connect and read timeout of 30s is set (see URLConnection.setConnectTimeout(int) and URLConnection.setReadTimeout(int)).
      • HTTP redirects (requests with response code 3xx) should be automatically followed by the connection (see HttpURLConnection.setInstanceFollowRedirects(boolean)).
      • The Accept-Encoding request property is set to gzip, deflate, compress, to allow servers to send compressed data. These encodings are specified in HTTP 1.1 (RFC 2616, section 3.5), and are supported by default in this class.
      • The User-Agent request property is set to Java version, to identify the source of the request. Some servers require to have a non-empty value for this property.
      • If a username and password have been supplied to the constructor, the Authorization request property is initialized with these credentials, following the HTTP Basic Authentication mechanism.
      • Connection request properties that are contained in a Map object associated with the OWS request (see ILcdOWSRequest.getTransportData() and URLConnection.setRequestProperty(String, String)).
      Parameters:
      aURI - the URI which is being accessed
      aRequest - the request parameters
      aConnection - the connection to configure
      Throws:
      IOException - if an error occurs while configuring the connection

    • sendData

      protected void sendData(HttpURLConnection aConnection, ILcdOWSRequest aRequest, String aMethod) throws TLcdOWSTransportException
      Writes request data to the given connection, if required by the request method. The request method must be either GET or POST. In case of a GET request, the request is fully defined by the URL itself (through the key-value parameters), so no further request data is sent to the connection. In case of a POST request, the request is not part of the URL itself, and needs to be written to the connection (see URLConnection.getOutputStream()).
      Parameters:
      aConnection - the connection to write request data to
      aRequest - the request
      aMethod - the request method, which must be GET or POST
      Throws:
      TLcdOWSTransportException - in case of an unsupported request method or when sending the request data fails