org.apache.axiom.util.blob

Class OverflowBlob

java.lang.Object

org.apache.axiom.util.blob.OverflowBlob

All Implemented Interfaces:

Blob, WritableBlob

public class OverflowBlob
extends java.lang.Object
implements WritableBlob

Blob implementation that stores data in a temporary file if the size exceeds a configurable threshold. The data is first stored into a fixed size buffer. Once this buffer overflows, it is transferred to a temporary file. The buffer is divided into a given number of fixed size chunks that are allocated on demand. Since a temporary file may be created it is mandatory to call release() to discard the blob.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
(package private) class	OverflowBlob.InputStreamImpl
(package private) class	OverflowBlob.OutputStreamImpl

Field Summary

Fields

Modifier and Type	Field and Description
(package private) int	chunkIndex Index of the chunk the next byte will be written to.
(package private) int	chunkOffset Offset into the chunk where the next byte will be written.
(package private) byte[][]	chunks Array of byte[] representing the chunks of the buffer.
(package private) int	chunkSize Size of the chunks that will be allocated in the buffer.
private static org.apache.commons.logging.Log	log
(package private) int	state The state of the blob.
(package private) static int	STATE_COMMITTED
(package private) static int	STATE_NEW
(package private) static int	STATE_UNCOMMITTED
(package private) java.io.File	temporaryFile The handle of the temporary file.
(package private) java.lang.String	tempPrefix The prefix to be used in generating the name of the temporary file.
(package private) java.lang.String	tempSuffix The suffix to be used in generating the name of the temporary file.

Constructor Summary

Constructors

Constructor and Description
OverflowBlob(int numberOfChunks, int chunkSize, java.lang.String tempPrefix, java.lang.String tempSuffix)

Method Summary

Modifier and Type	Method and Description
protected void	finalize()
(package private) byte[]	getCurrentChunk() Get the current chunk to write to, allocating it if necessary.
java.io.InputStream	getInputStream() Get an input stream to read the data in the blob.
long	getLength() Get the length of the data in the blob, i.e.
BlobOutputStream	getOutputStream() Create an output stream to write data to the blob.
boolean	isSupportingReadUncommitted() Determine whether the blob supports reading in state NEW or UNCOMMITTED.
long	readFrom(java.io.InputStream in, long length) Read data from the given input stream and write it to the blob.
long	readFrom(java.io.InputStream in, long length, boolean commit) Read data from the given input stream and write it to the blob.
void	release() Release all resources held by this blob.
(package private) java.io.FileOutputStream	switchToTempFile() Create a temporary file and write the existing in memory data to it.
void	writeTo(java.io.OutputStream out) Write the data to a given output stream.

Methods inherited from class java.lang.Object

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

Field Detail

log

private static final org.apache.commons.logging.Log log

STATE_NEW

static final int STATE_NEW

See Also:

Constant Field Values

STATE_UNCOMMITTED

static final int STATE_UNCOMMITTED

See Also:

Constant Field Values

STATE_COMMITTED

static final int STATE_COMMITTED

See Also:

Constant Field Values

chunkSize

final int chunkSize

Size of the chunks that will be allocated in the buffer.

tempPrefix

final java.lang.String tempPrefix

The prefix to be used in generating the name of the temporary file.

tempSuffix

final java.lang.String tempSuffix

The suffix to be used in generating the name of the temporary file.

chunks

byte[][] chunks

Array of byte[] representing the chunks of the buffer. A chunk is only allocated when the first byte is written to it. This attribute is set to null when the buffer overflows and is written out to a temporary file.

chunkIndex

int chunkIndex

Index of the chunk the next byte will be written to.

chunkOffset

int chunkOffset

Offset into the chunk where the next byte will be written.

temporaryFile

java.io.File temporaryFile

The handle of the temporary file. This is only set when the memory buffer overflows and is written out to a temporary file.

state

int state

The state of the blob.

Constructor Detail

OverflowBlob

public OverflowBlob(int numberOfChunks,
                    int chunkSize,
                    java.lang.String tempPrefix,
                    java.lang.String tempSuffix)

Method Detail

isSupportingReadUncommitted

public boolean isSupportingReadUncommitted()

Description copied from interface: WritableBlob

Determine whether the blob supports reading in state NEW or UNCOMMITTED. If this method returns false and the blob is in state NEW or UNCOMMITTED, any call to a method defined by the Blob superinterface will result in an IllegalStateException. If this method returns true, then any data written to the blob will be immediately available for reading. This is also true for an input stream obtained from Blob.getInputStream() before the data is written. This implies that it is possible for the input stream to first report the end of the stream and later allow reading additional data. Therefore, a pair of streams obtained from WritableBlob.getOutputStream() and Blob.getInputStream() behaves differently than a PipedOutputStream and PipedInputStream pair, because in this situation PipedInputStream would block.

Specified by:

isSupportingReadUncommitted in interface WritableBlob

Returns:

true if the blob allows reading the data in state NEW or UNCOMMITTED; false if the blob allows read operations only in state COMMITTED

getCurrentChunk

byte[] getCurrentChunk()

Get the current chunk to write to, allocating it if necessary.

Returns:

the current chunk to write to (never null)

switchToTempFile

java.io.FileOutputStream switchToTempFile()
                                   throws java.io.IOException

Create a temporary file and write the existing in memory data to it.

Returns:

an open FileOutputStream to the temporary file

Throws:

java.io.IOException

getOutputStream

public BlobOutputStream getOutputStream()

Description copied from interface: WritableBlob

Create an output stream to write data to the blob.

Precondition: The blob is in state NEW.

Postcondition: The blob is in state UNCOMMITTED.

Note that the pre- and postconditions imply that this method may be called at most once for a given blob instance.

Calls to methods of the returned output stream will modify the state of the blob according to the following rules:

• A call to OutputStream.close() will change the state to COMMITTED.
• Calls to other methods will not modify the state of the blob. They will result in an IOException if the state is COMMITTED, i.e. if the stream has already been closed.

Specified by:

getOutputStream in interface WritableBlob

Returns:

an output stream that can be used to write data to the blob

readFrom

public long readFrom(java.io.InputStream in,
                     long length,
                     boolean commit)
              throws StreamCopyException

Description copied from interface: WritableBlob

Read data from the given input stream and write it to the blob.

A call to this method has the same effect as requesting an output stream using WritableBlob.getOutputStream() and copying the data from the input stream to that output stream, but the implementation will achieve this result in a more efficient way.

Precondition: The blob is in state NEW or UNCOMMITTED.

Postcondition: The blob is in state UNCOMMITTED if commit is false. It is in state COMMITTED if commit is true.

The precondition implies that this method may be used after a call to WritableBlob.getOutputStream(). In that case it is illegal to set commit to true (because this would invalidate the state of the output stream).

The method transfers data from the input stream to the blob until one of the following conditions is met:

• The end of the input stream is reached.
• The value of the length argument is different from -1 and the number of bytes transferred is equal to length.

Specified by:

readFrom in interface WritableBlob

Parameters:

in - An input stream to read data from. This method will not close the stream.

length - the number of bytes to transfer, or -1 if the method should transfer data until the end of the input stream is reached

commit - indicates whether the blob should be in state COMMITTED after the operation

Returns:

the number of bytes transferred

Throws:

StreamCopyException

readFrom

public long readFrom(java.io.InputStream in,
                     long length)
              throws StreamCopyException

Description copied from interface: WritableBlob

Read data from the given input stream and write it to the blob.

This method is similar to WritableBlob.readFrom(InputStream, long, boolean), except that the state of the blob after the invocation (i.e. the commit argument) is determined automatically:

Precondition (state)	Postcondition (state)
NEW	COMMITTED
UNCOMMITTED	UNCOMMITTED
COMMITTED	illegal

There are thus two usage patterns for this method:

1. The method is used to fill the blob with the data from an input stream, but no other data is written to the blob.
2. The method is used in parallel with the output stream returned by WritableBlob.getOutputStream(): some data is written using the output stream and some data is written using this method (for efficiency reasons).

Specified by:

readFrom in interface WritableBlob

Parameters:

in - An input stream to read data from. This method will not close the stream.

length - the number of bytes to transfer, or -1 if the method should transfer data until the end of the input stream is reached

Returns:

the number of bytes transferred

Throws:

StreamCopyException

getInputStream

public java.io.InputStream getInputStream()
                                   throws java.io.IOException

Description copied from interface: Blob

Get an input stream to read the data in the blob.

Specified by:

getInputStream in interface Blob

Returns:

the input stream to read the data from

Throws:

java.io.IOException

writeTo

public void writeTo(java.io.OutputStream out)
             throws StreamCopyException

Description copied from interface: Blob

Write the data to a given output stream.

Specified by:

writeTo in interface Blob

Parameters:

out - The output stream to write the data to. This method will not close the stream.

Throws:

StreamCopyException - Thrown if there is an I/O when reading the data from the blob or when writing it to the stream. StreamCopyException.getOperation() can be used to determine whether the failed operation was a read or a write.

getLength

public long getLength()

Description copied from interface: Blob

Get the length of the data in the blob, i.e. the number of bytes.

Specified by:

getLength in interface Blob

Returns:

the length of the data in the blob

release

public void release()

Description copied from interface: WritableBlob

Release all resources held by this blob.

Specified by:

release in interface WritableBlob

finalize

protected void finalize()
                 throws java.lang.Throwable

Overrides:

finalize in class java.lang.Object

Throws:

java.lang.Throwable