/*
 * @(#)Demultiplexer.java	1.12 02/08/21
 *
 * Copyright (c) 1996-2002 Sun Microsystems, Inc.  All rights reserved.
 */

package javax.media;

import java.io.IOException;
import javax.media.format.*;
import javax.media.protocol.ContentDescriptor;

/**
 * A <code>Demultiplexer</code> is a media processing unit that 
 * takes an interleaved media stream as input, extracts the individual tracks from the stream,
 * and outputs the resulting tracks. It has one input and multiple outputs.
 * <p>
 * A <code>Demultiplexer</code> is a <CODE>MediaHandler</CODE> and needs to
 * implement the <code>setSource</code> method. This method
 * should throw an <CODE>IncompatibleSourceException</CODE> if the
 * <code>Demultiplexer</code> cannot use the specified <code>DataSource</code>.
 * This typically happens if:
 * <ul>
 * <li>The <code>Demultiplexer</code> doesn't support the type of <CODE>DataSource</CODE> specified (push or
 * pull). <br> </li>
 * <li>The <code>Demultiplexer</code> requires a positionable <CODE>DataSource</CODE>.<br> </li>
 * <li>The <code>Demultiplexer</code>  requires a seekable,  random-access stream.
 * (For example, the QuickTime <CODE>Demultiplexer</CODE> has this requirement.)</li>
 * </ul>
 * The <code>setSource</code> method should throw an <CODE>IOException</CODE> if the specified
 * <code>DataSource</code> contains a null stream array.
 * <p>
 * Note: No data is read by the <code>setSource</code> method.
 * When trying to select a <CODE>Demultiplexer</CODE> for a particular content-type from a
 * list of <CODE>Demultiplexer</CODE> implementations obtained through the <CODE>PlugInManager</CODE>,
 * the <CODE>Processor</CODE> picks the first
 * <CODE>Demultiplexer</CODE> that doesn't for throw an
 * <CODE>IncompatibleSourceException</CODE> or an
 * <CODE>IOException</CODE> when <CODE>setSource</CODE> is called. 
 * If a particular <code>Demultiplexer</code> reads some
 * data from the stream and then throws an <CODE>IncompatibleSourceException</CODE>,
 * the next <CODE>Demultiplexer</CODE> in the list gets the stream in a different state.
 * @since JMF 2.0
 */
public interface Demultiplexer extends PlugIn, MediaHandler, Duration {

    /**
     * Lists the all of the input content descriptors that this <CODE>Demultiplexer</CODE> supports.
     */
    public ContentDescriptor [] getSupportedInputContentDescriptors();

    /**
     * Signals that data is going to start being read from the <CODE>Demultiplexer</CODE>. 
     * The <CODE>start</CODE> method is called before any calls are made to <code>readFrame</code>.
     *
     * @exception IOException If there is an error when trying to read from the <code>DataSource</code>.
     */
    public void start() throws IOException;

    /**
     * Signals that data is going to stop being read from the <CODE>Demultiplexer</CODE>.
     * After the <CODE>stop</CODE> method is called, <code>readFrame</code> will not be called again unless  
     * <code>start</code> is called first.
     */
    public void stop();

    /**
     *<p>
     * Retrieves the individual tracks that the media stream contains.
     * A stream can contain multiple media tracks, such as separate tracks for
     * audio, video, and midi data. The information specific to a track
     * is abstracted by an instance of a class that implements the <code>Track</code> interface.
     * The <code>Track</code> interface also provides methods for enabling or disabling
     * a track.
     * <p>
     * When <CODE>getTracks</CODE> is called, the stream header is read and
     * parsed (if there is one), the track information is retrieved,
     * the maximum frame size for each track is computed, and 
     * the play list is built (if applicable).
     * @return 
     * An array of <code>Track</code> objects. The length of the array
     * is equal to the number of tracks in the stream.
     * @exception BadHeaderException If the header information
     * is incomplete or inconsistent.
     * @exception IOException If there is an error when trying to read from the <code>DataSource</code>.
     */
    public Track[] getTracks() throws IOException, BadHeaderException;


    /**
     * Checks whether or not the stream can be repositioned
     * to the beginning.
     * @return <CODE>true</CODE> if the stream can be repositioned, <CODE>false</CODE> if it cannot.
     */
    public boolean isPositionable();
    
    /**
     * Checks whether or not the stream can be positioned at any <CODE>Time</CODE>.
     * If <CODE>isRandomAccess</CODE> returns <CODE>true</CODE>, then the stream is also positionable (<CODE>isPositionable</CODE> returns <CODE>true</CODE>).
     * However, a stream can be positionable but not random access--the <CODE>isPositionable</CODE> method might return <CODE>true</CODE> even
     * if <CODE>isRandomAccess</CODE> returns <CODE>false</CODE>.
     * @return <CODE>true</CODE> if the stream is a random access stream, <CODE>false</CODE> if it is not.
     */
    public boolean isRandomAccess();

    /**
     * Sets the stream position (media time) to the specified <CODE>Time</CODE>.
     * Returns the rounded position that was actually set.
     * Implementations should set the position to a key frame, if possible.
     * @param time The new stream position, specified as a <CODE>Time</CODE>.
     * @param round The rounding technique to be used: <CODE>RoundUp</CODE>, <CODE>RoundDown</CODE>, or <CODE>RoundNearest</CODE>.
     * @return The actual stream position that was set as a <CODE>Time</CODE> object.
     */
    Time setPosition(Time where, int rounding);

    /**
     * Gets the current media time. This is the stream position that the next <CODE>readFrame</CODE> will read.
     * @return The current position in the media stream as a <CODE>Time</CODE> object.
     */
    public Time getMediaTime();

    /**
     * Gets the duration of this media stream
     * when played at the default rate.
     * <p>
     * Note that each track can have a different duration and a
     * different start time. This method returns
     * the total duration from when the first track starts and the last track ends.
     * @return A <CODE>Time</CODE> object that represents the duration
     * or <CODE>DURATION_UNKNOWN</CODE> if the duration cannot be determined.
     *
     */
    public Time getDuration();

}