This class defines a socket that can
receive and send unreliable datagram packets over the network using
the UDP protocol. A
datagram
is a very low-level networking interface: it is simply an array of
bytes sent over the network. A datagram does not implement any kind
of stream-based communication protocol, and there is no connection
established between the sender and the receiver. Datagram packets are
called unreliable because the protocol does not make any attempt to
ensure they arrive or to resend them if they don't.
Thus, packets sent through a DatagramSocket are
not guaranteed to arrive in the order sent or even to arrive at all.
On the other hand, this low-overhead protocol makes datagram
transmission very fast. See Socket and
URL for higher-level interfaces to networking.
This class was introduced in Java 1.0, and was enhanced in Java 1.4
to allow local and remote addresses to be specified using the
protocol-independent SocketAddress class.
send( ) sends a
DatagramPacket tHRough the socket. The packet must
contain the destination address to which it should be sent.
receive( ) waits for data to arrive at the socket
and stores it, along with the address of the sender, in the specified
DatagramPacket. close( ) closes
the socket and frees the local port for reuse. Once close(
) has been called, the DatagramSocket
should not be used again, except to call the isClosed(
) method which returns true if the
socket has been closed.
Each time a packet is sent or received,
the system must perform a security check to ensure that the calling
code has permission to send data to or receive data from the
specified host. In Java 1.2 and later, if you are sending multiple
packets to or receiving multiple packets from a single host, use
connect( ) to specify the host with which you are
communicating. This causes the security check to be done a single
time, but does not allow the socket to communicate with any other
host until disconnect( ) is called. Use
geTRemoteSocketAddress( ) or
getInetAddress( ) and getPort(
) to obtain the network address, if any, that the socket is
connected to. Use isConnected( ) to determine if
the socket is currently connected in this way.
By default, a DatagramSocket sends data through a
local address assigned by the system. If desired, however, you can
bind the socket to a specified local address. Do
this by using one of the constructors other than the no-arg
constructor. Or, bind the DatagramSocket to a
local SocketAddress with the bind(
)
method. You can determine whether a DatagramSocket is bound with
isBound( )
,
and you can obtain the local address of the socket with
getLocalSocketAddress( ) or with
getLocalAddress( ) and getLocalPort(
).
This
class defines a number of get/set method pairs for setting and
querying a variety of "socket
options" for datagram transmission.
setSoTimeout( ) specifies the number of
milliseconds that receive( ) waits for a packet to
arrive before throwing an InterruptedIOException.
Specify 0 milliseconds to wait forever.
setSendBufferSize(
)
and setReceiveBufferSize(
) set hints as to the underlying size of the networking
buffers.
setBroadcast( ), setReuseAddress(
), and setTrafficClass( ) set more
complex socket options; use of these options requires a sophisticated
understanding of low-level network protocols, and an explaination of
them is beyond the scope of this reference.
In Java 1.4 and later, getChannel(
)
returns a
java.nio.channels.DatagramChannel associated with
this DatagramSocket. Sockets created with one of
the DatagramSocket( ) constructors always return
null from this method. getChannel(
) only returns a useful value for sockets that were created
by and belong to a DatagramChannel.
public class DatagramSocket {
// Public Constructors
public DatagramSocket( ) throws SocketException;
1.4 public DatagramSocket(SocketAddress bindaddr) throws SocketException;
public DatagramSocket(int port) throws SocketException;
1.1 public DatagramSocket(int port, InetAddress laddr) throws SocketException;
// Protected Constructors
1.4 publicprotected DatagramSocket(DatagramSocketImpl impl);
// Public Class Methods
1.3 public static void setDatagramSocketImplFactory(DatagramSocketImplFactory
fac) throws java.io.IOException; synchronized
// Public Instance Methods
1.4 public void bind(SocketAddress addr) throws SocketException; synchronized
public void close( );
1.4 public void connect(SocketAddress addr) throws SocketException;
1.2 public void connect(InetAddress address, int port);
1.2 public void disconnect( );
1.4 public boolean getBroadcast( )
throws SocketException; synchronized default:true
1.4 public java.nio.channels.DatagramChannel getChannel( );
constant default:null
1.2 public InetAddress getInetAddress( ); default:null
1.1 public InetAddress getLocalAddress( ); default:Inet4Address
public int getLocalPort( ); default:32777
1.4 public SocketAddress getLocalSocketAddress( ); default:InetSocketAddress
1.2 public int getPort( ); default:-1
1.2 public int getReceiveBufferSize( )
throws SocketException; synchronized default:32767
1.4 public SocketAddress getRemoteSocketAddress( ); default:null
1.4 public boolean getReuseAddress( )
throws SocketException; synchronized default:false
1.2 public int getSendBufferSize( )
throws SocketException; synchronized default:32767
1.1 public int getSoTimeout( ) throws SocketException; synchronized default:0
1.4 public int getTrafficClass( ) throws SocketException; synchronized default:0
1.4 public boolean isBound( ); default:true
1.4 public boolean isClosed( ); default:false
1.4 public boolean isConnected( ); default:false
public void receive(DatagramPacket p) throws java.io.IOException; synchronized
public void send(DatagramPacket p) throws java.io.IOException;
1.4 public void setBroadcast(boolean on) throws SocketException; synchronized
1.2 public void setReceiveBufferSize(int size) throws SocketException; synchronized
1.4 public void setReuseAddress(boolean on) throws SocketException; synchronized
1.2 public void setSendBufferSize(int size) throws SocketException; synchronized
1.1 public void setSoTimeout(int timeout) throws SocketException; synchronized
1.4 public void setTrafficClass(int tc) throws SocketException; synchronized
}
