de.sciss.jcollider
Class NodeWatcher

java.lang.Object
  extended by de.sciss.jcollider.NodeWatcher
All Implemented Interfaces:
de.sciss.app.EventManager.Processor, Constants, OSCResponderNode.Action, java.lang.Runnable

public class NodeWatcher
extends java.lang.Object
implements de.sciss.app.EventManager.Processor, OSCResponderNode.Action, Constants, java.lang.Runnable

A node status managing class which has a similar concept as SCLang's NodeWatcher class, however the implementation is different and the feature set is different.

When a notification message arrives, it is deferred to the event dispatching thread. Interested objects can register a listener to receive NodeEvents. Right before the listener's nodeAction method is called, the client side Node status is updated, i.e. the node linked to or unlinked from neighbouring nodes, the running playing flags are set etc.

Since these updates occur in the event thread, it is safe to use the Node's TreeNode interface.

Version:
0.33, 19-Mar-08
Author:
Hanns Holger Rutz
Synchronization:
all methods are thread safe unless explicitely noted ; however you should avoid to register a node at more than one active node watcher at a time

Field Summary
protected  Server server
           
 boolean VERBOSE
          Set this to true for debugging all relevant actions of the watcher, such as starting, stopping, registering nodes, and updating node status.
 
Fields inherited from interface de.sciss.jcollider.Constants
kAddAfter, kAddBefore, kAddReplace, kAddToHead, kAddToTail, kAudioRate, kControlRate, kDemandRate, kDoneFree, kDoneFreeAll, kDoneFreeAllPred, kDoneFreeAllSucc, kDoneFreeGroup, kDoneFreePausePred, kDoneFreePauseSucc, kDoneFreePred, kDoneFreePredGroup, kDoneFreePredGroupDeep, kDoneFreeSucc, kDoneFreeSuccGroup, kDoneFreeSuccGroupDeep, kDoneNothing, kDonePause, kDumpBoth, kDumpHex, kDumpOff, kDumpText, kHeaderAIFF, kHeaderIRCAM, kHeaderNeXT, kHeaderRaw, kHeaderWAVE, kSampleALaw, kSampleDouble, kSampleFloat, kSampleInt16, kSampleInt24, kSampleInt32, kSampleInt8, kSampleMuLaw, kScalarRate
 
Method Summary
 void addListener(NodeListener l)
          Registers a listener to be informed about node status changes.
 void clear()
          Removes all nodes from the list of known nodes.
 void dispose()
          Disposes any resources allocated by this representation.
 void dumpIncomingOSC(int dumpMode)
          Changes the way incoming messages are dumped to the console.
 java.util.List getAllNodes()
          Queries a list of all registered nodes.
 boolean getFireAllNodes()
          Queries the event dispatching mode.
 boolean isWatching()
          Queries the watching state
static NodeWatcher newFrom(Server s)
          Returns a NodeWatcher to monitor a given server.
 void processEvent(de.sciss.app.BasicEvent e)
          This is used to dispatch node events.
 void queryAllNodes(float timeout, java.awt.event.ActionListener doneAction)
           
 void register(Node node)
          Adds a node to the list of known nodes.
 void register(Node node, boolean assumePlaying)
           
 void removeListener(NodeListener l)
          Unregisters a listener from being informed about node status changes.
 void respond(OSCResponderNode r, de.sciss.net.OSCMessage msg, long time)
          This method is part of the implementation of the OSCResponderNode.Action interface.
 void run()
          Part of internal message queueing.
 boolean setAutoRegister()
          Queries whether automatic node registration is enabled.
 void setAutoRegister(boolean onOff)
          Decides whether unknown nodes should be automatically added to the node watcher (usefull for debugging).
 void setFireAllNodes(boolean allNodes)
          Decides whether node changes for any node or only for registered nodes are delivered to event listeners.
 void start()
          Starts the OSC responders that trace incoming node notification events.
 void stop()
          Stops the OSC responders that trace incoming node notification events.
 void unregister(Node node)
          Unregister a node, that is remove it from the list of known nodes.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

VERBOSE

public boolean VERBOSE
Set this to true for debugging all relevant actions of the watcher, such as starting, stopping, registering nodes, and updating node status.


server

protected final Server server
Method Detail

newFrom

public static NodeWatcher newFrom(Server s)
                           throws java.io.IOException
Returns a NodeWatcher to monitor a given server. Note that the client must receive notifications, which is true by default when booting a server. By default, events are only fired for registered nodes. To change this behaviour, call setFireAllNodes( true )

Parameters:
s - the server to which the nodes to be watched belong
Throws:
java.io.IOException
See Also:
Server.notify( boolean )

start

public void start()
           throws java.io.IOException
Starts the OSC responders that trace incoming node notification events.

Throws:
java.io.IOException

stop

public void stop()
          throws java.io.IOException
Stops the OSC responders that trace incoming node notification events.

Throws:
java.io.IOException

isWatching

public boolean isWatching()
Queries the watching state

Returns:
true if we are watching for node changes (i.e. after calling start), false otherwise (i.e. after creating the watcher or after calling stop).

register

public void register(Node node)
Adds a node to the list of known nodes. The node will be automatically removed, when a corresponding "/n_end" message arrives. Note that there is a little chance that "/n_go" messages are missed if you register a node after it's new-message has been sent to the server. A safe way to register nodes is to call the basic-new-commands and send the new-message after the registration. for example:
        Synth mySynth = Synth.basicNew( "mySynthDef", myServer );
        myNodeWatcher.register( mySynth );
        myServer.sendMsg( mySynth.newMsg( myTarget, myArgNames, myArgValues ));
        

Parameters:
node - the node to register
See Also:
setFireAllNodes( boolean )

register

public void register(Node node,
                     boolean assumePlaying)

unregister

public void unregister(Node node)
Unregister a node, that is remove it from the list of known nodes. Note that you usually need not call this because when a node is automatically unregistered when a "/n_end" for that node arrives.

Parameters:
node - the node to unregister

getAllNodes

public java.util.List getAllNodes()
Queries a list of all registered nodes.

Returns:
a list whose elements are of class Node. the list itself is a copy and maybe modified. It will not be affected by successive calls to register or unregister

addListener

public void addListener(NodeListener l)
Registers a listener to be informed about node status changes. Status changes occur as of nodes being created, destroyed, paused, resumed, moved, or as a result of sending a /n_query message to the server. The fireAllNodes flag determines whether all status changes are forwarded to listeners, or only those for previously registered nodes.

Parameters:
l - listener to be added
See Also:
setFireAllNodes( boolean )

removeListener

public void removeListener(NodeListener l)
Unregisters a listener from being informed about node status changes.

Parameters:
l - listener to be removed

queryAllNodes

public void queryAllNodes(float timeout,
                          java.awt.event.ActionListener doneAction)
Parameters:
timeout - maximum time to wait for node info replies
doneAction - to be executed when the tree has been queried (can be null)

clear

public void clear()
Removes all nodes from the list of known nodes.


dispose

public void dispose()
Disposes any resources allocated by this representation. This shuts down OSC communication and server event dispatching. It clear the list of registered nodes. Do not use this object any more after calling this method.


dumpIncomingOSC

public void dumpIncomingOSC(int dumpMode)
Changes the way incoming messages are dumped to the console. By default incoming messages are not dumped. The server's print stream is used to do the dumping

Parameters:
dumpMode - only kDumpNone and kDumpText are supported at the moment.
See Also:
Server.dumpOSC( int )

setFireAllNodes

public void setFireAllNodes(boolean allNodes)
Decides whether node changes for any node or only for registered nodes are delivered to event listeners.

Parameters:
allNodes - true to deliver events for all incoming node messages; false to deliver events only if the corresponding node was registered

getFireAllNodes

public boolean getFireAllNodes()
Queries the event dispatching mode. See setFireAllNodes for details

See Also:
setFireAllNodes( boolean )

setAutoRegister

public void setAutoRegister(boolean onOff)
Decides whether unknown nodes should be automatically added to the node watcher (usefull for debugging).

Parameters:
onOff - true to have nodes automatically created and registered upon incoming notification events. false to stop automatic registration.

setAutoRegister

public boolean setAutoRegister()
Queries whether automatic node registration is enabled.

See Also:
setAutoRegister( boolean )

respond

public void respond(OSCResponderNode r,
                    de.sciss.net.OSCMessage msg,
                    long time)
This method is part of the implementation of the OSCResponderNode.Action interface. Do not call this method.

Specified by:
respond in interface OSCResponderNode.Action

run

public void run()
Part of internal message queueing. Never call this method.

Specified by:
run in interface java.lang.Runnable

processEvent

public void processEvent(de.sciss.app.BasicEvent e)
This is used to dispatch node events. Do not call this method.

Specified by:
processEvent in interface de.sciss.app.EventManager.Processor