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

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and 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 Detail

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

Copyright © The Apache Software Foundation. All Rights Reserved.