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(SocketAddress peer)
Connects this datagram socket to the address and port specified by peer.
void connect(InetAddress address, int port)
Connects this datagram socket to the specific address and port.
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()
Returns this socket's DatagramChannel, if one exists.
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()
Returns the SocketAddress this socket is bound to, or null for an unbound socket.
int getPort()
Gets the remote port which this socket is connected to.
synchronized int getReceiveBufferSize()
Returns this socket's receive buffer size.
SocketAddress getRemoteSocketAddress()
Returns the SocketAddress this socket is connected to, or null for an unconnected socket.
boolean getReuseAddress()
Gets the state of the socket option SocketOptions.SO_REUSEADDR.
synchronized int getSendBufferSize()
Returns this socket's send buffer size.
synchronized int getSoTimeout()
Gets the socket receive timeout.
int getTrafficClass()
Returns this socket's setting.
boolean isBound()
Returns true if this socket is bound to a local address.
boolean isClosed()
Gets the state of this socket.
boolean isConnected()
Returns true if this datagram socket is connected to a remote address.
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 this socket's receive buffer size.
void setReuseAddress(boolean reuse)
Sets the socket option SocketOptions.SO_REUSEADDR.
synchronized void setSendBufferSize(int size)
Sets this socket's send buffer size.
synchronized void setSoTimeout(int timeout)
Sets the read timeout in milliseconds for this socket.
void setTrafficClass(int value)
Sets the value for every packet sent by this socket.
[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 (SocketAddress peer)

Since: API Level 1

Connects this datagram socket to the address and port specified by peer. Future calls to send(DatagramPacket) will use this as the default target, and receive(DatagramPacket) will only accept packets from this source.

Throws
SocketException if an error occurs.

public void connect (InetAddress address, int port)

Since: API Level 1

Connects this datagram socket to the specific address and port. Future calls to send(DatagramPacket) will use this as the default target, and receive(DatagramPacket) will only accept packets from this source.

Beware: because it can't throw, this method silently ignores failures. Use connect(SocketAddress) instead.

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

Returns this socket's DatagramChannel, if one exists. A channel is available only if this socket wraps a channel. (That is, you can go from a channel to a socket and back again, but you can't go from an arbitrary socket to a channel.) In practice, this means that the socket must have been created by open().

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

Returns the SocketAddress this socket is bound to, or null for an unbound socket.

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

Returns this socket's receive buffer size.

Throws
SocketException

public SocketAddress getRemoteSocketAddress ()

Since: API Level 1

Returns the SocketAddress this socket is connected to, or null for an unconnected socket.

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

Returns this socket's send buffer size.

Throws
SocketException

public synchronized int getSoTimeout ()

Since: API Level 1

Gets the socket receive timeout.

Throws
SocketException if an error occurs while getting the option value.

public int getTrafficClass ()

Since: API Level 1

Returns this socket's setting.

Throws
SocketException if the socket is closed or the option is invalid.
See Also

public boolean isBound ()

Since: API Level 1

Returns true if this socket is bound to a local address. See bind(SocketAddress).

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

Returns true if this datagram socket is connected to a remote address. See connect(InetAddress, int).

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.

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.

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.

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 this socket's receive buffer size.

Throws
SocketException

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 this socket's send buffer size.

Throws
SocketException

public synchronized void setSoTimeout (int timeout)

Since: API Level 1

Sets the read timeout in milliseconds for this socket. 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.

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

public void setTrafficClass (int value)

Since: API Level 1

Sets the value for every packet sent by this socket.

Throws
SocketException if the socket is closed or the option could not be set.
See Also