OSCReceiver

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

de.sciss.net
Class OSCReceiver

java.lang.Object
  de.sciss.net.OSCReceiver

All Implemented Interfaces:: OSCChannel, Runnable

public abstract class OSCReceiver
extends Object
implements OSCChannel, Runnable
extends Object
implements OSCChannel, Runnable

An OSCReceiver manages reception of incoming OSC messages. A receiver can be either revivable or non-revivable.

A non-revivable receiver is bound to one particular network channel (DatagramChannel (for UDP) or SocketChannel (for TCP)). When the channel is closed, the receiver cannot be restarted. The network channel is closed for example when a TCP server shuts down, but also when trying to connect to a TCP server that is not yet reachable.
It is therefore recommended to use revivable receivers. A revivable receiver is created through one of the newUsing constructors that takes a protocol and address argument. A revivable receiver can be restarted because it recreates the network channel if necessary.

The receiver launches a listening Thread when startListening is called.

The OSCReceiver has methods for registering and unregistering listeners that get informed about incoming messages. Filtering out specific messages must be done by the listeners.

The listening thread is stopped using stopListening method.

Note that as of v0.3, you will most likely want to use preferably one of OSCClient or OSCServer over OSCReceiver. Also note that as of v0.3, OSCReceiver is abstract, which renders direct instantiation impossible. To update old code, occurrences of new OSCReceiver() must be replaced by one of the OSCReceiver.newUsing methods! The "filter" functionality of NetUtil 0.2 is now implied by calling setTarget( SocketAddress ).

Here is an example that also demonstrates message sending using an instance of OSCTransmitter:

      OSCReceiver     rcv     = null;
      OSCTransmitter  trns;
      DatagramChannel dch     = null;

      try {
          final SocketAddress addr    = new InetSocketAddress( InetAddress.getLocalHost(), 57110 );
          final Object notify         = new Object();
          
          // note: using constructors with SelectableChannel implies the receivers and
          // transmitters cannot be revived. to create revivable channels on the same socket,
          // you must use one of the newUsing methods that take an IP address and/or port
          // number.
          dch     = DatagramChannel.open();
          dch.socket().bind( null );    // assigns an automatic local socket address
          rcv     = OSCReceiver.newUsing( dch );
          trns    = OSCTransmitter.newUsing( dch );

          rcv.addOSCListener( new OSCListener() {
              public void messageReceived( OSCMessage msg, SocketAddress sender, long time )
              {
                  if( msg.getName().equals( "status.reply" )) {
                      System.out.println( "scsynth is running. contains " +
                          msg.getArg( 1 ) + " unit generators, " +
                          msg.getArg( 2 ) + " synths, " +
                          msg.getArg( 3 ) + " groups, " +
                          msg.getArg( 4 ) + " synth defs.\n" +
                          "CPU load is " + msg.getArg( 5 ) + "% (average) / " +
                          msg.getArg( 6 ) + "% (peak)" );
                      synchronized( notify ) {
                          notify.notifyAll();
                      }
                  }
              }
          });
          rcv.startListening();
          trns.send( new OSCMessage( "/status", OSCMessage.NO_ARGS ), addr );

          synchronized( notify ) {
              notify.wait( 5000 );
          }
      }
      catch( InterruptedException e1 ) {}
      catch( IOException e2 ) {
          System.err.println( e2.getLocalizedMessage() );
      }
      finally {
          if( rcv != null ) {
              rcv.dispose();
          } else if( dch != null ) {
              try {
                  dch.close();
              }
              catch( IOException e4 ) {};
          }
      }

Note that the datagram channel needs to be bound to a valid reachable address, because stopListening will be sending a terminating message to this channel. You can bind the channel using dch.socket().bind(), as shown in the example above.

Note that someone has reported trouble with the InetAddress.getLocalHost() method on a machine that has no proper IP configuration or DNS problems. In such a case when you need to communicate only on this machine and not a network, use the loopback address "127.0.0.1" as the filtering address or bind the socket to the loop address manually before calling new OSCReceiver().

Version:: 0.37, 12-May-09
Author:: Hanns Holger Rutz
See Also:: OSCClient, OSCServer, OSCTransmitter
Synchronization:: starting and stopping and listener registration is thread safe. starting and stopping listening is thread safe but must not be carried out in the OSC receiver thread.
Todo:: an explicit disconnect method might be useful (this is implicitly done when calling dispose)

Field Summary
`protected boolean`	`allocBuf`
`protected ByteBuffer`	`byteBuf`
`protected Object`	`generalSync`
`protected boolean`	`isListening`
`protected InetSocketAddress`	`localAddress`
`protected boolean`	`revivable`
`protected SocketAddress`	`target`
`protected Thread`	`thread`
`protected Object`	`threadSync`

Fields inherited from interface de.sciss.net.OSCChannel
`DEFAULTBUFSIZE, kDumpBoth, kDumpHex, kDumpOff, kDumpText, TCP, UDP`

Constructor Summary
`protected`	`OSCReceiver(OSCPacketCodec c, String protocol, InetSocketAddress localAddress, boolean revivable)`

Method Summary
`void`	`addOSCListener(OSCListener listener)` Registers a listener that gets informed about incoming messages.
`protected void`	`checkBuffer()`
`protected abstract void`	`closeChannel()`
`abstract void`	`connect()` Establishes connection for transports requiring connectivity (e.g.
`protected static String`	`debugTimeString()`
`void`	`dispose()` Disposes the resources associated with the OSC communicator.
`void`	`dumpOSC(int mode, PrintStream stream)` Changes the way processed OSC messages are printed to the standard err console.
`protected void`	`flipDecodeDispatch(SocketAddress sender)`
`int`	`getBufferSize()` Queries the buffer size used for coding or decoding OSC messages.
`OSCPacketCodec`	`getCodec()` Queries the codec used in packet coding and decoding.
`abstract InetSocketAddress`	`getLocalAddress()` Queries the receiver's local socket address.
`protected InetSocketAddress`	`getLocalAddress(InetAddress addr, int port)`
`String`	`getProtocol()` Queries the transport protocol used by this communicator.
`abstract boolean`	`isConnected()` Queries the connection state of the receiver.
`boolean`	`isListening()` Queries whether the `OSCReceiver` is listening or not.
`static OSCReceiver`	`newUsing(DatagramChannel dch)` Creates a new instance of a non-revivable `OSCReceiver`, using default codec and UDP transport on a given channel.
`static OSCReceiver`	`newUsing(OSCPacketCodec c, DatagramChannel dch)` Creates a new instance of a non-revivable `OSCReceiver`, using a specific codec and UDP transport on a given channel.
`static OSCReceiver`	`newUsing(OSCPacketCodec c, SocketChannel sch)` Creates a new instance of a non-revivable `OSCReceiver`, using a specific codec and TCP transport on a given channel.
`static OSCReceiver`	`newUsing(OSCPacketCodec c, String protocol)` Creates a new instance of a revivable `OSCReceiver`, using a specific codec and transport protocol.
`static OSCReceiver`	`newUsing(OSCPacketCodec c, String protocol, InetSocketAddress localAddress)` Creates a new instance of a revivable `OSCReceiver`, using a specific codec and transport protocol and local socket address.
`static OSCReceiver`	`newUsing(OSCPacketCodec c, String protocol, int port)` Creates a new instance of a revivable `OSCReceiver`, using a specific codec and transport protocol and port.
`static OSCReceiver`	`newUsing(OSCPacketCodec c, String protocol, int port, boolean loopBack)` Creates a new instance of a revivable `OSCReceiver`, using a specific codec and transport protocol and port.
`static OSCReceiver`	`newUsing(SocketChannel sch)` Creates a new instance of a non-revivable `OSCReceiver`, using default codec and TCP transport on a given channel.
`static OSCReceiver`	`newUsing(String protocol)` Creates a new instance of a revivable `OSCReceiver`, using default codec and a specific transport protocol.
`static OSCReceiver`	`newUsing(String protocol, InetSocketAddress localAddress)` Creates a new instance of a revivable `OSCReceiver`, using default codec and a specific transport protocol and local socket address.
`static OSCReceiver`	`newUsing(String protocol, int port)` Creates a new instance of a revivable `OSCReceiver`, using default codec and a specific transport protocol and port.
`static OSCReceiver`	`newUsing(String protocol, int port, boolean loopBack)` Creates a new instance of a revivable `OSCReceiver`, using default codec and a specific transport protocol and port.
`void`	`removeOSCListener(OSCListener listener)` Unregisters a listener that gets informed about incoming messages
`protected abstract void`	`sendGuardSignal()`
`void`	`setBufferSize(int size)` Adjusts the buffer size for OSC messages.
`protected abstract void`	`setChannel(SelectableChannel ch)`
`void`	`setCodec(OSCPacketCodec c)` Specifies which codec is used in packet coding and decoding.
`abstract void`	`setTarget(SocketAddress target)`
`void`	`startListening()` Starts to wait for incoming messages.
`void`	`stopListening()` Stops waiting for incoming messages.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Methods inherited from interface java.lang.Runnable
`run`

Field Detail

thread

protected Thread thread

generalSync

protected final Object generalSync

threadSync

protected final Object threadSync

isListening

protected boolean isListening

byteBuf

protected ByteBuffer byteBuf

allocBuf

protected boolean allocBuf

localAddress

protected final InetSocketAddress localAddress

revivable

protected final boolean revivable

target

protected SocketAddress target

Constructor Detail

OSCReceiver

protected OSCReceiver(OSCPacketCodec c,
                      String protocol,
                      InetSocketAddress localAddress,
                      boolean revivable)

Method Detail

newUsing

public static OSCReceiver newUsing(String protocol)
                            throws IOException

Creates a new instance of a revivable OSCReceiver, using default codec and a specific transport protocol. It picks an arbitrary free port and uses the local machine's IP. To determine the resulting port, you can use getLocalAddress afterwards.