org.apache.axiom.util.blob
Class MemoryBlob

java.lang.Object
  extended by org.apache.axiom.util.blob.MemoryBlob
All Implemented Interfaces:
Blob, WritableBlob

public class MemoryBlob
extends Object
implements WritableBlob

Blob implementation that stores data in memory.


Constructor Summary
MemoryBlob()
           
 
Method Summary
 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. the number of bytes.
 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(InputStream in, long length)
          Read data from the given input stream and write it to the blob.
 long readFrom(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.
 void writeTo(OutputStream os)
          Write the data to a given output stream.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

MemoryBlob

public MemoryBlob()
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

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

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:

Specified by:
getOutputStream in interface WritableBlob
Returns:
an output stream that can be used to write data to the blob

readFrom

public long readFrom(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:

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(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)
NEWCOMMITTED
UNCOMMITTEDUNCOMMITTED
COMMITTEDillegal

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 InputStream getInputStream()
                           throws 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:
IOException

writeTo

public void writeTo(OutputStream os)
             throws StreamCopyException
Description copied from interface: Blob
Write the data to a given output stream.

Specified by:
writeTo in interface Blob
Parameters:
os - 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.

release

public void release()
Description copied from interface: WritableBlob
Release all resources held by this blob.

Specified by:
release in interface WritableBlob


Copyright © 2004-2012 The Apache Software Foundation. All Rights Reserved.