JavaTM 2 Platform
Standard Ed. 6

java.net
类 DatagramSocket

java.lang.Object
  继承者 java.net.DatagramSocket
直接已知子类:
MulticastSocket

public class DatagramSocket
extends Object

此类表示用来发送和接收数据报包的套接字。

数据报套接字是包投递服务的发送或接收点。每个在数据报套接字上发送或接收的包都是单独编址和路由的。从一台机器发送到另一台机器的多个包可能选择不同的路由,也可能按不同的顺序到达。

在 DatagramSocket 上总是启用 UDP 广播发送。为了接收广播包,应该将 DatagramSocket 绑定到通配符地址。在某些实现中,将 DatagramSocket 绑定到一个更加具体的地址时广播包也可以被接收。

示例:DatagramSocket s = new DatagramSocket(null); s.bind(new InetSocketAddress(8888)); 这等价于:DatagramSocket s = new DatagramSocket(8888); 两个例子都能创建能够在 UDP 8888 端口上接收广播的 DatagramSocket。

从以下版本开始:
JDK1.0
另请参见:
DatagramPacket, DatagramChannel

构造方法摘要
  DatagramSocket()
          构造数据报套接字并将其绑定到本地主机上任何可用的端口。
protected DatagramSocket(DatagramSocketImpl impl)
          创建带有指定 DatagramSocketImpl 的未绑定数据报套接字。
  DatagramSocket(int port)
          创建数据报套接字并将其绑定到本地主机上的指定端口。
  DatagramSocket(int port, InetAddress laddr)
          创建数据报套接字,将其绑定到指定的本地地址。
  DatagramSocket(SocketAddress bindaddr)
          创建数据报套接字,将其绑定到指定的本地套接字地址。
 
方法摘要
 void bind(SocketAddress addr)
          将此 DatagramSocket 绑定到特定的地址和端口。
 void close()
          关闭此数据报套接字。
 void connect(InetAddress address, int port)
          将套接字连接到此套接字的远程地址。
 void connect(SocketAddress addr)
          将此套接字连接到远程套接字地址(IP 地址 + 端口号)。
 void disconnect()
          断开套接字的连接。
 boolean getBroadcast()
          检测是否启用了 SO_BROADCAST。
 DatagramChannel getChannel()
          返回与此数据报套接字关联的唯一 DatagramChannel 对象(如果有)。
 InetAddress getInetAddress()
          返回此套接字连接的地址。
 InetAddress getLocalAddress()
          获取套接字绑定的本地地址。
 int getLocalPort()
          返回此套接字绑定的本地主机上的端口号。
 SocketAddress getLocalSocketAddress()
          返回此套接字绑定的端点的地址,如果尚未绑定则返回 null
 int getPort()
          返回此套接字的端口。
 int getReceiveBufferSize()
          获取此 DatagramSocket 的 SO_RCVBUF 选项的值,该值是平台在 DatagramSocket 上输入时使用的缓冲区大小。
 SocketAddress getRemoteSocketAddress()
          返回此套接字连接的端点的地址,如果未连接则返回 null
 boolean getReuseAddress()
          检测是否启用了 SO_REUSEADDR。
 int getSendBufferSize()
          获取此 DatagramSocket 的 SO_SNDBUF 选项的值,该值是平台在 DatagramSocket 上输出时使用的缓冲区大小。
 int getSoTimeout()
          获取 SO_TIMEOUT 的设置。
 int getTrafficClass()
          为从此 DatagramSocket 上发送的包获取 IP 数据报头中的流量类别或服务类型。
 boolean isBound()
          返回套接字的绑定状态。
 boolean isClosed()
          返回是否关闭了套接字。
 boolean isConnected()
          返回套接字的连接状态。
 void receive(DatagramPacket p)
          从此套接字接收数据报包。
 void send(DatagramPacket p)
          从此套接字发送数据报包。
 void setBroadcast(boolean on)
          启用/禁用 SO_BROADCAST。
static void setDatagramSocketImplFactory(DatagramSocketImplFactory fac)
          为应用程序设置数据报套接字实现工厂。
 void setReceiveBufferSize(int size)
          将此 DatagramSocket 的 SO_RCVBUF 选项设置为指定的值。
 void setReuseAddress(boolean on)
          启用/禁用 SO_REUSEADDR 套接字选项。
 void setSendBufferSize(int size)
          将此 DatagramSocket 的 SO_SNDBUF 选项设置为指定的值。
 void setSoTimeout(int timeout)
          启用/禁用带有指定超时值的 SO_TIMEOUT,以毫秒为单位。
 void setTrafficClass(int tc)
          为从此 DatagramSocket 上发送的数据报在 IP 数据报头中设置流量类别 (traffic class) 或服务类型八位组 (type-of-service octet)。
 
从类 java.lang.Object 继承的方法
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

构造方法详细信息

DatagramSocket

public DatagramSocket()
               throws SocketException
构造数据报套接字并将其绑定到本地主机上任何可用的端口。套接字将被绑定到通配符地址,IP 地址由内核来选择。

如果有安全管理器,则首先使用 0 作为变量来调用其 checkListen 方法,以确保允许该操作。这可能会导致 SecurityException 异常。

抛出:
SocketException - 如果套接字不能被打开,或不能将其绑定到指定的本地端口。
SecurityException - 如果安全管理器存在并且其 checkListen 方法不允许进行该操作。
另请参见:
SecurityManager.checkListen(int)

DatagramSocket

protected DatagramSocket(DatagramSocketImpl impl)
创建带有指定 DatagramSocketImpl 的未绑定数据报套接字。

参数:
impl - 子类希望在 DatagramSocket 上使用的 DatagramSocketImpl 的实例。
从以下版本开始:
1.4

DatagramSocket

public DatagramSocket(SocketAddress bindaddr)
               throws SocketException
创建数据报套接字,将其绑定到指定的本地套接字地址。

如果地址为 null,创建未绑定的套接字。

如果有安全管理器,则首先使用套接字中的端口作为变量来调用其 checkListen 方法,以确保允许该操作。这可能会导致 SecurityException 异常。

参数:
bindaddr - 要绑定的本地套接字地址,对于未绑定的套接字为 null
抛出:
SocketException - 如果套接字不能被打开,或不能将其绑定到指定的本地端口。
SecurityException - 如果安全管理器存在并且其 checkListen 方法不允许进行该操作。
从以下版本开始:
1.4
另请参见:
SecurityManager.checkListen(int)

DatagramSocket

public DatagramSocket(int port)
               throws SocketException
创建数据报套接字并将其绑定到本地主机上的指定端口。套接字将被绑定到通配符地址,IP 地址由内核来选择。

如果存在安全管理器,则首先使用 port 参数作为参数调用其 checkListen 方法,以确保允许该操作。这可能会导致 SecurityException 异常。

参数:
port - 要使用的端口。
抛出:
SocketException - 如果套接字不能被打开,或不能将其绑定到指定的本地端口。
SecurityException - 如果安全管理器存在并且其 checkListen 方法不允许进行该操作。
另请参见:
SecurityManager.checkListen(int)

DatagramSocket

public DatagramSocket(int port,
                      InetAddress laddr)
               throws SocketException
创建数据报套接字,将其绑定到指定的本地地址。本地端口必须在 0 到 65535 之间(包括两者)。如果 IP 地址为 0.0.0.0,套接字将被绑定到通配符地址,IP 地址由内核选择。

如果存在安全管理器,则首先使用 port 参数作为参数调用其 checkListen 方法,以确保允许该操作。这可能会导致 SecurityException 异常。

参数:
port - 要使用的本地端口
laddr - 要绑定的本地地址
抛出:
SocketException - 如果套接字不能被打开,或不能将其绑定到指定的本地端口。
SecurityException - 如果安全管理器存在并且其 checkListen 方法不允许进行该操作。
从以下版本开始:
JDK1.1
另请参见:
SecurityManager.checkListen(int)
方法详细信息

bind

public void bind(SocketAddress addr)
          throws SocketException
将此 DatagramSocket 绑定到特定的地址和端口。

如果地址为 null,则系统将挑选一个临时端口和一个有效本地地址来绑定套接字。

参数:
addr - 要绑定的地址和端口。
抛出:
SocketException - 如果绑定过程中发生错误,或者套接字已经被绑定。
SecurityException - 如果安全管理器存在并且其 checkListen 方法不允许进行该操作。
IllegalArgumentException - 如果 addr 是不受此套接字支持的 SocketAddress 子类。
从以下版本开始:
1.4

connect

public void connect(InetAddress address,
                    int port)
将套接字连接到此套接字的远程地址。当套接字连接到远程地址时,包就只能从该地址发送或接收。默认情况下不连接数据报套接字。

如果套接字要连接的远程目标不存在或不可到达,并且收到了该地址的目标不可达 ICMP 包,那么后续发送和接收的调用可能会抛出 PortUnreachableException。注意,不能保证一定抛出该异常。

在连接时检查调用者对给定主机和端口的发送和接收数据报权限。当连接建立起来后,接收和发送除了对包和套接字的地址和端口进行匹配外,对传入和传出的包将不再执行任何安全性检查。对于发送操作,如果设置了包的地址并且包的地址和套接字的地址不匹配,则将抛出 IllegalArgumentException。连接到多播地址的套接字只能用于发送包。

参数:
address - 套接字的远程地址。
port - 套接字的远程端口。
抛出:
IllegalArgumentException - 如果地址为 null,或端口超出了范围。
SecurityException - 如果不允许调用者向此地址和端口发送也不允许从此地址接收数据报。
另请参见:
disconnect(), send(java.net.DatagramPacket), receive(java.net.DatagramPacket)

connect

public void connect(SocketAddress addr)
             throws SocketException
将此套接字连接到远程套接字地址(IP 地址 + 端口号)。

参数:
addr - 远程地址。
抛出:
SocketException - 如果连接失败
IllegalArgumentException - 如果 addr 为 null 或者 addr 是不受此套接字支持的 SocketAddress 子类。
从以下版本开始:
1.4
另请参见:
connect(java.net.InetAddress, int)

disconnect

public void disconnect()
断开套接字的连接。如果套接字没有连接,则此方法不执行任何操作。

另请参见:
connect(java.net.InetAddress, int)

isBound

public boolean isBound()
返回套接字的绑定状态。

返回:
如果将套接字成功地绑定到一个地址,则返回 true
从以下版本开始:
1.4

isConnected

public boolean isConnected()
返回套接字的连接状态。

返回:
如果将套接字成功地连接到服务器,则为 true。
从以下版本开始:
1.4

getInetAddress

public InetAddress getInetAddress()
返回此套接字连接的地址。如果套接字未连接,则返回 null。

返回:
此套接字连接的地址。

getPort

public int getPort()
返回此套接字的端口。如果套接字未连接,则返回 -1。

返回:
此套接字连接的端口。

getRemoteSocketAddress

public SocketAddress getRemoteSocketAddress()
返回此套接字连接的端点的地址,如果未连接则返回 null

返回:
表示此套接字远程端点的 SocketAddress,如果尚未连接则返回 null
从以下版本开始:
1.4
另请参见:
getInetAddress(), getPort(), connect(SocketAddress)

getLocalSocketAddress

public SocketAddress getLocalSocketAddress()
返回此套接字绑定的端点的地址,如果尚未绑定则返回 null

返回:
表示此套接字的本地端点的 SocketAddress,如果尚未绑定则返回 null
从以下版本开始:
1.4
另请参见:
getLocalAddress(), getLocalPort(), bind(SocketAddress)

send

public void send(DatagramPacket p)
          throws IOException
从此套接字发送数据报包。DatagramPacket 包含的信息指示:将要发送的数据、其长度、远程主机的 IP 地址和远程主机的端口号。

如果存在安全管理器,且套接字当前没有连接到远程地址,则此方法首先执行某些安全性检查。首先,如果 p.getAddress().isMulticastAddress() 为 true,则此方法以 p.getAddress() 作为参数调用安全管理器的 checkMulticast 方法。如果该表达式的值为 false,此方法改为调用安全管理器的以 p.getAddress().getHostAddress()p.getPort() 为参数的 checkConnect 方法。如果不允许该操作,则每次调用安全管理器方法都会导致 SecurityException。

参数:
p - 将要发送的 DatagramPacket
抛出:
IOException - 如果发生 I/O 错误。
SecurityException - 如果安全管理器存在并且其 checkMulticastcheckConnect 方法不允许进行发送。
PortUnreachableException - 套接字连接到当前不可达的目标时可能抛出。注意,不能保证一定抛出该异常。
IllegalBlockingModeException - 如果此套接字具有相关联的通道,且通道处于非阻塞模式。
另请参见:
DatagramPacket, SecurityManager.checkMulticast(InetAddress), SecurityManager.checkConnect(java.lang.String, int)

receive

public void receive(DatagramPacket p)
             throws IOException
从此套接字接收数据报包。当此方法返回时,DatagramPacket 的缓冲区填充了接收的数据。数据报包也包含发送方的 IP 地址和发送方机器上的端口号。

此方法在接收到数据报前一直阻塞。数据报包对象的 length 字段包含所接收信息的长度。如果信息比包的长度长,该信息将被截短。

如果存在安全管理器,而安全管理器的 checkAccept 方法不允许接收操作,则包不能被接收。

参数:
p - 要放置传入数据的 DatagramPacket
抛出:
IOException - 如果发生 I/O 错误。
SocketTimeoutException - 如果先前调用了 setSoTimeout 且超时值已过。
PortUnreachableException - 套接字连接到当前不可达的目标时可能抛出。注意,不能保证一定抛出该异常。
IllegalBlockingModeException - 如果此套接字具有相关联的通道,且通道处于非阻塞模式。
另请参见:
DatagramPacket, DatagramSocket

getLocalAddress

public InetAddress getLocalAddress()
获取套接字绑定的本地地址。

如果存在安全管理器,则首先使用主机地址和 -1 作为参数调用其 checkConnect 方法,以查看是否允许该操作。

返回:
套接字绑定的本地地址,如果套接字没有绑定或安全管理器的 checkConnect 方法不允许该操作,则返回表示任何本地地址的 InetAddress
另请参见:
SecurityManager.checkConnect(java.lang.String, int)

getLocalPort

public int getLocalPort()
返回此套接字绑定的本地主机上的端口号。

返回:
此套接字绑定的本地主机上的端口。

setSoTimeout

public void setSoTimeout(int timeout)
                  throws SocketException
启用/禁用带有指定超时值的 SO_TIMEOUT,以毫秒为单位。将此选项设为非零的超时值时,对此 DatagramSocket 调用 receive() 将只阻塞此时间长度。如果超过超时值,将引发 java.net.SocketTimeoutException,虽然 DatagramSocket 仍旧有效。选项必须在进入阻塞操作前被启用才能生效。超时值必须是 > 0 的数。超时值为 0 被解释为无穷大超时值。

参数:
timeout - 指定的以毫秒为单位的超时值。
抛出:
SocketException - 如果底层协议出现错误,例如 UDP 错误。
从以下版本开始:
JDK1.1
另请参见:
getSoTimeout()

getSoTimeout

public int getSoTimeout()
                 throws SocketException
获取 SO_TIMEOUT 的设置。返回 0 意味着禁用了选项(即无穷大的超时值)。

返回:
SO_TIMEOUT 的设置。
抛出:
SocketException - 如果底层协议出现错误,例如 UDP 错误。
从以下版本开始:
JDK1.1
另请参见:
setSoTimeout(int)

setSendBufferSize

public void setSendBufferSize(int size)
                       throws SocketException
将此 DatagramSocket 的 SO_SNDBUF 选项设置为指定的值。网络实现使用 SO_SNDBUF 选项作为设置底层网络 I/O 缓冲区大小的提示。网络实现也可以使用 SO_SNDBUF 设置来决定在此套接字上可以传送的包的最大大小。

由于 SO_SNDBUF 是一种提示,想要验证缓冲区大小的应用程序应该调用 getSendBufferSize()

当发送率很高时,增大缓冲区的大小可以允许网络实现对多个传出包进行排队。

注:如果使用 send(DatagramPacket) 来发送比 SO_SNDBUF 设置大的 DatagramPacket,包是被发送还是被丢弃是特定于实现的。

参数:
size - 将设置的发送缓冲区大小。此值必须大于 0。
抛出:
SocketException - 如果底层协议出现错误,例如 UDP 错误。
IllegalArgumentException - 如果值为 0 或负。
另请参见:
getSendBufferSize()

getSendBufferSize

public int getSendBufferSize()
                      throws SocketException
获取此 DatagramSocket 的 SO_SNDBUF 选项的值,该值是平台在 DatagramSocket 上输出时使用的缓冲区大小。

返回:
DatagramSocket 的 SO_SNDBUF 选项的值。
抛出:
SocketException - 如果底层协议出现错误,例如 UDP 错误。
另请参见:
setSendBufferSize(int)

setReceiveBufferSize

public void setReceiveBufferSize(int size)
                          throws SocketException
将此 DatagramSocket 的 SO_RCVBUF 选项设置为指定的值。网络实现使用 SO_RCVBUF 选项作为设置底层网络 I/O 缓冲区大小的提示。网络实现也可以使用 SO_RCVBUF 设置来决定在此套接字上可以接收的包的最大大小。

由于 SO_RCVBUF 是一种提示,想要验证缓冲区设置大小的应用程序应该调用 getReceiveBufferSize()

当包到达的速度快于使用 receive(DatagramPacket) 接收包的速度时,增大 SO_RCVBUF 可以允许网络实现缓存多个包。

注:是否能接收大于 SO_RCVBUF 的包是特定于实现的。

参数:
size - 要设置的接收缓冲区大小。此值必须大于 0。
抛出:
SocketException - 如果底层协议出现错误,例如 UDP 错误。
IllegalArgumentException - 如果值为 0 或负。
另请参见:
getReceiveBufferSize()

getReceiveBufferSize

public int getReceiveBufferSize()
                         throws SocketException
获取此 DatagramSocket 的 SO_RCVBUF 选项的值,该值是平台在 DatagramSocket 上输入时使用的缓冲区大小。

返回:
DatagramSocket 的 SO_RCVBUF 选项的值。
抛出:
SocketException - 如果底层协议出现错误,例如 UDP 错误。
另请参见:
setReceiveBufferSize(int)

setReuseAddress

public void setReuseAddress(boolean on)
                     throws SocketException
启用/禁用 SO_REUSEADDR 套接字选项。

对于 UDP 套接字可能有必要把超过一个的套接字绑定到相同的套接字地址。这样做的目的通常是为了接收多播包。(请参阅 MulticastSocket)。如果在使用 bind(SocketAddress) 绑定套接字之前启用 SO_REUSEADDR 套接字选项,则 SO_REUSEADDR 套接字选项允许将多个套接字绑定到相同的套结字地址。

注意:所有现有平台都不支持此功能,因此不管是否将忽略此选项,它都是特定于实现的。但是,如果此功能不受支持,则 getReuseAddress() 将始终返回 false

当创建 DatagramSocket 时,禁用 SO_REUSEADDR 的初始设置。

在绑定套接字(请参阅 isBound())后启用或禁用 SO_REUSEADDR 时的行为是不确定的。

参数:
on - 是否启用 SO_REUSEADDR 套接字选项
抛出:
如果启用或禁用 - SO_RESUEADDR 套接字选项时发生错误,或者关闭了套接字。
SocketException
从以下版本开始:
1.4
另请参见:
getReuseAddress(), bind(SocketAddress), isBound(), isClosed()

getReuseAddress

public boolean getReuseAddress()
                        throws SocketException
检测是否启用了 SO_REUSEADDR。

返回:
指示是否启用 SO_REUSEADDR 的 boolean 值。
抛出:
SocketException - 如果底层协议出现错误,例如 UDP 错误。
从以下版本开始:
1.4
另请参见:
setReuseAddress(boolean)

setBroadcast

public void setBroadcast(boolean on)
                  throws SocketException
启用/禁用 SO_BROADCAST。

参数:
on - 是否开启广播。
抛出:
SocketException - 如果底层协议出现错误,例如 UDP 错误。
从以下版本开始:
1.4
另请参见:
getBroadcast()

getBroadcast

public boolean getBroadcast()
                     throws SocketException
检测是否启用了 SO_BROADCAST。

返回:
指示是否启用 SO_BROADCAST 的 boolean 值。
抛出:
SocketException - 如果底层协议出现错误,例如 UDP 错误。
从以下版本开始:
1.4
另请参见:
setBroadcast(boolean)

setTrafficClass

public void setTrafficClass(int tc)
                     throws SocketException
为从此 DatagramSocket 上发送的数据报在 IP 数据报头中设置流量类别 (traffic class) 或服务类型八位组 (type-of-service octet)。由于底层网络实现可能忽略此值,应用程序应该将其视为一种提示。

tc 的值必须 0 <= tc <= 255 范围内,否则将抛出 IllegalArgumentException。

注:

对于 Internet Protocol v4 该值由包含优先级和 TOS 字段的八位组组成,这在 RFC 1349 中有详细叙述。TOS 字段是由以下逐位或所得值创建的位集:

末尾的最低位常常被忽略,因为该位对应于 MBZ(必须为 0)位。

设置优先级字段中的位可能导致 SocketException,指示不允许该操作。

对于 Internet Protocol v6 tc 是将被放置到 IP 头部的 sin6_flowinfo 字段中的值。

参数:
tc - 此位集的 int 值。
抛出:
SocketException - 如果设置流量类别或服务类型时出现错误
从以下版本开始:
1.4
另请参见:
getTrafficClass()

getTrafficClass

public int getTrafficClass()
                    throws SocketException
为从此 DatagramSocket 上发送的包获取 IP 数据报头中的流量类别或服务类型。

由于底层网络实现可能忽略使用 setTrafficClass(int) 设置的流量类别或服务类型,因而此方法可能返回一个不同于以前用 setTrafficClass(int) 在此 DatagramSocket 上设置的值。

返回:
已经设置的流量类别或服务类型
抛出:
SocketException - 如果获得流量类别或服务类型值时出现错误。
从以下版本开始:
1.4
另请参见:
setTrafficClass(int)

close

public void close()
关闭此数据报套接字。

在此套接字上 receive(java.net.DatagramPacket) 中所有当前阻塞的线程将会抛出 SocketException

如果此套接字有一个与之关联的通道,则关闭该通道。


isClosed

public boolean isClosed()
返回是否关闭了套接字。

返回:
如果已经关闭了套接字,则返回 true
从以下版本开始:
1.4

getChannel

public DatagramChannel getChannel()
返回与此数据报套接字关联的唯一 DatagramChannel 对象(如果有)。

当且仅当通过 DatagramChannel.open 方法创建了通道本身时,数据报套接字才具有一个通道。

返回:
与此数据报套接字关联的数据报通道,如果没有为通道创建套接字,则返回 null
从以下版本开始:
1.4

setDatagramSocketImplFactory

public static void setDatagramSocketImplFactory(DatagramSocketImplFactory fac)
                                         throws IOException
为应用程序设置数据报套接字实现工厂。工厂只能指定一次。

当应用程序创建新的数据报套接字时,调用套接字实现工厂的 createDatagramSocketImpl 方法创建实际的数据报套接字实现。

除非已经设置了工厂,否则向该方法传递 null 是无操作。

如果存在安全管理器,此方法首先调用安全管理器的 checkSetFactory 方法,确保允许该操作。这可能会导致 SecurityException 异常。

参数:
fac - 所需的工厂。
抛出:
IOException - 如果设置数据报套接字工厂时发生 I/O 错误。
SocketException - 如果已经定义该工厂。
SecurityException - 如果安全管理器存在并且其 checkSetFactory 方法不允许进行该操作。
从以下版本开始:
1.3
另请参见:
DatagramSocketImplFactory.createDatagramSocketImpl(), SecurityManager.checkSetFactory()

JavaTM 2 Platform
Standard Ed. 6

提交错误或意见
有关更多的 API 参考资料和开发人员文档,请参阅 Java 2 SDK SE 开发人员文档。该文档包含更详细的、面向开发人员的描述,以及总体概述、术语定义、使用技巧和工作代码示例。

版权所有 2004 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策