uk.ac.starlink.util

## Class ContentCoding

- java.lang.Object
- - uk.ac.starlink.util.ContentCoding

- All Implemented Interfaces:
    UrlConnector

      public abstract class ContentCoding
      extends java.lang.Object
      implements UrlConnector

  Defines a policy for Content Codings used in HTTP connections. An instance of this class is used to prepare requests and decode responses for some HTTP-based communications in this package. It controls whether HTTP-level content codings are used; typically this means transparent gzip compression of the HTTP response stream where negotiation indicates it is allowed.

  Two static instances `NONE` and `GZIP` are provided. It should be completely safe to use either of these in any context, since an instance of this class represents only an indication to an HTTP server that a particular coding scheme is supported by the client. A service is therefore always at liberty to ignore this hint/request and provide and unencoded response if, for instance, it does not support the requested compression scheme. Good practice for use of this class is therefore probably to use GZIP where the response is expected to be large and reasonably compressible (a long VOTable is a good example), and NONE where the response is expected to be short or, especially, not very gzippable (for instance noisy binary floating point data, or a byte stream that has already been compressed).

  The provided instances also include some logging functionality; information about how many bytes (and where applicable the level of compression) is logged for bytestreams read through these instances. The logging level for this information is currently CONFIG.

  See Also:
    RFC 2616 secs 3.5, 14.3, 14.11

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `ACCEPT_ENCODING` Name of HTTP request header to request coded response ("Accept-Encoding").
    `static java.lang.String` | `CONTENT_ENCODING` Name of HTTP response header to mark coded response ("Content-Encoding").
    `static ContentCoding` | `GZIP` Gzip encoding is requested.
    `static ContentCoding` | `NONE` No encoding is requested.

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `ContentCoding()` Constructor.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `connect(java.net.HttpURLConnection hconn)` Opens communication to an HTTP resource.
    `abstract java.io.InputStream` | `getErrorStream(java.net.URLConnection conn)` Returns the error stream response from the given connection, which was prepared using this object's `prepareRequest` method.
    `abstract java.io.InputStream` | `getInputStream(java.net.URLConnection conn)` Returns the input stream response from the given connection, which was prepared using this object's `prepareRequest` method.
    `java.net.URLConnection` | `openConnection(java.net.URL url)` Convenience method to open a new connection prepared in accordance with this object's encoding policy.
    `java.io.InputStream` | `openStream(java.net.URL url)` Convenience method to return a byte stream from a given URL in accordance with this object's encoding policy.
    `java.io.InputStream` | `openStreamAuth(java.net.URL url, AuthManager authManager)` Convenience method to return a byte stream from a given URL in accordance with this object's encoding policy and with authentication and redirects handled by a given AuthManager (typically `AuthManager.getInstance()`).
    `abstract void` | `prepareRequest(java.net.URLConnection conn)` Sets up request headers for the given connection.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### NONE

          public static final ContentCoding NONE

      No encoding is requested.

    - #### GZIP

          public static final ContentCoding GZIP

      Gzip encoding is requested.

    - #### ACCEPT_ENCODING

          public static final java.lang.String ACCEPT_ENCODING

      Name of HTTP request header to request coded response ("Accept-Encoding").
      See Also:
        Constant Field Values

    - #### CONTENT_ENCODING

          public static final java.lang.String CONTENT_ENCODING

      Name of HTTP response header to mark coded response ("Content-Encoding").
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### ContentCoding

          protected ContentCoding()

      Constructor.

  - ### Method Detail

    - #### prepareRequest

          public abstract void prepareRequest(java.net.URLConnection conn)

      Sets up request headers for the given connection. The connection must not have yet been connected.
      Parameters:
        `conn` - unconnected connection

    - #### getInputStream

          public abstract java.io.InputStream getInputStream(java.net.URLConnection conn)
                                                      throws java.io.IOException

      Returns the input stream response from the given connection, which was prepared using this object's `prepareRequest` method. Any required decoding will have been done transparently.
      Parameters:
        `conn` - connection
      Returns:
        stream decoded as required
      Throws:
        `java.io.IOException`
      See Also:
        `URLConnection.getInputStream()`

    - #### getErrorStream

          public abstract java.io.InputStream getErrorStream(java.net.URLConnection conn)
                                                      throws java.io.IOException

      Returns the error stream response from the given connection, which was prepared using this object's `prepareRequest` method. Any required decoding will have been done transparently.
      Parameters:
        `conn` - connection
      Returns:
        stream decoded as required
      Throws:
        `java.io.IOException`
      See Also:
        `URLConnection.getInputStream()`

    - #### openConnection

          public java.net.URLConnection openConnection(java.net.URL url)
                                                throws java.io.IOException

      Convenience method to open a new connection prepared in accordance with this object's encoding policy. Opens the connection and calls `prepareRequest`.
      Parameters:
        `url` - target URL
      Returns:
        prepared connection
      Throws:
        `java.io.IOException`

    - #### openStream

          public java.io.InputStream openStream(java.net.URL url)
                                         throws java.io.IOException

      Convenience method to return a byte stream from a given URL in accordance with this object's encoding policy. Opens the connection, prepares the request, and decodes the result.
      Parameters:
        `url` - target URL
      Returns:
        unencoded stream from the URL
      Throws:
        `java.io.IOException`

    - #### openStreamAuth

          public java.io.InputStream openStreamAuth(java.net.URL url,
                                                    AuthManager authManager)
                                             throws java.io.IOException

      Convenience method to return a byte stream from a given URL in accordance with this object's encoding policy and with authentication and redirects handled by a given AuthManager (typically `AuthManager.getInstance()`).
      Parameters:
        `url` - target URL
        `authManager` - authentication manager
      Returns:
        unencoded stream from the URL
      Throws:
        `java.io.IOException`

    - #### connect

          public void connect(java.net.HttpURLConnection hconn)
                       throws java.io.IOException

      Description copied from interface: `UrlConnector`
      Opens communication to an HTTP resource. The implementation will presumably at least call `URLConnection.connect()`, but it may optionally perform other actions as well, such as configuring the request headers as required and writing to the connection's output stream, before returning.

      If this object is being used with AuthManager, it will typically be a good idea to call `setInstanceFollowRedirects(false)`, since redirection can be handled by AuthManager.

      Specified by:
        `connect` in interface `UrlConnector`
      Parameters:
        `hconn` - URL connection; on entry connect() has not yet been called, but on exit it has
      Throws:
        `java.io.IOException`