hypermedia.net
Class UDP

java.lang.Object
  hypermedia.net.UDP

All Implemented Interfaces:

Runnable

public class UDP
extends Object
implements Runnable

Create and manage unicast, broadcast or multicast socket to send and receive datagram packets over the network.

The socket type is define at his initialyzation by the passed IP address. To reach a host (interface) within a network, you need to specified the kind of address:

• An unicast address refer to a unique host within a subnet.
• A broadcast address allow you to call every host within a subnet.
• A multicast address allows to call a specific group of hosts within the subnet. A multicast group is specified by a IP address in the range 224.0.0.0 (reserved, should not be used) to 239.255.255.255 inclusive, and by a standard UDP port number.
  notes: the complete reference of special multicast addresses should be found in the latest available version of the "Assigned Numbers RFC"

A packet sent to a unicast or broadcast address is only delivered to the host identified by that address. To the contrary, when packet is send to a multicast address, all interfaces identified by that address receive the data .

To perform actions on receive and/or timeout events, you must implement specific method(s) in your code. This method will be automatically called when the socket receive incoming data or a timeout event. By default, the "receive handler" is typically receive(byte[] data) but you can retrieve more informations about the datagram packet, see setReceiveHandler(String name) for more informations. In the same logic, the default "timeout handler" is explicitly timeout().

note: currently applets are not allowed to use multicast sockets

Version:

0.1

Author:

Cousot Stéphane - stef@ubaa.net, Douglas Edric Stanley - http://www.abstractmachine.net/

Field Summary

static int

BUFFER_SIZE The default socket buffer length in bytes.

Constructor Summary

UDP(Object owner)
Create a new datagram socket and binds it to an available port and every address on the local host machine.

UDP(Object owner, int port)
Create a new datagram socket and binds it to the specified port on the local host machine.

UDP(Object owner, int port, String ip)
Create a new datagram socket and binds it to the specified port on the specified local address or multicast group address.

Method Summary

String	address() Return the actual socket's local address, or null if the address correspond to any local address.
boolean	broadcast(boolean on) Enables or disables the ability of the current process to send broadcast messages.
void	close() Close the actuel datagram socket and all associate resources.
void	dispose() Close the socket.
int	getBuffer() Return the actual socket buffer length
int	getTimeToLive() Return the "Time to Live" value or -1 if an error occurred (or if the current socket is not a multicast socket).
boolean	isBroadcast() Returns whether the opened socket send broadcast message socket or not.
boolean	isClosed() Returns whether the current socket is closed or not.
boolean	isJoined() Returns whether the multicast socket is joined to a group address.
boolean	isListening() Returns whether the socket wait for incoming data or not.
boolean	isLoopback() Returns whether the multicast socket loopback mode is enable or not.
boolean	isMulticast() Returns whether the opened datagram socket is a multicast socket or not.
void	listen() Wait for incoming data, and call the appropriate handlers each time a message is received.
void	listen(boolean on) Start/stop waiting constantly for incoming data.
void	listen(int millis) Set the socket reception timeout and wait one time for incoming data.
void	log(boolean on) Enable or disable output process log.
void	loopback(boolean on) Enable or disable the multicast socket loopback mode.
int	port() Return the actual socket's local port, or -1 if the socket is closed.
void	run() Wait for incoming datagram packets.
boolean	send(byte[] buffer) Send data to the current socket.
boolean	send(byte[] buffer, String ip) Send data to the requested IP address, to the current socket port.
boolean	send(byte[] buffer, String ip, int port) Send data to the requested IP address and port.
boolean	send(String message) Send message to the current socket.
boolean	send(String message, String ip) Send message to the requested IP address, to the current socket port.
boolean	send(String message, String ip, int port) Send message to the requested IP address and port.
boolean	setBuffer(int size) Set the maximum size of the packet that can be sent or receive on the current socket.
void	setReceiveHandler(String name) Register the target's receive handler.
void	setTimeoutHandler(String name) Register the target's timeout handler.
boolean	setTimeToLive(int ttl) Control the life-time of a datagram in the network for multicast packets in order to indicates the scope of the multicasts (ie how far the packet will travel).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

BUFFER_SIZE

public static final int BUFFER_SIZE

The default socket buffer length in bytes.

See Also:

Constant Field Values

Constructor Detail

UDP

public UDP(Object owner)

Create a new datagram socket and binds it to an available port and every address on the local host machine.

Parameters:

owner - the target object to be call by the receive handler

UDP

public UDP(Object owner,
           int port)

Create a new datagram socket and binds it to the specified port on the local host machine.

Pass zero as port number, will let the system choose an available port.

Parameters:

owner - the target object to be call by the receive handler

port - local port to bind

UDP

public UDP(Object owner,
           int port,
           String ip)

Create a new datagram socket and binds it to the specified port on the specified local address or multicast group address.

Pass zero as port number, will let the system choose an available port. The absence of an address, explicitly null as IP address will assign the socket to the Unspecified Address (Also called anylocal or wildcard address). To set up the socket as multicast socket, pass the group address to be joined. If this address is not a valid multicast address, a broadcast socket will be created by default.

Parameters:

owner - the target object to be call by the receive handler

port - local port to bind

ip - host address or group address

Method Detail

dispose

public void dispose()

Close the socket. This method is automatically called by Processing when the PApplet shuts down.

See Also:

close()

close

public void close()

Close the actuel datagram socket and all associate resources.

isClosed

public boolean isClosed()

Returns whether the current socket is closed or not.

Returns:

boolean

port

public int port()

Return the actual socket's local port, or -1 if the socket is closed.

Returns:

int

address

public String address()

Return the actual socket's local address, or null if the address correspond to any local address.

Returns:

String

send

public boolean send(String message)

Send message to the current socket. Explicitly, send message to the multicast group/port or to itself.

Parameters:

message - the message to be send

Returns:

boolean

See Also:

send(String message, String ip), send(String message, String ip, int port)

send

public boolean send(byte[] buffer)

Send data to the current socket. Explicitly, send data to the multicast group/port or to itself.

Parameters:

buffer - data to be send

Returns:

boolean

See Also:

send(byte[] data, String ip), send(byte[] data, String ip, int port)

send

public boolean send(String message,
                    String ip)

Send message to the requested IP address, to the current socket port.

Parameters:

message - the message to be send

ip - the destination host's IP address

Returns:

boolean

See Also:

send(String message), send(String message, String ip, int port)

send

public boolean send(byte[] buffer,
                    String ip)

Send data to the requested IP address, to the current socket port.

Parameters:

buffer - data to be send

ip - the destination host's IP address

Returns:

boolean

See Also:

send(byte[] buffer), send(byte[] buffer, String ip, int port)

send

public boolean send(String message,
                    String ip,
                    int port)

Send message to the requested IP address and port.

A null IP address will assign the packet address to the local host. Use this method to send message to another application by passing null as the destination address.

Parameters:

message - the message to be send

ip - the destination host's IP address

port - the destination host's port

Returns:

boolean

See Also:

send(String message), send(String message, String ip)

send

public boolean send(byte[] buffer,
                    String ip,
                    int port)

Send data to the requested IP address and port.

A null IP address will assign the packet address to the local host. Use this method to send data to another application by passing null as the destination address.

Parameters:

buffer - data to be send

ip - the destination host's IP address

port - the destination host's port

Returns:

boolean

See Also:

send(byte[] buffer, String ip), send(byte[] buffer, String ip, int port)

setBuffer

public boolean setBuffer(int size)

Set the maximum size of the packet that can be sent or receive on the current socket. This value must be greater than 0, otherwise the buffer size is set to the his default value.

return true if the new buffer value have been correctly set, false otherwise.

note : this method has no effect if the socket is listening. To define a new buffer size, call this method before implementing a new buffer in memory. Explicitly before calling a receive methods.

Parameters:

size - the buffer size value in bytes or n<=0

Returns:

boolean

See Also:

getBuffer()

getBuffer

public int getBuffer()

Return the actual socket buffer length

Returns:

int

See Also:

setBuffer(int size)

isListening

public boolean isListening()

Returns whether the socket wait for incoming data or not.

Returns:

boolean

listen

public void listen(boolean on)

Start/stop waiting constantly for incoming data.

Parameters:

on - the required listening status.

See Also:

listen(), listen(int millis), setReceiveHandler(String name)

listen

public void listen(int millis)

Set the socket reception timeout and wait one time for incoming data. If the timeout period occured, the owner timeout() method is automatically called.

Parameters:

millis - the required timeout value in milliseconds.

See Also:

listen(), listen(boolean on)

listen

public void listen()

Wait for incoming data, and call the appropriate handlers each time a message is received. If the owner's class own the appropriate target handler, this method send it the receive message as byte[], the sender IP address and port.

This method force the current Thread to be ceased for a temporary period. If you prefer listening without blocking the current thread, use the listen(int millis) or listen(boolean on) method instead.

See Also:

listen(), listen(boolean on), setReceiveHandler(String name)

run

public void run()

Wait for incoming datagram packets. This method is called automaticlly, you do not need to call it.

Specified by:

run in interface Runnable

setReceiveHandler

public void setReceiveHandler(String name)

Register the target's receive handler.

By default, this method name is "receive" with one argument representing the received data as byte[]. For more flexibility, you can change this method with another useful method by passing his name. You could get more informations by implementing two additional arguments, a String representing the sender IP address and a int representing the sender port :

 void myCustomReceiveHandler(byte[] message, String ip, int port) {
        // do something here...
 }
 

Parameters:

name - the receive handler name

See Also:

setTimeoutHandler(String name)

setTimeoutHandler

public void setTimeoutHandler(String name)

Register the target's timeout handler. By default, this method name is "timeout" with no argument.

Parameters:

name - the timeout handler name

See Also:

setReceiveHandler(String name)

isMulticast

public boolean isMulticast()

Returns whether the opened datagram socket is a multicast socket or not.

Returns:

boolean

isJoined

public boolean isJoined()

Returns whether the multicast socket is joined to a group address.

Returns:

boolean

isBroadcast

public boolean isBroadcast()

Returns whether the opened socket send broadcast message socket or not.

Returns:

boolean

broadcast

public boolean broadcast(boolean on)

Enables or disables the ability of the current process to send broadcast messages.

Returns:

boolean

loopback

public void loopback(boolean on)

Enable or disable the multicast socket loopback mode. By default loopback is enable.
Setting loopback to false means this multicast socket does not want to receive the data that it sends to the multicast group.

Parameters:

on - local loopback of multicast datagrams

isLoopback

public boolean isLoopback()

Returns whether the multicast socket loopback mode is enable or not.

Returns:

boolean

setTimeToLive

public boolean setTimeToLive(int ttl)

Control the life-time of a datagram in the network for multicast packets in order to indicates the scope of the multicasts (ie how far the packet will travel).

The TTL value must be in range of 0 to 255 inclusive. The larger the number, the farther the multicast packets will travel (by convention):

 0      -> restricted to the same host
 1      -> restricted to the same subnet (default)
 <32 -> restricted to the same site
 <64 -> restricted to the same region
 <128        -> restricted to the same continent
 <255        -> no restriction
 

The default value is 1, meaning that the datagram will not go beyond the local subnet.

return true if no error occured.

Parameters:

ttl - the "Time to Live" value

Returns:

boolean

See Also:

getTimeToLive()

getTimeToLive

public int getTimeToLive()

Return the "Time to Live" value or -1 if an error occurred (or if the current socket is not a multicast socket).

Returns:

int

See Also:

setTimeToLive(int ttl)

log

public void log(boolean on)

Enable or disable output process log.