de.sciss.net
Class OSCTransmitter

java.lang.Object
  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()