net.sf.eBus.net

Class AsyncDatagramSocket

java.lang.Object

net.sf.eBus.net.AsyncChannel

net.sf.eBus.net.AbstractAsyncDatagramSocket

net.sf.eBus.net.AsyncDatagramSocket

public final class AsyncDatagramSocket
extends AbstractAsyncDatagramSocket

AsyncDatagramSocket uses the selector thread to process a DatagramChannel. This prevents the calling thread from blocking while sending data or blocking the socket while processing input. Incoming DatagramPackets and socket closure events are sent to the registered listener via the DatagramListener interface.

eBus v. 4.5.1 introduced AsyncDatagramSocket.DatagramBuilder class which is now the preferred way to create an AsyncDatagramSocket instance. The following example shows how a datagram socket should now be created:

DatagramListener l = ...;
final DatagramBuilder builder = AsyncDatagramSocket.builder();

AsyncDatagramSocket socket = builder.inputBufferSize(512)
                                    .outputBufferSize(512)
                                    .byteOrder(ByteOrder.BIG_ENDIAN)
                                    .selector("dgramSelector")
                                    .listener(l)
                                    .build();

Author:

Charles Rapp

See Also:

DatagramListener, AsyncSocket

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	AsyncDatagramSocket.DatagramBuilder Constructs an AsyncDatagramSocket instance based on the parameters set via this builder's API.

Nested classes/interfaces inherited from class net.sf.eBus.net.AbstractAsyncDatagramSocket

AbstractAsyncDatagramSocket.AbstractDatagramBuilder

Nested classes/interfaces inherited from class net.sf.eBus.net.AsyncChannel

AsyncChannel.ChannelBuilder

Field Summary

Fields inherited from class net.sf.eBus.net.AbstractAsyncDatagramSocket

mBoundFlag, mOpenFlag, sLogger

Fields inherited from class net.sf.eBus.net.AsyncChannel

DEFAULT_BUFFER_SIZE, defaultSelector, LOCALHOST, MAX_PORT, mChannel, MIN_PORT, mInputBuffer, mInputBufferSize, mLocalAddress, mOutputBuffer, mOutputBufferSize, mRemoteAddress, mSelectorThread, sSelectors

Method Summary

Modifier and Type	Method and Description
static AsyncDatagramSocket.DatagramBuilder	builder() Returns the builder used to open new AsyncDatagramSocket instances.
void	connect(java.net.SocketAddress remoteAddr) "Connects" the datagram socket to the given remote socket address.
static AsyncDatagramSocket	create(DatagramListener listener) Deprecated. AsyncDatagramSocket.DatagramBuilder is the preferred mechanism for creating AsyncDatagramSocket instances. This method will be removed in future releases.
static AsyncDatagramSocket	create(int inputBufferSize, int outputBufferSize, java.nio.ByteOrder byteOrder, DatagramListener listener) Deprecated. AsyncDatagramSocket.DatagramBuilder is the preferred mechanism for creating AsyncDatagramSocket instances. This method will be removed in future releases.
static AsyncDatagramSocket	create(int inputBufferSize, int outputBufferSize, java.nio.ByteOrder byteOrder, java.lang.String selector, DatagramListener listener) Deprecated. AsyncDatagramSocket.DatagramBuilder is the preferred mechanism for creating AsyncDatagramSocket instances. This method will be removed in future releases.
static AsyncDatagramSocket	create(int inputBufferSize, int outputBufferSize, DatagramListener listener) Deprecated. AsyncDatagramSocket.DatagramBuilder is the preferred mechanism for creating AsyncDatagramSocket instances. This method will be removed in future releases.
void	disconnect() Removes an in-place datagram "connection".
boolean	isConnected() Returns true if the datagram socket is connected and false otherwise.
void	open() Opens an unconnected IPv4 datagram socket.
void	open(java.net.ProtocolFamily family) Opens an unconnected datagram socket for the specified protocol.
void	open(java.net.SocketAddress bindAddr) Opens an unconnected, IPv4 datagram socket bound to the provided port and IP address.
void	open(java.net.SocketAddress bindAddr, java.net.ProtocolFamily family) Opens an unconnected, datagram socket for the specified protocol and bound to the provided port and IP address.
void	send(byte[] b) Sends the given bytes as a single UDP packet directly to the socket's peer.
void	send(byte[] b, int off, int len) Sends the given bytes as a single UDP packet directly to the socket's peer.
void	send(byte[] b, int off, int len, java.net.SocketAddress target) Sends the given bytes as a single UDP packet directly to the target address.
void	send(byte[] b, java.net.SocketAddress target) Sends the given bytes as a single UDP packet directly to the target address.
void	send(DatagramBufferWriter writer) When it is time to send the UDP packet generated by writer, BufferWriter.fill(ByteBuffer) is called, passing in the outbound buffer.
void	send(int b) Sends the given byte in a UDP datagram directly to the socket's peer.
void	send(int b, java.net.SocketAddress target) Sends the given byte in a UDP datagram directly to the target address.

Methods inherited from class net.sf.eBus.net.AbstractAsyncDatagramSocket

close, close, closeNow, datagramSocket, doSend, isBound, isOpen, opened, write

Methods inherited from class net.sf.eBus.net.AsyncChannel

getOption, inputBufferSize, isKnownSelector, localSocketAddress, outputBufferSize, remoteSocketAddress, setOption, supportedOptions

Methods inherited from class java.lang.Object

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

Method Detail

send

public void send(int b,
                 java.net.SocketAddress target)
          throws java.nio.channels.ClosedChannelException,
                 java.io.IOException

Sends the given byte in a UDP datagram directly to the target address. This method depends on this datagram socket not being connected.

Specified by:

send in class AbstractAsyncDatagramSocket

Parameters:

b - sends this single byte to the socket's peer.

target - send the UDP packet to this address.

Throws:

java.lang.IllegalArgumentException - if target is null.

java.nio.channels.ClosedChannelException - if this datagram socket is closed.

java.io.IOException - if this socket is connected.

send

public void send(byte[] b,
                 java.net.SocketAddress target)
          throws java.nio.channels.ClosedChannelException,
                 java.io.IOException

Sends the given bytes as a single UDP packet directly to the target address. This method depends on this socket not being connected.

Specified by:

send in class AbstractAsyncDatagramSocket

Parameters:

b - fill the UDP packet with this entire byte array.

target - send the UDP packet to this address.

Throws:

java.lang.IllegalArgumentException - if either b or target is null.

java.lang.IndexOutOfBoundsException - if b.length exceeds the outbound buffer size (which is set to the maximum allowed datagram size).

java.nio.channels.ClosedChannelException - if this datagram socket is closed.

java.io.IOException - if this socket is connected.

send

public void send(byte[] b,
                 int off,
                 int len,
                 java.net.SocketAddress target)
          throws java.nio.channels.ClosedChannelException,
                 java.io.IOException

Sends the given bytes as a single UDP packet directly to the target address. This method depends on this socket not being connected.

Specified by:

send in class AbstractAsyncDatagramSocket

Parameters:

b - send len bytes from this array starting at off offset.

off - offset into b.

len - send this many bytes from b.

target - send the UDP packet to this address.

Throws:

java.lang.IllegalArgumentException - if either b or target is null.

java.lang.IndexOutOfBoundsException - if off or off+len exceeds b bounds or len exceeds the maximum allowed datagram size.

java.nio.channels.ClosedChannelException - if this datagram socket is closed.

java.io.IOException - if this socket is connected.

send

public void send(DatagramBufferWriter writer)
          throws java.nio.channels.ClosedChannelException,
                 java.io.IOException

When it is time to send the UDP packet generated by writer, BufferWriter.fill(ByteBuffer) is called, passing in the outbound buffer. Upon completion, the UDP packet is sent to the target address. This method depends on this datagram socket not being connected.

Specified by:

send in class AbstractAsyncDatagramSocket

Parameters:

writer - fills the outbound buffer with the UDP packet contents and provides the target socket address.

Throws:

java.lang.IllegalArgumentException - if writer or target is null.

java.nio.channels.ClosedChannelException - if this datagram socket is closed.

java.nio.channels.NotYetConnectedException - if this datagram socket is not connected to a peer and DatagramBufferWriter.fill(ByteBuffer) returns null.

java.io.IOException - if this socket is connected.

isConnected

public boolean isConnected()

Returns true if the datagram socket is connected and false otherwise.

Returns:

true if the datagram socket is connected and false otherwise.

See Also:

AbstractAsyncDatagramSocket.close(), AbstractAsyncDatagramSocket.closeNow()

create

@Deprecated
public static AsyncDatagramSocket create(DatagramListener listener)

Deprecated. AsyncDatagramSocket.DatagramBuilder is the preferred mechanism for creating AsyncDatagramSocket instances. This method will be removed in future releases.

Returns a closed asynchronous datagram socket, forwarding all incoming packets to listener. The input and output buffer sizes are set to AsyncChannel.DEFAULT_BUFFER_SIZE and set to big-endian byte order . Uses the default selector to monitor this channel.

Parameters:

listener - forward all incoming packets to this listener.

Returns:

an un-opened, asynchronous datagram socket.

Throws:

java.lang.NullPointerException - if listener is null.

See Also:

DatagramListener, AsyncMulticastSocket, AsyncDatagramSocket.DatagramBuilder, create(int, int, DatagramListener), create(int, int, ByteOrder, DatagramListener), create(int, int, ByteOrder, String, DatagramListener), open(), open(ProtocolFamily), open(SocketAddress), open(SocketAddress, ProtocolFamily)

create

@Deprecated
public static AsyncDatagramSocket create(int inputBufferSize,
                                                     int outputBufferSize,
                                                     DatagramListener listener)

Deprecated. AsyncDatagramSocket.DatagramBuilder is the preferred mechanism for creating AsyncDatagramSocket instances. This method will be removed in future releases.

Returns a closed AsyncDatagramSocket, forwarding all incoming data to listener. The datagram socket directly-allocated input and output byte buffers will be of the specified sizes. The input and output buffers are set to big-endian byte order. Uses the default selector to monitor this channel.

Parameters:

inputBufferSize - allocate this many bytes for the direct input buffer.

outputBufferSize - allocate this many bytes for the direct output buffer.

listener - forward all incoming packets to this listener.

Returns:

an un-opened, asynchronous datagram socket.

Throws:

java.lang.NullPointerException - if any of the required parameters is null.

java.lang.IllegalArgumentException - if any of the parameters are invalid values.

See Also:

DatagramListener, AsyncMulticastSocket, AsyncDatagramSocket.DatagramBuilder, create(DatagramListener), create(int, int, ByteOrder, DatagramListener), create(int, int, ByteOrder, String, DatagramListener), open(), open(ProtocolFamily), open(SocketAddress), open(SocketAddress, ProtocolFamily)

create

@Deprecated
public static AsyncDatagramSocket create(int inputBufferSize,
                                                     int outputBufferSize,
                                                     java.nio.ByteOrder byteOrder,
                                                     DatagramListener listener)

Deprecated. AsyncDatagramSocket.DatagramBuilder is the preferred mechanism for creating AsyncDatagramSocket instances. This method will be removed in future releases.

Returns a closed AsyncDatagramSocket, forwarding all incoming data to listener. The datagram socket directly-allocated input and output byte buffers will be of the specified sizes. The input and output buffers are set to the given byte order. Uses the default selector thread to monitor the datagram channel.

Parameters:

inputBufferSize - allocate this many bytes for the direct input buffer.

outputBufferSize - allocate this many bytes for the direct output buffer.

byteOrder - the input and output buffers are set to this byte ordering.

listener - forward all incoming packets to this listener.

Returns:

an un-opened, asynchronous datagram socket.

Throws:

java.lang.NullPointerException - if any of the required parameters is null.

java.lang.IllegalArgumentException - if any of the given parameters is invalid.

See Also:

DatagramListener, AsyncMulticastSocket, AsyncDatagramSocket.DatagramBuilder, create(DatagramListener), create(int, int, DatagramListener), create(int, int, ByteOrder, String, DatagramListener), open(), open(ProtocolFamily), open(SocketAddress), open(SocketAddress, ProtocolFamily), SelectorThread, ThreadType

create

@Deprecated
public static AsyncDatagramSocket create(int inputBufferSize,
                                                     int outputBufferSize,
                                                     java.nio.ByteOrder byteOrder,
                                                     java.lang.String selector,
                                                     DatagramListener listener)

Deprecated. AsyncDatagramSocket.DatagramBuilder is the preferred mechanism for creating AsyncDatagramSocket instances. This method will be removed in future releases.

Returns a closed AsyncDatagramSocket, forwarding all incoming data to listener. The datagram socket directly-allocated input and output byte buffers will be of the specified sizes. The input and output buffers are set to the given byte order. Specifies the selector used to monitor this channel.

Parameters:

inputBufferSize - allocate this many bytes for the direct input buffer.

outputBufferSize - allocate this many bytes for the direct output buffer.

byteOrder - the input and output buffers are set to this byte ordering.

selector - use this selector thread to handle this socket.

listener - forward all incoming packets to this listener.

Returns:

an un-opened, asynchronous datagram socket.

Throws:

java.lang.NullPointerException - if any of the required parameters is null.

java.lang.IllegalArgumentException - if any of the given parameters is invalid.

See Also:

DatagramListener, AsyncMulticastSocket, AsyncDatagramSocket.DatagramBuilder, create(DatagramListener), create(int, int, DatagramListener), create(int, int, ByteOrder, DatagramListener), open(), open(ProtocolFamily), open(SocketAddress), open(SocketAddress, ProtocolFamily), SelectorThread, ThreadType

open

public void open()
          throws java.io.IOException

Opens an unconnected IPv4 datagram socket. The datagram is bound to any available port on the host. If this datagram socket is already open, then throws an IOException.

If you need to "connect" this UDP socket to a remote address, then call connect(SocketAddress) after successfully opening this datagram socket.

If the datagram socket is used for IP multicasting, then use open(ProtocolFamily) to be certain that this socket's protocol matches the multicast group address type. If the protocol types do not match, then this datagram socket will not be able to join the multicast group.

Throws:

java.io.IOException - if there is a datagram socket already open or an I/O exception occurs while opening the socket.

See Also:

open(ProtocolFamily), open(SocketAddress), open(SocketAddress, ProtocolFamily), connect(SocketAddress), disconnect(), AbstractAsyncDatagramSocket.close(), AbstractAsyncDatagramSocket.closeNow()

open

public void open(java.net.ProtocolFamily family)
          throws java.io.IOException

Opens an unconnected datagram socket for the specified protocol. The datagram is bound to any available port on the host. If this datagram socket is already open, then throws IOException.

If you need to "connect" this UDP socket to a remote address, then call connect(SocketAddress) after successfully opening this datagram socket.

If the datagram socket will be used for IP multicasting, then family should correspond to the multicast group address to which this datagram socket will join. If the multicast group is IPv4, then set family to StandardProtocolFamily.INET. If the multicast group is IPv6, then set family to StandardProtocolFamily.INET6.

Parameters:

family - protocol family.

Throws:

java.lang.UnsupportedOperationException - if the platform does not support the specified family.

java.io.IOException - if there is a datagram socket already open or an I/O exception occurs while opening the socket.

See Also:

open(), open(SocketAddress), open(SocketAddress, ProtocolFamily), connect(SocketAddress), disconnect(), AbstractAsyncDatagramSocket.close(), AbstractAsyncDatagramSocket.closeNow()

open

public void open(java.net.SocketAddress bindAddr)
          throws java.io.IOException

Opens an unconnected, IPv4 datagram socket bound to the provided port and IP address. If localAddr is 0.0.0.0, the socket is bound to the local host machine's wildcard address. If localAddr is null, then the socket is bound to any available port on the host.

If a datagram socket is already open, then throws an IOException.

Parameters:

bindAddr - bind the datagram socket to this address. If null, opens an unbound socket.

Throws:

java.io.IOException - if there is a datagram socket already open or an I/O exception occurs while opening the socket.

See Also:

open(), connect(SocketAddress), disconnect(), AbstractAsyncDatagramSocket.close(), AbstractAsyncDatagramSocket.closeNow()

open

public void open(java.net.SocketAddress bindAddr,
                 java.net.ProtocolFamily family)
          throws java.io.IOException

Opens an unconnected, datagram socket for the specified protocol and bound to the provided port and IP address. If localAddr is 0.0.0.0, the socket is bound to the local host machine's wildcard address. If localAddr is null, then the socket is bound to any available port on the host.

If a datagram socket is already open, then throws an IOException.

Parameters:

bindAddr - bind the datagram socket to this address. If null, opens an unbound socket.

family - protocol family.

Throws:

java.lang.UnsupportedOperationException - if the platform does not support the specified family.

java.io.IOException - if there is a datagram socket already open or an I/O exception occurs while opening the socket.

See Also:

open(), open(ProtocolFamily), open(SocketAddress), connect(SocketAddress), disconnect(), AbstractAsyncDatagramSocket.close(), AbstractAsyncDatagramSocket.closeNow()

connect

public void connect(java.net.SocketAddress remoteAddr)
             throws java.io.IOException

"Connects" the datagram socket to the given remote socket address. Since UDP is a connection-less protocol, what is actually happening is the datagram socket is configured to receive datagrams from and send datagrams to the remoteAddr. Once successfully connected, datagrams cannot be received or sent to any other address. This datagram socket remains connected until either disconnected or closed.

This method performs exactly the same security checks as the connect method of the DatagramSocket class. If a security manager has been installed then this method verifies that its checkAccept and checkConnect methods permit datagrams to be received from and sent to the remoteAddr.

This method may be invoked at any time. It will not have any effect on read or write operations already in progress when invoked.

Parameters:

remoteAddr - connect to this remote address.

Throws:

java.lang.IllegalArgumentException - if remoteAddr is null.

java.lang.IllegalStateException - if datagram socket is already connected or closed.

java.io.IOException - if some I/O error occurs.

See Also:

disconnect(), AbstractAsyncDatagramSocket.close(), AbstractAsyncDatagramSocket.closeNow()

disconnect

public void disconnect()
                throws java.io.IOException

Removes an in-place datagram "connection". When disconnected, the datagram socket can send to and receive from any remote address permitted by the security manager.

This method may be invoked at any time. It will not have any effect on read or write operations already in progress when invoked.

If this datagram socket is not connected or is closed, then invoking this method has no effect.

Throws:

java.io.IOException - if some I/O error occurs.

See Also:

connect(java.net.SocketAddress), AbstractAsyncDatagramSocket.close(), AbstractAsyncDatagramSocket.closeNow()

send

public void send(int b)
          throws java.nio.channels.ClosedChannelException,
                 java.io.IOException

Sends the given byte in a UDP datagram directly to the socket's peer. This method depends on this datagram socket being connected.

Parameters:

b - sends this single byte to the socket's peer.

Throws:

java.nio.channels.ClosedChannelException - if this datagram socket is closed.

java.nio.channels.NotYetConnectedException - if this datagram socket is not connected to a peer.

java.io.IOException - if the buffer was only partially transmitted or an underlying I/O error occurs.

send

public void send(byte[] b)
          throws java.nio.channels.ClosedChannelException,
                 java.io.IOException

Sends the given bytes as a single UDP packet directly to the socket's peer. This method depends on this datagram socket being connected.

Parameters:

b - fill the UDP packet with this data.

Throws:

java.lang.IllegalArgumentException - if b is null.

java.lang.IndexOutOfBoundsException - if b.length exceeds the outbound buffer size (which is set to the maximum allowed datagram size).

java.nio.channels.ClosedChannelException - if this datagram socket is closed.

java.nio.channels.NotYetConnectedException - if this datagram socket is not connected to a peer.

java.io.IOException - if the buffer was only partially transmitted or an underlying I/O error occurs.

send

public void send(byte[] b,
                 int off,
                 int len)
          throws java.nio.channels.ClosedChannelException,
                 java.io.IOException

Sends the given bytes as a single UDP packet directly to the socket's peer. This method depends on this datagram socket being connected.

Parameters:

b - send len bytes from this array starting at off offset.

off - offset into b.

len - send this many bytes from b.

Throws:

java.lang.IllegalArgumentException - if b is null.

java.lang.IndexOutOfBoundsException - if off or off+len exceeds b bounds or len exceeds the maximum allowed datagram size.

java.nio.channels.ClosedChannelException - if this datagram socket is closed.

java.nio.channels.NotYetConnectedException - if this datagram socket is not connected to a peer.

java.io.IOException - if the buffer was only partially transmitted or an underlying I/O error occurs.

builder

public static AsyncDatagramSocket.DatagramBuilder builder()

Returns the builder used to open new AsyncDatagramSocket instances.

Returns:

AsyncDatagramSocket builder.