java.net
Class DatagramSocket

java.lang.Object
  java.net.DatagramSocket

Direct Known Subclasses:

MulticastSocket

public class DatagramSocket
extends Object

This class models a socket for sending & receiving datagram packets.

See Also:

DatagramPacket

Field Summary

(package private) InetAddress	address
(package private) static DatagramSocketImplFactory	factory
(package private) DatagramSocketImpl	impl
(package private) boolean	isBound
(package private) int	port

Constructor Summary

	DatagramSocket() Constructs a datagram socket, bound to any available port on the localhost.
protected	DatagramSocket(DatagramSocketImpl socketImpl) Constructs a DatagramSocket using the specified DatagramSocketImpl.
	DatagramSocket(int aPort) Returns a datagram socket, bound to the nominated port on the localhost.
	DatagramSocket(int aPort, InetAddress addr) Constructs a datagram socket, bound to the nominated localhost/port.
	DatagramSocket(SocketAddress localAddr) Constructs a DatagramSocket bound to the host/port specified by the SocketAddress, or an unbound DatagramSocket if the SocketAddress is null.

Method Summary

void	bind(SocketAddress localAddr) Bind the DatagramSocket to the nominated local host/port.
(package private) void	checkClosedAndBind(boolean bind)
(package private) void	checkListen(int aPort) Sent prior to attempting to bind the socket, check that the port is within the valid port range and verify with the security manager that the port may be bound by the current context.
void	close() Close the socket.
void	connect(InetAddress anAddress, int aPort) Connect the datagram socket to a remote host and port.
void	connect(SocketAddress remoteAddr) Connect the datagram socket to a remote host and port.
(package private) void	createSocket(int aPort, InetAddress addr)
void	disconnect() 'Disconnect' the datagram socket from a remote host and port.
boolean	getBroadcast() Get the state of the SO_BROADCAST socket option.
DatagramChannel	getChannel() if DatagramSocket is created by a DatagramChannel, returns the related DatagramChannel
InetAddress	getInetAddress() Returns an InetAddress instance representing the address this socket has connected to.
InetAddress	getLocalAddress() Returns an InetAddress instance representing the local address this socket is bound to.
int	getLocalPort() Answer the local port to which the socket is bound.
SocketAddress	getLocalSocketAddress() Answer the local SocketAddress for this socket, or null if the socket is not bound.
int	getPort() Returns the number of the remote port this socket is connected to.
int	getReceiveBufferSize() Answer the socket receive buffer size (SO_RCVBUF).
SocketAddress	getRemoteSocketAddress() Answer the remote SocketAddress for this socket, or null if the socket is not connected.
boolean	getReuseAddress() Get the state of the SO_REUSEADDR socket option.
int	getSendBufferSize() Answer the socket send buffer size (SO_SNDBUF).
int	getSoTimeout() Answer the socket receive timeout (SO_RCVTIMEOUT), in milliseconds.
int	getTrafficClass() Get the IP_TOS socket option.
boolean	isBound() Return if the socket is bound to a local address and port.
boolean	isClosed() Return if the socket is closed.
boolean	isConnected() Return if the socket is connected.
(package private) boolean	isMulticastSocket() Returns whether this socket is multicast.
void	receive(DatagramPacket pack) Receive on this socket into the packet argument.
void	send(DatagramPacket pack) Send the packet on this socket.
void	setBroadcast(boolean broadcast) Set the SO_BROADCAST socket option.
static void	setDatagramSocketImplFactory(DatagramSocketImplFactory fac) Specifies the application's socket implementation factory.
void	setReceiveBufferSize(int size) Set the socket receive buffer size.
void	setReuseAddress(boolean reuse) Set the SO_REUSEADDR socket option.
void	setSendBufferSize(int size) Set the socket send buffer size.
void	setSoTimeout(int timeout) Set the SO_RCVTIMEOUT to timeout, in milliseconds.
void	setTrafficClass(int value) Set the IP_TOS socket option.

Methods inherited from class java.lang.Object

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

Field Detail

impl

DatagramSocketImpl impl

address

InetAddress address

port

int port

factory

static DatagramSocketImplFactory factory

isBound

boolean isBound

Constructor Detail

DatagramSocket

public DatagramSocket()
               throws SocketException

Constructs a datagram socket, bound to any available port on the localhost.

Throws:

SocketException - if a problem occurs creating or binding the socket

DatagramSocket

public DatagramSocket(int aPort)
               throws SocketException

Returns a datagram socket, bound to the nominated port on the localhost.

Parameters:

aPort - the port to bind on the localhost

Throws:

SocketException - if a problem occurs creating or binding the socket

DatagramSocket

public DatagramSocket(int aPort,
                      InetAddress addr)
               throws SocketException

Constructs a datagram socket, bound to the nominated localhost/port.

Parameters:

aPort - the port on the localhost to bind

addr - the address on the multihomed localhost to bind

Throws:

SocketException - if a problem occurs creating or binding the socket

DatagramSocket

protected DatagramSocket(DatagramSocketImpl socketImpl)

Constructs a DatagramSocket using the specified DatagramSocketImpl. The DatagramSocket is not bound.

Parameters:

socketImpl - the DatagramSocketImpl to use

DatagramSocket

public DatagramSocket(SocketAddress localAddr)
               throws SocketException

Constructs a DatagramSocket bound to the host/port specified by the SocketAddress, or an unbound DatagramSocket if the SocketAddress is null.

Parameters:

localAddr - the local machine address and port to bind to

Throws:

IllegalArgumentException - if the SocketAddress is not supported

SocketException - if a problem occurs creating or binding the socket

Method Detail

checkListen

void checkListen(int aPort)

Sent prior to attempting to bind the socket, check that the port is within the valid port range and verify with the security manager that the port may be bound by the current context.

Parameters:

aPort - the port on the localhost that is to be bound

close

public void close()

Close the socket.

connect

public void connect(InetAddress anAddress,
                    int aPort)

Connect the datagram socket to a remote host and port. The host and port are validated, thereafter the only validation on send() and receive() is that the packet address/port matches the connected target.

Parameters:

anAddress - the target address

aPort - the target port

disconnect

public void disconnect()

'Disconnect' the datagram socket from a remote host and port. This method may be called on an unconnected socket.

createSocket

void createSocket(int aPort,
                  InetAddress addr)
            throws SocketException

Throws:

SocketException

getInetAddress

public InetAddress getInetAddress()

Returns an InetAddress instance representing the address this socket has connected to.

Returns:

if this socket is connected, the address it is connected to. A null return signifies no connection has been made.

getLocalAddress

public InetAddress getLocalAddress()

Returns an InetAddress instance representing the local address this socket is bound to.

Returns:

the local address to which the socket is bound

getLocalPort

public int getLocalPort()

Answer the local port to which the socket is bound.

Returns:

int local port to which the socket is bound

getPort

public int getPort()

Returns the number of the remote port this socket is connected to.

Returns:

int the remote port number that this socket has connected to. A return of -1 indicates that there is no connection in place.

isMulticastSocket

boolean isMulticastSocket()

Returns whether this socket is multicast.

Returns:

Always returns false.

getReceiveBufferSize

public int getReceiveBufferSize()
                         throws SocketException

Answer the socket receive buffer size (SO_RCVBUF).

Returns:

int socket receive buffer size

Throws:

SocketException - when an error occurs

getSendBufferSize

public int getSendBufferSize()
                      throws SocketException

Answer the socket send buffer size (SO_SNDBUF).

Returns:

int socket send buffer size

Throws:

SocketException - when an error occurs

getSoTimeout

public int getSoTimeout()
                 throws SocketException

Answer the socket receive timeout (SO_RCVTIMEOUT), in milliseconds. Zero implies the timeout is disabled.

Returns:

int socket receive timeout

Throws:

SocketException - when an error occurs

receive

public void receive(DatagramPacket pack)
             throws IOException

Receive on this socket into the packet argument. This method blocks until a packet is received or, if a timeout has been defined, the timeout period expires. If this is a connected socket, the packet host/port are compared to the connection host/port otherwise the security manager if present is queried whether the packet host/port is acceptable. Any packets from unacceptable origins will be silently discarded. The packet fields are set according to the data received. If the received data is longer than the packet buffer, it is truncated.

Parameters:

pack - the DatagramPacket to receive data into

Throws:

IOException - If a receive error occurs.

send

public void send(DatagramPacket pack)
          throws IOException

Send the packet on this socket. The packet must satisfy the security policy before it may be sent.

Parameters:

pack - the DatagramPacket to send

Throws:

IOException - If a send error occurs.

setSendBufferSize

public void setSendBufferSize(int size)
                       throws SocketException

Set the socket send buffer size.

Parameters:

size - the buffer size, in bytes. Must be at least one byte.

Throws:

SocketException - If an error occurs while setting the size or the size is invalid.

setReceiveBufferSize

public void setReceiveBufferSize(int size)
                          throws SocketException

Set the socket receive buffer size.

Parameters:

size - the buffer size, in bytes. Must be at least one byte.

Throws:

SocketException - If an error occurs while setting the size or the size is invalid.

setSoTimeout

public void setSoTimeout(int timeout)
                  throws SocketException

Set the SO_RCVTIMEOUT to timeout, in milliseconds. The receive timeout defines the period a socket will block waiting to receive data, before throwing an InterruptedIOException.

Parameters:

timeout - the timeout period, in milliseconds

Throws:

SocketException - If an error occurs while setting the timeout or the period is invalid.

setDatagramSocketImplFactory

public static void setDatagramSocketImplFactory(DatagramSocketImplFactory fac)
                                         throws IOException

Specifies the application's socket implementation factory. This may only be invoked once over the lifetime of the application.

Parameters:

fac - the socket factory to set

Throws:

IOException - thrown if the factory has already been set

checkClosedAndBind

void checkClosedAndBind(boolean bind)
                  throws SocketException

Throws:

SocketException

bind

public void bind(SocketAddress localAddr)
          throws SocketException

Bind the DatagramSocket to the nominated local host/port.

Parameters:

localAddr - the local machine address and port to bind on

Throws:

IllegalArgumentException - if the SocketAddress is not supported

SocketException - if the socket is already bound, or a problem occurs during the bind

connect

public void connect(SocketAddress remoteAddr)
             throws SocketException

Connect the datagram socket to a remote host and port. The host and port are validated, thereafter the only validation on send() and receive() is that the packet address/port matches the connected target.

Parameters:

remoteAddr - the target address and port

Throws:

SocketException - if a problem occurs during the connect

isBound

public boolean isBound()

Return if the socket is bound to a local address and port.

Returns:

true if the socket is bound to a local address, false otherwise.

isConnected

public boolean isConnected()

Return if the socket is connected.

Returns:

true if the socket is connected, false otherwise.

getRemoteSocketAddress

public SocketAddress getRemoteSocketAddress()

Answer the remote SocketAddress for this socket, or null if the socket is not connected.

Returns:

the remote socket address

getLocalSocketAddress

public SocketAddress getLocalSocketAddress()

Answer the local SocketAddress for this socket, or null if the socket is not bound.

This is useful on multihomed hosts.

Returns:

the local socket address

setReuseAddress

public void setReuseAddress(boolean reuse)
                     throws SocketException

Set the SO_REUSEADDR socket option.

Parameters:

reuse - the socket SO_REUSEADDR option setting

Throws:

SocketException - if the socket is closed or the option is invalid.

getReuseAddress

public boolean getReuseAddress()
                        throws SocketException

Get the state of the SO_REUSEADDR socket option.

Returns:

true if the SO_REUSEADDR is enabled, false otherwise.

Throws:

SocketException - if the socket is closed or the option is invalid.

setBroadcast

public void setBroadcast(boolean broadcast)
                  throws SocketException

Set the SO_BROADCAST socket option.

Parameters:

broadcast - the socket SO_BROADCAST option setting

Throws:

SocketException - if the socket is closed or the option is invalid.

getBroadcast

public boolean getBroadcast()
                     throws SocketException

Get the state of the SO_BROADCAST socket option.

Returns:

true if the SO_BROADCAST is enabled, false otherwise.

Throws:

SocketException - if the socket is closed or the option is invalid.

setTrafficClass

public void setTrafficClass(int value)
                     throws SocketException

Set the IP_TOS socket option.

Parameters:

value - the socket IP_TOS setting

Throws:

SocketException - if the socket is closed or the option is invalid.

getTrafficClass

public int getTrafficClass()
                    throws SocketException

Get the IP_TOS socket option.

Returns:

the IP_TOS socket option value

Throws:

SocketException - if the option is invalid

isClosed

public boolean isClosed()

Return if the socket is closed.

Returns:

true if the socket is closed, false otherwise.

getChannel

public DatagramChannel getChannel()

if DatagramSocket is created by a DatagramChannel, returns the related DatagramChannel

Returns:

the related DatagramChannel if any