Interface WritableBlob
-
- All Superinterfaces:
Blob
- All Known Implementing Classes:
MemoryBlob
,OverflowBlob
public interface WritableBlob extends Blob
Deprecated.UseWritableBlob
instead.A writable blob.The behavior of the methods defined by this interface is described in terms of three 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.
isSupportingReadUncommitted()
.Blobs are not thread safe.
-
-
Method Summary
All Methods Instance Methods Abstract Methods Deprecated Methods Modifier and Type Method Description BlobOutputStream
getOutputStream()
Deprecated.Create an output stream to write data to the blob.boolean
isSupportingReadUncommitted()
Deprecated.Determine whether the blob supports reading in state NEW or UNCOMMITTED.long
readFrom(InputStream in, long length)
Deprecated.Read data from the given input stream and write it to the blob.long
readFrom(InputStream in, long length, boolean commit)
Deprecated.Read data from the given input stream and write it to the blob.void
release()
Deprecated.Release all resources held by this blob.-
Methods inherited from interface org.apache.axiom.util.blob.Blob
getInputStream, getLength, writeTo
-
-
-
-
Method Detail
-
isSupportingReadUncommitted
boolean isSupportingReadUncommitted()
Deprecated.Determine whether the blob supports reading in state NEW or UNCOMMITTED. If this method returnsfalse
and the blob is in state NEW or UNCOMMITTED, any call to a method defined by theBlob
superinterface will result in anIllegalStateException
. If this method returnstrue
, then any data written to the blob will be immediately available for reading. This is also true for an input stream obtained fromBlob.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 fromgetOutputStream()
andBlob.getInputStream()
behaves differently than aPipedOutputStream
andPipedInputStream
pair, because in this situationPipedInputStream
would block.- 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
-
getOutputStream
BlobOutputStream getOutputStream()
Deprecated.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.
- Returns:
- an output stream that can be used to write data to the blob
- Throws:
IllegalStateException
- if the blob is not in state NEW
- A call to
-
readFrom
long readFrom(InputStream in, long length, boolean commit) throws org.apache.axiom.ext.io.StreamCopyException
Deprecated.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 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
isfalse
. It is in state COMMITTED ifcommit
istrue
.The precondition implies that this method may be used after a call to
getOutputStream()
. In that case it is illegal to setcommit
totrue
(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 tolength
.
- 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 reachedcommit
- indicates whether the blob should be in state COMMITTED after the operation- Returns:
- the number of bytes transferred
- Throws:
org.apache.axiom.ext.io.StreamCopyException
IllegalStateException
- if the blob is in state COMMITTED or ifgetOutputStream()
has been called before andcommit
istrue
-
readFrom
long readFrom(InputStream in, long length) throws org.apache.axiom.ext.io.StreamCopyException
Deprecated.Read data from the given input stream and write it to the blob.This method is similar to
readFrom(InputStream, long, boolean)
, except that the state of the blob after the invocation (i.e. thecommit
argument) is determined automatically:State transitions Precondition (state) Postcondition (state) NEW COMMITTED UNCOMMITTED UNCOMMITTED COMMITTED illegal There are thus two usage patterns for this method:
- The method is used to fill the blob with the data from an input stream, but no other data is written to the blob.
- The method is used in parallel with the output stream returned by
getOutputStream()
: some data is written using the output stream and some data is written using this method (for efficiency reasons).
- 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:
org.apache.axiom.ext.io.StreamCopyException
IllegalStateException
- if the blob is in state COMMITTED
-
release
void release()
Deprecated.Release all resources held by this blob.
-
-