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

package javax.media;

import java.io.IOException;


/**
 * <code>DataSink</code> is the base interface for objects that
 * read media content delivered by a <code>DataSource</code>
 * and render the media to some destination.  The destination is
 * specified with a <code>MediaLocator</code>.  One example of a <CODE>DataSink</CODE> is a file 
 * writer object that stores the media in a file.
 * <p>
 * A <CODE>DataSink</CODE> is created according to the factory mechanism used to create a <CODE>Player</CODE>.
 * @see Manager#createDataSink
 * @since JMF 2.0
 */
public interface DataSink extends MediaHandler, Controls {

    /**
     * Sets the output <code>MediaLocator</code> for this <CODE>DataSink</CODE>.
     * This method should only be called once; an error is thrown if
     * the locator has already been set.
     * @param output A <code>MediaLocator</code> that describes where 
     * the output of this <CODE>DataSink</CODE> goes.
     */
    public void setOutputLocator(MediaLocator output);

    /**
     * Gets the output <code>MediaLocator</code> that describes where
     * the output of this <CODE>DataSink</CODE> goes.
     * @return The output <code>MediaLocator</code> for this 
     * <code>DataSink</code>.
     */
    public MediaLocator getOutputLocator();

    /**
     * Initiates data transfer. 
     * You must call <CODE>open</CODE> before calling the <CODE>start</CODE> method.
     *
     * @exception IOException If there are IO problems with the source
     * when <CODE>start</CODE> is called.
     */
    public void start() throws IOException;

    /**
     * Stops the data transfer.
     * If the source has not been connected and started,
     * <CODE>stop</CODE> does nothing.
     * @exception IOException If there are IO problems with the source
     * when <CODE>stop</CODE> is called.
     */
    public void stop() throws IOException;

    /**
     * Opens a connection to the destination described by
     * the output <CODE>MediaLocator</CODE>. This method 
     * establishes a channel between this <CODE>DataSink</CODE> and its destination.
     *
     * @exception IOException If there are IO problems
     * when <CODE>open</CODE> is called.
     * @exception SecurityException If there are any security
     * violations while attempting to access the destination described
     * by the output <CODE>MediaLocator</CODE>.  
     */
    public void open() throws IOException, SecurityException; 

    /**
     * Closes the connection to the destination described by the 
     * output <CODE>MediaLocator</CODE>.
     * This method frees the resources used to maintain a
     * connection to the destination.
     * If no resources are in use, <CODE>close</CODE> is ignored.
     * If <CODE>stop</CODE> hasn't already been called,
     * calling <CODE>close</CODE> stops the data transfer.
     * A <CODE>DataSink</CODE> can no longer be used once it has been closed.
     */
    public void close();

    /*
     * Question : it isn't really an error to call getContentType()
     * even if connect() has not been called.
     */

    /**
     * Gets a string that describes the content type of the media
     * that this <CODE>DataSink</CODE> is consuming.
     * @return A String that contains the name of the content-type.
     */
    public String getContentType();

    /**
     * Adds an event listener for events generated by this <CODE>DataSink</CODE>.
     * @param listener The <CODE>DataSinkListener</CODE> to add.
     */
    public void addDataSinkListener(javax.media.datasink.DataSinkListener listener);

    /**
     * Removes the specified event listener from this <CODE>DataSink</CODE>.
     * @param listener The <CODE>DataSinkListener</CODE> to remove.
     */
    public void removeDataSinkListener(javax.media.datasink.DataSinkListener listener);

}