TLcdOWSHttpTransport (LuciadLightspeed API documentation)

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 Summary

Constructors
Constructor and Description
`TLcdOWSHttpTransport()` Creates a new HTTP transport.
`TLcdOWSHttpTransport(boolean aPreferPOST)` Creates a new HTTP transport with the given request type preference.
`TLcdOWSHttpTransport(String aUsername, String aPassword)` Creates a new HTTP transport with the given username and password.
`TLcdOWSHttpTransport(String aUsername, String aPassword, boolean aPreferPOST)` Creates a new HTTP transport with the given credentials and request type preference.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`canPerformRequest(TLcdOWSOperation aOperation, ILcdOWSRequest aRequest)` Fast check to see whether or not this transport is capable of performing the request.
`protected void`	`configureConnection(URI aURI, ILcdOWSRequest aRequest, HttpURLConnection aConnection)` Configures the specified connection.
`TLcdOWSDCP`	`createDCP(URI aURI)` Creates an OpenGIS Web Service DCP that can be used to access the specified URI using this transport.
`protected TLcdOWSInputStream`	`handleResponse(URI aURI, ILcdOWSRequest aRequest, int aResponse, String aResponseMessage, Map aHeaderFields)` 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.
`boolean`	`isCompatibleURI(URI aUri)` Determines whether the specified URI is compatible with this transport implementation.
`protected HttpURLConnection`	`openConnection(URL aUrl)` Opens a connection to the specified URL.
`TLcdOWSInputStream`	`performRequest(TLcdOWSOperation aOperation, ILcdOWSRequest aRequest)` Performs the specified operation passing in the parameters defined in the request object.
`protected void`	`sendData(HttpURLConnection aConnection, ILcdOWSRequest aRequest, String aMethod)` Writes request data to the given connection, if required by the request method.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - 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:
    
    aPreferPOST - indicates whether POST requests are preferred above GET
    
    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
- Method Detail
  - 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

LuciadLightspeedClass TLcdOWSHttpTransport

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

TLcdOWSHttpTransport

TLcdOWSHttpTransport

TLcdOWSHttpTransport

TLcdOWSHttpTransport

Method Detail

canPerformRequest

performRequest

isCompatibleURI

createDCP

openConnection

handleResponse

configureConnection

sendData