SubStream Class

Package:

com.microsoft.azure.storage.blob

• java.lang.Object
• • InputStream
  • • com.microsoft.azure.storage.blob.SubStream

public class SubStream

Constructor Summary

Constructor	Description
SubStream(InputStream source, long startIndex, long streamLength, Object lock)	Creates a new substream instance that partitions the wrapped stream from up to . Each substream instance that wraps the same underlying must share the same mutual exclusion to avoid race conditions from concurrent operations.

Method Summary

Modifier and Type	Method and Description
void	close() Closes the substream.
InputStream	getInputStream()
long	getLength()
synchronized void	mark(int readlimit) Marks the current position in the substream. A subsequent call to the method will reposition the stream to this stored position.
boolean	markSupported() The substream wrapper class is only compatible with markable input streams and hence will always return true. This requirement is enforced in the class constructor.
int	read() Reads the next byte of data from the wrapped stream. The value byte is returned as an in the range to . If no byte is available because the end of the substream has been reached, the value is returned. This method blocks until input data is available, the end of the stream is detected, or an exception is thrown.
synchronized int	read(byte[] b) Reads some number of bytes from the wrapped stream and stores them into the buffer array . The number of bytes actually read is returned as an integer. This method blocks until input data is available, end of file is detected, or an exception is thrown. If the length of is zero, then no bytes are read and is returned; otherwise, there is an attempt to read at least one byte. If no byte is available because the substream is at the end of the file, the value is returned; otherwise, at least one byte is read and stored into . The first byte read is stored into element , the next one into , and so on. The number of bytes read is, at most, equal to the length of . Let k be the number of bytes actually read; these bytes will be stored in elements through k, leaving elements k through unaffected. The method for class has the same effect as:
synchronized int	read(byte[] b, int off, int len) Reads up to bytes of data from the substream. Buffers data from the wrapped stream in order to minimize skip and read overhead. The wrappedstream will only be invoked if the readBuffer cannot fulfil the the read request. In order to ensure valid results, the wrapped stream must be marked prior to reading from the substream. This allows us to reset to the relative substream position in the wrapped stream. The number of bytes actually read is returned as an integer. All these operations are done synchronously within an intrinsic lock to ensure other concurrent requests by substream instances do not result in race conditions. The underlying call to the read of the wrapped stream will blocks until input data is available, end of file is detected, or an exception is thrown. If is zero, then no bytes are read and is returned; otherwise, there is an attempt to read at least one byte. If no byte is available because the substream is at end of file, the value is returned; otherwise, at least one byte is read and stored into .
synchronized void	reset() Repositions the substream position to the index where the method was last called. The new reset position on substream does not take effect until subsequent reads.
long	skip(long n) Advances the current position of the substream by . The method does not invoke the underlying method of the wrapped stream class. The actual skipping of bytes will be accounted for during subsequent substream read operations.

Constructor Details

SubStream

public SubStream(InputStream source, long startIndex, long streamLength, Object lock)

Creates a new substream instance that partitions the wrapped stream from up to . Each substream instance that wraps the same underlying must share the same mutual exclusion to avoid race conditions from concurrent operations.

Parameters:

source - The markable InputStream to be wrapped.

startIndex - A valid index in the wrapped stream where the substream should logically begin.

streamLength - The length of the substream.

lock - An intrinsic lock to ensure thread-safe, concurrent operations on substream instances wrapping the same InputStream.

Method Details

close

public void close()

Closes the substream.

getInputStream

public InputStream getInputStream()

getLength

public long getLength()

mark

public synchronized void mark(int readlimit)

Marks the current position in the substream. A subsequent call to the method will reposition the stream to this stored position.

Parameters:

readlimit - the maximum limit of bytes that can be read before the mark position becomes invalid.

markSupported

public boolean markSupported()

The substream wrapper class is only compatible with markable input streams and hence will always return true. This requirement is enforced in the class constructor.

Returns:

true

read

public int read()

Reads the next byte of data from the wrapped stream. The value byte is returned as an in the range to . If no byte is available because the end of the substream has been reached, the value is returned. This method blocks until input data is available, the end of the stream is detected, or an exception is thrown.

Returns:

the next byte of data, or -1 if the end of the substream is reached.

Throws:

IOException - if an I/O error occurs.

read

public synchronized int read(byte[] b)

Reads some number of bytes from the wrapped stream and stores them into the buffer array . The number of bytes actually read is returned as an integer. This method blocks until input data is available, end of file is detected, or an exception is thrown.

If the length of is zero, then no bytes are read and is returned; otherwise, there is an attempt to read at least one byte. If no byte is available because the substream is at the end of the file, the value is returned; otherwise, at least one byte is read and stored into .

The first byte read is stored into element , the next one into , and so on. The number of bytes read is, at most, equal to the length of . Let k be the number of bytes actually read; these bytes will be stored in elements through k, leaving elements k through unaffected.

The method for class has the same effect as:

Parameters:

b - the buffer into which the data is read.

Returns:

the total number of bytes read into the buffer, or -1 if there is no more data because the end of the stream has been reached.

Throws:

IOException - If the first byte cannot be read for any reason other than the end of the file, if the wrapped stream has been closed, or if some other I/O error occurs.

NullPointerException - if b is null.

read

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

Reads up to bytes of data from the substream. Buffers data from the wrapped stream in order to minimize skip and read overhead. The wrappedstream will only be invoked if the readBuffer cannot fulfil the the read request. In order to ensure valid results, the wrapped stream must be marked prior to reading from the substream. This allows us to reset to the relative substream position in the wrapped stream. The number of bytes actually read is returned as an integer. All these operations are done synchronously within an intrinsic lock to ensure other concurrent requests by substream instances do not result in race conditions.

The underlying call to the read of the wrapped stream will blocks until input data is available, end of file is detected, or an exception is thrown.

If is zero, then no bytes are read and is returned; otherwise, there is an attempt to read at least one byte. If no byte is available because the substream is at end of file, the value is returned; otherwise, at least one byte is read and stored into .

Parameters:

b - the buffer into which the data is read.

off - the start offset in array b at which the data is written.

len - the maximum number of bytes to read.

Returns:

the total number of bytes read into the buffer, or -1 if there is no more data because the end of the stream has been reached.

Throws:

IOException - If the first byte cannot be read for any reason other than end of file, or if the wrapped stream has been closed, or if some other I/O error occurs.

NullPointerException - If b is null.

IndexOutOfBoundsException - If off is negative, len is negative, or len is greater than b.length - off

reset

public synchronized void reset()

Repositions the substream position to the index where the method was last called.

The new reset position on substream does not take effect until subsequent reads.

skip

public long skip(long n)

Advances the current position of the substream by . The method does not invoke the underlying method of the wrapped stream class. The actual skipping of bytes will be accounted for during subsequent substream read operations.

Parameters:

n - the number of bytes to be effectively skipped.

Returns:

the actual number of bytes skipped.