org.apache.derby.impl.jdbc
Class PositionedStoreStream

java.lang.Object
  java.io.InputStream
      org.apache.derby.impl.jdbc.PositionedStoreStream

All Implemented Interfaces:

java.io.Closeable, PositionedStream, Resetable

public class PositionedStoreStream
extends java.io.InputStream
implements PositionedStream, Resetable

A wrapper-stream able to reposition the underlying store stream.

Where a user expects the underlying stream to be at a given position, reposition(long) must be called with the expected position first. A use case for this scenario is the LOB objects, where you can request a stream and at the same time (this does not mean concurrently) query the LOB about its length or ask to get a part of the LOB returned. Such multiplexed operations must result in consistent and valid data, and to achieve this the underlying store stream must be able to reposition itself. Synchronization: Access to instances of this class must be externally synchronized on the connection synchronization object. There are two reasons for this:

• Access to store must be single threaded.
• This class is not thread safe, and calling the various methods from different threads concurrently can result in inconsistent position values. To avoid redundant internal synchronization, this class assumes and requires external synchronization (also called client-side locking).

See Also:

EmbedConnection.getConnectionSynchronization()

Field Summary

private long	pos Position of the underlying store stream.
private java.io.InputStream	stream Underlying store stream serving bytes.

Constructor Summary

PositionedStoreStream(java.io.InputStream in)
Creates a positioned store stream on top of the specified resettable stream.

Method Summary

java.io.InputStream	asInputStream() Returns a reference to self as an InputStream.
void	closeStream() Closes the resettable stream.
long	getPosition() Returns the current position of the underlying store stream.
void	initStream() Initialize the resettable stream for use.
int	read() Reads a single byte from the underlying stream.
int	read(byte[] b) Reads a number of bytes from the underlying stream and stores them in the specified byte array.
int	read(byte[] b, int off, int len) Reads a number of bytes from the underlying stream and stores them in the specified byte array at the specified offset.
void	reposition(long requestedPos) Repositions the underlying store stream to the requested position.
void	resetStream() Resets the resettable stream.
long	skip(long toSkip) Skips up to the specified number of bytes from the underlying stream.

Methods inherited from class java.io.InputStream

available, close, mark, markSupported, reset

Methods inherited from class java.lang.Object

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

Field Detail

stream

private final java.io.InputStream stream

Underlying store stream serving bytes.

pos

private long pos

Position of the underlying store stream. Note that the position is maintained by this class, not the underlying store stream itself. Future improvement: Add this functionality to the underlying store stream itself to avoid another level in the stream stack.

Constructor Detail

PositionedStoreStream

public PositionedStoreStream(java.io.InputStream in)
                      throws java.io.IOException,
                             StandardException

Creates a positioned store stream on top of the specified resettable stream.

Upon creation, the underlying stream is initiated and reset to make sure the states of the streams are in sync with each other.

Parameters:

in - a Resetable-stream

Throws:

java.io.IOException

StandardException

Method Detail

read

public int read(byte[] b)
         throws java.io.IOException

Reads a number of bytes from the underlying stream and stores them in the specified byte array.

Overrides:

read in class java.io.InputStream

Returns:

The actual number of bytes read, or -1 if the end of the stream is reached.

Throws:

java.io.IOException - if an I/O error occurs

read

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

Reads a number of bytes from the underlying stream and stores them in the specified byte array at the specified offset.

Overrides:

read in class java.io.InputStream

Returns:

The actual number of bytes read, or -1 if the end of the stream is reached.

Throws:

java.io.IOException - if an I/O error occurs

read

public int read()
         throws java.io.IOException

Reads a single byte from the underlying stream.

Specified by:

read in class java.io.InputStream

Returns:

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

Throws:

java.io.IOException - if an I/O error occurs

skip

public long skip(long toSkip)
          throws java.io.IOException

Skips up to the specified number of bytes from the underlying stream.

Overrides:

skip in class java.io.InputStream

Returns:

The actual number of bytes skipped.

Throws:

java.io.IOException - if an I/O error occurs

resetStream

public void resetStream()
                 throws java.io.IOException,
                        StandardException

Resets the resettable stream.

Specified by:

resetStream in interface Resetable

Throws:

java.io.IOException

StandardException - if resetting the stream in store fails

See Also:

Resetable.resetStream()

initStream

public void initStream()
                throws StandardException

Initialize the resettable stream for use.

Specified by:

initStream in interface Resetable

Throws:

StandardException - if initializing the store in stream fails

See Also:

Resetable.initStream()

closeStream

public void closeStream()

Closes the resettable stream.

Specified by:

closeStream in interface Resetable

See Also:

Resetable.closeStream()

reposition

public void reposition(long requestedPos)
                throws java.io.IOException,
                       StandardException

Repositions the underlying store stream to the requested position.

Repositioning is required because there can be several uses of the store stream, which changes the position of it. If a class is dependent on the underlying stream not changing its position, it must call reposition with the position it expects before using the stream again.

If the repositioning fails because the stream is exhausted, most likely because of an invalid position specified by the user, the stream is reset to position zero and the EOFException is rethrown.

Specified by:

reposition in interface PositionedStream

Parameters:

requestedPos - requested byte position, first position is 0

Throws:

java.io.EOFException - if the stream is exhausted before the requested position is reached

java.io.IOException - if reading from the store stream fails

StandardException - if resetting the store in stream fails, or some other exception happens in store

See Also:

getPosition()

getPosition

public long getPosition()

Returns the current position of the underlying store stream.

Specified by:

getPosition in interface PositionedStream

Returns:

Current byte position of the store stream.

asInputStream

public java.io.InputStream asInputStream()

Description copied from interface: PositionedStream

Returns a reference to self as an InputStream.

This method is not allowed to return null.

Specified by:

asInputStream in interface PositionedStream

Returns:

An InputStream reference to self.