net.sf.fmj.media.Connector Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of fmj Show documentation
Freedom for Media in Java
There is a newer version: 1.0.2-jitsi
package net.sf.fmj.media;

import javax.media.*;

/**
 * Defines common interface to input and output Connectors. Inter Module
 * Connection is made of InputConnector and OutputConnector and is essentially a
 * cyclic queue of references to Buffer Objects.

 * The queue is constructed at the Connectors connectTo() method, so the
 * suggested size should be set before that.

 *
 * 

 * Note that these connectors are almost symetrical so they can support both
 * push and pull connection. 

 * In addition the two threads sync. mechanism is also supported by this
 * suggested API. 
 *
 *
 *
 *
 *
 * @see Module
 * @see InputConnector
 * @see OutputConnector
 * @see javax.media.Format
 *
 */
public interface Connector
{
    /**
     * constant to indicate that this connector runs on "Push" protocol. meaning
     * writing to this connector is propagated to the connected InputConnector.
     */
    public static int ProtocolPush = 0;

    /**
     * constant to indicate that this connector runs on "Safe" protocol. meaning
     * reading and writing from this connection is done using thread safe
     * monitor.
     */
    public static int ProtocolSafe = 1;

    /**
     * returns the circular buffer Object which is locked (by wait()/notify()
     * )during safe data transfer. 

     * This method should not really be part of the API, but it is put here
     * in order to remove implementation dependencies.
     */
    public Object getCircularBuffer();

    /**
     * The selected format. If setFormat() has not been called,
     * getFormat() will return null.
     *
     * @return the currently selected format.
     */
    public Format getFormat();

    /**
     * Returns the Module which registered this Connector.
     */
    public Module getModule();

    /** returns the name of this Connector in the owning Module */
    public String getName();

    /**
     * returns the data transfer protocol used by this connector. 

     * either ProtocolPush, ProtocolSafe
     */
    public int getProtocol();

    /**
     * gets the minimum number of buffer objects this Connector should
     * create.
     */
    public int getSize();

    /**
     * restores this Connector to its initial state: removes all the buffer
     * locks. this method is typically called when the owning Module is
     * requested to reset.
     */
    public void reset();

    /**
     * Sets the circular buffer object of the connection. This method is called
     * only by the OutputConnector.connectTo() method.

     * This method should not really be part of the API, but it is put here
     * in order to remove implementation dependencies.
     *
     * @param circularBuffer
     *            the circular buffer used by this Connection
     */
    public void setCircularBuffer(Object circularBuffer);

    /**
     * Selects a format for this Connector (the default is null). The
     * setFormat() method is typically called by the Manager as part of
     * the Connector connection method call. The connector should delegate this
     * call to its owning Module.
     */
    public void setFormat(Format format);

    /**
     * sets the Module which registered this Connector.
     *
     */
    public void setModule(Module module);

    /**
     * sets the name of this Connector. Called by the owning Module
     * registerConnector() method
     */
    public void setName(String name);

    /**
     * determines the data transfer protocol used by this connector.

     * Perhaps the only way to change the protocol is in the constructor ?
     * 
     *
     * @param protocol
     *            either ProtocolPush, ProtocolSafe
     */
    public void setProtocol(int protocol);

    /**
     * sets the minimum number of buffer objects this Connector should
     * create. The default value should be one buffer object.
     */
    public void setSize(int numOfBufferObjects);
}