PIRL.Image_Tools
Class HTTP_ImageInputStream

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

All Implemented Interfaces:

DataInput, 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.

Version:

1.14

Author:

Bradford Castalia UA/PIRL

See Also:

ImageInputStream

Nested Class Summary

class

HTTP_ImageInputStream.Range A Range contains Start, End and Length values.

Field Summary

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

HTTP_ImageInputStream(URL url)
Constructs an HTTP_ImageInputStream on a URL.

Method Summary

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 connection 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 received 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 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 draining 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 draining 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.

: 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 Fetched 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 Fetched 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 reconnection 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 draining 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 Sending additional request messages - and Ended, 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 and are byte offsets into the source file for the start and end (inclusive) of the bytes returned. The 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()