PIRL.Image_Tools

## Class HTTP_ImageInputStream

- java.lang.Object
- - javax.imageio.stream.ImageInputStreamImpl
  - - PIRL.Image_Tools.HTTP_ImageInputStream

All Implemented Interfaces:
  Closeable, DataInput, AutoCloseable, ImageInputStream

    public class HTTP_ImageInputStream
    extends ImageInputStreamImpl

An HTTP_ImageInputStream provides an ImageInputStream interface to a remote source file accessed by a URL reference.

The URL used to reference the source file must use the http protocol. Any HTTP server compatible with version 1.1 of the protocol should be capable of providing selective access to the source file.

The source file data is buffered using a sliding window that is mapped to an arbitrary location offset of the source file. Data is fetched on demand using a Content_Range request to the server from which the response data content is placed at the appropriate position in the buffer. During normal read operations when the end of buffered data is reached a relatively small input increment is fetched into the buffer. When the amount of data has reached the buffer capacity the buffer "slides" forward, dropping data from the beginning of the buffer Arbitrary random access seeks within the source file are supported. If the seek location is currently buffered, no data fetch is needed, of course. Seeks beyond the range of buffered data to a "nearby" location will retain as much buffered data as possible to optimize short seeks.

If the connection to the server is lost repeated attempts are made to reconnect. Reconnecting to the server does cause any loss of buffered data.

See Also:
  `ImageInputStream`

### Nested Class Summary

Nested Classes
`class` `HTTP_ImageInputStream.Range` A Range contains Start, End and Length values.

### Field Summary

Fields
`static int` `DEFAULT_BUFFER_SIZE` The default buffer capacity to `allocate`.
`static int` `DEFAULT_CONNECT_TIMEOUT` The amount of time (ms) to wait for a server connection.
`static int` `DEFAULT_PORT` The default port to use for communication with the server.
`static String` `DEFAULT_USER_AGENT` The default `User Agent` reported to the server.
`static String` `ENCODING_SCHEME` The character encoding for messages sent to the server.
`static String` `HTTP_VERSION` The HTTP version identifier used in communication with the server.
`static String` `ID`
`static int` `INPUT_INCREMENT` The amount of source data to `fetch` when performing an automatic refresh of buffer contents.
`static String` `LOG_INPUT_PREFIX` When `Logging` is enabled, the prefix to print before each response header line that is reported received from the server.
`static String` `LOG_OUTPUT_PREFIX` When `Logging` is enabled, the prefix to print before each request message line that is reported sent to the server.
`static int` `MAX_RECONNECT_ATTEMPTS` The maximum number of repeated server reconnect tries.
`protected long` `NO_SOURCE_SIZE` Source size value if no source has been found.
`static long` `RECONNECT_WAIT` The amount of time (ms) to wait before trying to reconnect with the server.
`static int` `SOURCE_NOT_FOUND_STATUS` HTTP `Status` code when the source can not be found on the server.
`protected long` `Source_Size` Total size (bytes) of the source data file.
`static int` `SUCCESS_STATUS_LIMIT` HTTP `Status` code value below which the request is deemed successful.

### Fields inherited from class javax.imageio.stream.ImageInputStreamImpl

`bitOffset, byteOrder, flushedPos, streamPos`

### Constructor Summary

Constructors
Constructor and Description
`HTTP_ImageInputStream(URL url)` Constructs an HTTP_ImageInputStream on a URL.

### Method Summary

Methods
`void` `Allocate_Buffer(int capacity)` Allocates a data storage buffer.
`long` `Buffer_Location()` Get the virtual source location of the beginning of the buffer.
`protected void` `Buffer_Location(long location)` Set the virtual source location of the beginning of the buffer.
`int` `Check_Source()` Check the server status of the source.
`void` `close()` All access to the source is closed.
`void` `Connect(URL url)` Connect to the server.
`long` `Content_Length()` Get the length of server response data content.
`HTTP_ImageInputStream.Range` `Content_Range()` Get the Content-Range header values.
`long` `Data_End_Location()` Get the virtual source location of the end (exclusive) of buffered data.
`protected void` `Data_End_Location(long location)` Set the virtual source location of the end (exclusive) of buffered data.
`static String` `Default_User_Agent()` Get the default user agent that will be used with new HTTP_ImageInputStream objects.
`static void` `Default_User_Agent(String name)` Set the default user agent that will be used with new HTTP_ImageInputStream objects.
`int` `Drain()` Drain source data before the current stream position.
`int` `Drain(int amount)` Drain data from the buffer.
`int` `Empty()` Empty the buffer of all source data.
`protected void` `End_Request()` Send the end-of-request sequence to the server.
`int` `Fetch(int amount)` Fetch source data from the server (relative fetch).
`int` `Fetch(long start, long end)` Fetch source data from the server (absolute fetch).
`void` `flushBefore(long location)` Discard buffered data before a source location.
`String` `Header_Content(String name)` Get the header content for a named header.
`String` `Header_Field(String name)` Get the complete header field for a named header.
`String` `Header_Value(String name, int value_index)` Get a header field value by index within the field content.
`String` `Header_Value(String name, String value_name)` Get a header field value by name.
`protected int` `Headers()` Get the HTTP response headers from the server.
`long` `Image_Buffer_Range(long location)` Clip a source location to the currently buffered data range.
`boolean` `in_Image_Buffer_Range(long location)` Test if a source location is in the range of buffered data.
`boolean` `is_Closed()` Checks if the server connection is closed.
`boolean` `isCached()` Determine if the source data is cached.
`boolean` `isCachedMemory()` Determine if the source data is cached in memory.
`long` `length()` Get the size of the source file.
`protected long` `Location_for_Position(int position)` Convert a buffer position to a virtual source location.
`boolean` `Logging()` Check if server communication logging is enabled.
`HTTP_ImageInputStream` `Logging(boolean enabled)` Enable or disable server communication logging.
`static void` `main(String[] args)`
`protected int` `Position_for_Location(long location)` Convert a virtual source location to a buffer position.
`int` `read()` Read a source byte.
`int` `read(byte[] data, int offset, int length)` Read a sequence of source bytes and store them in an array.
`protected int` `Receive()` Receive a response to a server request.
`protected void` `Reconnect()` Reconnect to the server.
`protected HTTP_ImageInputStream` `Request_Source_Data(long start, long end)` Get a range of source data.
`protected void` `Request(String method, String request)` Issue a Request preamble to the server.
`void` `Reset(long location)` Reset the buffer to a new source location and empty it.
`void` `seek(long location)` Set the current source file location where the next byte will be read.
`protected void` `Send(String message)` Send a message line to the server.
`String` `Server_Hostname()` Get the source server hostname.
`String` `Source_Pathname()` Get the source pathname.
`long` `Source_Size()` Get the size of the source file.
`URL` `Source_URL()` Get the URL used to access the source.
`int` `Status()` Get the HTTP status of the last response from the server.
`protected long` `Stream_Location()` Get the virtual source location where the next image buffer will be read.
`void` `Stream_Location(long location)` Set the virtual source location where the next image buffer will be read.
`long` `Total_Received()` Get the total number of bytes received from the server so far.
`long` `Total_Sent()` Get the total number of bytes sent to the server so far.
`static void` `Usage()`
`String` `User_Agent()` Get the HTTP user agent name reported to the server.
`HTTP_ImageInputStream` `User_Agent(String name)` Set the HTTP user agent name to be reported to the server.

### Methods inherited from class javax.imageio.stream.ImageInputStreamImpl

`checkClosed, finalize, flush, getBitOffset, getByteOrder, getFlushedPosition, getStreamPosition, isCachedFile, mark, read, readBit, readBits, readBoolean, readByte, readBytes, readChar, readDouble, readFloat, readFully, readFully, readFully, readFully, readFully, readFully, readFully, readFully, readInt, readLine, readLong, readShort, readUnsignedByte, readUnsignedInt, readUnsignedShort, readUTF, reset, setBitOffset, setByteOrder, skipBytes, skipBytes`

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

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

### Field Detail

#### ID

    public static final String ID

See Also:
  Constant Field Values

#### HTTP_VERSION

    public static final String HTTP_VERSION

The HTTP version identifier used in communication with the server.

See Also:
  Constant Field Values

#### ENCODING_SCHEME

    public static final String ENCODING_SCHEME

The character encoding for messages sent to the server.

See Also:
  Constant Field Values

#### DEFAULT_USER_AGENT

    public static final String DEFAULT_USER_AGENT

The default `User Agent` reported to the server.

See Also:
  Constant Field Values

#### DEFAULT_PORT

    public static final int DEFAULT_PORT

The default port to use for communication with the server.

The URL used to construct the HTTP_ImageInputStream may specify a different port to be used.

See Also:
  Constant Field Values

#### DEFAULT_CONNECT_TIMEOUT

    public static final int DEFAULT_CONNECT_TIMEOUT

The amount of time (ms) to wait for a server connection.

See Also:
  Constant Field Values

#### RECONNECT_WAIT

    public static final long RECONNECT_WAIT

The amount of time (ms) to wait before trying to reconnect with the server.

See Also:
  Constant Field Values

#### MAX_RECONNECT_ATTEMPTS

    public static final int MAX_RECONNECT_ATTEMPTS

The maximum number of repeated server reconnect tries.

See Also:
  Constant Field Values

#### SOURCE_NOT_FOUND_STATUS

    public static final int SOURCE_NOT_FOUND_STATUS

HTTP `Status` code when the source can not be found on the server.

See Also:
  Constant Field Values

#### SUCCESS_STATUS_LIMIT

    public static final int SUCCESS_STATUS_LIMIT

HTTP `Status` code value below which the request is deemed successful.

See Also:
  Constant Field Values

#### NO_SOURCE_SIZE

    protected long NO_SOURCE_SIZE

Source size value if no source has been found.

#### Source_Size

    protected long Source_Size

Total size (bytes) of the source data file.

The value is initialized to `NO_SOURCE_SIZE` to indicate that the size is unknown. When HTTP response `headers` are received an attempt is made to get the `size of the source file` if it is not already known.

#### LOG_OUTPUT_PREFIX

    public static final String LOG_OUTPUT_PREFIX

When `Logging` is enabled, the prefix to print before each request message line that is reported sent to the server.

See Also:
  Constant Field Values

#### LOG_INPUT_PREFIX

    public static final String LOG_INPUT_PREFIX

When `Logging` is enabled, the prefix to print before each response header line that is reported received from the server.

See Also:
  Constant Field Values

#### INPUT_INCREMENT

    public static final int INPUT_INCREMENT

The amount of source data to `fetch` when performing an automatic refresh of buffer contents.

See Also:
  Constant Field Values

#### DEFAULT_BUFFER_SIZE

    public static final int DEFAULT_BUFFER_SIZE

The default buffer capacity to `allocate`.

See Also:
  Constant Field Values

### Constructor Detail

#### HTTP_ImageInputStream

    public HTTP_ImageInputStream(URL url)
                          throws IOException,
                                 UnknownHostException,
                                 IllegalArgumentException

Constructs an HTTP_ImageInputStream on a URL.

After a successful `connect`ion to the server has been established, a data storage buffer is `allocated` with the `DEFAULT_BUFFER_SIZE` capacity. Then the validity of the source is `checked`. If the source can not be confirmed the connection to the server is closed. Otherwise, if the server response to the source check contains a `content length` that is used to set the size of the source file.

Parameters:
  `url` - The URL to use to access the source file.
Throws:
  `IllegalArgumentException` - If the URL does not specify the http protocol nor provide a source file pathname.
  `UnknownHostException` - If the hostname of the URL can not be resolved to an internet address.
  `FileNotFoundException` - If the source was not found on the server.
  `ProtocolException` - If an HTTP `Status` protocol error was returned by the server.
  `IOException` - If the server connection could not be established.

### Method Detail

#### Source_URL

    public URL Source_URL()

Get the URL used to access the source.

Returns:
  The source URL.

#### Server_Hostname

    public String Server_Hostname()

Get the source server hostname.

Returns:
  The hostname String for the server.

#### Source_Pathname

    public String Source_Pathname()

Get the source pathname.

Returns:
  The pathname String where the source to be found by the server.

#### User_Agent

    public String User_Agent()

Get the HTTP user agent name reported to the server.

Returns:
  The user agent name String.
See Also:
  `User_Agent(String)`

#### User_Agent

    public HTTP_ImageInputStream User_Agent(String name)

Set the HTTP user agent name to be reported to the server.

Every time a request is sent to the server a "User-Agent" message is included. This information can be used by the server to gather statistics on it's use by the identified client agent. When an HTTP_ImageInputStream object is constructed the user agent is set as the `Default_User_Agent`.

Parameters:
  `name` - The user agent name String. If this is null, the `Default_User_Agent` will be assigned.
Returns:
  This HTTP_ImageInputStream.

#### Default_User_Agent

    public static String Default_User_Agent()

Get the default user agent that will be used with new HTTP_ImageInputStream objects.

Returns:
  The default user agent String.
See Also:
  `User_Agent(String)`

#### Default_User_Agent

    public static void Default_User_Agent(String name)

Set the default user agent that will be used with new HTTP_ImageInputStream objects.

Parameters:
  `name` - The user agent name String. If this is null, the `DEFAULT_USER_AGENT` will be assigned.
See Also:
  `User_Agent(String)`

#### Total_Sent

    public long Total_Sent()

Get the total number of bytes sent to the server so far.

Returns:
  A long value that is the number of bytes that have been sent to the server.

#### Total_Received

    public long Total_Received()

Get the total number of bytes received from the server so far.

Returns:
  A long value that is the number of bytes that have been received from the server.

#### Logging

    public boolean Logging()

Check if server communication logging is enabled.

Returns:
  true if logging is enabled; false otherwise.
See Also:
  `Logging(boolean)`

#### Logging

    public HTTP_ImageInputStream Logging(boolean enabled)

Enable or disable server communication logging.

When logging is enabled, each message `sent` to the server is printed to stdout preceded by the `LOG_OUTPUT_PREFIX` String, and each `header` response line is printed preceded by the `LOG_INPUT_PREFIX` String. In addition, the amount of data content `receive`d is printed on a ling after a LOG_INPUT_PREFIX.

Parameters:
  `enabled` - true if logging is to be enabled; false otherwise.
Returns:
  This HTTP_ImageInputStream.

#### read

    public int read()
             throws IOException

Read a source byte.

The `bit offset` is set to zero.

Specified by:
  `read` in interface `ImageInputStream`
Specified by:
  `read` in class `ImageInputStreamImpl`
Returns:
  The next byte value from the source. This will be -1 if the current source location is end of file.
Throws:
  `IOException` - If access to the source is closed or there was a problem obtaining source data.

#### read

    public int read(byte[] data,
           int offset,
           int length)
             throws IOException

Read a sequence of source bytes and store them in an array.

The number of bytes actually read may be less than the specified length. The length will be reduced to the smaller of the amount of space in the data array following the offset or the amount of buffered data remaining after an attempt to provide length bytes.

The `bit offset` is set to zero.

The current source input location is advanced by the amount of data read.

Specified by:
  `read` in interface `ImageInputStream`
Specified by:
  `read` in class `ImageInputStreamImpl`
Parameters:
  `data` - The byte array into which the data is to be stored.
  `offset` - The offset of the array where the first byte read is to be stored.
  `length` - The number of bytes to read.
Returns:
  The number of bytes read and stored. This will be -1 if the current source location is end of file.
Throws:
  `NullPointerException` - If the data array is null.
  `IndexOutOfBoundsException` - If the offset or length are negative, or the offset is greater than the length of the data array.
  `IOException` - If access to the source is closed or there was a problem obtaining source data.
See Also:
  `Fetch(int)`

#### isCached

    public boolean isCached()

Determine if the source data is cached.

Specified by:
  `isCached` in interface `ImageInputStream`
Overrides:
  `isCached` in class `ImageInputStreamImpl`
Returns:
  true

#### isCachedMemory

    public boolean isCachedMemory()

Determine if the source data is cached in memory.

Specified by:
  `isCachedMemory` in interface `ImageInputStream`
Overrides:
  `isCachedMemory` in class `ImageInputStreamImpl`
Returns:
  true

#### length

    public long length()

Get the size of the source file.

Specified by:
  `length` in interface `ImageInputStream`
Overrides:
  `length` in class `ImageInputStreamImpl`
Returns:
  The size of the source file. This will be -1 if the size is not yet known. This information may become available after further interaction with the server providing access to the source file.

#### flushBefore

    public void flushBefore(long location)
                     throws IOException

Discard buffered data before a source location.

Specified by:
  `flushBefore` in interface `ImageInputStream`
Overrides:
  `flushBefore` in class `ImageInputStreamImpl`
Parameters:
  `location` - The source file offset before which buffered data is to be discarded. If the location is before the beginning of buffered data nothing is done.
Throws:
  `IOException` - If the source file stream is closed.
  `IndexOutOfBoundsException` - If the location is greater than the current `source input location`.
See Also:
  `Drain(int)`

#### seek

    public void seek(long location)
              throws IOException

Set the current source file location where the next byte will be read.

The `bit offset` is set to zero.

Specified by:
  `seek` in interface `ImageInputStream`
Overrides:
  `seek` in class `ImageInputStreamImpl`
Parameters:
  `location` - The source file offset for the image buffer's next read position. A location less than zero will be set to zero; a location greater than the source file size will be set to the end of the source file.
Throws:
  `IOException` - If the source file stream is closed or there was a problem reading data from from the source.
See Also:
  `Stream_Location(long)`

#### close

    public void close()
               throws IOException

All access to the source is closed.

Specified by:
  `close` in interface `Closeable`
Specified by:
  `close` in interface `AutoCloseable`
Specified by:
  `close` in interface `ImageInputStream`
Overrides:
  `close` in class `ImageInputStreamImpl`
Throws:
  `IOException` - If there was a problem closing the server input or output streams or the socket connection.

#### is_Closed

    public boolean is_Closed()

Checks if the server connection is closed.

Returns:
  true if the server connection is closed; false otherwise.

#### Connect

    public void Connect(URL url)
                 throws IOException

Connect to the server.

The specified URL checked for validity. If the URL does not specify a port number, the `DEFAULT_PORT` will be used.

N.B.: Establishing a new server connection causes any existing connection to be closed and the source input location to be `Reset` to the beginning of the file.

Parameters:
  `url` - The URL to use in connection to the server.
Throws:
  `IllegalArgumentException` - If the URL does not specify the http protocol nor provide a source file pathname.
  `UnknownHostException` - If the hostname of the URL can not be resolved to an internet address.
  `IOException` - If the socket connection could not be established or the input or output streams could not be opened.
See Also:
  `Reconnect()`

#### Reconnect

    protected void Reconnect()
                      throws IOException

Reconnect to the server.

If a Socket for communication with the server exists it is closed.

A new Socket connection to the server is constructed. A maximum of `DEFAULT_CONNECT_TIMEOUT` milliseconds is allowed for the connection to be established. Then input and output communication streams with the server are opened over the Socket. Up to `MAX_RECONNECT_ATTEMPTS` connection attempts will be made. On the last attempt, the first connection operation failure that occurs will throw an IOException.

Throws:
  `IOException` - If a Socket could not be constructed on the server address within the `DEFAULT_CONNECT_TIMEOUT` time, a Writer could not be constructed on the Socket or an InputStream could not be constructed on the Socket.

#### Allocate_Buffer

    public void Allocate_Buffer(int capacity)

Allocates a data storage buffer.

A ByteBuffer of the specified size (bytes) is allocated and cleared (position set to zero and limit set to the capacity).

If there is no previously existing source buffer, the newly allocated buffer is set as the source buffer. It is duplicated to provide the image buffer view and the image buffer's limit is set to zero.

If there is a previously existing source buffer, all valid source data is copied from it into the new buffer, up to the capacity of the new buffer, and then the new buffer is set as the source buffer. N.B.: If the new buffer capacity is less than the previous buffer's valid data content, the excess data will be dropped. The source buffer is duplicated onto the temporary buffer, the image buffer limit and position copied over, and then the temporary buffer is set as the image buffer. N.B.: If the previous image buffer limit is greater than the new buffer capacity the new limit will be the new capacity; the same applies to the image buffer position, which would result in a corresponding move back of the logical stream location. Garbage collection is initiated to recover the previous buffer resources.

Parameters:
  `capacity` - The capacity of the new buffer. If less than twice the `INPUT_INCREMENT` it will be increased to this value.

#### Drain

    public int Drain(int amount)

Drain data from the buffer.

The logical location of the buffer in the source data stream is moved forward by some amount. This has the effect of draining valid source data from the front of the buffer and sliding the buffer forward to a new location in the source file.

If the amount is less than or equal to zero, nothing is done.

If the amount is greater than or equal to the end of valid source data in the buffer (image buffer limit), the buffer is simply (@link #Empty() emptied}.

The remaining source data beyond the amount buffer index is moved to the beginning of the buffer. The buffer's logical position is the source data stream is moved forward by the amount of data removed (the slide distance). The source buffer input position and image buffer limit are reset to the new end of valid source data. The image buffer position is moved back by the amount of of data removed. However, if this new position would be less than zero it is set to zero, and the current logical stream location is moved up by the difference (i.e. to the buffer's logical position in the stream).

Parameters:
  `amount` - The amount of data to drain.
Returns:
  The amount of source data effectively removed from the buffer (i.e. the slide distance).

#### Drain

    public int Drain()

Drain source data before the current stream position.

This has the same effect as `drain`ing all data before the current stream (image buffer) position.

Returns:
  The amount of source data effectively removed from the buffer (i.e. the slide distance).
See Also:
  `Drain(int)`

#### Empty

    public int Empty()

Empty the buffer of all source data.

The buffer's logical location in the source data stream is moved up to the end of source data content in the buffer, and the current source data stream position is set to this location. The source buffer position is set to the beginning of the buffer as are the image buffer position and data limit. This has the same effect as `drain`ing all the data content from the buffer.

Returns:
  The amount of source data effectively removed from the buffer (i.e. the slide distance).

#### Reset

    public void Reset(long location)

Reset the buffer to a new source location and empty it.

<b.N.B.: All buffered source data is dropped regardless of the location relative to the current buffered source data range.

Parameters:
  `location` - The new buffer and stream position location.

#### Buffer_Location

    public long Buffer_Location()

Get the virtual source location of the beginning of the buffer.

Returns:
  The source file offset where the buffer begins.

#### Buffer_Location

    protected void Buffer_Location(long location)

Set the virtual source location of the beginning of the buffer.

N.B.: Changing the virtual source location of the buffer will affect all other buffer virtual locations because they are relative to the buffer location.

Parameters:
  `location` - The source file offset where the buffer begins. A value less than zero is set to zero; a value greater than the size of the source file is set to the size of the source file.

#### Stream_Location

    protected long Stream_Location()

Get the virtual source location where the next image buffer will be read.

Returns:
  The current image buffer virtual source file offset location.

#### Stream_Location

    public void Stream_Location(long location)
                         throws IOException

Set the virtual source location where the next image buffer will be read.

If the location is within the range of buffered source data the image buffer position is simply moved to the corresponding position.

The location is less than zero, zero will be used; if it is greater than the size of the source file, the location will be set to the end of the source data.

If the location is the same as the current virtual source stream location nothing is done.

If the location is before the stream location of the first byte in the image buffer and within `INPUT_INCREMENT` bytes of the beginning of the buffer, the current buffered data will be shifted up by INPUT_INCREMENT bytes and the resulting gap at the beginning of the buffer filled with data `Fetch`ed from the corresponding offset range of the source file. The image buffer position is then set to correspond to the new stream location.

If the location is beyond the end of buffered data, but not beyond the end of the maximum capacity of the buffer, and within INPUT_INCREMENT bytes of the end of data, up to INPUT_INCREMENT additional bytes (not more than would fill the buffer to capacity) are `Fetch`ed from the source file to extend the buffered data. The image buffer position is then set to correspond to the new stream location.

For any other case the buffer is simply `Reset` to the new location.

The effect is a random access seek to any location within the source file, with data pre-fetch optimization when the new location is near the currently buffered data.

Parameters:
  `location` - The source file offset for the image buffer's next read position.
Throws:
  `IOException`

#### Data_End_Location

    public long Data_End_Location()

Get the virtual source location of the end (exclusive) of buffered data.

Returns:
  The source file offset where buffered data ends.

#### Data_End_Location

    protected void Data_End_Location(long location)

Set the virtual source location of the end (exclusive) of buffered data.

N.B.: If the new location is less than the buffer's current virtual source location, the virtual source location will also be moved to the new location. This enforces the constraint that the virtual source location is always less than or equal to the end of data location.

Parameters:
  `location` - The source file offset where the end of buffered data is located. The location is clipped to produce a buffer position with the range of the buffer capacity.

#### Location_for_Position

    protected long Location_for_Position(int position)

Convert a buffer position to a virtual source location.

Parameters:
  `position` - A buffer position int.
Returns:
  A source location long.

#### Position_for_Location

    protected int Position_for_Location(long location)

Convert a virtual source location to a buffer position.

Parameters:
  `location` - A source location long.
Returns:
  A buffer position int.

#### Image_Buffer_Range

    public long Image_Buffer_Range(long location)

Clip a source location to the currently buffered data range.

Parameters:
  `location` - A source location long.
Returns:
  The source location clipped to the range of buffered data.

#### in_Image_Buffer_Range

    public boolean in_Image_Buffer_Range(long location)

Test if a source location is in the range of buffered data.

The buffered data range begins at the `Buffer_Location()` (inclusive) and extends to the `Data_End_Location()` (exclusive).

Parameters:
  `location` - A source location long.
Returns:
  true if the location is the range of buffered data; false otherwise.

#### Check_Source

    public int Check_Source()

Check the server status of the source.

A "HEAD" request for the source file is made to the server. The reponse to a "HEAD" request will contain all the HTTP headers of a normal request, but no data content will be included.

If access to the server is closed, then the last HTTP status value will be returned. If no HTTP status value was ever obtained zero will be returned. If an end of file condition is encountered will communicating with the server, -1 will be returned. If some other IOException is thrown, -2 will be returned. If any other Exception is thrown, -3 will be returned.

The HTTP status when the source file is correctly found is less than `SUCCESS_STATUS_LIMIT`. If the source file is not found the status will be `SOURCE_NOT_FOUND_STATUS`.

Returns:
  The HTTP response status.

#### Fetch

    public int Fetch(long start,
            long end)
              throws IllegalArgumentException,
                     IOException

Fetch source data from the server (absolute fetch).

The data will be fetched from the source file beginning at the start location up to, but not including, the end location.

If the start location is within the buffered source data range it is moved up to the end of data location. If the start location is at or beyond the end of the source file, nothing is done and zero is returned. If, after range clipping, the start location is not the same as the end of source data location in the buffer, the buffer is is `reset` to the start location. The end location will be clipped to the size of the source file.

If communication with the server is lost during the data fetch, a `reconnect`ion will be tried. If this succeeds the data fetch will be repeated.

Parameters:
  `start` - The source file offset (inclusive) where the data fetch is to begin.
  `end` - The source file offset (exclusive) where the data fetch is to end.
Returns:
  The amount of data received from the server.
Throws:
  `IllegalArgumentException` - If start is less than zero or greater than end.
  `IOException` - If there was a problem communicating with the server.
See Also:
  `Request_Source_Data(long, long)`, `Receive()`

#### Fetch

    public int Fetch(int amount)
              throws IOException

Fetch source data from the server (relative fetch).

The data will be fetched from the source file starting at the current end of source data location in the buffer.

Parameters:
  `amount` - The amount of data to fetch.
Returns:
  The amount of data fetched.
Throws:
  `IOException` - If there was a problem send or receiving data from the server.

#### Request_Source_Data

    protected HTTP_ImageInputStream Request_Source_Data(long start,
                                            long end)
                                                 throws IllegalArgumentException,
                                                        BufferOverflowException,
                                                        IOException

Get a range of source data.

N.B.: No check is made of the validity of the source range.

Parameters:
  `start` - The file offset of the start of the data range (inclusive).
  `end` - The file offset of the end of the data range (exclusive).
Returns:
  This HTTP_ImageInputStream.
Throws:
  `IllegalArgumentException` - If start is greater than end.
  `BufferOverflowException` - If the (end - start) amount is greater than Integer.MAX_VALUE.
  `IOException` - If there was a problem sending the request to the server.

#### Request

    protected void Request(String method,
               String request)
                    throws IOException

Issue a Request preamble to the server.

After the HTTP formatted request is `sent` to the server, the Host, User-Agent, and Cache-Control (no-cache) requests are also sent. N.B.: The request sequence has not been `ended`.

Parameters:
  `method` - The request method String. This is typically "GET".
  `request` - The request operation.
Throws:
  `IOException`
See Also:
  `Send(String)`

#### End_Request

    protected void End_Request()
                        throws IOException

Send the end-of-request sequence to the server.

An single empty line is sent.

Throws:
  `IOException`

#### Send

    protected void Send(String message)
                 throws IOException

Send a message line to the server.

The message is expected to be a single line to be sent to the server. An end of line sequence will be appended to the message that is sent if it is not already present.

If `Logging` is enabled the message, preceded by the `LOG_OUTPUT_PREFIX`, will be printed to stdout before it is sent to the server.

Parameters:
  `message` - The message String to be sent.
Throws:
  `IOException` - If the connection to the server is closed or there was a problem sending the message.

#### Receive

    protected int Receive()
                   throws IOException

Receive a response to a server request.

Server interaction always occurs in `Request`-Receive pairs. After a Request has been sent it is necessary to Receive the response from the server. The first part of the response is sequence of one or more HTTP header lines. If a Content-Length line is present the header lines are followed by data content of Content-Length bytes.

If the HTTP response headers contain a `Status` value that is less than 300, the data content is read into the Source_Buffer starting at its current position. However, if the amount of free space remaining in the buffer (buffer storage not occupied by valid data content; i.e. locations [position, limit), where limit == capacity) is less than the Content-Length, more buffer space is first provided.

Space to store data content in the buffer is provided by `drain`ing away data from the beginning of the buffer before the current source stream position.

Returns:
  The amount of source data received, or -1 if EOF was encountered before any data was received.
Throws:
  `IOException`

#### Headers

    protected int Headers()
                   throws IOException

Get the HTTP response headers from the server.

After a `Request` has been sent to the server - probably followed by `Send`ing additional request messages - and `End`ed, the server response will begin with a sequence of HTTP headers. Each response line up to, but not including, an empty line will be added to a Vector of HTTP Headers in which each element is itself a Vector containing the header name and content. Note: A header line can be wrapped across multiple response lines; the wrapped line(s) begin with whitespace. In addition, a header with the same name as a previous header will have its content appended to previous header. This guarantees that each header in the Vector of HTTP Headers will have a unique name.

Before the header lines are accumulated the HTTP Headers Vector is cleared and the HTTP response `Status` is reset to zero. As the header lines are being accumulated the HTTP response status will be updated if it is found. In addition, the `source file size` will also be set if it is found the response.

Returns:
  The HTTP response status.
Throws:
  `IOException` - If an problem was encountered while reading response lines. This will be an EOFException if an end of input from the server was encountered.

#### Header_Content

    public String Header_Content(String name)

Get the header content for a named header.

Parameters:
  `name` - The name of a header.
Returns:
  The content String for the named header, or null if the header name was not found.

#### Header_Field

    public String Header_Field(String name)

Get the complete header field for a named header.

The header field is provided in the same syntax as it was received from the server. However, any header wrapping has been removed. If multiple headers with the same name were received, a single header field with all content appended in the order it was received is provided.

Parameters:
  `name` - The name of a header.
Returns:
  The complete header field String.

#### Header_Value

    public String Header_Value(String name,
                      String value_name)

Get a header field value by name.

A header field is divided into value fields by any one of the ':', ';', ',', '&' or whitespace characters. A value field occurs in in header content as a value name separated from its value by an '=' character.

Parameters:
  `name` - The name of a header.
  `value_name` - The name of a content value.
Returns:
  The value String. This will be null if the header or value name is not found.

#### Header_Value

    public String Header_Value(String name,
                      int value_index)

Get a header field value by index within the field content.

Parameters:
  `name` - The name of a header.
  `value_index` - An index int, starting with zero for the first value in the content.
Returns:
  The value String. This will be null if the header or value is not found.
See Also:
  `Header_Value(String, String)`

#### Status

    public int Status()

Get the HTTP status of the last response from the server.

The HTTP status is expected to be the second field value of the "HTTP" response header.

Returns:
  The HTTP status value. This will be zero if no HTTP status has yet been found. It will be negative if the expected HTTP status field does not contain an integer value.

#### Source_Size

    public long Source_Size()

Get the size of the source file.

If the source file size has already been determined the cached value is returned.

The size of the source file is obtained from the `"Content-Range"` HTTP response header. If a valid size value is found the cached value is updated and that value returned.

Returns:
  The size of the source file. This will be `NO_SOURCE_SIZE` if the size is unknown.

#### Content_Length

    public long Content_Length()

Get the length of server response data content.

The length of the data content is expected to be the first field of the "Content-Length" HTTP response header.

Returns:
  The long value length of the response data content. This will be -1 if the content length could not be found. It will be -2 if the expected HTTP header field does not contain an valid value.

#### Content_Range

    public HTTP_ImageInputStream.Range Content_Range()

Get the Content-Range header values.

The format of the Content-Range header is:

Content-Range: bytes start-end/length

Where <start> and <end> are byte offsets into the source file for the start and end (inclusive) of the bytes returned. The <length> value is the total length of the source file.

Returns:
  A Range containing the Content-Range values, or null if no Content-Range header could be found. Missing values in the range are indicated by the value -1.

#### main

    public static void main(String[] args)

#### Usage

    public static void Usage()