java.nio.channels
類別 SocketChannel

java.lang.Object
  java.nio.channels.spi.AbstractInterruptibleChannel
      java.nio.channels.SelectableChannel
          java.nio.channels.spi.AbstractSelectableChannel
              java.nio.channels.SocketChannel

所有已實作的介面：

Closeable, ByteChannel, Channel, GatheringByteChannel, InterruptibleChannel, ReadableByteChannel, ScatteringByteChannel, WritableByteChannel

public abstract class SocketChannel
extends AbstractSelectableChannel
implements ByteChannel, ScatteringByteChannel, GatheringByteChannel

針對導向串流的連接Socket的可選擇通道。

Socket通道不是連接網路Socket的完整抽象。必須通過調用 socket 方法所獲得的關聯 Socket 物件來完成對Socket選項的綁定、關閉和操作。不可能為任意的已有Socket創建通道，也不可能指定與Socket通道關聯的Socket所使用的 SocketImpl 物件。

通過調用此類別的某個 open 方法創建Socket通道。新創建的Socket通道已打開，但尚未連接。試圖在未連接的通道上調用 I/O 操作將導致拋出 NotYetConnectedException。可通過調用Socket通道的 connect 方法連接該通道；一旦連接後，關閉Socket通道之前它會一直保持已連接狀態。可通過調用Socket通道的 isConnected 方法來確定Socket通道是否已連接。

Socket通道支持非阻塞連接：可創建一個Socket通道，並且通過 connect 方法可以發起到遠端Socket的連接，之後通過 finishConnect 方法完成該連接。可通過調用 isConnectionPending 方法來確定是否正在進行連接操作。

可單獨地關閉 Socket通道的輸入端和輸出端，而無需實際關閉該通道。調用關聯Socket物件的 shutdownInput 方法來關閉某個通道的輸入端將導致該通道上的後續讀取操作返回 -1（指示串流的末尾）。調用關聯Socket物件的 shutdownOutput 方法來關閉通道的輸出端將導致該通道上的後續寫入操作拋出 ClosedChannelException。

Socket通道支持非同步關閉，這與 Channel 類別中所指定的非同步 close 操作類似。如果一個執行緒關閉了某個Socket的輸入端，而同時另一個執行緒被阻塞在該Socket通道上的讀取操作中，那麼處於阻塞執行緒中的讀取操作將完成，而不讀取任何位元組且返回 -1。I如果一個執行緒關閉了某個Socket的輸出端，而同時另一個執行緒被阻塞在該Socket通道上的寫入操作中，那麼阻塞執行緒將收到 AsynchronousCloseException。

多個共時執行緒可安全地使用Socket通道。儘管在任意給定時刻最多只能有一個執行緒進行讀取和寫入操作，但資料電報通道支持共時的讀寫。connect 和 finishConnect 方法是相互同步的，如果正在調用其中某個方法的同時試圖發起讀取或寫入操作，則在該調用完成之前該操作被阻塞。

從以下版本開始：

1.4

建構子摘要

protected

SocketChannel(SelectorProvider provider) 初始化此類別的一個新實例。

方法摘要

abstract boolean	connect(SocketAddress remote) 連接此通道的Socket。
abstract boolean	finishConnect() 完成Socket通道的連接過程。
abstract boolean	isConnected() 判斷是否已連接此通道的網路Socket。
abstract boolean	isConnectionPending() 判斷此通道上是否正在進行連接操作。
static SocketChannel	open() 打開Socket通道。
static SocketChannel	open(SocketAddress remote) 打開Socket通道並將其連接到遠端位址。
abstract int	read(ByteBuffer dst) 將位元組序列從此通道中讀入給定的緩衝區。
long	read(ByteBuffer[] dsts) 將位元組序列從此通道讀入給定的緩衝區。
abstract long	read(ByteBuffer[] dsts, int offset, int length) 將位元組序列從此通道讀入給定緩衝區的子序列中。
abstract Socket	socket() 獲取與此通道關聯的Socket。
int	validOps() 返回一個操作集，標識此通道所支持的操作。
abstract int	write(ByteBuffer src) 將位元組序列從給定的緩衝區中寫入此通道。
long	write(ByteBuffer[] srcs) 將位元組序列從給定的緩衝區寫入此通道。
abstract long	write(ByteBuffer[] srcs, int offset, int length) 將位元組序列從給定緩衝區的子序列寫入此通道。

從類別 java.nio.channels.spi.AbstractSelectableChannel 繼承的方法

blockingLock, configureBlocking, implCloseChannel, implCloseSelectableChannel, implConfigureBlocking, isBlocking, isRegistered, keyFor, provider, register

從類別 java.nio.channels.SelectableChannel 繼承的方法

register

從類別 java.nio.channels.spi.AbstractInterruptibleChannel 繼承的方法

begin, close, end, isOpen

從類別 java.lang.Object 繼承的方法

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

從介面 java.nio.channels.Channel 繼承的方法

close, isOpen

建構子詳細資訊

SocketChannel

protected SocketChannel(SelectorProvider provider)

初始化此類別的一個新實例。

方法詳細資訊

open

public static SocketChannel open()
                          throws IOException

打開Socket通道。

通過調用系統級預設 SelectorProvider 物件的 openSocketChannel 方法來創建新的通道。

返回：

新的Socket通道

拋出：

IOException - 如果發生 I/O 錯誤

open

public static SocketChannel open(SocketAddress remote)
                          throws IOException

打開Socket通道並將其連接到遠端位址。

這種便捷方法的工作方式就像以下過程一樣：調用 open() 方法、在得到的Socket通道上調用 connect 方法、向其傳遞 remote，然後返回該通道。

參數：

remote - 與新通道連接的遠端位址

拋出：

AsynchronousCloseException - 如果正在進行連接操作時另一個執行緒關閉了此通道

ClosedByInterruptException - 如果正在進行連接操作時另一個執行緒中斷了當前執行緒，因此關閉了該通道並將當前執行緒設置為中斷狀態

UnresolvedAddressException - 如果無法完全解析給定的遠端位址

UnsupportedAddressTypeException - 如果不支持給定的遠端位址型別

SecurityException - 如果已安裝安全管理器並且它不允許對給定遠端端點進行存取

IOException - 如果發生其他 I/O 錯誤

validOps

public final int validOps()

返回一個操作集，標識此通道所支持的操作。

Socket通道支持連接、讀取和寫入，所以此方法返回 (SelectionKey.OP_CONNECT | SelectionKey.OP_READ | SelectionKey.OP_WRITE)。

指定者：

類別 SelectableChannel 中的 validOps

返回：

有效操作集

socket

public abstract Socket socket()

獲取與此通道關聯的Socket。

返回的物件不會宣告任何在 Socket 類別中未宣告的公共方法。

返回：

與此通道關聯的Socket

isConnected

public abstract boolean isConnected()

判斷是否已連接此通道的網路Socket。

返回：

當且僅當已連接此通道的網路Socket時才返回 true

isConnectionPending

public abstract boolean isConnectionPending()

判斷此通道上是否正在進行連接操作。

返回：

當且僅當已在此通道上發起連接操作，但是尚未通過調用 finishConnect 方法完成連接時才返回 true

connect

public abstract boolean connect(SocketAddress remote)
                         throws IOException

連接此通道的Socket。

如果此通道處於非阻塞網要，則調用此方法會發起一個非阻塞連接操作。如果立即建立連接（使用本地連接時就是如此），則此方法返回 true。否則此方法返回 false，並且必須在以後通過調用 finishConnect 方法來完成該連接操作。

如果此通道處於阻塞網要，則在建立連接或發生 I/O 錯誤之前將阻塞此方法的調用。

此方法執行與 Socket 類別完全相同的安全檢查。也就是說，如果已安裝了安全管理器，則此方法驗證其 checkConnect 方法是否允許連接到給定遠端端點的位址和埠號號。

可在任意時間調用此方法。如果正在調用此方法時在此通道上調用讀取或寫入操作，則在此調用完成前將首先阻塞該操作。如果試圖發起連接但失敗了，也就是說如果調用此方法拋出經過檢查的異常，則關閉此通道。

參數：

remote - 與此通道連接的遠端位址

返回：

如果已建立連接，則返回 true，如果此通道處於非阻塞網要並且正在進行連接操作，則返回 false

拋出：

AlreadyConnectedException - 如果已連接此通道

ConnectionPendingException - 如果已在此通道上進行非阻塞連接操作

ClosedChannelException - 如果此通道已關閉

AsynchronousCloseException - 如果正在進行連接操作時另一個執行緒關閉了此通道

ClosedByInterruptException - 如果正在進行連接操作時另一個執行緒中斷了當前執行緒，因此關閉了該通道並將當前執行緒設置為中斷狀態

UnresolvedAddressException - 如果沒有完全解析給定的遠端位址

UnsupportedAddressTypeException - 如果不支持給定的遠端位址型別

SecurityException - 如果已安裝安全管理器並且它不允許對給定遠端端點進行存取

IOException - 如果發生其他 I/O 錯誤

finishConnect

public abstract boolean finishConnect()
                               throws IOException

完成Socket通道的連接過程。

通過將Socket通道置於非阻塞網要，然後調用其 connect 方法來發起非阻塞連接操作。一旦建立了連接，或者嘗試已失敗，該Socket通道就變為可連接的，並且可調用此方法完成連接序列。如果連接操作失敗，則調用此方法將導致拋出合適的 IOException。

如果已連接了此通道，則不阻塞此方法並且立即返回 true。如果此通道處於非阻塞網要，那麼當連接過程尚未完成時，此方法將返回 false。如果此通道處於阻塞網要，則在連接完成或失敗之前將阻塞此方法，並且總是返回 true 或拋出描述該失敗的、經過檢查的異常。

可在任意時間調用此方法。如果正在調用此方法時在此通道上調用讀取或寫入操作，則在此調用完成前將首先阻塞該操作。如果試圖發起連接但失敗了，也就是說如果調用此方法導致拋出經過檢查的異常，則關閉此通道。

返回：

當且僅當已連接此通道的Socket時才返回 true

拋出：

NoConnectionPendingException - 如果未連接此通道並且尚未發起連接操作

ClosedChannelException - 如果此通道已關閉

AsynchronousCloseException - 如果正在進行連接操作時另一個執行緒關閉了此通道

ClosedByInterruptException - 如果正在進行連接操作時另一個執行緒中斷了當前執行緒，因此關閉了該通道並將當前執行緒設置為中斷狀態

IOException - 如果發生其他 I/O 錯誤

read

public abstract int read(ByteBuffer dst)
                  throws IOException

從介面 ReadableByteChannel 複製的描述

將位元組序列從此通道中讀入給定的緩衝區。

嘗試最多從該通道中讀取 r 個位元組，其中 r 是調用此方法時緩衝區中剩餘的位元組數，即 dst.remaining()。

假定讀取的位元組序列長度為 n，其中 0 <= n <= r。此位元組序列將被傳輸到緩衝區中，序列中的第一個位元組位於索引 p 處，最後一個位元組則位於索引 p + n - 1 處，其中 p 是調用此方法時緩衝區的位置。返回時，該緩衝區的位置將等於 p + n；其限制不會更改。

讀取操作可能不填充緩衝區，實際上它可能根本不讀取任何位元組。是否如此執行取決於通道的性質和狀態。例如，處於非阻塞網要的Socket通道只能從該Socket的輸入緩衝區中讀取立即可用的位元組；類似地，檔案通道只能讀取檔案中剩餘的位元組。但是可以保證，如果某個通道處於阻塞網要，並且緩衝區中至少剩餘一個位元組，則在讀取至少一個位元組之前將阻塞此方法。

可在任意時間調用此方法。但是如果另一個執行緒已經在此通道上發起了一個讀取操作，則在該操作完成前此方法的調用被阻塞。

指定者：

介面 ReadableByteChannel 中的 read

參數：

dst - 要向其中傳輸位元組的緩衝區

返回：

讀取的位元組數，可能為零，如果該通道已到達串流的末尾，則返回 -1

拋出：

NotYetConnectedException - 如果尚未連接此通道

ClosedChannelException - 如果此通道已關閉

AsynchronousCloseException - 如果正在進行讀取操作時另一個執行緒關閉了此通道

ClosedByInterruptException - 如果正在進行讀取操作時另一個執行緒中斷了當前執行緒，因此關閉了該通道並將當前執行緒設置為中斷狀態

IOException - 如果發生其他 I/O 錯誤

read

public abstract long read(ByteBuffer[] dsts,
                          int offset,
                          int length)
                   throws IOException

從介面 ScatteringByteChannel 複製的描述

將位元組序列從此通道讀入給定緩衝區的子序列中。

調用此方法會嘗試最多從此通道讀取 r 個位元組，其中 r 是給定緩衝區陣列的指定子序列中剩餘的位元組數，也就是

 dsts[offset].remaining()
     + dsts[offset+1].remaining()
     + ... + dsts[offset+length-1].remaining()

假定讀取的位元組序列長度為 n，其中 0 <= n <= r。將此序列的前 dsts[offset].remaining() 個位元組傳輸到緩衝區 dsts[offset] 中，然後將後面的 dsts[offset+1].remaining() 個位元組傳輸到緩衝區 dsts[offset+1] 中，依此類別推，直到將整個位元組序列傳輸到給定緩衝區中。向每個緩衝區中傳輸盡可能多的位元組，因為要保證每個已更新緩衝區（最後一個已更新緩衝區除外）的最終位置等於該緩衝區的限制。

可在任意時間調用此方法。但是如果另一個執行緒已經在此通道上發起了一個讀取操作，則在該操作完成前此方法的調用被阻塞。

指定者：

介面 ScatteringByteChannel 中的 read

參數：

dsts - 要向其中傳輸位元組的緩衝區

offset - 第一個緩衝區（位元組傳輸到該緩衝區中）在緩衝區陣列中的偏移量；必須為非負數並且不能大於 dsts.length

length - 要存取的最大緩衝區數；必須為非負數並且不能大於 dsts.length - offset

返回：

讀取的位元組數，可能為零，如果該通道已到達串流的末尾，則返回 -1

拋出：

NotYetConnectedException - 如果尚未連接此通道

ClosedChannelException - 如果此通道已關閉

AsynchronousCloseException - 如果正在進行讀取操作時另一個執行緒關閉了此通道

ClosedByInterruptException - 如果正在進行讀取操作時另一個執行緒中斷了當前執行緒，因此關閉了該通道並將當前執行緒設置為中斷狀態

IOException - 如果發生其他 I/O 錯誤

read

public final long read(ByteBuffer[] dsts)
                throws IOException

從介面 ScatteringByteChannel 複製的描述

將位元組序列從此通道讀入給定的緩衝區。

調用此方法的形式為 c.read(dsts)，該調用與以下調用完全相同：

 c.read(dsts, 0,dsts.length);

指定者：

介面 ScatteringByteChannel 中的 read

參數：

dsts - 要向其中傳輸位元組的緩衝區

返回：

讀取的位元組數，可能為零，如果該通道已到達串流的末尾，則返回 -1

拋出：

NotYetConnectedException - 如果尚未連接此通道

ClosedChannelException - 如果此通道已關閉

AsynchronousCloseException - 如果正在進行讀取操作時另一個執行緒關閉了此通道

ClosedByInterruptException - 如果正在進行讀取操作時另一個執行緒中斷了當前執行緒，因此關閉了該通道並將當前執行緒設置為中斷狀態

IOException - 如果發生其他 I/O 錯誤

write

public abstract int write(ByteBuffer src)
                   throws IOException

從介面 WritableByteChannel 複製的描述

將位元組序列從給定的緩衝區中寫入此通道。

嘗試最多向該通道中寫入 r 個位元組，其中 r 是調用此方法時緩衝區中剩餘的位元組數，即 src.remaining()。

假定寫入長度為 n 的位元組序列，其中 0 <= n <= r。從緩衝區的索引 p 處開始傳輸該位元組，其中 p 是調用此方法時該緩衝區的位置；最後寫入的位元組索引是 p + n - 1。返回時，該緩衝區的位置將等於 p + n；其限制不會更改。

除非另行指定，否則僅在寫入所有請求的 r 個位元組後 write 操作才會返回。有些型別的通道（取決於它們的狀態）可能僅寫入某些位元組或者可能根本不寫入。例如，處於非阻塞網要的Socket通道只能寫入該Socket輸出緩衝區中的位元組。

可在任意時間調用此方法。但是如果另一個執行緒已經在此通道上發起了一個寫入操作，則在該操作完成前此方法的調用被阻塞。

指定者：

介面 WritableByteChannel 中的 write

參數：

src - 要從中獲取位元組的緩衝區

返回：

寫入的位元組數，可能為零

拋出：

NotYetConnectedException - 如果尚未連接此通道

ClosedChannelException - 如果此通道已關閉

AsynchronousCloseException - 如果正在進行寫入操作時另一個執行緒關閉了此通道

ClosedByInterruptException - 如果正在進行寫入操作時另一個執行緒中斷了當前執行緒，因此關閉了該通道並將當前執行緒的狀態設置為中斷

IOException - 如果發生其他 I/O 錯誤

write

public abstract long write(ByteBuffer[] srcs,
                           int offset,
                           int length)
                    throws IOException

從介面 GatheringByteChannel 複製的描述

將位元組序列從給定緩衝區的子序列寫入此通道。

嘗試最多向此通道中寫入 r 個位元組，其中 r 是給定緩衝區陣列的指定子序列中剩餘的位元組數，也就是

 srcs[offset].remaining()
     + srcs[offset+1].remaining()
     + ... + srcs[offset+length-1].remaining()

假定寫入長度為 n 的位元組序列，其中 0 <= n <= r。從緩衝區 srcs[offset] 中寫入此序列的前 srcs[offset].remaining() 個位元組，然後從緩衝區 srcs[offset+1] 中寫入後面的 srcs[offset+1].remaining() 個位元組，依此類別推，直到寫入整個位元組序列。從每個緩衝區中寫入盡可能多的位元組，因為要保證每個已更新緩衝區（最後一個已更新緩衝區除外）的最終位置等於該緩衝區的限制。

除非另行指定，否則僅在寫入所有請求的 r 個位元組後 write 操作才會返回。有些型別的通道（取決於它們的狀態）可能僅寫入某些位元組或者可能根本不寫入。例如，處於非阻塞網要的Socket通道無法寫入超出該Socket輸出緩衝區剩餘空間的位元組。

可在任意時間調用此方法。但是如果另一個執行緒已經在此通道上發起了一個寫入操作，則在該操作完成前此方法的調用被阻塞。

指定者：

介面 GatheringByteChannel 中的 write

offset - 第一個緩衝區（要獲取該緩衝區中的位元組）在緩衝區陣列中的偏移量；必須為非負數並且不能大於 srcs.length

length - 要存取的最大緩衝區數；必須為非負數並且不能大於 srcs.length - offset

返回：

寫入的位元組數，可能為零

拋出：

NotYetConnectedException - 如果尚未連接此通道

ClosedChannelException - 如果此通道已關閉

AsynchronousCloseException - 如果正在進行寫入操作時另一個執行緒關閉了此通道

ClosedByInterruptException - 如果正在進行寫入操作時另一個執行緒中斷了當前執行緒，因此關閉了該通道並將當前執行緒的狀態設置為中斷

IOException - 如果發生其他 I/O 錯誤

write

public final long write(ByteBuffer[] srcs)
                 throws IOException

從介面 GatheringByteChannel 複製的描述

將位元組序列從給定的緩衝區寫入此通道。

調用此方法的形式為 c.write(srcs) ，該調用與以下調用完全相同：

 c.write(srcs, 0, srcs.length);

指定者：

介面 GatheringByteChannel 中的 write

返回：

寫入的位元組數，可能為零

拋出：

NotYetConnectedException - 如果尚未連接此通道

ClosedChannelException - 如果此通道已關閉

AsynchronousCloseException - 如果正在進行寫入操作時另一個執行緒關閉了此通道

ClosedByInterruptException - 如果正在進行寫入操作時另一個執行緒中斷了當前執行緒，因此關閉了該通道並將當前執行緒的狀態設置為中斷

IOException - 如果發生其他 I/O 錯誤