Package org.apache.axiom.blob

Interface WritableBlob

All Superinterfaces:
Blob
All Known Subinterfaces:
MemoryBlob, OverflowableBlob
All Known Implementing Classes:
AbstractWritableBlob
public interface WritableBlob extends Blob
A writable blob.

The behavior of the methods defined by this interface is described in terms of four logical states the blob can be in:

NEW
The blob has just been created and no data has been written to it yet.
UNCOMMITTED
Data is being written to the blob.
COMMITTED
All data has been written to the blob and the blob will no longer accept any new data.
RELEASED
The blob has been released, i.e. its data has been discarded.
Reading data from a blob in state NEW or UNCOMMITTED is not supported: methods defined by the Blob interface will throw IllegalStateException if the blob is not in state COMMITTED.

WritableBlob instances are generally not thread safe. However, for a blob in state COMMITTED, all methods defined by the Blob interface are thread safe.

  • Method Details

    • getOutputStream

      OutputStream getOutputStream() throws IOException
      Create an output stream to write data to the blob. The blob must be in state NEW when this method is called. It will be in state UNCOMMITTED after this method completes successfully. Note that this implies 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.

      The returned stream may implement ReadFromSupport, especially if the blob stores its data in memory (in which case ReadFromSupport.readFrom(InputStream, long) would read data directly into the buffers managed by the blob).

      Returns:
      an output stream that can be used to write data to the blob
      Throws:
      IllegalStateException - if the blob is not in state NEW
      IOException - if an I/O error occurred

    • readFrom

      long readFrom(InputStream in) throws org.apache.axiom.ext.io.StreamCopyException
      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 getOutputStream() and copying the data from the input stream to that output stream, but the implementation may achieve this result in a more efficient way.

      The blob must be in state NEW when this method is called. It will be in state COMMITTED after this method completes successfully.

      The method transfers data from the input stream to the blob until the end of the input stream is reached.

      Parameters:
      in - An input stream to read data from. This method will not close the stream.
      Returns:
      the number of bytes transferred
      Throws:
      org.apache.axiom.ext.io.StreamCopyException
      IllegalStateException - if the blob is not in state NEW

    • release

      void release() throws IOException
      Release all resources held by this blob. This method will put the blob into the RELEASED state and the content will no longer be accessible.
      Throws:
      IOException - if the cleanup could not be completed because an I/O error occurred