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 Summary

  Modifier and Type
  Method
  Description
  `OutputStream`
  `getOutputStream()`
  Create an output stream to write data to the blob.
  `long`
  `readFrom(InputStream in)`
  Read data from the given input stream and write it to the blob.
  `void`
  `release()`
  Release all resources held by this blob.

  ### Methods inherited from interface org.apache.axiom.blob.Blob

  `getInputStream, getSize, writeTo`

- ## 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