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
}