org.apache.axiom.util.blob.WritableBlob Maven / Gradle / Ivy
Show all versions of axiom-compat Show documentation
/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
package org.apache.axiom.util.blob;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import org.apache.axiom.ext.io.StreamCopyException;
/**
* 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.
*
* Whether or not reading data from the blob if is in state NEW or UNCOMMITTED depends on the
* return value of {@link #isSupportingReadUncommitted()}.
*
* Blobs are not thread safe.
*
* @deprecated Use {@link org.apache.axiom.blob.WritableBlob} instead.
*/
public interface WritableBlob extends Blob {
/**
* 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 {@link Blob} superinterface will result in an {@link 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
* {@link 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 {@link #getOutputStream()} and
* {@link Blob#getInputStream()} behaves differently than a {@link java.io.PipedOutputStream}
* and {@link java.io.PipedInputStream} pair, because in this situation
* {@link java.io.PipedInputStream} would block.
*
* @return true if the blob allows reading the data in state NEW or UNCOMMITTED;
* false if the blob allows read operations only in state COMMITTED
*/
boolean isSupportingReadUncommitted();
/**
* 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 {@link 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 {@link IOException} if the state is COMMITTED, i.e. if the stream has already been
* closed.
*
*
* @return an output stream that can be used to write data to the blob
*
* @throws IllegalStateException if the blob is not in state NEW
*/
BlobOutputStream getOutputStream();
/**
* 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
* {@link #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
* {@link #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:
*
* - 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 to length.
*
*
* @param in An input stream to read data from. This method will not
* close the stream.
* @param length the number of bytes to transfer, or -1 if the method should
* transfer data until the end of the input stream is reached
* @param commit indicates whether the blob should be in state COMMITTED after the operation
* @return the number of bytes transferred
* @throws StreamCopyException
* @throws IllegalStateException if the blob is in state COMMITTED or if
* {@link #getOutputStream()} has been called before and commit is
* true
*/
long readFrom(InputStream in, long length, boolean commit) throws StreamCopyException;
/**
* Read data from the given input stream and write it to the blob.
*
* This method is similar to {@link #readFrom(InputStream, long, boolean)}, except that the state
* of the blob after the invocation (i.e. the commit 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
* {@link #getOutputStream()}: some data is written using the output stream and some
* data is written using this method (for efficiency reasons).
*
*
* @param in An input stream to read data from. This method will not
* close the stream.
* @param length the number of bytes to transfer, or -1 if the method should
* transfer data until the end of the input stream is reached
* @return the number of bytes transferred
* @throws StreamCopyException
* @throws IllegalStateException if the blob is in state COMMITTED
*/
long readFrom(InputStream in, long length) throws StreamCopyException;
/**
* Release all resources held by this blob.
*/
void release();
}