org.dvb.media
Interface MasterSlaveSyncLinkageControl

All Superinterfaces:
javax.media.Control

public interface MasterSlaveSyncLinkageControl
extends javax.media.Control

MasterSlaveSyncLinkageControl handles Player-based Master/Slave relationship for synchronization of JMF Players. A JMF Player that provides master clock for synchronization is a master Player. MasterSlaveSyncLinkageControl allows a JMF Player from which this Control is obtained to be a master Player. At the time MasterSlaveSyncLinkageControl object is obtained from a Controller object of a JMF Player, the Player is a potential master Player. When a Controller object of a slave Player is added this control by addSlave() method, actual synchronization relationship is established. If synchronization between the Players is successfully established, a JMF Player to which MasterSlaveSyncLinkageControl object belongs becomes a master Player. When all the slave Players are removed from the MasterSlaveSyncLinkageControl object by removeSlave() method, a master Player is back to a potential master Player.

MasterSlaveSyncLinkageControl object monitors synchronization status between the master and slave Players. When synchronization status is changed, MasterSlaveSyncLinkageControl object notifies the situation by throwing SyncStateChangedEvent to the application. Before adding a slave Player, synchronization status is 'Unsynchronized'. At the time a slave Player is registered by addSlave() method, synchronization status is 'Synchronizing'. When synchronization is successfully established, the status is 'Synchronized'. In case that established synchronization cannot be kept within given tolerance, the status returns to 'Synchronizing' and related control objects try to re-synchronize automatically unless synchronization status is set to OUT_OF_SYNC_UNSYNCHRONIZABLE.

MasterSlaveSyncLinkageControl supports only simple Master/Slave relationship. That is, the object accepts relationship between a single master Player and slave Players. It is not allowed that a single JMF Player becomes a master Player and a slave Player at the same time. (A potential master Player can be a slave Player.) In addition, a slave Player can have only a single master Player. In case that an application tries to establish the relationship that violates these conditions, IllegalArgumentException is thrown when addSlave() is called.

Instance of MasterSlaveSyncLinkageControl can be obtained from a JMF Controller via the methods getControl(String) and getControls(). A single Controller object of a JMF Player can create at most one instance of MasterSlaveSyncLinkageControl.

Synchronization Status and Status Constants

Unsynchronized

Master/Slave relationship is not established and Players can be running freely.

Synchronizing

MASTERPLAYER_STOOPED, SLAVEPLAYER_STOPPED, OUT_OF_SYNC_MASTER_CLK, OUT_OF_SYNC_SLAVE_CLK, OUT_OF_SYNC_OTHERSs

Synchronized

IN_SYNC

Unsynchronizable

OUT_OF_SYNC_UNSYNCHRONIZABLE




Field Summary
static int IN_SYNC
          Status representing synchronized
static int MASTERPLAYER_STOPPED
          Status representing stop() method is applied to a master Player
static int OUT_OF_SYNC_MASTER_CLK
          Status representing out of sync due to unstable clock of master Player
static int OUT_OF_SYNC_OTHERS
          Status representing out of sync due to other reasons
static int OUT_OF_SYNC_SLAVE_CLK
          Status representing out of sync due to unstable clock of slave Player
static int OUT_OF_SYNC_UNSYNCHRONIZABLE
          Status representing out of sync and Unsynchronzable state
static int SLAVEPLAYER_STOPPED
          Status representing stop() method is applied to a slave Player
 
Method Summary
 void addSlave(javax.media.Controller ctrl)
          Adds a specified Player as a slave Player that synchronizes with a master Player.
 void addSlave(javax.media.Controller ctrl, javax.media.Time t)
          Adds a specified Player as a slave Player that synchronizes with a master Player.
 void addSyncStateChangedEventListener(SyncStateChangedEventListener l)
          Adds the specified SyncStateChangedEventListener to receive the events.
 javax.media.Controller[] getSlaves()
          Gets slave Players added by addSlave method.
 SyncStateChangedEventListener[] getSyncStateChangedEventListeners()
          Returns an array of all the SyncStateChangedEvent listeners registered on this control.
 int getSyncStatus(javax.media.Controller ctrl)
          Gets currrent synchronization status of s specified slave Player.
 void removeSlave(javax.media.Controller ctrl)
          Removes a specified slave Player.
 void removeSyncStateChangedEventListener(SyncStateChangedEventListener l)
          Removes a specified SyncStateChangedEventListener to receive the events.
 
Methods inherited from interface javax.media.Control
getControlComponent
 

Field Detail

IN_SYNC

static final int IN_SYNC
Status representing synchronized

See Also:
Constant Field Values

OUT_OF_SYNC_UNSYNCHRONIZABLE

static final int OUT_OF_SYNC_UNSYNCHRONIZABLE
Status representing out of sync and Unsynchronzable state

See Also:
Constant Field Values

OUT_OF_SYNC_MASTER_CLK

static final int OUT_OF_SYNC_MASTER_CLK
Status representing out of sync due to unstable clock of master Player

See Also:
Constant Field Values

OUT_OF_SYNC_SLAVE_CLK

static final int OUT_OF_SYNC_SLAVE_CLK
Status representing out of sync due to unstable clock of slave Player

See Also:
Constant Field Values

MASTERPLAYER_STOPPED

static final int MASTERPLAYER_STOPPED
Status representing stop() method is applied to a master Player

See Also:
Constant Field Values

SLAVEPLAYER_STOPPED

static final int SLAVEPLAYER_STOPPED
Status representing stop() method is applied to a slave Player

See Also:
Constant Field Values

OUT_OF_SYNC_OTHERS

static final int OUT_OF_SYNC_OTHERS
Status representing out of sync due to other reasons

See Also:
Constant Field Values
Method Detail

addSlave

void addSlave(javax.media.Controller ctrl,
              javax.media.Time t)
              throws javax.tv.service.selection.InsufficientResourcesException,
                     IncompatibleSynchronizableMediaTypeException,
                     java.lang.IllegalArgumentException
Adds a specified Player as a slave Player that synchronizes with a master Player. Offset value given as a Time object states offset of time position of the specified slave Player and the master Player. If the specified Player already establishes synchronization, this method does nothing.

Parameters:
ctrl - Controller object of a potential slave Player to synchronize with this master Player.
t - Time object to represent offset between master Player's clock and the specified Player.
Throws:
javax.tv.service.selection.InsufficientResourcesException - If the operation cannot be completed due to a lack of system resources.
IncompatibleSynchronizableMediaTypeException - If media type Player handles is incompatible to establish synchronization.
java.lang.IllegalArgumentException - If a specified Controller object already forms a master or slave Player.

addSlave

void addSlave(javax.media.Controller ctrl)
              throws javax.tv.service.selection.InsufficientResourcesException,
                     IncompatibleSynchronizableMediaTypeException,
                     java.lang.IllegalArgumentException
Adds a specified Player as a slave Player that synchronizes with a master Player. Offset value between master Player and a specified Player is implicitly given as zero in this method. If the specified Player already establishes synchronization, this method does nothing.

Parameters:
ctrl - Controller object of a potential slave Player to synchronize with this master Player.
Throws:
javax.tv.service.selection.InsufficientResourcesException - If the operation cannot be completed due to a lack of system resources.
IncompatibleSynchronizableMediaTypeException - If media type Player handles is incompatible to establish synchronization.
java.lang.IllegalArgumentException - If a specified Controller object already forms a master or slave Player.

removeSlave

void removeSlave(javax.media.Controller ctrl)
                 throws java.lang.IllegalArgumentException
Removes a specified slave Player. The specified Player turns self-running. This removal should not affect any progress of a master Player.

Parameters:
ctrl - Controller object of a potential slave Player to synchronize with this master Player.
Throws:
java.lang.IllegalArgumentException - If the specified Controller object is not registered as a slave Player.

getSlaves

javax.media.Controller[] getSlaves()
Gets slave Players added by addSlave method. Actual synchronization status of each slave Player is not considered in return value of this method.

Returns:
An array of Controller objects which are added by addSlave method.

getSyncStatus

int getSyncStatus(javax.media.Controller ctrl)
Gets currrent synchronization status of s specified slave Player.

Parameters:
ctrl - Controller objcet of a slave Player object to obtain current synchronization status.
Returns:
Synchronization status in field values.
See Also:
Fields

addSyncStateChangedEventListener

void addSyncStateChangedEventListener(SyncStateChangedEventListener l)
Adds the specified SyncStateChangedEventListener to receive the events. SyncStateChangedEvent occurs when synchronization status between the master Player and any slave Player is changed. If l is null, no exception is thrown and no action is performed.

Parameters:
l - SyncStateChangedEvent listener.

removeSyncStateChangedEventListener

void removeSyncStateChangedEventListener(SyncStateChangedEventListener l)
Removes a specified SyncStateChangedEventListener to receive the events. If l is null, no exception is thrown and no action is performed.

Parameters:
l - SyncStateChangedEvent listener.

getSyncStateChangedEventListeners

SyncStateChangedEventListener[] getSyncStateChangedEventListeners()
Returns an array of all the SyncStateChangedEvent listeners registered on this control.

Returns:
An array of registered SyncStateChangedEvent listeners.