Module  java.base
软件包  java.nio.channels

Class AsynchronousSocketChannel

  • All Implemented Interfaces:
    Closeable ， AutoCloseable ， AsynchronousByteChannel ， AsynchronousChannel ， Channel ， NetworkChannel 

    public abstract class AsynchronousSocketChannel
extends Object
implements AsynchronousByteChannel, NetworkChannel
    用于面向流的连接插座的异步通道。

    异步套接字通道以两种方式之一创建。 新创建的AsynchronousSocketChannel是通过调用此类定义的一个open方法创建的。 新创建的频道已打开但尚未连接。 A相连接AsynchronousSocketChannel当连接到的插座制成创建AsynchronousServerSocketChannel 。 不可能为任意的，预先存在的socket创建异步套接字通道。

    新创建的通道通过调用其connect方法进行连接; 一旦连接，通道保持连接，直到它被关闭。 是否连接套接字通道可以通过调用其getRemoteAddress方法来确定。 尝试在未连接的通道上调用I / O操作将导致抛出NotYetConnectedException 。

    这种类型的通道可以安全地被多个并发线程使用。 它们支持并发读写，但最多只能读取一次读写操作，一次写操作可以随时进行。 如果线程在先前的读取操作完成之前启动了读取操作，那么将抛出一个ReadPendingException 。 类似地，在前一次写入完成之前尝试启动写入操作将抛出一个WritePendingException 。

    套接字选项使用setOption方法进行配置。 异步套接字通道支持以下选项：

    Socket options
    Option Name 描述
    SO_SNDBUF The size of the socket send buffer
    SO_RCVBUF The size of the socket receive buffer
    SO_KEEPALIVE Keep connection alive
    SO_REUSEADDR Re-use address
    TCP_NODELAY Disable the Nagle algorithm
    还可以支持附加（实现特定）选项。

    超时

    此类定义的read和write方法允许在启动读取或写入操作时指定超时。 如果在操作完成之前经过了超时，则操作完成，异常InterruptedByTimeoutException 。 超时可能会使通道或底层连接处于不一致的状态。 在实现不能保证字节没有从通道读取的情况下，它将通道置于实现特定的错误状态 。 随后尝试启动read操作会导致未指定的运行时异常被抛出。 类似地，如果write操作超时，并且实现不能保证字节尚未写入通道，则进一步尝试write通道发送write会导致未指定的运行时异常被抛出。 当超时过后，则不会定义用于I / O操作的ByteBuffer或缓冲区序列的状态。 应该丢弃缓冲区，或者至少要小心，以确保在通道保持打开状态时缓冲区不被访问。 接受超时参数的所有方法都将小于或等于0的值表示为I / O操作不超时。

    从以下版本开始：
    1.7

    • 构造方法详细信息

      • AsynchronousSocketChannel

        protected AsynchronousSocketChannel​(AsynchronousChannelProvider provider)
        初始化此类的新实例。
        参数
        provider - 创建此频道的提供商

    • 方法详细信息

      • provider

        public final AsynchronousChannelProvider provider​()
        返回创建此通道的提供程序。
        结果
        创建此频道的提供商

      • open

        public static AsynchronousSocketChannel open​()
                                      throws IOException
        打开异步套接字通道。

        此方法返回绑定到默认组的异步套接字通道。此方法等效于评估表达式： 

         open((AsynchronousChannelGroup)null);
        结果
        一个新的异步套接字通道
        异常
        IOException - 如果发生I / O错误

      • shutdownInput

        public abstract AsynchronousSocketChannel shutdownInput​()
                                                 throws IOException
        关闭连接进行阅读，不关闭频道。

        一旦关闭读取，则通道上的进一步读取将返回-1 ，流末端指示。 如果连接的输入端已经关闭，则调用此方法没有任何作用。 对未完成的读取操作的影响是系统依赖的，因此未指定。 如果有的话，如果套接字接收缓冲区中尚未读取数据或数据到达的影响，也是系统依赖的。

        结果
        这个频道
        异常
        NotYetConnectedException - 如果此通道尚未连接
        ClosedChannelException - 如果此频道关闭
        IOException - 如果发生其他I / O错误

      • getRemoteAddress

        public abstract SocketAddress getRemoteAddress​()
                                        throws IOException
        返回此通道的插座所连接的远程地址。

        通道绑定并连接到Internet协议套接字地址时，此方法的返回值为InetSocketAddress 。

        结果
        远程地址; null如果通道的插座未连接
        异常
        ClosedChannelException - 如果通道关闭
        IOException - 如果发生I / O错误

      • connect

        public abstract <A> void connect​(SocketAddress remote,
                                 A attachment,
                                 CompletionHandler<Void,? super A> handler)
        连接此频道。

        此方法启动连接此通道的操作。 handler参数是一个完成处理程序，在连接成功建立或无法建立连接时调用。 如果无法建立连接，则通道关闭。

        该方法执行与Socket类完全相同的安全检查。 也就是说，如果安装了一个安全管理器，则该方法验证其checkConnect方法是否允许连接到给定远程端点的地址和端口号。

        参数类型
        A - 附件的类型
        参数
        remote - 要连接该通道的远程地址
        attachment - 要附加到I / O操作的对象; 可以是null
        handler - 消费结果的处理程序
        异常
        UnresolvedAddressException - 如果给定的远程地址未完全解析
        UnsupportedAddressTypeException - 如果不支持给定远程地址的类型
        AlreadyConnectedException - 如果此频道已连接
        ConnectionPendingException - 如果此通道上已经进行了连接操作
        ShutdownChannelGroupException - 如果通道组已终止
        SecurityException - 如果已安装安全管理器，并且不允许访问给定的远程端点
        另请参见：
        getRemoteAddress()

      • read

        public abstract <A> void read​(ByteBuffer dst,
                              long timeout,
                              TimeUnit unit,
                              A attachment,
                              CompletionHandler<Integer,? super A> handler)
        从该通道读取到给定缓冲区的字节序列。

        该方法启动异步读取操作，以从该通道读取到给定缓冲器中的字节序列。 handler参数是一个完成处理程序，在读取操作完成（或失败）时调用该处理程序。 传递给完成处理程序的结果是读取的字节数或-1如果没有字节可以读取，因为通道已经到达流终止。

        如果指定了超时，并且在操作完成之前超时，则操作将完成，异常InterruptedByTimeoutException 。 在发生超时的情况下，实现不能保证字节未被读取，或者不会从通道读入给定的缓冲区，所以进一步尝试从通道中读取将导致抛出非特定的运行时异常。

        否则该方法的工作方式与AsynchronousByteChannel.read(ByteBuffer,Object,CompletionHandler)方法相同。

        参数类型
        A - 附件的类型
        参数
        dst - 要传输字节的缓冲区
        timeout - 完成I / O操作的最长时间
        unit - timeout参数的时间单位
        attachment - 要附加到I / O操作的对象; 可以是null
        handler - 消费结果的处理程序
        异常
        IllegalArgumentException - 如果缓冲区是只读的
        ReadPendingException - 如果此通道上的读取操作已在进行中
        NotYetConnectedException - 如果此频道尚未连接
        ShutdownChannelGroupException - 如果通道组已终止

      • read

        public final <A> void read​(ByteBuffer dst,
                           A attachment,
                           CompletionHandler<Integer,? super A> handler)
        说明从接口AsynchronousByteChannel复制
        从该通道读取到给定缓冲区的字节序列。

        该方法启动异步读取操作，以从该通道读取到给定缓冲器中的字节序列。 handler参数是一个完成处理程序，在读取操作完成（或失败）时调用该处理程序。 传递给完成处理程序的结果是读取的字节数或-1如果没有字节可以读取，因为通道已经到达流终止。

        读取操作可以从通道读取r个字节，其中r是缓冲区中剩余的字节数，即在尝试读取时为dst.remaining() 。 其中r为0，读操作立即完成，结果为0而不启动I / O操作。

        假设长度为n的字节序列被读出，其中0 < Ñ <= 河 该字节序列将被转移到缓冲器，使得序列中的第一个字节是在索引p和最后一个字节是在索引p + Ñ - 1 ，其中p为缓冲区的位置在执行读取的时刻。 完成后，缓冲区的位置将等于p + n ; 其限制将不会改变。

        缓冲区不能安全地被多个并发线程使用，因此在操作完成之前，请注意不要访问缓冲区。

        可以随时调用此方法。 某些渠道类型在任何给定时间可能不允许多于一个读取。 如果线程在先前的读取操作完成之前启动了读取操作，那么将抛出一个ReadPendingException 。

        Specified by:
        read在接口 AsynchronousByteChannel
        参数类型
        A - 附件的类型
        参数
        dst - 要传输字节的缓冲区
        attachment - 要附加到I / O操作的对象; 可以是null
        handler - 完成处理程序
        异常
        IllegalArgumentException - 如果缓冲区是只读的
        ReadPendingException - 如果通道不允许多个读取未完成，并且以前的读取尚未完成
        NotYetConnectedException - 如果此频道尚未连接
        ShutdownChannelGroupException - 如果通道组已终止

      • read

        public abstract <A> void read​(ByteBuffer[] dsts,
                              int offset,
                              int length,
                              long timeout,
                              TimeUnit unit,
                              A attachment,
                              CompletionHandler<Long,? super A> handler)
        从该通道读取字节序列到给定缓冲区的子序列中。 这种操作（有时称为散射读取 ）通常在实现将数据分组成由一个或多个固定长度的标题后跟可变长度主体组成的段的网络协议时很有用。 handler参数是一个完成处理程序，在读取操作完成（或失败）时调用该处理程序。 传递给完成处理程序的结果是读取的字节数或-1如果没有字节可以读取，因为通道已达到流出尾。

        该方法从该通道开始读取最多r个字节，其中r是给定缓冲区数组的指定子序列中剩余的总字节数，也就是说， 

         dsts[offset].remaining()
     + dsts[offset+1].remaining()
     + ... + dsts[offset+length-1].remaining()
        在尝试阅读的时刻。

        假设长度为n的字节序列被读出，其中0 < Ñ <= 河 该序列的最初dsts[offset].remaining()个字节被传送到缓冲区dsts[offset] ，直到下一个dsts[offset+1].remaining()字节被传送到缓冲区dsts[offset+1]等等，直到整个字节序列被传送到给定的缓冲区。 尽可能多的字节被传送到每个缓冲器中，因此除了最后更新的缓冲器之外，每个更新的缓冲器的最终位置被保证等于该缓冲器的限制。 底层操作系统可能对可能在I / O操作中使用的缓冲区数量施加限制。 当缓冲区的数量（剩余字节数）超过此限制时，I / O操作将由操作系统允许的最大缓冲区数来执行。

        如果指定了超时，并且操作完成之前超时已过，则完成异常InterruptedByTimeoutException 。 在发生超时的情况下，实现不能保证字节未被读取，或者不会从通道读入给定的缓冲区，所以进一步尝试从通道中读取将导致抛出非特定的运行时异常。

        参数类型
        A - 附件的类型
        参数
        dsts - 要传输字节的缓冲区
        offset - 要传输字节的第一个缓冲区的缓冲区数组中的偏移量; 必须是非负数，不得大于dsts.length
        length - 要访问的缓冲区的最大数量; 必须是非负数，不得大于dsts.length - offset
        timeout - 完成I / O操作的最长时间
        unit - timeout参数的时间单位
        attachment - 要附加到I / O操作的对象; 可以是null
        handler - 消费结果的处理程序
        异常
        IndexOutOfBoundsException - 如果不符合 offset和 length参数的前提条件
        IllegalArgumentException - 如果缓冲区是只读的
        ReadPendingException - 如果此通道上的读取操作已在进行中
        NotYetConnectedException - 如果此通道尚未连接
        ShutdownChannelGroupException - 如果通道组已终止

      • write

        public abstract <A> void write​(ByteBuffer src,
                               long timeout,
                               TimeUnit unit,
                               A attachment,
                               CompletionHandler<Integer,? super A> handler)
        从给定的缓冲区向该通道写入一个字节序列。

        该方法启动异步写入操作，以从给定的缓冲区向该通道写入字节序列。 handler参数是在写操作完成（或失败）时调用的完成处理程序。 传递给完成处理程序的结果是写入的字节数。

        如果指定了超时，并且操作完成之前超时已过，则完成异常InterruptedByTimeoutException 。 在发生超时的情况下，实现不能保证字节未被写入或不会从给定缓冲区写入通道，所以进一步尝试写入通道将导致抛出非特定的运行时异常。

        否则，此方法的工作方式与AsynchronousByteChannel.write(ByteBuffer,Object,CompletionHandler)方法相同。

        参数类型
        A - 附件的类型
        参数
        src - 要检索字节的缓冲区
        timeout - 完成I / O操作的最长时间
        unit - timeout参数的时间单位
        attachment - 要附加到I / O操作的对象; 可以是null
        handler - 消费结果的处理程序
        异常
        WritePendingException - 如果此通道上的写操作已在进行中
        NotYetConnectedException - 如果此通道尚未连接
        ShutdownChannelGroupException - 如果通道组已经终止

      • write

        public final <A> void write​(ByteBuffer src,
                            A attachment,
                            CompletionHandler<Integer,? super A> handler)
        说明从界面AsynchronousByteChannel复制
        从给定的缓冲区向该通道写入一个字节序列。

        该方法启动异步写入操作，以从给定的缓冲区向该通道写入字节序列。 handler参数是在写操作完成（或失败）时调用的完成处理程序。 传递给完成处理程序的结果是写入的字节数。

        写入操作可以写入r字节到通道，其中r是缓冲区中剩余的字节数，即在尝试写入时的src.remaining() 。 其中r为0，写操作立即完成，结果为0而不启动I / O操作。

        假设长度为n的字节序列写入，其中0 < Ñ <= 河 该字节序列将从索引p开始从缓冲区传送，其中p是执行写入时的缓冲区的位置; 写入的最后一个字节的索引将为p + n - 1 。 完成后，缓冲区的位置将等于p + n ; 其限制将不会改变。

        缓冲区不能安全地被多个并发线程使用，因此在操作完成之前，请注意不要访问缓冲区。

        可以随时调用此方法。 某些频道类型可能不允许在任何给定时间多出一个写入。 如果线程在先前写入操作完成之前启动写入操作，那么将抛出一个WritePendingException 。

        Specified by:
        write在接口 AsynchronousByteChannel
        参数类型
        A - 附件的类型
        参数
        src - 要检索字节的缓冲区
        attachment - 要附加到I / O操作的对象; 可以是null
        handler - 完成处理程序对象
        异常
        WritePendingException - 如果通道不允许多个写入未完成，并且以前的写入尚未完成
        NotYetConnectedException - 如果此频道尚未连接
        ShutdownChannelGroupException - 如果通道组已经终止

      • write

        public abstract <A> void write​(ByteBuffer[] srcs,
                               int offset,
                               int length,
                               long timeout,
                               TimeUnit unit,
                               A attachment,
                               CompletionHandler<Long,? super A> handler)
        从给定缓冲区的子序列将一个字节序列写入该通道。 这种操作（有时称为采集写入 ）通常用于实现将数据分组到由一个或多个固定长度的标题后跟可变长度主体组成的段的网络协议。 handler参数是在写操作完成（或失败）时调用的完成处理程序。 传递给完成处理程序的结果是写入的字节数。

        该方法启动对该通道的最多r个字节的写入，其中r是给定缓冲区数组的指定子序列中剩余的总字节数，也就是说， 

         srcs[offset].remaining()
     + srcs[offset+1].remaining()
     + ... + srcs[offset+length-1].remaining()
        在尝试写入的时刻。

        假设写入长度为n的字节序列，其中0 < n <= r 。 直到该序列的第一个srcs[offset].remaining()字节从缓冲器srcs[offset]写入，直到下一个srcs[offset+1].remaining()字节从缓冲器srcs[offset+1]写入，等等，直到整个字节序列被写入。 尽可能多的字节从每个缓冲区写入，因此除了最后更新的缓冲区之外，每个更新的缓冲区的最终位置被保证等于该缓冲区的限制。 底层操作系统可能对可能在I / O操作中使用的缓冲区数量施加限制。 当缓冲区的数量（剩余字节数）超过此限制时，I / O操作将由操作系统允许的最大缓冲区数来执行。

        如果指定了超时，并且操作完成之前超时已过，则完成异常InterruptedByTimeoutException 。 在发生超时的情况下，实现不能保证字节未被写入，或者不会从给定的缓冲区写入通道，所以进一步尝试写入通道将导致抛出非特定的运行时异常。

        参数类型
        A - 附件的类型
        参数
        srcs - 要检索字节的缓冲区
        offset - 要检索字节的第一个缓冲区的缓冲区数组中的偏移量; 必须是非负数，不得大于srcs.length
        length - 要访问的缓冲区的最大数量; 必须是非负数，不得大于srcs.length - offset
        timeout - 完成I / O操作的最长时间
        unit - timeout参数的时间单位
        attachment - 要附加到I / O操作的对象; 可以是null
        handler - 消费结果的处理程序
        异常
        IndexOutOfBoundsException - 如果不符合 offset和 length参数的前提条件
        WritePendingException - 如果此通道上的写操作已经进行中
        NotYetConnectedException - 如果此频道尚未连接
        ShutdownChannelGroupException - 如果通道组已经终止

      • getLocalAddress

        public abstract SocketAddress getLocalAddress​()
                                       throws IOException
        返回此通道的套接字所绑定的套接字地址。

        通道为Internet协议套接字地址的bound ，则此方法的返回值为InetSocketAddress 。

        如果有一个安全管理器设置，它的checkConnect方法被调用本地地址和-1作为参数来查看是否允许该操作。 如果不允许操作，则SocketAddress表示loopback地址的SocketAddress和通道套接字的本地端口。

        Specified by:
        getLocalAddress在接口 NetworkChannel
        结果
        该 SocketAddress的套接字绑定到，或 SocketAddress代表的环回地址，如果安全管理器拒绝，或者 null如果通道的套接字不绑定
        异常
        ClosedChannelException - 如果通道关闭
        IOException - If an I/O error occurs