de.sciss.jcollider
Class Server

java.lang.Object
  extended by de.sciss.jcollider.Server
All Implemented Interfaces:
de.sciss.app.EventManager.Processor, Constants

public class Server
extends java.lang.Object
implements Constants, de.sciss.app.EventManager.Processor

Closely following SClang's server class, this is the client side representation of a supercollider server.

As of v0.29, the server must be started explicitly by calling start() unless the server is booted. The call to start() tells the OSCClient to start listening for incoming messages. For TCP connections, this will try to connect to the server.

Version:
0.33, 25-Aug-08
Author:
Hanns Holger Rutz
Synchronization:
unless specified, all methods should be regarded thread safe
Todo:
the behaviour should be changed to the server representation automatically sending dumpOSC and notification status and initializing the tree, whenever the running status becomes true!
Warning:
don't rely on the default group's node ID. it is planned to use a client specific ID in the next version, so JCollider and SClang can peacefully coexist on the same server without killing each other's groups (which happens at the moment if you press cmd+period in sclang)

Nested Class Summary
static interface Server.CompletionAction
          This interface is used to describe an action to be executed after some process such as booting the server has completed.
static class Server.Status
          A static field only class describing the snapshot of the server status as delivered by getStatus
 
Field Summary
protected  de.sciss.jcollider.Server.BootThread bootThread
           
protected  Buffer[] bufferArray
           
protected  OSCResponderNode bufInfoResponder
           
protected  de.sciss.net.OSCClient c
           
static int DEFAULT_PORT
          We just use the same default scsynth server port (57110) here as assumed by sclang
protected  Server enc_this
           
protected static java.io.PrintStream printStream
           
protected  boolean serverBooting
           
protected  Server.Status status
           
protected  java.lang.Object syncBootThread
           
protected  int waitingBufs
           
protected  boolean waitingForBufInfo
           
 
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
 
Constructor Summary
Server(java.lang.String name)
          Creates a representation for a server which listens at the loopback address (127.0.0.1:57110).
Server(java.lang.String name, java.net.InetSocketAddress addr)
          Creates a server representation for the default client (0), using default options.
Server(java.lang.String name, java.net.InetSocketAddress addr, ServerOptions options)
          Creates a server representation for the default client (0).
Server(java.lang.String name, java.net.InetSocketAddress addr, ServerOptions options, int clientID)
          Creates a new Server representation object.
 
Method Summary
protected  void addBuf(Buffer buf)
          For internal use by Buffer objects.
 void addDoWhenBooted(Server.CompletionAction action)
          Registers an action to be executed after the boot process is complete.
 void addListener(ServerListener l)
          Registers a listener to be informed about server status changes.
 Group asTarget()
          Returns a group representation of the server, which at the moment is a synonym for getDefaultGroup.
 void boot()
          Starts booting a local server and establishes the ping-thread when done
 void boot(boolean startAliveThread)
          Starts booting a local server.
protected  void changed(int id)
           
 boolean didWeBootTheServer()
          Returns true if the server was locally booted by this client.
 void dispose()
          Disposes any resources allocated by this representation.
 void dumpIncomingOSC(int dumpMode)
          Changes the way incoming messages are dumped to the console.
 void dumpOSC()
          Sends a message to the server requesting OSC dump (text format).
 void dumpOSC(int dumpMode)
          Sends a message to the server requesting OSC dumping being turned on or off
 de.sciss.net.OSCMessage dumpOSCMsg(int dumpMode)
          Creates the OSC message which will ask the server to turn on or off OSC dumping
 void dumpOutgoingOSC(int dumpMode)
          Changes the way outgoing messages are dumped to the console.
protected  void freeBuf(int idx)
          For internal use by Buffer objects.
 java.net.InetSocketAddress getAddr()
          Returns the address which is assumed to be the one at which the server listens
protected  BlockAllocator getAudioBusAllocator()
          Automatic audio bus allocator for package internal use only.
protected  BlockAllocator getBufferAllocator()
          Automatic buffer ID allocator for package internal use only.
 int getClientID()
          Queries the client ID used for allocating node IDs.
protected  BlockAllocator getControlBusAllocator()
          Automatic control bus allocator for package internal use only.
 Group getDefaultGroup()
          Returns the "default" group of the server.
 int getDumpMode()
          Queries the current OSC dumping mode.
protected  OSCMultiResponder getMultiResponder()
           
 java.lang.String getName()
          Queries the server representation's name
 ServerOptions getOptions()
          Queries the options for booting the server.
static java.io.PrintStream getPrintStream()
          Queries the currently used print stream for outputting messages
static java.lang.String getProgram()
          Queries the application path to scsynth.
 double getSampleRate()
          Queries the server's (audio) sampling rate.
 Server.Status getStatus()
          Queries the latest reported server status.
protected static void inform(java.lang.String txt)
           
 void initTree()
          After the server has been contacted, calling this method will create the default group.
 boolean isBooting()
          Queries the booting state
 boolean isLocal()
          Returns true if the server has an address on the same machine as the client.
 boolean isNotified()
          Queries the server notification status.
 boolean isRunning()
          Queries the running state.
 int nextNodeID()
          Allocates a new free node ID for a group or synth.
 void notify(boolean notified)
          Sends a message to the server requesting to be notified about server actions such as nodes being added and deleted.
protected static void printError(java.lang.String name, java.lang.Throwable t)
           
 void printOn(java.io.PrintStream stream)
          Prints a textual representation of this object onto the given stream
 void processEvent(de.sciss.app.BasicEvent e)
          This is used to dispatch server events.
 void quit()
          Sends an asynchronous /quit to the server and cleans up the client's resources
static void quitAll()
          Synchronously quits all known servers.
 boolean quitAndWait()
          Synchronously quit the server.
 de.sciss.net.OSCMessage quitMsg()
          Constructs a quit message for the server
 void removeDoWhenBooted(Server.CompletionAction action)
          Unregisters an action from being executed after the boot process.
 void removeListener(ServerListener l)
          Unregisters a listener from being informed about server status changes.
 void sendBundle(de.sciss.net.OSCBundle bndl)
          Sends an OSC bundle for scheduling to the server
 boolean sendBundleSync(de.sciss.net.OSCBundle bndl, java.lang.String cmdName, float timeout)
          Sends a bundle and waits for a /done reply for a given command name from the server.
 de.sciss.net.OSCMessage sendBundleSync(de.sciss.net.OSCBundle bndl, java.lang.String doneCmd, java.lang.String failCmd, int[] doneArgIndices, java.lang.Object[] doneArgMatches, int[] failArgIndices, java.lang.Object[] failArgMatches, float timeout)
          Sends a bundle and waits for a corresponding reply or failure message from the server.
 de.sciss.net.OSCMessage sendBundleSync(de.sciss.net.OSCBundle bndl, java.lang.String doneCmd, java.lang.String failCmd, int argIdx, java.lang.Object argMatch, float timeout)
          Sends a bundle and waits for a corresponding reply or failure message from the server.
 void sendMsg(de.sciss.net.OSCMessage msg)
          Sends an OSC message to the server
 boolean sendMsgSync(de.sciss.net.OSCMessage msg, float timeout)
          Sends a message and waits for a corresponding /done reply from the server.
 de.sciss.net.OSCMessage sendMsgSync(de.sciss.net.OSCMessage msg, java.lang.String doneCmd, java.lang.String failCmd, int[] doneArgIndices, java.lang.Object[] doneArgMatches, int[] failArgIndices, java.lang.Object[] failArgMatches, float timeout)
          Sends a message and waits for a corresponding reply or failure message from the server.
 de.sciss.net.OSCMessage sendMsgSync(de.sciss.net.OSCMessage msg, java.lang.String doneCmd, java.lang.String failCmd, int doneArgIdx, java.lang.Object doneArgMatch, float timeout)
          Sends a message and waits for a corresponding reply or failure message from the server.
protected  void setBooting(boolean serverBooting)
           
static void setInform(boolean onOff)
          Turns on or off verbose messaging of the server representation.
static void setPrintStream(java.io.PrintStream printStream)
          Changes the stream to which messages are printed.
static void setProgram(java.lang.String program)
          Changes the path at which scsynth is supposed to located on the local harddisk.
protected  void setRunning(boolean serverRunning)
           
 void start()
           
 void startAliveThread()
          Begins to ping the server in regular intervals to detect a newly established connection, the loss of the connection and the current server status.
 void startAliveThread(float delay, float period, int deathBounces)
          Starts the ping-thread with specified initial delay and ping period.
protected  void status()
           
 void stopAliveThread()
          Stops the ping-thread.
 boolean sync(float timeout)
          Sends a /sync message to the server and waits for a corresponding /synced reply.
 boolean sync(de.sciss.net.OSCBundle bndl, float timeout)
          Attaches a /sync message to the list of messages in a bundle and sends the bundle to server, waiting for a corresponding /synced reply.
protected  void waitForBufInfo()
          For internal use by Buffer objects.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_PORT

public static final int DEFAULT_PORT
We just use the same default scsynth server port (57110) here as assumed by sclang

See Also:
Constant Field Values

serverBooting

protected volatile boolean serverBooting

bufferArray

protected Buffer[] bufferArray

bufInfoResponder

protected OSCResponderNode bufInfoResponder

waitingForBufInfo

protected boolean waitingForBufInfo

waitingBufs

protected int waitingBufs

printStream

protected static volatile java.io.PrintStream printStream

c

protected final de.sciss.net.OSCClient c

status

protected final Server.Status status

bootThread

protected de.sciss.jcollider.Server.BootThread bootThread

enc_this

protected final Server enc_this

syncBootThread

protected final java.lang.Object syncBootThread
Constructor Detail

Server

public Server(java.lang.String name,
              java.net.InetSocketAddress addr,
              ServerOptions options,
              int clientID)
       throws java.io.IOException
Creates a new Server representation object. Note that this will neither "create" a server, nor boot one, nor contact one. It simply establishes means of communication to a server at the given address. The caller is responsible for contacting the server and, before starting to create nodes and such, to initialize the default tree using initTree, and to ping the server using startAliveThread if one wishes to be informed about server boots and quits.

Parameters:
name - the name of the server. this arbitrary but must be unique since a set of created servers is internally maintained. currently no check on this uniqueness is performed. this is also the name of the OSC thread and the one shown in a server panel
addr - the address at which scsynth responds. as of this writing, the communication will use the UDP protocol
options - an instance of ServerOptions which needn't reflect the actual server settings when contacting a remote server, but which are used when booting a local server.
clientID - this is a concept taken from sclang, something about which the server knows nothing. it merely conditions the node ID allocator to occupy different value ranges for up to 31 different clients, so they won't conflict. beware, that as of this writing, there is no mechanism to coordinate the use of buffers and busses between different concurrent clients. the ID can be something between 0 (default) and NodeIDAllocator.getUserMax()
Throws:
java.io.IOException - if a networking error occurs
See Also:
startAliveThread(), boot(), initTree()

Server

public Server(java.lang.String name,
              java.net.InetSocketAddress addr,
              ServerOptions options)
       throws java.io.IOException
Creates a server representation for the default client (0).

Throws:
java.io.IOException

Server

public Server(java.lang.String name,
              java.net.InetSocketAddress addr)
       throws java.io.IOException
Creates a server representation for the default client (0), using default options.

Throws:
java.io.IOException
See Also:
ServerOptions.ServerOptions()

Server

public Server(java.lang.String name)
       throws java.io.IOException
Creates a representation for a server which listens at the loopback address (127.0.0.1:57110).

Throws:
java.io.IOException
Method Detail

getAddr

public java.net.InetSocketAddress getAddr()
Returns the address which is assumed to be the one at which the server listens

Returns:
the address (IP plus port) which was used to instantiate the server representation

getMultiResponder

protected OSCMultiResponder getMultiResponder()

start

public void start()
           throws java.io.IOException
Throws:
java.io.IOException

getName

public java.lang.String getName()
Queries the server representation's name

Returns:
the name which was used to instantiate the Server class

getOptions

public ServerOptions getOptions()
Queries the options for booting the server. The returned object is not a copy, and it's mutable, so any changes made to the returned objects will become effective when calling the boot method.

Returns:
the server options describing the options to pass to scsynth when booting it

getClientID

public int getClientID()
Queries the client ID used for allocating node IDs.

Returns:
the ID used in the Server constructor

getProgram

public static java.lang.String getProgram()
Queries the application path to scsynth.

Returns:
the pathname stored for the location of scsynth. this is the path which will be used when booting the server. the default value being the cwd will probably not work for your application, therefore it's advised to set the path using setProgram before trying to boot

setProgram

public static void setProgram(java.lang.String program)
Changes the path at which scsynth is supposed to located on the local harddisk. This is the path used to boot a local server. Note that this path is stored globally (for all server instances). For simplicity, this is a string and not a File object. To convert from a file, use File.getAbsolutePath().

Parameters:
program - full pathname to scsynth(.exe)
See Also:
File.getAbsolutePath()

setInform

public static void setInform(boolean onOff)
Turns on or off verbose messaging of the server representation. This has little effect at the moment, but when turned on, a few more messages will be printed to the console.

Parameters:
onOff - true means, be a bit more verbose

setPrintStream

public static void setPrintStream(java.io.PrintStream printStream)
Changes the stream to which messages are printed. By default, Server will print on System.err. This is a global method and affects all server instances. This method is particularly important because it's value will be read by the boot method to determine the print stream to which a locally booted server will print. Changing the stream after the server was booted, will not affect it's print out at all, so that needs to be done in advance.

Parameters:
printStream - the new print stream to use

getPrintStream

public static java.io.PrintStream getPrintStream()
Queries the currently used print stream for outputting messages

Returns:
the print stream used for message printout and for the locally booted server

isBooting

public boolean isBooting()
Queries the booting state

Returns:
true if the local server is being booted at the moment, false otherwise.
See Also:
isRunning()

setBooting

protected void setBooting(boolean serverBooting)

isRunning

public boolean isRunning()
Queries the running state. To become automatically informed about changes of this state, register a listener using the addListener method.

Returns:
true if a connection is established to a supercollider server. false if the server is not running or communication broke down. note that this value will only be valid, when the ping-thread is running, which is either started automatically when booting the server (boot) or manually by invoking startAliveThread().
See Also:
addListener( ServerListener ), boot(), startAliveThread()
Todo:
a future version may incorporate automatic service discovery.

setRunning

protected void setRunning(boolean serverRunning)

getBufferAllocator

protected BlockAllocator getBufferAllocator()
Automatic buffer ID allocator for package internal use only.


getAudioBusAllocator

protected BlockAllocator getAudioBusAllocator()
Automatic audio bus allocator for package internal use only.


getControlBusAllocator

protected BlockAllocator getControlBusAllocator()
Automatic control bus allocator for package internal use only.


getSampleRate

public double getSampleRate()
Queries the server's (audio) sampling rate. This is the nominal rate as returned by the status.reply message from the server. This is only valid when the server is running and the ping-thread was started. To be automatically informed about status changes, you can register a listener using addListener.

Returns:
the nominal (i.e. constant) sampling rate of the server
See Also:
addListener( ServerListener ), startAliveThread(), getStatus()

getStatus

public Server.Status getStatus()
Queries the latest reported server status. The returned object is a snapshot of what the server last send using a status.reply message. It's only valid when the server is running and the ping-thread is running.

Returns:
the Status with fields for number of UGens, Nodes etc.

getDumpMode

public int getDumpMode()
Queries the current OSC dumping mode. Note that the value reflects just what we know about the status. When the server is booted, a dump message is automatically send, so the reported value should be considered correct, until a different client sends a dumpOSC message or the server is terminated and restarted.

Returns:
the mode at which the server dumps OSC messages it receives. this can be either of kDumpOff, kDumpText, kDumpHex or kDumpBoth.
See Also:
Constants.kDumpText

getDefaultGroup

public Group getDefaultGroup()
Returns the "default" group of the server. This is the one used as target when no explicit target is specified for node creation, such as in new Synth( defName, argNames, argValues, null ).

Returns:
the default group. the value is only valid (i.e. representing a group that really exists), when the server representation has initialized it's node tree, which is done automatically after booting, or by calling initTree explicitly.
See Also:
initTree()
Warning:
do not rely on a particular group returned here, since it is likely that it will change in a future version

asTarget

public Group asTarget()
Returns a group representation of the server, which at the moment is a synonym for getDefaultGroup. This will change in one of the next version to return the root node (ID 0) however!!


inform

protected static void inform(java.lang.String txt)

boot

public void boot()
          throws java.io.IOException
Starts booting a local server and establishes the ping-thread when done

Throws:
java.io.IOException
Synchronization:
must be called in the event thread

boot

public void boot(boolean startAliveThread)
          throws java.io.IOException
Starts booting a local server. A local server can only be booted, when the server's address is local. Be sure to set the appropriate application path using setProgram before calling this method.

This method does nothing, when the booting process is assumed to be ongoing already, or when the server has already been successfully booted.

When booting is finished, the ping-thread is established depending on the startAliveThread flag, the node tree is initialized (initTree), and all actions registered through addDoWhenBooted are executed. Independantly, when the ping-thread receives the first reply, the running status is updated, hence informing all listeners registered using addListener.

Parameters:
startAliveThread - true to start a ping-thread once the server was booted. this is required if you wish to read the running status using isRunning() or using listeners
Throws:
java.io.IOException - if an error occurs when starting server, particularly if the path to the server application is wrong.
java.lang.IllegalStateException - if you try to boot a remote server
See Also:
setProgram( String ), isLocal(), isBooting(), isRunning(), addDoWhenBooted( Server.CompletionAction ), startAliveThread()
Synchronization:
must be called in the event thread

dumpOSC

public void dumpOSC()
             throws java.io.IOException
Sends a message to the server requesting OSC dump (text format).

Throws:
java.io.IOException - if the message failed to be sent

dumpOSC

public void dumpOSC(int dumpMode)
             throws java.io.IOException
Sends a message to the server requesting OSC dumping being turned on or off

Parameters:
dumpMode - either of kDumpOff (do not dump), kDumpText (dump text format), kDumpHex (hexadecimal printout), kDumpBoth (both text + hex)
Throws:
java.io.IOException - if the message failed to be sent
See Also:
Constants.kDumpText

dumpOSCMsg

public de.sciss.net.OSCMessage dumpOSCMsg(int dumpMode)
Creates the OSC message which will ask the server to turn on or off OSC dumping

Parameters:
dumpMode - see dumpOSC( int ) for details
See Also:
dumpOSC( int )

dumpIncomingOSC

public void dumpIncomingOSC(int dumpMode)
Changes the way incoming messages are dumped to the console. By default incoming messages are not dumped. Incoming messages are those received by the client from the server, before they get delivered to registered OSCResponderNodes.

Parameters:
dumpMode - see dumpOSC( int ) for details
See Also:
dumpOSC( int )

dumpOutgoingOSC

public void dumpOutgoingOSC(int dumpMode)
Changes the way outgoing messages are dumped to the console. By default outgoing messages are not dumped. Outgoing messages are those send via sendMsg or sendBundle.

Parameters:
dumpMode - see dumpOSC( int ) for details
See Also:
dumpOSC( int )

notify

public void notify(boolean notified)
            throws java.io.IOException
Sends a message to the server requesting to be notified about server actions such as nodes being added and deleted. This is also required to receive /tr messages from a sendTrig UGen. The status of the notification flag is saved internally, so when a local server is booted and notification was turned on, a new /notify message is sent.

By default (when creating a new instance of Server), the notification flag is true.

Parameters:
notified - true to turn notification on, false to turn it off
Throws:
java.io.IOException - if the message failed to be sent
Warning:
if you boot a local server, the flag is sent to the server. However, if you wish to contact a server manually, you will have to call this method explicitly. In a future version this behaviour will change, so the server representation automatically sends dumpOSC and notification flag as well as tree initialization, whenever the server becomes available.

isNotified

public boolean isNotified()
Queries the server notification status. By default, notification is turned on. However, the flag represents the true notification state only, when it was send to the server, which happens after a local boot but not when simply starting the ping-thread! this will change in a future version.

Returns:
true if notification is turned on.

initTree

public void initTree()
              throws java.io.IOException
After the server has been contacted, calling this method will create the default group. This is automatically called after booting, but not automatically when starting the ping-thread manually. this behaviour will change in a future version.

Throws:
java.io.IOException
Synchronization:
must be called in the event thread

addDoWhenBooted

public void addDoWhenBooted(Server.CompletionAction action)
Registers an action to be executed after the boot process is complete. Often it may be more convenient to simply add a server listener.

Parameters:
action - action to be executed, when the server running status becomes true after the boot process

removeDoWhenBooted

public void removeDoWhenBooted(Server.CompletionAction action)
Unregisters an action from being executed after the boot process. Note that the action is automatically removed after it has been executed, so you have to call this method only if you wish to cancel the action.

Parameters:
action - action to be removed

addListener

public void addListener(ServerListener l)
Registers a listener to be informed about server status changes. These changes include the server starting to run (or more precisely being successfully contact), the server being stopped (or more precisely having lost contact), and status changes, which are updated regularly when the ping-thread was started.

Parameters:
l - listener to be added

removeListener

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

Parameters:
l - listener to be removed

changed

protected void changed(int id)

isLocal

public boolean isLocal()
Returns true if the server has an address on the same machine as the client.


didWeBootTheServer

public boolean didWeBootTheServer()
Returns true if the server was locally booted by this client.

Returns:
true if we booted the server ourselves. this suggests that we are also responsible for shutting it down when quitting the client

startAliveThread

public void startAliveThread()
                      throws java.io.IOException
Begins to ping the server in regular intervals to detect a newly established connection, the loss of the connection and the current server status. By default, this thread is started after booting the local server. In other cases, for the running status to become valid and for the listeners to be informed about server starts and stops, this method needs to be called manually.

If the ping-thread is already running, this method does nothing.

Throws:
java.io.IOException - if a networking error occurs
Synchronization:
must be called in the event thread

startAliveThread

public void startAliveThread(float delay,
                             float period,
                             int deathBounces)
                      throws java.io.IOException
Starts the ping-thread with specified initial delay and ping period.

If the ping-thread is already running, this method does nothing.

Parameters:
delay - delay in seconds after which the first ping is send (defaults to 2 seconds)
period - period in seconds at which pings are send (defaults to 0.7 seconds). note that the behaviour of lost pings might change in a future version. As of now, a lost ping will result in server running status becoming false and firing a corresponding server event to registered listeners. The can be inappropriate if the listener starts to dispose internals while actually the server was just too slow and keeps playing orphaned synths.
Throws:
java.io.IOException - if a networking error occurs
Synchronization:
must be called in the event thread

stopAliveThread

public void stopAliveThread()
                     throws java.io.IOException
Stops the ping-thread. Note that the thread is a demon. Therefore it will not block quitting the java VM and will automatically terminate System.exit is called.

Throws:
java.io.IOException - if a networking error occurs
Synchronization:
must be called in the event thread

status

protected void status()
               throws java.io.IOException
Throws:
java.io.IOException

sendMsg

public void sendMsg(de.sciss.net.OSCMessage msg)
             throws java.io.IOException
Sends an OSC message to the server

Parameters:
msg - the message to send
Throws:
java.io.IOException - if sending the message fails. this can happen because of a network error, because of a malformed message or because of a buffer overflow (message exceeding 8K)

sendBundle

public void sendBundle(de.sciss.net.OSCBundle bndl)
                throws java.io.IOException
Sends an OSC bundle for scheduling to the server

Parameters:
bndl - the bundle to send
Throws:
java.io.IOException - if sending the bundle fails. this can happen because of a network error, because of a malformed bundle or its contained messages or because of a buffer overflow (bundle exceeding 8K)

sendMsgSync

public boolean sendMsgSync(de.sciss.net.OSCMessage msg,
                           float timeout)
                    throws java.io.IOException
Sends a message and waits for a corresponding /done reply from the server.

Parameters:
msg - the message to send
timeout - the maximum amount of time in seconds to wait
Returns:
true if the successfull reply was receivied within the timeout; false if no reply was received in time or a /fail message was received.
Throws:
java.io.IOException - if sending the message or receiving the reply fails

sendMsgSync

public de.sciss.net.OSCMessage sendMsgSync(de.sciss.net.OSCMessage msg,
                                           java.lang.String doneCmd,
                                           java.lang.String failCmd,
                                           int doneArgIdx,
                                           java.lang.Object doneArgMatch,
                                           float timeout)
                                    throws java.io.IOException
Sends a message and waits for a corresponding reply or failure message from the server.

Parameters:
msg - the message to send
doneCmd - the OSC command with which the server replies upon success
failCmd - the OSC command with which the server replies upon failure (can be null)
doneArgIdx - the OSC reply message argument index to match
doneArgMatch - the OSC reply message argument value to match
timeout - the maximum amount of time in seconds to wait
Returns:
the reply message or null if no reply was received in time
Throws:
java.io.IOException - if sending the message or receiving the reply fails

sendMsgSync

public de.sciss.net.OSCMessage sendMsgSync(de.sciss.net.OSCMessage msg,
                                           java.lang.String doneCmd,
                                           java.lang.String failCmd,
                                           int[] doneArgIndices,
                                           java.lang.Object[] doneArgMatches,
                                           int[] failArgIndices,
                                           java.lang.Object[] failArgMatches,
                                           float timeout)
                                    throws java.io.IOException
Sends a message and waits for a corresponding reply or failure message from the server.

Parameters:
msg - the message to send
doneCmd - the OSC command with which the server replies upon success
failCmd - the OSC command with which the server replies upon failure (can be null)
doneArgIndices - the OSC reply message argument indices to match for success
doneArgMatches - the OSC reply message argument values to match for success
failArgIndices - the OSC reply message argument indices to match for failure
failArgMatches - the OSC reply message argument values to match for failure
timeout - the maximum amount of time in seconds to wait
Returns:
the reply message or null if no reply was received in time
Throws:
java.io.IOException - if sending the message or receiving the reply fails

sendBundleSync

public boolean sendBundleSync(de.sciss.net.OSCBundle bndl,
                              java.lang.String cmdName,
                              float timeout)
                       throws java.io.IOException
Sends a bundle and waits for a /done reply for a given command name from the server.

Parameters:
bndl - the bundle to send
cmdName - to name of the message command to be replied to
timeout - the maximum amount of time in seconds to wait
Returns:
true if the successfull reply was receivied within the timeout; false if no reply was received in time or a /fail message was received.
Throws:
java.io.IOException - if sending the bundle or receiving the reply fails

sendBundleSync

public de.sciss.net.OSCMessage sendBundleSync(de.sciss.net.OSCBundle bndl,
                                              java.lang.String doneCmd,
                                              java.lang.String failCmd,
                                              int argIdx,
                                              java.lang.Object argMatch,
                                              float timeout)
                                       throws java.io.IOException
Sends a bundle and waits for a corresponding reply or failure message from the server.

Parameters:
bndl - the bundle to send
doneCmd - the OSC command with which the server replies upon success
failCmd - the OSC command with which the server replies upon failure (can be null)
argIdx - the OSC reply message argument index to match
argMatch - the OSC reply message argument value to match
timeout - the maximum amount of time in seconds to wait
Returns:
the reply message or null if no reply was received in time
Throws:
java.io.IOException - if sending the bundle or receiving the reply fails

sendBundleSync

public de.sciss.net.OSCMessage sendBundleSync(de.sciss.net.OSCBundle bndl,
                                              java.lang.String doneCmd,
                                              java.lang.String failCmd,
                                              int[] doneArgIndices,
                                              java.lang.Object[] doneArgMatches,
                                              int[] failArgIndices,
                                              java.lang.Object[] failArgMatches,
                                              float timeout)
                                       throws java.io.IOException
Sends a bundle and waits for a corresponding reply or failure message from the server.

Parameters:
bndl - the bundle to send
doneCmd - the OSC command with which the server replies upon success
failCmd - the OSC command with which the server replies upon failure (can be null)
doneArgIndices - the OSC reply message argument indices to match
doneArgMatches - the OSC reply message argument values to match
timeout - the maximum amount of time in seconds to wait
Returns:
the reply message or null if no reply was received in time
Throws:
java.io.IOException - if sending the bundle or receiving the reply fails

sync

public boolean sync(float timeout)
             throws java.io.IOException
Sends a /sync message to the server and waits for a corresponding /synced reply.

Parameters:
timeout - the maximum amount of time in seconds to wait
Returns:
true if the successfull reply was receivied within the timeout.
Throws:
java.io.IOException - if sending the message or receiving the reply fails

sync

public boolean sync(de.sciss.net.OSCBundle bndl,
                    float timeout)
             throws java.io.IOException
Attaches a /sync message to the list of messages in a bundle and sends the bundle to server, waiting for a corresponding /synced reply.

Parameters:
bndl - the bundle to send. a /sync message is appended to this bundle. bndl may be null, in this case the /sync is send alone.
timeout - the maximum amount of time in seconds to wait
Returns:
true if the successfull reply was receivied within the timeout.
Throws:
java.io.IOException - if sending the message or receiving the reply fails

nextNodeID

public int nextNodeID()
Allocates a new free node ID for a group or synth.

Returns:
the new node ID.
Todo:
should be accompanied by a nextPermanentNodeID method, should throw a RuntimeException if the allocator reaches its limit?

addBuf

protected void addBuf(Buffer buf)
For internal use by Buffer objects. Do not use yourself.


freeBuf

protected void freeBuf(int idx)
For internal use by Buffer objects. Do not use yourself.


waitForBufInfo

protected void waitForBufInfo()
                       throws java.io.IOException
For internal use by Buffer objects. Do not use yourself.

Throws:
java.io.IOException

printOn

public void printOn(java.io.PrintStream stream)
Prints a textual representation of this object onto the given stream

Parameters:
stream - the stream to print on

quit

public void quit()
          throws java.io.IOException
Sends an asynchronous /quit to the server and cleans up the client's resources

Throws:
java.io.IOException - if the message failed to be sent or if cleanup failed
Synchronization:
must be called in the event thread
Warning:
unlike in SClang, this stops the alive thread, so in case you want to recognize remote server starts, call startAliveThread afterwards.

quitMsg

public de.sciss.net.OSCMessage quitMsg()
Constructs a quit message for the server

Returns:
OSCMessage requesting the server to quit

dispose

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

Synchronization:
must be called in the event thread

quitAndWait

public boolean quitAndWait()
                    throws java.io.IOException
Synchronously quit the server. If the server is not booting and not running according to the running status, this method returns immediately. Otherwise sends a /quit message and waits for the reply. If no reply is received, and the server was locally booted, terminates the server process.

Returns:
true if the server has successfully quit
Throws:
java.io.IOException - if the message failed to be sent or if cleanup failed
Synchronization:
must be called in the event thread

quitAll

public static void quitAll()
Synchronously quits all known servers. That is all servers for which a Server representation instance has been created. Cathes all thrown exceptions.

Synchronization:
must be called in the event thread

printError

protected static void printError(java.lang.String name,
                                 java.lang.Throwable t)

processEvent

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

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