com.levigo.jadice.document.io
Class HTTPRangeRequestStream

java.lang.Object
  java.io.InputStream
      com.levigo.jadice.document.io.SeekableInputStream
          com.levigo.jadice.document.io.HTTPRangeRequestStream

All Implemented Interfaces:

Closeable, DataInput, ImageInputStream

public class HTTPRangeRequestStream
extends SeekableInputStream

A SeekableInputStream which uses HTTP Range Requests as specified in RFC7233 in order to provide efficient random access to resources available through a range-request-capable HTTP server. Accessing resources on servers which do not support range requests is possible but in most cases horribly inefficient. A warning is issued, if a server does not support range requests. The property setFailOnUnsupportedRangeRequest(boolean) may be set to true in order to cause an explicit failure in this situation. It is not recommended to use this stream implementation directly as a source for document data. Access patterns with frequent seeks and small request sizes (may) lead to frequent HTTP reconnects. Instead, please consider wrapping this stream in caching streams supporting random access like the BufferManagerInputStream.

Field Summary

Fields inherited from class com.levigo.jadice.document.io.SeekableInputStream

bitOffset, byteOrder, flushedPos

Constructor Summary

HTTPRangeRequestStream(URL url)
Create a stream for a resource at the given URL for which the length is not already known.

HTTPRangeRequestStream(URL url, long length)
Create a stream for a resource at the given URL which is known to have the given length.

Method Summary

long	getRangeRequestSize() Get the length of the range request to issue.
long	getReopenForwardThreshold() Get the threshold beyond which we re-open a connection if the current (seek) position is after the current stream position.
long	getSizeEstimate() A rough estimated size for this stream instance, which is used for internal cache management.
long	getStreamPosition()
boolean	isFailOnUnsupportedRangeRequest() Return whether the transfer will fail if the target HTTP service does not support range requests ( true) or fall back to plain streaming transfer (false).
long	length() Returns the length of this stream contents, if available.
int	read() Reads a single byte from the stream and returns it as an int between 0 and 255.
int	read(byte[] b, int off, int len) Reads up to len bytes from the stream, and stores them into b starting at index off.
void	seek(long pos) Sets the current stream position, measured from the beginning of this data stream, at which the next read occurs.
void	setFailOnUnsupportedRangeRequest(boolean failOnUnsupportedRangeRequest) Set whether to fail if the target HTTP service does not support range requests ( true) or to fall back to plain streaming transfer (false).
void	setRangeRequestSize(long rangeRequestSize) Set the length of the range request to issue.
void	setReopenForwardThreshold(long reopenForwardThreshold) Set the threshold beyond which we re-open a connection if the current (seek) position is after the current stream position.

Methods inherited from class com.levigo.jadice.document.io.SeekableInputStream

checkClosed, close, finalize, flush, flushBefore, getBitOffset, getByteOrder, getFlushedPosition, isCached, isCachedFile, isCachedMemory, mark, mark, read, readBit, readBits, readBoolean, readByte, readBytes, readChar, readDouble, readFloat, readFully, readFully, readFully, readFully, readFully, readFully, readFully, readFully, readInt, readInt, readLine, readLong, readShort, readUnsignedByte, readUnsignedInt, readUnsignedInt, readUnsignedShort, readUTF, reset, resetToInitialState, setBitOffset, setByteOrder, skip, skipBytes, skipBytes

Methods inherited from class java.io.InputStream

available, markSupported

Methods inherited from class java.lang.Object

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

Constructor Detail

HTTPRangeRequestStream

public HTTPRangeRequestStream(URL url)
                       throws IOException

Create a stream for a resource at the given URL for which the length is not already known. An attempt will be made during construction to determine the resource's length. If this attempt results in a server response indicating that the resource's length cannot be determined by the server, calls to length() will return -1.

Parameters:

url -

Throws:

IOException - if the request used to determine the resource length fails

HTTPRangeRequestStream

public HTTPRangeRequestStream(URL url,
                              long length)

Create a stream for a resource at the given URL which is known to have the given length.

Parameters:

url -

length -

Method Detail

getStreamPosition

public long getStreamPosition()
                       throws IOException

Throws:

IOException

getSizeEstimate

public long getSizeEstimate()

Description copied from class: SeekableInputStream

A rough estimated size for this stream instance, which is used for internal cache management.

Specified by:

getSizeEstimate in class SeekableInputStream

Returns:

an estimated size

length

public long length()
            throws IOException

Description copied from class: SeekableInputStream

Returns the length of this stream contents, if available. Otherwise -1L will be returned.

Specified by:

length in interface ImageInputStream

Specified by:

length in class SeekableInputStream

Returns:

the length, measured in bytes or -1L if unknown.

Throws:

IOException - if an I/O error occurs.

read

public int read()
         throws IOException

Description copied from class: SeekableInputStream

Reads a single byte from the stream and returns it as an int between 0 and 255. If EOF is reached, -1 is returned.

Subclasses must provide an implementation for this method. The subclass implementation should update the stream position before exiting.

The bit offset within the stream must be reset to zero before the read occurs.

Specified by:

read in interface ImageInputStream

Specified by:

read in class SeekableInputStream

Returns:

the value of the next byte in the stream, or -1 if EOF is reached.

Throws:

IOException - if the stream has been closed.

read

public int read(byte[] b,
                int off,
                int len)
         throws IOException

Description copied from class: SeekableInputStream

Reads up to len bytes from the stream, and stores them into b starting at index off. If no bytes can be read because the end of the stream has been reached, -1 is returned.

The bit offset within the stream must be reset to zero before the read occurs.

Subclasses must provide an implementation for this method. The subclass implementation should update the stream position before exiting.

Specified by:

read in interface ImageInputStream

Specified by:

read in class SeekableInputStream

Parameters:

b - an array of bytes to be written to.

off - the starting position within b to write to.

len - the maximum number of bytes to read.

Returns:

the number of bytes actually read, or -1 to indicate EOF.

Throws:

IOException - if an I/O error occurs.

seek

public void seek(long pos)
          throws IOException

Description copied from class: SeekableInputStream

Sets the current stream position, measured from the beginning of this data stream, at which the next read occurs. The offset may be set beyond the end of this data stream. Setting the offset beyond the end does not change the data length, an EOFException will be thrown only if a read is performed. The bit offset is set to 0.

An IndexOutOfBoundsException will be thrown if pos is smaller than the flushed position (as returned by getflushedPosition).

It is legal to seek past the end of the file; an EOFException will be thrown only if a read is performed.

Specified by:

seek in interface ImageInputStream

Specified by:

seek in class SeekableInputStream

Parameters:

pos - a long containing the desired file pointer position.

Throws:

IOException - if any other I/O error occurs.

getRangeRequestSize

public long getRangeRequestSize()

Get the length of the range request to issue.

Returns:

the size in bytes

setRangeRequestSize

public void setRangeRequestSize(long rangeRequestSize)

Set the length of the range request to issue. Smaller length lead to more round-trips but may also mean less overhead if only a small parts of the resource are needed. If set to -1 open-ended range requests are issued. Those are ideal if access is mostly forward-streaming but preclude the connection from using HTTP keep-alive as each connection must be forcibly torn down when seeking.

Parameters:

rangeRequestSize - the size in bytes

getReopenForwardThreshold

public long getReopenForwardThreshold()

Get the threshold beyond which we re-open a connection if the current (seek) position is after the current stream position.

Returns:

the size in bytes

setReopenForwardThreshold

public void setReopenForwardThreshold(long reopenForwardThreshold)

Set the threshold beyond which we re-open a connection if the current (seek) position is after the current stream position. If the delta is below the threshold, repositioning will be performed by skipping over the current stream. Use large values if you expect your network to be fast and the cost of additional HTTP turn-arounds to outweigh the bandwidth wasted by skipping over unwanted data. In general, using values close to or below the size of an HTTP handshake (i.e. a few 100 to 1000 bytes) will be inefficient and is not recommended.

Parameters:

reopenForwardThreshold - the size in bytes

isFailOnUnsupportedRangeRequest

public boolean isFailOnUnsupportedRangeRequest()

Return whether the transfer will fail if the target HTTP service does not support range requests ( true) or fall back to plain streaming transfer (false).

Returns:

true if transfers will fail if the target HTTP service does not support range requests.

setFailOnUnsupportedRangeRequest

public void setFailOnUnsupportedRangeRequest(boolean failOnUnsupportedRangeRequest)

Set whether to fail if the target HTTP service does not support range requests ( true) or to fall back to plain streaming transfer (false). Default: false

Parameters:

failOnUnsupportedRangeRequest - set to true to fail if the target HTTP service does not support range requests.