public class

DatagramSocket

extends Object
java.lang.Object
   ↳ java.net.DatagramSocket
Known Direct Subclasses

Class Overview

This class implements a UDP socket for sending and receiving DatagramPacket. A DatagramSocket object can be used for both endpoints of a connection for a packet delivery service.

See Also

Summary

Public Constructors
DatagramSocket()
Constructs a UDP datagram socket which is bound to any available port on the localhost.
DatagramSocket(int aPort)
Constructs a UDP datagram socket which is bound to the specific port aPort on the localhost.
DatagramSocket(int aPort, InetAddress addr)
Constructs a UDP datagram socket which is bound to the specific local address addr on port aPort.
DatagramSocket(SocketAddress localAddr)
Constructs a new DatagramSocket bound to the host/port specified by the SocketAddress localAddr or an unbound DatagramSocket if the SocketAddress is null.
Protected Constructors
DatagramSocket(DatagramSocketImpl socketImpl)
Constructs a new DatagramSocket using the specific datagram socket implementation socketImpl.
Public Methods
void bind(SocketAddress localAddr)
Binds this socket to the local address and port specified by localAddr.
void close()
Closes this UDP datagram socket and all possibly associated channels.
void connect(InetAddress anAddress, int aPort)
Connects this UDP datagram socket to the specific target host with the address anAdress on port aPort.
void connect(SocketAddress remoteAddr)
Connects this datagram socket to the remote host and port specified by remoteAddr.
void disconnect()
Disconnects this UDP datagram socket from the remote host.
boolean getBroadcast()
Gets the state of the socket option SocketOptions.SO_BROADCAST.
DatagramChannel getChannel()
Gets the related DatagramChannel of this socket.
InetAddress getInetAddress()
Gets the InetAddress instance representing the remote address to which this UDP datagram socket is connected.
InetAddress getLocalAddress()
Gets the InetAddress instance representing the bound local address of this UDP datagram socket.
int getLocalPort()
Gets the local port which this socket is bound to.
SocketAddress getLocalSocketAddress()
Gets the bound local address and port of this socket.
int getPort()
Gets the remote port which this socket is connected to.
synchronized int getReceiveBufferSize()
Gets the socket receive buffer size.
SocketAddress getRemoteSocketAddress()
Gets the address and port of the connected remote host.
boolean getReuseAddress()
Gets the state of the socket option SocketOptions.SO_REUSEADDR.
synchronized int getSendBufferSize()
Gets the socket send buffer size.
synchronized int getSoTimeout()
Gets the socket receive timeout in milliseconds.
int getTrafficClass()
Gets the value of the type-of-service socket option SocketOptions.IP_TOS.
boolean isBound()
Determines whether the socket is bound to an address or not.
boolean isClosed()
Gets the state of this socket.
boolean isConnected()
Determines whether the socket is connected to a target host.
synchronized void receive(DatagramPacket pack)
Receives a packet from this socket and stores it in the argument pack.
void send(DatagramPacket pack)
Sends a packet over this socket.
void setBroadcast(boolean broadcast)
Sets the socket option SocketOptions.SO_BROADCAST.
synchronized static void setDatagramSocketImplFactory(DatagramSocketImplFactory fac)
Sets the socket implementation factory.
synchronized void setReceiveBufferSize(int size)
Sets the socket receive buffer size.
void setReuseAddress(boolean reuse)
Sets the socket option SocketOptions.SO_REUSEADDR.
synchronized void setSendBufferSize(int size)
Sets the socket send buffer size.
synchronized void setSoTimeout(int timeout)
Sets the timeout period in milliseconds for the receive() method.
void setTrafficClass(int value)
Sets the socket option SocketOptions.IP_TOS.
[Expand]
Inherited Methods
From class java.lang.Object

Public Constructors

public DatagramSocket ()

Since: API Level 1

Constructs a UDP datagram socket which is bound to any available port on the localhost.

Throws
SocketException if an error occurs while creating or binding the socket.

public DatagramSocket (int aPort)

Since: API Level 1

Constructs a UDP datagram socket which is bound to the specific port aPort on the localhost. Valid values for aPort are between 0 and 65535 inclusive.

Parameters
aPort the port to bind on the localhost.
Throws
SocketException if an error occurs while creating or binding the socket.

public DatagramSocket (int aPort, InetAddress addr)

Since: API Level 1

Constructs a UDP datagram socket which is bound to the specific local address addr on port aPort. Valid values for aPort are between 0 and 65535 inclusive.

Parameters
aPort the port to bind on the localhost.
addr the address to bind on the localhost.
Throws
SocketException if an error occurs while creating or binding the socket.

public DatagramSocket (SocketAddress localAddr)

Since: API Level 1

Constructs a new DatagramSocket bound to the host/port specified by the SocketAddress localAddr 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.

Protected Constructors

protected DatagramSocket (DatagramSocketImpl socketImpl)

Since: API Level 1

Constructs a new DatagramSocket using the specific datagram socket implementation socketImpl. The created DatagramSocket will not be bound.

Parameters
socketImpl the DatagramSocketImpl to use.

Public Methods

public void bind (SocketAddress localAddr)

Since: API Level 1

Binds this socket to the local address and port specified by localAddr. If this value is null any free port on a valid local address is used.

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 binding.

public void close ()

Since: API Level 1

Closes this UDP datagram socket and all possibly associated channels.

public void connect (InetAddress anAddress, int aPort)

Since: API Level 1

Connects this UDP datagram socket to the specific target host with the address anAdress on port aPort. The host and port are validated, thereafter the only validation on send() and receive() is to check whether the packet address/port matches the connected target.

Parameters
anAddress the target address of this socket.
aPort the target port of this socket.

public void connect (SocketAddress remoteAddr)

Since: API Level 1

Connects this datagram socket to the remote host and port specified by remoteAddr. 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 address and port of the target host.
Throws
SocketException if an error occurs during connecting.

public void disconnect ()

Since: API Level 1

Disconnects this UDP datagram socket from the remote host. This method called on an unconnected socket does nothing.

public boolean getBroadcast ()

Since: API Level 1

Gets the state of the socket option SocketOptions.SO_BROADCAST.

Returns
  • true if the option is enabled, false otherwise.
Throws
SocketException if the socket is closed or the option is invalid.

public DatagramChannel getChannel ()

Since: API Level 1

Gets the related DatagramChannel of this socket. This implementation returns always null.

Returns
  • the related DatagramChannel or null if this socket was not created by a DatagramChannel object.

public InetAddress getInetAddress ()

Since: API Level 1

Gets the InetAddress instance representing the remote address to which this UDP datagram socket is connected.

Returns
  • the remote address this socket is connected to or null if this socket is not connected.

public InetAddress getLocalAddress ()

Since: API Level 1

Gets the InetAddress instance representing the bound local address of this UDP datagram socket.

Returns
  • the local address to which this socket is bound to or null if this socket is closed.

public int getLocalPort ()

Since: API Level 1

Gets the local port which this socket is bound to.

Returns
  • the local port of this socket or -1 if this socket is closed and 0 if it is unbound.

public SocketAddress getLocalSocketAddress ()

Since: API Level 1

Gets the bound local address and port of this socket. If the socket is unbound, null is returned.

Returns
  • the local socket address.

public int getPort ()

Since: API Level 1

Gets the remote port which this socket is connected to.

Returns
  • the remote port of this socket. The return value -1 indicates that this socket is not connected.

public synchronized int getReceiveBufferSize ()

Since: API Level 1

Gets the socket receive buffer size. ( SocketOptions.SO_RCVBUF )

Returns
  • the input buffer size.
Throws
SocketException if an error occurs while getting the option value.

public SocketAddress getRemoteSocketAddress ()

Since: API Level 1

Gets the address and port of the connected remote host. If this socket is not connected yet, null is returned.

Returns
  • the remote socket address.

public boolean getReuseAddress ()

Since: API Level 1

Gets the state of the socket option SocketOptions.SO_REUSEADDR.

Returns
  • true if the option is enabled, false otherwise.
Throws
SocketException if the socket is closed or the option is invalid.

public synchronized int getSendBufferSize ()

Since: API Level 1

Gets the socket send buffer size. ( SocketOptions.SO_SNDBUF )

Returns
  • the output buffer size.
Throws
SocketException if an error occurs while getting the option value.

public synchronized int getSoTimeout ()

Since: API Level 1

Gets the socket receive timeout in milliseconds. The return value 0 implies the timeout is disabled/infinitive. ( SocketOptions.SO_TIMEOUT )

Returns
  • the socket receive timeout.
Throws
SocketException if an error occurs while getting the option value.

public int getTrafficClass ()

Since: API Level 1

Gets the value of the type-of-service socket option SocketOptions.IP_TOS.

Returns
  • the type-of-service socket option value.
Throws
SocketException if the socket is closed or the option is invalid.

public boolean isBound ()

Since: API Level 1

Determines whether the socket is bound to an address or not.

Returns
  • true if the socket is bound, false otherwise.

public boolean isClosed ()

Since: API Level 1

Gets the state of this socket.

Returns
  • true if the socket is closed, false otherwise.

public boolean isConnected ()

Since: API Level 1

Determines whether the socket is connected to a target host.

Returns
  • true if the socket is connected, false otherwise.

public synchronized void receive (DatagramPacket pack)

Since: API Level 1

Receives a packet from this socket and stores it in the argument pack. All fields of pack must be set according to the data received. If the received data is longer than the packet buffer size it is truncated. This method blocks until a packet is received or a timeout has expired. If a security manager exists, its checkAccept method determines whether or not a packet is discarded. Any packets from unacceptable origins are silently discarded.

Parameters
pack the DatagramPacket to store the received data.
Throws
IOException if an error occurs while receiving the packet.

public void send (DatagramPacket pack)

Since: API Level 1

Sends a packet over this socket. The packet must satisfy the security policy before it may be sent. If a security manager is installed, this method checks whether it is allowed to send this packet to the specified address.

Parameters
pack the DatagramPacket which has to be sent.
Throws
IOException if an error occurs while sending the packet.

public void setBroadcast (boolean broadcast)

Since: API Level 1

Sets the socket option SocketOptions.SO_BROADCAST. This option must be enabled to send broadcast messages.

Parameters
broadcast the socket option value to enable or disable this option.
Throws
SocketException if the socket is closed or the option could not be set.

public static synchronized void setDatagramSocketImplFactory (DatagramSocketImplFactory fac)

Since: API Level 1

Sets the socket implementation factory. This may only be invoked once over the lifetime of the application. This factory is used to create a new datagram socket implementation. If a security manager is set its method checkSetFactory() is called to check if the operation is allowed. A SecurityException is thrown if the operation is not allowed.

Parameters
fac the socket factory to use.
Throws
IOException if the factory has already been set.
See Also

public synchronized void setReceiveBufferSize (int size)

Since: API Level 1

Sets the socket receive buffer size. This buffer size determines which the maximum packet size is that can be received over this socket. It depends on the network implementation what will happen if the packet is bigger than the buffer size. ( SocketOptions.SO_RCVBUF )

Parameters
size the buffer size in bytes. The size must be at least one byte.
Throws
SocketException if an error occurs while setting the option.

public void setReuseAddress (boolean reuse)

Since: API Level 1

Sets the socket option SocketOptions.SO_REUSEADDR. This option has to be enabled if more than one UDP socket wants to be bound to the same address. That could be needed for receiving multicast packets.

There is an undefined behavior if this option is set after the socket is already bound.

Parameters
reuse the socket option value to enable or disable this option.
Throws
SocketException if the socket is closed or the option could not be set.

public synchronized void setSendBufferSize (int size)

Since: API Level 1

Sets the socket send buffer size. This buffer size determines which the maximum packet size is that can be sent over this socket. It depends on the network implementation what will happen if the packet is bigger than the buffer size. ( SocketOptions.SO_SNDBUF )

Parameters
size the buffer size in bytes. The size must be at least one byte.
Throws
SocketException if an error occurs while setting the option.

public synchronized void setSoTimeout (int timeout)

Since: API Level 1

Sets the timeout period in milliseconds for the receive() method. This receive timeout defines the period the socket will block waiting to receive data before throwing an InterruptedIOException. The value 0 (default) is used to set an infinite timeout. To have effect this option must be set before the blocking method was called. ( SocketOptions.SO_TIMEOUT )

Parameters
timeout the timeout period in milliseconds or 0 for infinite.
Throws
SocketException if an error occurs while setting the option.

public void setTrafficClass (int value)

Since: API Level 1

Sets the socket option SocketOptions.IP_TOS. This option defines the value of the type-of-service field of the IP-header for every packet sent by this socket. The value could be ignored by the underlying network implementation.

Values between 0 and 255 inclusive are valid for this option.

Parameters
value the socket option value to be set as type-of-service.
Throws
SocketException if the socket is closed or the option could not be set.