lava.riff
Interface IRiffOutput

All Known Implementing Classes:

RiffOutputFile

public interface IRiffOutput

Riff output sink.

Details: IRiffOutput defines methods for writing BYTEs, WORDs, DWORDs, and chunks to a RIFF data file. Since this interface represents a generic byte output sink, the underlying data sink may or may not be file based. While IRiffOutput is typically used for writing static RIFF files, it can also be used to produce other data products, such as RIFF "streams" shipped over a network.

IRiffOutput implementations maintain a "write offset," or a value that indicates the position of the next element to be written. Because this value is settable, it is possible that RIFF data producers will produce RIFF data in random order. (The write offset is similar to the "file pointer" concept used in java.io.RandomAccessFile). The offset of the first byte in an IRiffOutput data source is 0.

Because IRiffOutput allows clients to write byte sequences in random order, some implementations will need to buffer their underlying data sinks if they do not support random access. IRiffOutput maintains a "commit offset," or the offset of the first byte in the sequence whose value is still mutable. In other words, all bytes written through this interface are subject to overwriting until the commit offset has advanced beyond them (through calls to flush). To facilitate efficient memory usage and reduce buffering requirements, interface users should commit data as soon and as often as possible.

Since:

1999.09.24

Version:

1999.09.24

Method Summary

void	close() Closes stream.
void	commit(long upto) Commits BYTEs.
long	getLength() Returns stream length.
long	getPosition() Returns write offset.
void	setLength(long length) Sets stream length.
void	setPosition(long newpos) Sets write offset.
void	write(byte[] src, int offset, int amount) Writes BYTEs.
void	write(int b) Writes BYTE.

Method Detail

setLength

public void setLength(long length)
               throws java.io.IOException

Sets stream length.

Details: This method sets the length of this stream to length. Declaring the stream's length in advance can help some implementations perform more efficiently and should be done whenever possible. It is illegal to call setLength with a length value that is less than the current flush pointer. If the sequence is closed before length bytes are written, the implementation may choose unpredictable values for the remaining bytes.

Parameters:

length - the new length of this stream

getLength

public long getLength()
               throws java.io.IOException

Returns stream length.

Details: This method returns the length of this stream if it is known, or -1 otherwise.

Returns:

the length

getPosition

public long getPosition()
                 throws java.io.IOException

Returns write offset.

Details: This method returns the offset of the next BYTE that will be written if a write method is called.

Returns:

the stream pointer

setPosition

public void setPosition(long newpos)
                 throws java.io.IOException

Sets write offset.

Details: This method sets the write offset, or the offset of the next BYTE to be written. If the new offset is less than the flush pointer, an error may occur.

Parameters:

newpos - the new position

write

public void write(int b)
           throws java.io.IOException

Writes BYTE.

Details: This method writes a single BYTE (b) to the output stream. Only the least significant 8 bits of b are used.

Parameters:

b - the byte

write

public void write(byte[] src,
                  int offset,
                  int amount)
           throws java.io.IOException

Writes BYTEs.

Details: This method writes a sequence of BYTEs to the output stream. The BYTEs are read from the source array (src) beginning at the given offset (offset). amount BYTEs are written. The write offset is advanced by the number of bytes written.

Parameters:

src - the sequence of bytes

offset - offset into src

amount - number of bytes to write

commit

public void commit(long upto)
            throws java.io.IOException

Commits BYTEs.

Details: This method freezes and commits the bytes written up to the given offset (upto). The values of bytes written to this point should no longer be modified. Bytes whose offsets are less than the new commit offset which were never written may be filled with zeros or unpredictable values.

It is acceptable to call commit with an upto value that is less than the current commit offset, but doing so has no effect.

Parameters:

upto - the new commit offset

close

public void close()
           throws java.io.IOException

Closes stream.

Details: This method commits all BYTEs that are currently buffered and releases resources associated with this implementation.