de.sciss.net
Class OSCTransmitter

java.lang.Object
  extended by de.sciss.net.OSCTransmitter
All Implemented Interfaces:
OSCChannel

public abstract class OSCTransmitter
extends Object
implements OSCChannel

A class that sends OSC packets (messages or bundles) to a target OSC server. Each instance takes a network channel, either explictly specified by a DatagramChannel (for UDP) or SocketChannel (for TCP), or internally opened when a protocol type is specified.

Messages are send by invoking one of the send methods. For an example, please refer to the OSCReceiver document.

Note that as of v0.3, you will most likely want to use preferably one of OSCClient or OSCServer over OSCTransmitter. Also note that as of v0.3, OSCTransmitter is abstract, which renders direct instantiation impossible. To update old code, occurences of new OSCTransmitter() must be replaced by one of the OSCTransmitter.newUsing methods!

Version:
0.33, 05-Mar-09
Author:
Hanns Holger Rutz
See Also:
OSCClient, OSCServer, OSCReceiver
Synchronization:
sending messages is thread safe
Todo:
an explicit disconnect method might be useful (this is implicitly done when calling dispose)

Field Summary
protected  boolean allocBuf
           
protected  ByteBuffer byteBuf
           
protected  int dumpMode
           
protected  InetSocketAddress localAddress
           
protected  PrintStream printStream
           
protected  boolean revivable
           
protected  Object sync
           
protected  SocketAddress target
           
 
Fields inherited from interface de.sciss.net.OSCChannel
DEFAULTBUFSIZE, kDumpBoth, kDumpHex, kDumpOff, kDumpText, TCP, UDP
 
Constructor Summary
protected OSCTransmitter(OSCPacketCodec c, String protocol, InetSocketAddress localAddress, boolean revivable)
           
 
Method Summary
protected  void checkBuffer()
           
abstract  void connect()
          Establishes connection for transports requiring connectivity (e.g.
 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.
 int getBufferSize()
          Queries the buffer size used for coding or decoding OSC messages.
protected abstract  SelectableChannel getChannel()
           
 OSCPacketCodec getCodec()
          Queries the codec used in packet coding and decoding.
abstract  InetSocketAddress getLocalAddress()
          Queries the transmitter'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 transmitter.
static OSCTransmitter newUsing(DatagramChannel dch)
          Creates a new instance of an OSCTransmitter, using default codec and UDP transport on a given channel.
static OSCTransmitter newUsing(OSCPacketCodec c, DatagramChannel dch)
          Creates a new instance of an OSCTransmitter, using a specific codec and UDP transport on a given channel.
static OSCTransmitter newUsing(OSCPacketCodec c, SocketChannel sch)
          Creates a new instance of an OSCTransmitter, using a specific codec and TCP transport on a given channel.
static OSCTransmitter newUsing(OSCPacketCodec c, String protocol)
          Creates a new instance of an OSCTransmitter, using a specific codec and transport protocol.
static OSCTransmitter newUsing(OSCPacketCodec c, String protocol, InetSocketAddress localAddress)
          Creates a new instance of an OSCTransmitter, using a specific codec and transport protocol and local socket address.
static OSCTransmitter newUsing(OSCPacketCodec c, String protocol, int port)
          Creates a new instance of an OSCTransmitter, using a specific codec and transport protocol and port.
static OSCTransmitter newUsing(OSCPacketCodec c, String protocol, int port, boolean loopBack)
          Creates a new instance of an OSCTransmitter, using a specific codec and transport protocol and port.
static OSCTransmitter newUsing(SocketChannel sch)
          Creates a new instance of an OSCTransmitter, using default codec and TCP transport on a given channel.
static OSCTransmitter newUsing(String protocol)
          Creates a new instance of an OSCTransmitter, using default codec and a specific transport protocol.
static OSCTransmitter newUsing(String protocol, InetSocketAddress localAddress)
          Creates a new instance of an OSCTransmitter, using default codec and a specific transport protocol and local socket address.
static OSCTransmitter newUsing(String protocol, int port)
          Creates a new instance of an OSCTransmitter, using default codec and a specific transport protocol and port.
static OSCTransmitter newUsing(String protocol, int port, boolean loopBack)
          Creates a new instance of an OSCTransmitter, using default codec and a specific transport protocol and port.
 void send(OSCPacket p)
          Sends an OSC packet (bundle or message) to the default network address, using the current codec.
abstract  void send(OSCPacketCodec c, OSCPacket p)
          Sends an OSC packet (bundle or message) to the default network address, using a particular codec.
abstract  void send(OSCPacketCodec c, OSCPacket p, SocketAddress target)
          Sends an OSC packet (bundle or message) to the given network address, using a particular codec.
 void send(OSCPacket p, SocketAddress target)
          Sends an OSC packet (bundle or message) to the given network address, using the current codec.
 void setBufferSize(int size)
          Adjusts the buffer size for OSC messages.
 void setCodec(OSCPacketCodec c)
          Specifies which codec is used in packet coding and decoding.
 void setTarget(SocketAddress target)
          Specifies the transmitter's target address, that is the address of the remote side to talk to.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

sync

protected final Object sync

allocBuf

protected boolean allocBuf

byteBuf

protected ByteBuffer byteBuf

dumpMode

protected int dumpMode

printStream

protected PrintStream printStream

target

protected SocketAddress target

localAddress

protected final InetSocketAddress localAddress

revivable

protected final boolean revivable
Constructor Detail

OSCTransmitter

protected OSCTransmitter(OSCPacketCodec c,
                         String protocol,
                         InetSocketAddress localAddress,
                         boolean revivable)
Method Detail

newUsing

public static OSCTransmitter newUsing(String protocol)
                               throws IOException
Creates a new instance of an OSCTransmitter, 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.

Parameters:
protocol - the protocol to use, currently either UDP or TCP
Returns:
the newly created transmitter
Throws:
IOException - if a networking error occurs while creating the socket
IllegalArgumentException - if an illegal protocol is used
See Also:
OSCChannel.UDP, OSCChannel.TCP, getLocalAddress()

newUsing

public static OSCTransmitter newUsing(OSCPacketCodec c,
                                      String protocol)
                               throws IOException
Creates a new instance of an OSCTransmitter, using a specific codec and 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.

Parameters:
c - the codec to use
protocol - the protocol to use, currently either UDP or TCP
Returns:
the newly created transmitter
Throws:
IOException - if a networking error occurs while creating the socket
IllegalArgumentException - if an illegal protocol is used
Since:
NetUtil 0.33
See Also:
OSCChannel.UDP, OSCChannel.TCP, getLocalAddress()

newUsing

public static OSCTransmitter newUsing(String protocol,
                                      int port)
                               throws IOException
Creates a new instance of an OSCTransmitter, using default codec and a specific transport protocol and port. It uses the local machine's IP. Note that the port specifies the local socket, not the remote (or target) port. This can be set using the setTarget method!

Parameters:
protocol - the protocol to use, currently either UDP or TCP
port - the port number for the OSC socket, or 0 to use an arbitrary free port
Returns:
the newly created transmitter
Throws:
IOException - if a networking error occurs while creating the socket
IllegalArgumentException - if an illegal protocol is used

newUsing

public static OSCTransmitter newUsing(OSCPacketCodec c,
                                      String protocol,
                                      int port)
                               throws IOException
Creates a new instance of an OSCTransmitter, using a specific codec and transport protocol and port. It uses the local machine's IP. Note that the port specifies the local socket, not the remote (or target) port. This can be set using the setTarget method!

Parameters:
c - the codec to use
protocol - the protocol to use, currently either UDP or TCP
port - the port number for the OSC socket, or 0 to use an arbitrary free port
Returns:
the newly created transmitter
Throws:
IOException - if a networking error occurs while creating the socket
IllegalArgumentException - if an illegal protocol is used
Since:
NetUtil 0.33

newUsing

public static OSCTransmitter newUsing(String protocol,
                                      int port,
                                      boolean loopBack)
                               throws IOException
Creates a new instance of an OSCTransmitter, using default codec and a specific transport protocol and port. It uses the local machine's IP or the "loopback" address. Note that the port specifies the local socket, not the remote (or target) port. This can be set using the setTarget method!

Parameters:
protocol - the protocol to use, currently either UDP or TCP
port - the port number for the OSC socket, or 0 to use an arbitrary free port
loopBack - if true, the "loopback" address ("127.0.0.1") is used which limits communication to the local machine. If false, the special IP "0.0.0.0" is used which means any local host is picked
Returns:
the newly created transmitter
Throws:
IOException - if a networking error occurs while creating the socket
IllegalArgumentException - if an illegal protocol is used

newUsing

public static OSCTransmitter newUsing(OSCPacketCodec c,
                                      String protocol,
                                      int port,
                                      boolean loopBack)
                               throws IOException
Creates a new instance of an OSCTransmitter, using a specific codec and transport protocol and port. It uses the local machine's IP or the "loopback" address. Note that the port specifies the local socket, not the remote (or target) port. This can be set using the setTarget method!

Parameters:
c - the codec to use
protocol - the protocol to use, currently either UDP or TCP
port - the port number for the OSC socket, or 0 to use an arbitrary free port
loopBack - if true, the "loopback" address ("127.0.0.1") is used which limits communication to the local machine. If false, the special IP "0.0.0.0" is used which means any local host is picked
Returns:
the newly created transmitter
Throws:
IOException - if a networking error occurs while creating the socket
IllegalArgumentException - if an illegal protocol is used
Since:
NetUtil 0.33

newUsing

public static OSCTransmitter newUsing(String protocol,
                                      InetSocketAddress localAddress)
                               throws IOException
Creates a new instance of an OSCTransmitter, using default codec and a specific transport protocol and local socket address. Note that localAddress specifies the local socket, not the remote (or target) socket. This can be set using the setTarget method!

Parameters:
protocol - the protocol to use, currently either UDP or TCP
localAddress - a valid address to use for the OSC socket. If the port is 0, an arbitrary free port is picked when the transmitter is connected. (you can find out the actual port in this case by calling getLocalAddress() after the transmitter was connected).
Returns:
the newly created transmitter
Throws:
IOException - if a networking error occurs while creating the socket
IllegalArgumentException - if an illegal protocol is used

newUsing

public static OSCTransmitter newUsing(OSCPacketCodec c,
                                      String protocol,
                                      InetSocketAddress localAddress)
                               throws IOException
Creates a new instance of an OSCTransmitter, using a specific codec and transport protocol and local socket address. Note that localAddress specifies the local socket, not the remote (or target) socket. This can be set using the setTarget method!

Parameters:
c - the codec to use
protocol - the protocol to use, currently either UDP or TCP
localAddress - a valid address to use for the OSC socket. If the port is 0, an arbitrary free port is picked when the transmitter is connected. (you can find out the actual port in this case by calling getLocalAddress() after the transmitter was connected).
Returns:
the newly created transmitter
Throws:
IOException - if a networking error occurs while creating the socket
IllegalArgumentException - if an illegal protocol is used
Since:
NetUtil 0.33

newUsing

public static OSCTransmitter newUsing(DatagramChannel dch)
                               throws IOException
Creates a new instance of an OSCTransmitter, using default codec and UDP transport on a given channel. The caller should ensure that the provided channel's socket was bound to a valid address (using dch.socket().bind( SocketAddress )). Note that dch specifies the local socket, not the remote (or target) socket. This can be set using the setTarget method!

Parameters:
dch - the DatagramChannel to use as UDP socket.
Returns:
the newly created transmitter
Throws:
IOException - if a networking error occurs while configuring the socket

newUsing

public static OSCTransmitter newUsing(OSCPacketCodec c,
                                      DatagramChannel dch)
                               throws IOException
Creates a new instance of an OSCTransmitter, using a specific codec and UDP transport on a given channel. The caller should ensure that the provided channel's socket was bound to a valid address (using dch.socket().bind( SocketAddress )). Note that dch specifies the local socket, not the remote (or target) socket. This can be set using the setTarget method!

Parameters:
c - the codec to use
dch - the DatagramChannel to use as UDP socket.
Returns:
the newly created transmitter
Throws:
IOException - if a networking error occurs while configuring the socket
Since:
NetUtil 0.33

newUsing

public static OSCTransmitter newUsing(SocketChannel sch)
                               throws IOException
Creates a new instance of an OSCTransmitter, using default codec and TCP transport on a given channel. The caller should ensure that the provided channel's socket was bound to a valid address (using sch.socket().bind( SocketAddress )). Furthermore, the channel must be connected (using connect()) before being able to transmit messages. Note that sch specifies the local socket, not the remote (or target) socket. This can be set using the setTarget method!

Parameters:
sch - the SocketChannel to use as TCP socket.
Returns:
the newly created transmitter
Throws:
IOException - if a networking error occurs while configuring the socket

newUsing

public static OSCTransmitter newUsing(OSCPacketCodec c,
                                      SocketChannel sch)
                               throws IOException
Creates a new instance of an OSCTransmitter, using a specific codec and TCP transport on a given channel. The caller should ensure that the provided channel's socket was bound to a valid address (using sch.socket().bind( SocketAddress )). Furthermore, the channel must be connected (using connect()) before being able to transmit messages. Note that sch specifies the local socket, not the remote (or target) socket. This can be set using the setTarget method!

Parameters:
c - the codec to use
sch - the SocketChannel to use as TCP socket.
Returns:
the newly created transmitter
Throws:
IOException - if a networking error occurs while configuring the socket
Since:
NetUtil 0.33

getProtocol

public String getProtocol()
Description copied from interface: OSCChannel
Queries the transport protocol used by this communicator.

Specified by:
getProtocol in interface OSCChannel
Returns:
the protocol, such as UDP or TCP
See Also:
OSCChannel.UDP, OSCChannel.TCP

getLocalAddress

public abstract InetSocketAddress getLocalAddress()
                                           throws IOException
Queries the transmitter's local socket address. You can determine the host and port from the returned address by calling getHostName() (or for the IP getAddress().getHostAddress()) and getPort(). This port number may be 0 if the transmitter was called with an unspecified port and has not yet been connected. In this case, to determine the port actually used, call this method after the transmitter has been connected.

Specified by:
getLocalAddress in interface OSCChannel
Returns:
the address of the transmitter's local socket.
Throws:
IOException - if the local host could not be resolved
See Also:
InetSocketAddress.getHostName(), InetSocketAddress.getAddress(), InetSocketAddress.getPort()

setTarget

public void setTarget(SocketAddress target)
Specifies the transmitter's target address, that is the address of the remote side to talk to. You should call this method only once and you must call it before starting to send messages using the shortcut call send( OSCPacket ).

Parameters:
target - the address of the remote target socket. Usually you construct an appropriate InetSocketAddress
See Also:
InetSocketAddress

setCodec

public void setCodec(OSCPacketCodec c)
Description copied from interface: OSCChannel
Specifies which codec is used in packet coding and decoding.

Specified by:
setCodec in interface OSCChannel
Parameters:
c - the codec to use

getCodec

public OSCPacketCodec getCodec()
Description copied from interface: OSCChannel
Queries the codec used in packet coding and decoding.

Specified by:
getCodec in interface OSCChannel
Returns:
the current codec of this channel
See Also:
OSCPacketCodec.getDefaultCodec()

connect

public abstract void connect()
                      throws IOException
Establishes connection for transports requiring connectivity (e.g. TCP). For transports that do not require connectivity (e.g. UDP), this ensures the communication channel is created and bound.

When a UDP transmitter is created without an explicit DatagramChannel – say by calling OSCTransmitter.newUsing( "udp" ), you are required to call connect() so that an actual DatagramChannel is created and bound. For a UDP transmitter which was created with an explicit DatagramChannel, this method does noting, so it is always safe to call connect(). However, for TCP transmitters, this may throw an IOException if the transmitter was already connected, therefore be sure to check isConnected() before.

Throws:
IOException - if a networking error occurs. Possible reasons: - the underlying network channel had been closed by the server. - the transport is TCP and the server is not available. - the transport is TCP and an OSCReceiver sharing the same socket was stopped before (unable to revive).
See Also:
isConnected()

getLocalAddress

protected InetSocketAddress getLocalAddress(InetAddress addr,
                                            int port)
                                     throws UnknownHostException
Throws:
UnknownHostException

isConnected

public abstract boolean isConnected()
Queries the connection state of the transmitter.

Returns:
true if the transmitter is connected, false otherwise. For transports that do not use connectivity (e.g. UDP) this returns false, if the underlying DatagramChannel has not yet been created.
See Also:
connect()

send

public final void send(OSCPacket p,
                       SocketAddress target)
                throws IOException
Sends an OSC packet (bundle or message) to the given network address, using the current codec.

Parameters:
p - the packet to send
target - the target address to send the packet to
Throws:
IOException - if a write error, OSC encoding error, buffer overflow error or network error occurs

send

public abstract void send(OSCPacketCodec c,
                          OSCPacket p,
                          SocketAddress target)
                   throws IOException
Sends an OSC packet (bundle or message) to the given network address, using a particular codec.

Parameters:
c - the codec to use
p - the packet to send
target - the target address to send the packet to
Throws:
IOException - if a write error, OSC encoding error, buffer overflow error or network error occurs
Since:
NetUtil 0.33

send

public final void send(OSCPacket p)
                throws IOException
Sends an OSC packet (bundle or message) to the default network address, using the current codec. The default address is the one specified using the setTarget method. Therefore this will throw a NullPointerException if no default address was specified.

Parameters:
p - the packet to send
Throws:
IOException - if a write error, OSC encoding error, buffer overflow error or network error occurs
NullPointerException - if no default address was specified
See Also:
setTarget( SocketAddress )

send

public abstract void send(OSCPacketCodec c,
                          OSCPacket p)
                   throws IOException
Sends an OSC packet (bundle or message) to the default network address, using a particular codec. The default address is the one specified using the setTarget method. Therefore this will throw a NullPointerException if no default address was specified.

Parameters:
c - the codec to use
p - the packet to send
Throws:
IOException - if a write error, OSC encoding error, buffer overflow error or network error occurs
NullPointerException - if no default address was specified
Since:
NetUtil 0.33
See Also:
setTarget( SocketAddress )

setBufferSize

public void setBufferSize(int size)
Description copied from interface: OSCChannel
Adjusts the buffer size for OSC messages. This is the maximum size an OSC packet (bundle or message) can grow to.

Specified by:
setBufferSize in interface OSCChannel
Parameters:
size - the new size in bytes.
See Also:
OSCChannel.getBufferSize()

getBufferSize

public int getBufferSize()
Description copied from interface: OSCChannel
Queries the buffer size used for coding or decoding OSC messages. This is the maximum size an OSC packet (bundle or message) can grow to.

Specified by:
getBufferSize in interface OSCChannel
Returns:
the buffer size in bytes.
See Also:
OSCChannel.setBufferSize( int )

dumpOSC

public void dumpOSC(int mode,
                    PrintStream stream)
Description copied from interface: OSCChannel
Changes the way processed OSC messages are printed to the standard err console. By default messages are not printed.

Specified by:
dumpOSC in interface OSCChannel
Parameters:
mode - one of kDumpOff (don't dump, default), kDumpText (dump human readable string), kDumpHex (hexdump), or kDumpBoth (both text and hex)
stream - the stream to print on, or null which is shorthand for System.err
See Also:
OSCChannel.kDumpOff, OSCChannel.kDumpText, OSCChannel.kDumpHex, OSCChannel.kDumpBoth

dispose

public void dispose()
Description copied from interface: OSCChannel
Disposes the resources associated with the OSC communicator. The object should not be used any more after calling this method.

Specified by:
dispose in interface OSCChannel

checkBuffer

protected void checkBuffer()

getChannel

protected abstract SelectableChannel getChannel()