hu.netmind.ogg
Class LogicalOutputStream

java.lang.Object
  java.io.OutputStream
      hu.netmind.ogg.LogicalOutputStream

All Implemented Interfaces:

java.io.Closeable, java.io.Flushable

public class LogicalOutputStream
extends java.io.OutputStream

This is a logical output stream to a given Ogg stream. This stream is used for relaying data from a single codec (or source) to an Ogg stream.
To use a logical stream, construct it with an ogg output stream, then call writePacket() once to write the initial header packet to the ogg stream. According to specification this header packet should at least contain some information to identify the codec used, preferably in the first few bytes. (it may contain more information of course).
Also all other logical streams, that may be associated with the same ogg output stream must also write out their header packets before any other data packets can be written, this is handled automatically by this framework, but you should be aware, that all data packets will be queued until all logical streams had written their header packets.
The original intent of the Ogg format is to deliver so called 'packets' from the encoder to the decoder which holds logically related data. (eg. a single image, a chunk of sound, etc.) Packets written from this logical stream will arrive in the same order and size on the reader side. But also, this class may be used to write unmarked bitstream into an ogg stream. Using the write() methods arbitrary bitstream can be written into the ogg stream. Note however, that this will cause the framework to randomly make packets of the data (this is nescessary, since otherwise all data would be written to a single packet, which would probably cause the virutal machine to run out of memory). You can switch off the automatic packaging with setAutoPacketizer(false).
Note, that this class is not thread-safe, use only from one thread.

Method Summary

void	close() Close this logical stream.
void	flush() Flush the data waiting to be written.
void	flush(long position) Flush the data waiting to be written.
boolean	getAutoPacketizer()
OggOutputStream	getOggOutputStream() Get the ogg stream this logical stream should write to.
PageFactory	getPageFactory() Get the page factory of this logical stream.
boolean	isEmpty() Returns whether the internal buffer has some bytes or not.
void	setAutoPacketizer(boolean autoPacketizer) Set the autopacketizer on or off.
void	write(byte[] b) Write to the internal buffer.
void	write(byte[] b, int offset, int length) Write to the internal buffer.
void	write(int b) Write to the internal buffer.
void	writePacket(byte[] b) This method is equivalent to writePacket(b,-1).
void	writePacket(byte[] b, long position) This method causes a packet to be written to the ogg stream.
void	writePacket(Packet packet) This method causes a packet to be written to the ogg stream.

Methods inherited from class java.lang.Object

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

Method Detail

getOggOutputStream

public OggOutputStream getOggOutputStream()

Get the ogg stream this logical stream should write to.

Returns:

The ogg stream to write to.

getPageFactory

public PageFactory getPageFactory()

Get the page factory of this logical stream.

Returns:

The page factory of this logical stream.

close

public void close()
           throws java.io.IOException

Close this logical stream. This method will cause all data waiting to be written, and the logical stream to be closed. Subsequent calls to write will result in io exceptions.

Specified by:

close in interface java.io.Closeable

Overrides:

close in class java.io.OutputStream

Throws:

java.io.IOException - If the output could not be written, or already closed.

isEmpty

public boolean isEmpty()

Returns whether the internal buffer has some bytes or not.

Returns:

True, if internal buffer is empty, false otherwise.

flush

public void flush()
           throws java.io.IOException

Flush the data waiting to be written. When flush is called, and there were bytes in the internal buffer, then that data will be considered as a packet, and written to the ogg stream. Note however, if the internal buffer is empty, a 'nil' packet will be created anyway (this may have some meaning, eg. theora).

Specified by:

flush in interface java.io.Flushable

Overrides:

flush in class java.io.OutputStream

Throws:

java.io.IOException - If some errors occur during write.

flush

public void flush(long position)
           throws java.io.IOException

Flush the data waiting to be written. When flush is called, and there were bytes in the internal buffer, then that data will be considered as a packet, and written to the ogg stream. This method also accepts a parameter, that is the 'granule position' variable of the ogg header. This field may contain any information useful for decoding purposes about the position of stream (eg. number of video frames written, number of sound samples written, etc.)

Parameters:

position - The granule position after the packet generated by this call.

Throws:

java.io.IOException - If some errors occur during write.

write

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

Write to the internal buffer. This write will simply append this data to the internal buffer, and not cause any packets to be written.

Overrides:

write in class java.io.OutputStream

Parameters:

b - The byte array of data.

offset - The offset of data inside the buffer.

length - The length of available data to write.

Throws:

java.io.IOException - If some errors occur during write.

write

public void write(byte[] b)
           throws java.io.IOException

Write to the internal buffer. This write will simply append this data to the internal buffer, and not cause any packets to be written. This call is equivalent to write(b,0,b.length).

Overrides:

write in class java.io.OutputStream

Parameters:

b - The byte array of data.

Throws:

java.io.IOException - If some errors occur during write.

write

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

Write to the internal buffer. This write will simply append this data to the internal buffer, and not cause any packets to be written.

Specified by:

write in class java.io.OutputStream

Parameters:

b - The byte to write (lower byte of integer).

Throws:

java.io.IOException - If some errors occur during write.

writePacket

public void writePacket(byte[] b)
                 throws java.io.IOException

This method is equivalent to writePacket(b,-1).

Parameters:

b - The byte array of data, which is a packet (that is, a logical unit of data for the codec).

Throws:

java.io.IOException - If some errors occur during write.

writePacket

public void writePacket(byte[] b,
                        long position)
                 throws java.io.IOException

This method causes a packet to be written to the ogg stream. This call is only a wrapper for writePacket() with packet parameter.

Parameters:

b - The byte array of data, which is a packet (that is, a logical unit of data for the codec).

position - The granule position after packe.

Throws:

java.io.IOException - If some errors occur during write.

writePacket

public void writePacket(Packet packet)
                 throws java.io.IOException

This method causes a packet to be written to the ogg stream. This call is effectively equivalent to the following code:

    if ( ! isEmpty() )
       flush();
    write(b);
    flush();
 

Parameters:

packet - The packet to write.

Throws:

java.io.IOException - If some errors occur during write.

getAutoPacketizer

public boolean getAutoPacketizer()

setAutoPacketizer

public void setAutoPacketizer(boolean autoPacketizer)

Set the autopacketizer on or off. (Default is on).

Parameters:

autoPacketizer - True if bitstream written with write() should be automatically packetized, false otherwise.