/*
* @(#)OutputConnector.java 1.7 02/08/21
*
* Copyright (c) 1996-2002 Sun Microsystems, Inc. All rights reserved.
*/
package com.sun.media;
import javax.media.Format;
import javax.media.Buffer;
/**
* OutputConnector defines the buffer movement and format typing
* interface for output connectors.
*
* @see InputConnector
* @see Module
*
*/
public interface OutputConnector extends Connector {
/**
* Connects an InputConnector to this OutputConnector.
* This method should only be called by the Manager when it
* is connecting this OutputConnector.<br>
* The protocol of the two connectors must match. <br>
* the number of buffer objects in the created connection should be at least
* the size requested by both the input and the output connector
*
* @param inputConnector input connector to connect to.
* @param useThisFormat states the format of the connection.
* If it is null the format would be negotiated.
* @return the Format of the connection.
*/
public Format connectTo(InputConnector inputConnector, Format useThisFormat);
/**
* check if a connection to the specified InputConnector would succeed.
*
* @param inputConnector input connector to check connection to.
* @param useThisFormat states the format of the connection.
* If it is null the format would be negotiated.
* @return the Format of the connection, null if the connection would fail.
*/
public Format canConnectTo(InputConnector inputConnector, Format useThisFormat);
/**
* Return the InputConnectore this OutputConnector is connected
* to. If this Connector is unconnected return null.
*
* @return the InputConnector this is connected to.
*/
public InputConnector getInputConnector();
/**
* checks if there are empty Buffer objects in the Connector's queue.
* @return true if there are empty Buffer objects in the Connector's queue.
*/
public boolean isEmptyBufferAvailable();
/**
* Get an empty buffer object.
* The exact behavior depands on the protocol:
* <ul>
* <li><b>ProtocolPush</b> - if empty buffer is not available throws RuntimeException </li>
* <li><b>ProtocolSafe</b> - if empty buffer is available read the buffer.<br>
* if empty buffer is not available perform wait() on the connection. </li>
* </ul>
*
* <i> Note that this method can be called several times before it blocks
* (depending on circular buffer size). </i>
*/
public Buffer getEmptyBuffer();
/**
* Indicates the oldest Buffer object got from this Connector (by calling the
* getEmptyBuffer method) now contains
* valid buffer object, which can be used by the downstream Module.<br>
*
* if such buffer Objects does not exists throws RuntimeException.
*
* The exact behavior depands on the protocol:
* <ul>
* <li><b>ProtocolPush</b> - if bufferValid call the connected InputConnector Module
* connectorPushed() method in the calling thread. method blocks until the downstream module
* finishes processing the buffer.</li>
* <li><b>ProtocolSafe</b> - perform notify() on the connection lock object.<br>
* </ul>
*
* <i>The bufferValid flag was removed. If the buffer Object is just returned,
* it should be marked in the Buffer itself, by specifying this is a discarded Buffer chunk. </i>
* @see javax.media.Buffer
*/
public void writeReport();
}
|