net.rim.device.api.io
Class SharedInputStream

java.lang.Object
  java.io.InputStream
      net.rim.device.api.io.SharedInputStream

public class SharedInputStream
extends InputStream

Input stream that can share its stream data with a number of readers.

This class allows you to have multiple readers reading from one shared input stream, but allows each reader to have their own independent read position in the stream.

This class could be used to implement something like an ASN1 parser where one reader could be reading an internal SEQUENCE structure while another reader is reading from the external ASN1 stream of which the internal SEQUENCE is just a part.

Constructor Summary

SharedInputStream(byte[] input)
Deprecated. Use instead SharedInputStream.getSharedInputStream( byte[] input )

SharedInputStream(SharedInputStream input)
Constructs a new SharedInputStream instance on provided shared input stream.

SharedInputStream(SharedInputStream input, int length)
Deprecated. Use instead new SharedInputStream( SharedInputStream input ) and then setLength( int length ) on the new stream

Method Summary
int	available() Retrieves number of bytes immediately available for reading.
int	getCurrentPosition() Retrieves current read position within this stream.
static SharedInputStream	getSharedInputStream(byte[] input) Retrieves a SharedInputStream from byte[].
static SharedInputStream	getSharedInputStream(InputStream input) Retrieves a SharedInputStream from provided input stream.
static SharedInputStream	getSharedInputStream(InputStream input, int length) Deprecated. Use instead SharedInputStream.getSharedInputStream( InputStream input ) and then setLength on the new stream.
int	peek() Looks at the next byte in the stream without advancing the read position.
int	read() Read next byte in the stream.
int	read(byte[] buffer, int offset, int length) Reads a number of bytes from the stream.
SharedInputStream	readInputStream() Retrieves new shared input stream built on current stream.
SharedInputStream	readInputStream(int length) Deprecated. Use instead readInputStream() and then use setLength( int length ) on the new stream.
void	setCurrentPosition(int currentPosition) Sets current read position within this stream.
void	setLength(int length) Sets length for this input stream.
long	skip(long n) Skip read position forward.

Methods inherited from class java.io.InputStream

close, mark, markSupported, read, reset

Methods inherited from class java.lang.Object

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

Constructor Detail

SharedInputStream

public SharedInputStream(byte[] input)

Deprecated. Use instead SharedInputStream.getSharedInputStream( byte[] input )

Constructs a new SharedInputStream instance on provided byte array.

Parameters:

input - Byte array to use as underlying data buffer for this stream.

SharedInputStream

public SharedInputStream(SharedInputStream input)

Constructs a new SharedInputStream instance on provided shared input stream.

This builds a new shared input stream that shares the underlying data buffer of another shared input stream.

Parameters:

input - Shared input stream whose buffer to share.

SharedInputStream

public SharedInputStream(SharedInputStream input,
                         int length)

Deprecated. Use instead new SharedInputStream( SharedInputStream input ) and then setLength( int length ) on the new stream

Constructs a new SharedInputStream instance on a section of provided shared input stream.

This builds a new shared input stream that shares a section of the underlying data buffer of another shared input stream.

Parameters:

input - Shared input stream whose buffer to share.

length - Section of buffer to read from starts at the provided input stream parameter's read position, and proceeds for length bytes.

Method Detail

getSharedInputStream

public static SharedInputStream getSharedInputStream(InputStream input)

Retrieves a SharedInputStream from provided input stream.

Parameters:

input - The InputStream to use as source of input.

Returns:

A SharedInputStream reading from the provided the InputStream.

getSharedInputStream

public static SharedInputStream getSharedInputStream(byte[] input)

Retrieves a SharedInputStream from byte[].

Parameters:

input - byte[] to use as source of input.

Returns:

A SharedInputStream reading from the provided InputStream.

Since:

BlackBerry API 3.6.0

getSharedInputStream

public static SharedInputStream getSharedInputStream(InputStream input,
                                                     int length)

Deprecated. Use instead SharedInputStream.getSharedInputStream( InputStream input ) and then setLength on the new stream.

Retrieves a SharedInputStream from section of provided InputStream.

Parameters:

input - The InputStream to use as source of input.

length - Section of input stream to read from starts at the provided input stream parameter's read position, and proceeds for length bytes.

Returns:

A SharedInputStream reading from the provided InputStream.

setLength

public void setLength(int length)

Sets length for this input stream.

Parameters:

length - Maximum number of bytes for this input stream.

peek

public int peek()
         throws IOException

Looks at the next byte in the stream without advancing the read position.

Returns:

Next byte in stream returned as an integer in the range 0 to 255; if no more bytes to read, then this method returns -1.

Throws:

IOException

read

public int read()
         throws IOException

Read next byte in the stream.

Specified by:

read in class InputStream

Returns:

Next byte in stream returned as an integer in the range 0 to 255; if no more bytes to read, then this method returns -1.

Throws:

IOException - if an I/O error occurs.

read

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

Reads a number of bytes from the stream.

Use this method to read a number of bytes from the stream into a buffer. This method blocks until input data is available, it detects an end of file, or an exception is thrown.

Overrides:

read in class InputStream

Parameters:

buffer - Buffer to contain the read bytes; must not be null.

offset - First element in the buffer parameter to receive a byte from the stream.

length - Number of bytes to read from the stream.

Returns:

Number of bytes actually read, or -1 if the stream is at the end of file.

Throws:

IOException - If an I/O error occurs.

See Also:

InputStream.read()

skip

public long skip(long n)
          throws IOException

Skip read position forward.

Overrides:

skip in class InputStream

Parameters:

n - Number of bytes to skip forward.

Returns:

Actual number of bytes skipped.

Throws:

IOException - If an I/O error occurs.

available

public int available()
              throws IOException

Retrieves number of bytes immediately available for reading.

Overrides:

available in class InputStream

Returns:

Number of bytes that could immediately be read from the stream.

Throws:

IOException - If an I/O error occurs.

readInputStream

public SharedInputStream readInputStream()

Retrieves new shared input stream built on current stream.

Returns:

A SharedInputStream built on current stream, using this stream's current read position as the new stream's initial read position.

readInputStream

public SharedInputStream readInputStream(int length)

Deprecated. Use instead readInputStream() and then use setLength( int length ) on the new stream.

Retrieves a new SharedInputStream built on a section of the current stream.

Parameters:

length - Number of bytes available in new stream.

Returns:

A SharedInputStream built on current stream, using this stream's current read position as the initial read position, and extending for a number of bytes equal to the length parameter.

getCurrentPosition

public int getCurrentPosition()

Retrieves current read position within this stream.

Returns:

Current read position.

setCurrentPosition

public void setCurrentPosition(int currentPosition)

Sets current read position within this stream.

Parameters:

currentPosition - New read position to use; must be greater than or equal to zero, or this method will throw an IllegalArgumentException.

Throws:

IllegalArgumentException - Thrown if the value of currentPosition is less than zero.