com.filenet.api.util

Class ExtendedInputStream

java.lang.Object

java.io.InputStream

com.filenet.api.util.ExtendedInputStream

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable

public abstract class ExtendedInputStream
extends java.io.InputStream

An ExtendedInputStream is an input stream that can retrieve content at arbitrary positions within the stream. The ExtendedInputStream class includes methods that can read a certain number of bytes from the stream or read an unspecified number of bytes. The stream keeps track of the last byte position that was read. You can specify a position in the input stream to get to a later or earlier position within the stream.

Although ExtendedInputStream supports all types of storage devices, the ability to efficiently seek within a content stream is limited to the capabilities of the underlying media, and might not be appropriate for some types of storage devices. For example, the FileStorageArea, CmAdvancedStorageArea file system storage device and content that has been cached in the content cache are optimized to do native re-positioning of the input stream and, therefore, can efficiently seek within a content stream.

See Also:

InlineContentRetrievalLimit property on the ContentConfiguration class

Constructor Summary

Constructors

Constructor and Description
ExtendedInputStream()

Method Summary

Modifier and Type	Method and Description
abstract long	position() Returns the current position in this stream.
abstract void	position(long newPosition) Sets this input stream's position.
int	read() The standard java.io.InputStream.read() method.
int	read(byte[] buffer) The standard java.io.InputStream.read(byte[] b) method.
int	readAt(long position, byte[] b, int offset, int len) Sets the input stream to the specified position, then reads up to len bytes of data from the input stream into an array of bytes.
abstract long	size() Returns the total size of the underlying content.
abstract boolean	sizeSupported() Returns true if this input stream can return the total size of the underlying content.

Methods inherited from class java.io.InputStream

available, close, mark, markSupported, read, reset, skip

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ExtendedInputStream

public ExtendedInputStream()

Method Detail

position

public abstract long position()
                       throws java.io.IOException

Returns the current position in this stream. The position is a non-negative integer counting the number of bytes from the beginning of the stream to the current position

Throws:

java.io.IOException

position

public abstract void position(long newPosition)
                       throws java.io.IOException

Sets this input stream's position. The next read operation begins reading from the input stream at this position. You can set the position to a value that is greater than the current size, but doing so does not change the size of the entity. A later attempt to read bytes at such a position will immediately return an end-of-file indication. If you set the position to a value of less than zero (0), this method throws an exception.

Parameters:

newPosition - A long that specifies the offset into the stream (from the beginning of the streamed data) at which to set the position.

Throws:

java.io.IOException - If an I/O error occurs.

EngineRuntimeException - Throws EngineRuntimeException with ExceptionCode.API_EXTENDED_STREAM_INVALID_POSITION if the position specified is less than zero (0).

read

public int read()
         throws java.io.IOException

The standard java.io.InputStream.read() method. Refer to the Java Platform Standard Edition documentation for details about the use of this method.

Specified by:

read in class java.io.InputStream

Throws:

java.io.IOException

read

public int read(byte[] buffer)
         throws java.io.IOException

The standard java.io.InputStream.read(byte[] b) method. Refer to the Java Platform Standard Edition documentation for details about the use of this method.

Overrides:

read in class java.io.InputStream

Throws:

java.io.IOException

readAt

public int readAt(long position,
                  byte[] b,
                  int offset,
                  int len)
           throws java.io.IOException

Sets the input stream to the specified position, then reads up to len bytes of data from the input stream into an array of bytes. This method attempts to read as many as len bytes, but a smaller number might be read. The number of bytes read is returned as an integer.

This method blocks until input data is available, the end of the stream is detected, or an exception is thrown. This method does not close the embedded stream when the end of the file is reached.

If len is zero (0), then no bytes are read and this method returns 0; otherwise, this method attempts to read at least one byte. If no byte is available because the stream is at end of file, this method returns -1; otherwise, this method reads at least one byte and stores the value into b.

The first byte read is stored into element b[offset], the next one into b[offset+1], and so on. The number of bytes read is, at most, equal to len. Let k be the number of bytes actually read; these bytes will be stored in elements b[offset] through b[offset+k-1], leaving elements b[offset+k] through b[offset+len-1] unaffected.

In every case, elements b[0] through b[offset] and elements b[offset+len] through b[b.length-1] are unaffected.

Parameters:

position - A long that specifies the position from which to begin reading the input stream.

b - An array of bytes that is the buffer into which the data is read. When this method returns, the buffer contains the specified byte array with the values between offset and (offset+len-1) replaced by the bytes read from the current source.

offset - The byte offset in array b at which to begin writing the data read from the current input stream.

len - The maximum number of bytes to read from the current stream.

Returns:

The total number of bytes read into the buffer, or -1 if the end of the stream is reached. Returns zero (0) if len is zero.

Throws:

java.io.IOException - If an I/O error occurs.

sizeSupported

public abstract boolean sizeSupported()

Returns true if this input stream can return the total size of the underlying content.

size

public abstract long size()
                   throws java.io.IOException

Returns the total size of the underlying content. Call the sizeSupported() method before calling size() to determine whether the input stream supports returning a size.

Throws:

java.io.IOException - If an I/O error occurs.

EngineRuntimeException - Throws EngineRuntimeException with ExceptionCode.API_EXTENDED_STREAM_SIZE_UNAVAILABLE if this input stream does not support returning a size (sizeSupported returns false).