javaFlacEncoder
Interface FLACOutputStream

All Known Implementing Classes:

FLACFileOutputStream

public interface FLACOutputStream

This interface defines a location to write the output of the FLAC encoder to. We don't want to require that the entire stream is buffered in the encoder prior to being written, as that could require significant memory and would make live handling of streams impossible. However, we can't write the stream headers completely until the entire stream is encoded(specifically because the MD5 hash which appears at the beginning of the FLAC stream, isn't known till the last audio value is given to the encoder). Therefore, the output stream would ideally be seekable, which prevents us from outputting to just a standard "OutputStream". So we can't guarantee the stream is seekable, can't write everything in order given, but can't always buffer till we have the data for the stream headers. This interface allows the implementation to determine the proper tradeoffs. Following is a description of how the FLACEncoder class will treat objects of this type

If canSeek() returns false: The file will be written as normal, but the headers will not be updated once the stream is closed. This means the FLAC file will not contain a count of the total number of samples, nor the MD5 hash of the original input(used for verifying the data).
If canSeek() returns true: Data will be written as it becomes available, and the encoder will seek() to a point near the beginning of the stream to fix the stream headers once the stream is closed. However, in the case you both can't seek and musn't buffer(e.g, if the stream is being written to network immediately upon encode), the implementing code may simply choose to claim it can seek, but "ignore" any seeks, and handle the data as it wishes. The FLACEncoder never reads, so it doesn't care if it's really where it thinks it is or not.

Author:

Preston Lacey

Method Summary

boolean	canSeek() Test whether this object allows seeking.
long	getPos() Get current write position of this stream.
long	seek(long pos) Attempt to seek to the given position.
long	size() Get the number of bytes that have been written in length.
void	write(byte data) Write a single byte to the stream.
int	write(byte[] data, int offset, int count) Write the given number of bytes from a byte array.

Method Detail

seek

long seek(long pos)

Attempt to seek to the given position.

Parameters:

pos - target position.

Returns:

current position after seek.

write

int write(byte[] data,
          int offset,
          int count)
          throws java.io.IOException

Write the given number of bytes from a byte array.

Parameters:

data - array containing source bytes to write

offset - index of source array to begin reading from.

count - number of bytes to write.

Returns:

number of bytes written.

Throws:

java.io.IOException - IOException raised upon write error.

size

long size()

Get the number of bytes that have been written in length. This takes into account seeking to different portions.

Returns:

total writtne length of stream.

write

void write(byte data)
           throws java.io.IOException

Write a single byte to the stream.

Parameters:

data - byte to write.

Throws:

java.io.IOException - IOException raised upon write error.

canSeek

boolean canSeek()

Test whether this object allows seeking.

Returns:

true if seeking is allowed, false otherwise.

getPos

long getPos()

Get current write position of this stream.

Returns:

current write position.