/*
* @(#)Module.java 1.11 02/08/21
*
* Copyright (c) 1996-2002 Sun Microsystems, Inc. All rights reserved.
*/
package com.sun.media;
import javax.media.*;
import javax.media.Format;
/**
* A Module is a "black box" which does a part of the overall processing. <br>
* It might have InputConnectors from which it receives data.
* It might have OutputConnectors to which it transmits data.
* its properties are exposed via Java Beans compliant accessing methods
* (setXXX()/getXXX) <br>
* <i> getLatency(.) removed since it was not used</i>
* <center><h2>data transfer protocols</center></h2>
* We define four protocols of data transfer between Modules:
* <ul>
*
* <li><b>Push - Output Data Driven</b> the upstream Module runs in its own thread. The Module loops on
* its "process" method and when it finishes one frame it calls the writeReport() method it triggers a call in the
* downstream Module to its "process" method which is executed in the current thread. When The downstream Module
* finishes, it call its downstream Module, recursively. This is the natural protocol for capture.
*
* <br>Here is a sample call graph for a push protocol (Source is pushing data to the Drain).<br>
* <pre>
* Source.process calls MediaOutputConnector.getEmptyBuffer()
* Source.process puts buffer in the empty buffer container
* Source.process calls MediaOutputConnector.writeReport(true)
* MediaOutputConnector.writeReport calls Drain.connectorPushed.
* Drain.connectorPushed calls Drain.process
* Drain.process calls MediaInputConnector.getValidBuffer
* Drain.process proccesses the Buffer
* Drain.process calls MediaInputConnector.readReport
* </pre>
*
* <li><b>Safe - Buffer Driven</b> both the downstream Module and the upstream Module run in separate threads.
* Both the Modules loops on their "process" method and a call to either readReport() in the downstream Module
* or writeReport() in the upstream Module wakes the other thread, if it is not running. When one of the threads
* is blocked, it waits until it is wakened by the other thread. This is the natural protocol for multiple threads.
* </li>
* </ul>
* @see Control
* @see Connector
* @see InputConnector
* @see OutputConnector
*/
public interface Module extends javax.media.Controls {
/**
* Return an array of strings containing this Module's
* input connectors names (both connected and unconnected).
* If this Module contains no inputs an array of length zero
* is returned.
*
* @return list of input connectors as strings.
**/
public String[] getInputConnectorNames();
/**
* Return an array of strings containing this Module's
* output connectors names (both connected and unconnected).
* If this Module contains no outputs an array of length zero
* is returned.
*
* @return list of output connectors as strings.
**/
public String[] getOutputConnectorNames();
/**
* Return the specified input connector. Connectors and their names
* are typically constructed in the Module's constructor, but their construction
* can be delayed until the Player <b>Realizing</b> state.
* Returns null if the string doesn't match any of the Module's
* InputConnectors.
*
* @param connectorName the name of the connector.
* @return InputConnector associated with this name.
**/
public InputConnector getInputConnector(String connectorName);
/**
* Return the specified output connector. Connectors and their names
* are typically constructed in the Module's constructor.
* Returns null if the String doesn't match any of the Module's
* OutputConnectors.
*
* @param connectorName the name of the connector
* @return OutputConnector associated with this name.
**/
public OutputConnector getOutputConnector(String connectorName);
/**
* Each of the inputConnectors of this Module has to be
* registered with this function.
* This method also sets the Module reference of the Connector
**/
void registerInputConnector(String name, InputConnector in);
/**
* Each of the outputConnectors of this Module has to be
* registered with this function.
* This method also sets the Module reference of the Connector
**/
void registerOutputConnector(String name, OutputConnector out);
/**
* Return the Module to its initial state. <br>
* A Module should call its Connectors reset method, and then clear its
* internal buffers typically by calling the StateTransistor's method dealloc().
**/
public void reset();
/**
* A callback function denoting data was written to one of this Module input Connectors.
* This function is needed in case of <b>Push</b> protocol
* Typical reaction of the module is to process one frame in the calling thread and return.
*
* @param inputConnector the inputConnector of the connection which have received data.
**/
public void connectorPushed(InputConnector inputConnector) ;
/**
* returns the name of this Module in the Player
*/
public String getName();
/**
* sets the name of this Module. Called by the owning Player registerModule() method
*/
public void setName(String name);
/**
* Selects a format for the Connector (the default is null).
* The <b>setFormat()</b> method is typically called by the Manager
* as part of the Connector connection method call.
* Typically the connector would delegate this call to its owning Module.
**/
public void setFormat(Connector connector,Format format);
/**
* Specify a <code>ModuleListener</code> to which this <code>Module</code>
* will send events.
*
* @param listener The listener to which the <code>Module</code> will
* post events.
*/
public void setModuleListener(ModuleListener listener);
/**
* Query to see if the module has just been interrupted.
* @return true if the module has just been interrupted.
*/
public boolean isInterrupted();
/**
* Set the JMD debugger instance for the module to use.
*/
public void setJMD(JMD jmd);
}