java.io
類別 InputStream

java.lang.Object
  java.io.InputStream

所有已實作的介面：

Closeable

直接已知子類別：

AudioInputStream, ByteArrayInputStream, FileInputStream, FilterInputStream, InputStream, ObjectInputStream, PipedInputStream, SequenceInputStream, StringBufferInputStream

public abstract class InputStream
extends Object
implements Closeable

此抽象類別是表示位元組輸入串流的全部類別的父級類別。

需要定義 InputStream 子類別的應用程序必須總是提供返回下一個輸入位元組的方法。

從以下版本開始：

JDK1.0

另請參見：

BufferedInputStream, ByteArrayInputStream, DataInputStream, FilterInputStream, read(), OutputStream, PushbackInputStream

建構子摘要

InputStream()

方法摘要

int	available() 返回此輸入串流下一個方法調用可以不受阻塞地從此輸入串流讀取（或跳過）的估計位元組數。
void	close() 關閉此輸入串流並釋放與該串流關聯的所有系統資源。
void	mark(int readlimit) 在此輸入串流中標記當前的位置。
boolean	markSupported() 測試此輸入串流是否支持 mark 和 reset 方法。
abstract int	read() 從輸入串流中讀取資料的下一個位元組。
int	read(byte[] b) 從輸入串流中讀取一定數量的位元組，並將其存儲在緩衝區陣列 b 中。
int	read(byte[] b, int off, int len) 將輸入串流中最多 len 個資料位元組讀入 byte 陣列。
void	reset() 將此串流重新定位到最後一次對此輸入串流調用 mark 方法時的位置。
long	skip(long n) 跳過和丟棄此輸入串流中資料的 n 個位元組。

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

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

建構子詳細資訊

InputStream

public InputStream()

方法詳細資訊

read

public abstract int read()
                  throws IOException

從輸入串流中讀取資料的下一個位元組。返回 0 到 255 範圍內的 int 位元組值。如果因為已經到達串流末尾而沒有可用的位元組，則返回值 -1。在輸入資料可用、檢測到串流末尾或者拋出異常前，此方法一直阻塞。

子類別必須提供此方法的一個實作。

返回：

下一個資料位元組；如果到達串流的末尾，則返回 -1。

拋出：

IOException - 如果發生 I/O 錯誤。

read

public int read(byte[] b)
         throws IOException

從輸入串流中讀取一定數量的位元組，並將其存儲在緩衝區陣列 b 中。以整數形式返回實際讀取的位元組數。在輸入資料可用、檢測到檔案末尾或者拋出異常前，此方法一直阻塞。

如果 b 的長度為 0，則不讀取任何位元組並返回 0；否則，嘗試讀取至少一個位元組。如果因為串流位於檔案末尾而沒有可用的位元組，則返回值 -1；否則，至少讀取一個位元組並將其存儲在 b 中。

將讀取的第一個位元組存儲在元素 b[0] 中，下一個存儲在 b[1] 中，依次類別推。讀取的位元組數最多等於 b 的長度。設 k 為實際讀取的位元組數；這些位元組將存儲在 b[0] 到 b[k-1] 的元素中，不影響 b[k] 到 b[b.length-1] 的元素。

類別 InputStream 的 read(b) 方法的效果等同於：

 read(b, 0, b.length) 

參數：

b - 存儲讀入資料的緩衝區。

返回：

讀入緩衝區的總位元組數；如果因為已經到達串流末尾而不再有資料可用，則返回 -1。

拋出：

IOException - 如果不是因為串流位於檔案末尾而無法讀取第一個位元組；如果輸入串流已關閉；如果發生其他 I/O 錯誤。

NullPointerException - 如果 b 為 null。

另請參見：

read(byte[], int, int)

read

public int read(byte[] b,
                int off,
                int len)
         throws IOException

將輸入串流中最多 len 個資料位元組讀入 byte 陣列。嘗試讀取 len 個位元組，但讀取的位元組也可能小於該值。以整數形式返回實際讀取的位元組數。

在輸入資料可用、檢測到串流末尾或者拋出異常前，此方法一直阻塞。

如果 len 為 0，則不讀取任何位元組並返回 0；否則，嘗試讀取至少一個位元組。如果因為串流位於檔案末尾而沒有可用的位元組，則返回值 -1；否則，至少讀取一個位元組並將其存儲在 b 中。

將讀取的第一個位元組存儲在元素 b[off] 中，下一個存儲在 b[off+1] 中，依次類別推。讀取的位元組數最多等於 len。設 k 為實際讀取的位元組數；這些位元組將存儲在 b[off] 到 b[off+k-1] 的元素中，不影響 b[off+k] 到 b[off+len-1] 的元素。

在任何情況下，b[0] 到 b[off] 的元素以及 b[off+len] 到 b[b.length-1] 的元素都不會受到影響。

類別 InputStream 的 read(b, off, len) 方法重複調用方法 read()。如果第一次這樣的調用導致 IOException，則從對 read(b, off, len) 方法的調用中返回該異常。如果對 read() 的任何後續調用導致 IOException，則捕獲該異常並將其視為到達檔案末尾；到達該點時讀取的位元組存儲在 b 中，並返回發生異常之前讀取的位元組數。在已讀取輸入資料 len 的請求數量、檢測到檔案結束標記、拋出異常前，此方法的預設實作將一直阻塞。建議子類別提供此方法更為有效的實作。

參數：

b - 讀入資料的緩衝區。

off - 陣列 b 中將寫入資料的初始偏移量。

len - 要讀取的最大位元組數。

返回：

讀入緩衝區的總位元組數；如果因為已到達串流末尾而不再有資料可用，則返回 -1。

拋出：

IOException - 如果不是因為位於檔案末尾而無法讀取第一個位元組；如果輸入串流已關閉；如果發生其他 I/O 錯誤。

NullPointerException - 如果 b 為 null。

IndexOutOfBoundsException - 如果 off 為負，len 為負，或者 len 大於 b.length - off

另請參見：

read()

skip

public long skip(long n)
          throws IOException

跳過和丟棄此輸入串流中資料的 n 個位元組。出於各種原因，skip 方法結束時跳過的位元組數可能小於該數，也可能為 0。導致這種情況的原因很多，跳過 n 個位元組之前已到達檔案末尾只是其中一種可能。返回跳過的實際位元組數。如果 n 為負，則不跳過任何位元組。

此類別的 skip 方法創建一個 byte 陣列，然後重複將位元組讀入其中，直到讀夠 n 個位元組或已到達串流末尾為止。建議子類別提供此方法更為有效的實作。例如，可依賴搜尋能力的實作。

參數：

n - 要跳過的位元組數。

返回：

跳過的實際位元組數。

拋出：

IOException - 如果串流不支持搜尋，或者發生其他 I/O 錯誤。

available

public int available()
              throws IOException

返回此輸入串流下一個方法調用可以不受阻塞地從此輸入串流讀取（或跳過）的估計位元組數。下一個調用可能是同一個執行緒，也可能是另一個執行緒。一次讀取或跳過此估計數個位元組不會受阻塞，但讀取或跳過的位元組數可能小於該數。

注意，有些 InputStream 的實作將返回串流中的位元組總數，但也有很多實作不會這樣做。試圖使用此方法的返回值分派緩衝區，以保存此串流所有資料的做法是不正確的。

如果已經調用 close() 方法關閉了此輸入串流，那麼此方法的子類別實作可以選擇拋出 IOException。

類別 InputStream 的 available 方法總是返回 0。

此方法應該由子類別覆寫。

返回：

可以不受阻塞地從此輸入串流讀取（或跳過）的估計位元組數；如果到達輸入串流末尾，則返回 0。

拋出：

IOException - 如果發生 I/O 錯誤。

close

public void close()
           throws IOException

關閉此輸入串流並釋放與該串流關聯的所有系統資源。

InputStream 的 close 方法不執行任何操作。

指定者：

介面 Closeable 中的 close

拋出：

IOException - 如果發生 I/O 錯誤。

mark

public void mark(int readlimit)

在此輸入串流中標記當前的位置。對 reset 方法的後續調用會在最後標記的位置重新定位此串流，以便後續讀取重新讀取相同的位元組。

readlimit 參數告知此輸入串流在標記位置失效之前允許讀取的位元組數。

mark 的常規協定是：如果方法 markSupported 返回 true，那麼輸入串流總是在調用 mark 之後記錄所有讀取的位元組，並時刻準備在調用方法 reset 時（無論何時），再次提供這些相同的位元組。但是，如果在調用 reset 之前可以從串流中讀取多於 readlimit 的位元組，則不需要該串流記錄任何資料。

標記已關閉的串流對其無效。

InputStream 的 mark 方法不執行任何操作。

參數：

readlimit - 在標記位置失效前可以讀取位元組的最大限制。

另請參見：

reset()

reset

public void reset()
           throws IOException

將此串流重新定位到最後一次對此輸入串流調用 mark 方法時的位置。

reset 的常規協定是：

• 如果方法 markSupported 返回 true，那麼：
  • 如果創建串流以後未調用方法 mark，或最後調用 mark 以後從該串流讀取的位元組數大於最後調用 mark 時的參數，則可能拋出 IOException。
  • 如果未拋出這樣的 IOException，則將該串流重新設置為這種狀態：最近一次調用 mark 以後（如果未調用過 mark，則從檔案開頭開始）讀取的所有位元組將重新提供給 read 方法的後續調用者，後跟任何從調用 reset 時起將作為下一輸入資料的位元組。
• 如果方法 markSupported 返回 false，那麼：
  • 對 reset 的調用可能拋出 IOException。
  • 如果未拋出 IOException，則將該串流重新設置為一種固定狀態，該狀態取決於輸入串流的特定型別及其創建方式。提供給 read 方法後續調用者的位元組取決於特定型別的輸入串流。

除了拋出 IOException 之外，類別 InputStream 的方法 reset 不執行任何操作。

拋出：

IOException - 如果未標記此串流或該標記失效。

另請參見：

mark(int), IOException

markSupported

public boolean markSupported()

測試此輸入串流是否支持 mark 和 reset 方法。是否支持 mark 和 reset 是特定輸入串流實例的不變屬性。InputStream 的 markSupported 方法返回 false。

返回：

如果此輸入串流實例支持 mark 和 reset 方法，則返回 true；否則返回 false。

另請參見：

mark(int), reset()