モジュール java.base

パッケージ java.io

クラスInputStream

java.lang.Object

java.io.InputStream

すべての実装されたインタフェース:

Closeable, AutoCloseable

直系の既知のサブクラス:

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

public abstract class InputStream extends Object implements Closeable

この抽象クラスは、バイト入力ストリームを表現するすべてのクラスのスーパー・クラスです。

InputStreamのサブクラスを定義する必要のあるアプリケーションは、必ず入力の次のバイトを返すメソッドを提供しなければなりません。

導入されたバージョン:

1.0

関連項目:

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

コンストラクタのサマリー

コンストラクタ

コンストラクタ	説明
InputStream()	サブクラスが呼び出すためのコンストラクタ。

メソッドのサマリー

修飾子と型	メソッド	説明
int	available()	ブロックせずにこの入力ストリームから(またはスキップ)を読み取ることができるバイト数の見積りを返します(0またはストリームの終わりが検出された場合は0)。
void	close()	この入力ストリームを閉じて、そのストリームに関連するすべてのシステム・リソースを解放します。
void	mark(int readlimit)	この入力ストリームの現在位置にマークを設定します。
boolean	markSupported()	この入力ストリームがmarkおよびresetメソッドをサポートしているかどうかを判定します。
static InputStream	nullInputStream()	バイトを読み取らない新しいInputStreamを返します。
abstract int	read()	入力ストリームからデータの次のバイトを読み込みます。
int	read(byte[] b)	入力ストリームから数バイトを読み込み、それをバッファ配列bに格納します。
int	read(byte[] b, int off, int len)	最大lenバイトのデータを、入力ストリームからバイト配列に読み込みます。
byte[]	readAllBytes()	残りのすべてのバイトを入力ストリームから読み込みます。
int	readNBytes(byte[] b, int off, int len)	リクエストされたバイト数を入力ストリームから指定されたバイト配列に読み込みます。
byte[]	readNBytes(int len)	入力ストリームから指定のバイト数まで読み取ります。
void	reset()	このストリームを、この入力ストリームで最後にmarkメソッドが呼び出されたときの位置に再配置します。
long	skip(long n)	この入力ストリームからnバイトのデータをスキップして破棄します。
void	skipNBytes(long n)	この入力ストリームからのデータのnバイトに正確にスキップし、破棄します。
long	transferTo(OutputStream out)	この入力ストリームからすべてのバイトを読み込んで、指定された出力ストリームに読み込まれた順序でバイトを書き込みます。

クラス java.lang.Objectで宣言されたメソッド

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

コンストラクタの詳細

InputStream

public InputStream()

サブクラスが呼び出すためのコンストラクタ。

メソッドの詳細

nullInputStream

public static InputStream nullInputStream()

バイトを読み取らない新しいInputStreamを返します。 返されるストリームは、最初はオープンしています。 ストリームを閉じるには、close()メソッドを呼び出します。 後からclose()をコールしても効果はありません。

ストリームが開いている間、available()、read()、read(byte[])、read(byte[], int, int)、readAllBytes()、readNBytes(byte[], int, int)、readNBytes(int)、skip(long)、skipNBytes(long)、およびtransferTo()の各メソッドは、ストリームの最後に達したかのように動作します。 ストリームが閉じられると、これらのメソッドはすべてIOExceptionをスローします。

markSupported()メソッドはfalseを返します。 mark()メソッドは何も行わず、reset()メソッドはIOExceptionをスローします。

戻り値:

バイトを含まないInputStream

導入されたバージョン:

11

read

public abstract int read() throws IOException

入力ストリームからデータの次のバイトを読み込みます。 バイト値は、0 - 255の範囲のintとして返されます。 ストリームの終わりに達したために読み込むバイトがない場合は、-1が返されます。 入力データが読み込めるようになるか、ストリームの終わりが検出されるか、または例外が発生するまで、このメソッドはブロックされます。

サブクラスは、このメソッドの実装を提供しなければなりません。

戻り値:

データの次のバイト。ストリームの終わりに達した場合は-1。

例外:

IOException - 入出力エラーが発生した場合。

read

public int read(byte[] b) throws IOException

入力ストリームから数バイトを読み込み、それをバッファ配列bに格納します。 実際に読み込まれたバイト数は整数として返されます。 このメソッドは、入力データが読み込めるようになるか、ファイルの終わりが検出されるか、あるいは例外がスローされるまでブロックします。

bの長さがゼロの場合、バイトは読み込まれず、0が返されます。それ以外の場合は、少なくとも1バイトを読み込もうとします。 ストリームがファイルの終わりに達したために読み込むバイトがない場合は値-1が返されます。そうでない場合は、少なくとも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 - ファイルの終わりに達していること以外の理由で最初のバイトを読み込めない場合、入力ストリームが閉じられた場合、またはその他の入出力エラーが発生した場合。

NullPointerException - bがnullである場合。

関連項目:

read(byte[], int, int)

read

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

最大lenバイトのデータを、入力ストリームからバイト配列に読み込みます。 lenバイトまでの読込みが試行されますが、読み込まれるバイト数はもっと少ない場合もあります。 実際に読み込まれたバイト数は整数として返されます。

このメソッドは、入力データが読み込めるようになるか、ファイルの終わりが検出されるか、あるいは例外がスローされるまでブロックします。

lenがゼロの場合、バイトは読み込まれず、0が返されます。それ以外の場合は、少なくとも1バイトを読み込もうとします。 ストリームがファイルの終わりに達したために読み込むバイトがない場合は値-1が返されます。それ以外の場合は、少なくとも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-1]までの要素とb[b.length-1]からの要素b[off+len]は影響を受けません。

InputStreamクラスのread(b, off, len)メソッドは、単純にread()メソッドを繰返し呼び出します。 そのような呼出しの最初の呼出しでIOExceptionが発生した場合、その例外はread(b, off, len)メソッドの呼び出しから返されます。 その後のread()の呼出し結果がIOExceptionになった場合は、ファイルの終わりに達した場合と同じように例外がキャッチされて処理されます。つまり、その時点までに読み込まれたバイトはbに格納され、例外が発生するまでに読み込まれたバイト数が返されます。 このメソッドのデフォルトの実装は、要求された量lenの入力データが読み込まれるか、ファイルの終わりが検出されるか、あるいは例外がスローされるまでブロックします。 サブクラスでこのメソッドを実装する場合は、より効率的に実装してください。

パラメータ:

b - データの読込み先のバッファ。

off - データが書き込まれる配列bの開始オフセット。

len - 読み込む最大バイト数。

戻り値:

バッファに読み込まれたバイトの合計数。ストリームの終わりに達してデータがない場合は-1。

例外:

IOException - ファイルの終わりに達していること以外の理由で最初のバイトを読み込めない場合、入力ストリームが閉じられた場合、またはその他の入出力エラーが発生した場合。

NullPointerException - bがnullである場合。

IndexOutOfBoundsException - offが負の値の場合、lenが負の値の場合、あるいはlenがb.length - offより大きい場合

関連項目:

read()

readAllBytes

public byte[] readAllBytes() throws IOException

残りのすべてのバイトを入力ストリームから読み込みます。 このメソッドは、残りのバイトがすべて読み込まれ、ストリームの終わりが検出されるか、または例外がスローされるまでブロックします。 このメソッドでは入力ストリームは閉じられません。

このストリームがストリームの終わりに達すると、このメソッドを呼び出すと空のバイト配列が返されます。

このメソッドが、すべてのバイトを1つのバイト配列に読み取ると都合が良い簡単なケースで使用するものであることに注意してください。 大量のデータを持つ入力ストリームを読み込むためのものではありません。

入力ストリームが「非同期クローズ」の場合、または読み込み中に割り込みが発生した場合の動作は、ストリーム固有の入力ストリームであり、したがって指定されていません。

入力ストリームからの読み込みでI/Oエラーが発生した場合は、すべてではなく一部のバイトが読み込まれた後でエラーが発生することがあります。 その結果、入力ストリームがストリームの終わりに配置されず、整合性のない状態になる可能性があります。 I/Oエラーが発生した場合は、ストリームを即座にクローズすることを強くお勧めします。

実装要件:

このメソッドは、Integer.MAX_VALUEの長さを持つreadNBytes(int)を起動します。

戻り値:

この入力ストリームから読み込まれたバイトを含むバイト配列

例外:

IOException - 入出力エラーが発生した場合

OutOfMemoryError - 必要なサイズの配列を割り当てることができない場合。

導入されたバージョン:

9

readNBytes

public byte[] readNBytes(int len) throws IOException

入力ストリームから指定のバイト数まで読み取ります。 このメソッドは、リクエストされたバイト数が読み取られるか、ストリームの終わりが検出されるか、または例外がスローされるまでブロックします。 このメソッドでは入力ストリームは閉じられません。

返される配列の長さは、ストリームから読み取られるバイト数と同じです。 lenが0の場合、バイトは読み取られず、空のバイト配列が返されます。 それ以外の場合、ストリームから最大lenバイトまでが読み取られます。 ストリームの終わりが検出されると、lenバイトよりも少ない確率で読み取られる可能性があります。

このストリームがストリームの終わりに達すると、このメソッドを呼び出すと空のバイト配列が返されます。

このメソッドは、指定されたバイト数をバイト配列に読み込むと簡単になるような場合に使用します。 このメソッドによって割り当てられるメモリーの合計量は、lenによってバインドされているストリームから読み取られたバイト数に比例します。 したがって、十分なメモリーが使用できる場合、メソッドは非常に大きな値のlenを使って安全に呼び出される可能性があります。

入力ストリームが「非同期クローズ」の場合、または読み込み中に割り込みが発生した場合の動作は、ストリーム固有の入力ストリームであり、したがって指定されていません。

入力ストリームからの読み込みでI/Oエラーが発生した場合は、すべてではなく一部のバイトが読み込まれた後でエラーが発生することがあります。 その結果、入力ストリームがストリームの終わりに配置されず、整合性のない状態になる可能性があります。 I/Oエラーが発生した場合は、ストリームを即座にクローズすることを強くお勧めします。

実装上のノート:

このストリームからデータを読み取って結果を戻すために割り当てられたバイト数は、2*(long)len (これを含む)で制限されます。

パラメータ:

len - 読み込む最大バイト数

戻り値:

この入力ストリームから読み込まれたバイトを含むバイト配列

例外:

IllegalArgumentException - lengthが負の場合

IOException - 入出力エラーが発生した場合

OutOfMemoryError - 必要なサイズの配列を割り当てることができない場合。

導入されたバージョン:

11

readNBytes

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

リクエストされたバイト数を入力ストリームから指定されたバイト配列に読み込みます。 このメソッドは、入力データのlenバイトが読み込まれるか、ストリームの終わりが検出されるか、または例外がスローされるまでブロックします。 実際に読み取られたバイト数(おそらくゼロ)が返されます。 このメソッドでは入力ストリームは閉じられません。

lenバイトが読み込まれる前にストリームの終わりに達した場合、実際に読み込まれたバイト数が返されます。 このストリームがストリームの終わりに達すると、このメソッドをさらに呼び出しても0が返されます。

lenがゼロの場合、バイトは読み取られず、0が返されます。それ以外の場合は、lenバイトまで読み込もうとしています。

読み込まれた最初のバイトは、要素b[off]に格納され、次のバイトはb[off+1]に格納されます。 読み込まれるバイト数の上限はlenと同じです。 実際に読み込まれたバイト数をkとします。これらのバイトは要素b[off]〜b[off+ k -1]に格納され、要素b[off+ k ]〜b[off+len-1]は影響を受けないままになります。

入力ストリームが「非同期クローズ」の場合、または読み込み中に割り込みが発生した場合の動作は、ストリーム固有の入力ストリームであり、したがって指定されていません。

I/Oエラーが入力ストリームから読み取られた場合、bの一部であるがすべてではないバイトが入力ストリームからのデータで更新された後に、I/Oエラーが発生する可能性があります。 その結果、入力ストリームとbは矛盾した状態になる可能性があります。 I/Oエラーが発生した場合は、ストリームを即座にクローズすることを強くお勧めします。

パラメータ:

b - データが読み込まれるバイト配列

off - データが書き込まれるbの開始オフセット

len - 読み込む最大バイト数

戻り値:

バッファに読み込まれる実際のバイト数

例外:

IOException - 入出力エラーが発生した場合

NullPointerException - bがnullである場合

IndexOutOfBoundsException - offが負の値の場合、lenが負の値の場合、あるいはlenがb.length - offより大きい場合

導入されたバージョン:

9

skip

public long skip(long n) throws IOException

この入力ストリームからnバイトのデータをスキップして破棄します。 さまざまな理由から、skipメソッドは指定よりも少ないバイト数しかスキップしないことがあります。0の場合もあります。 このスキップは複数の条件に起因する可能性がありますが、考えられる唯一の場合は、nバイトがスキップされる前にファイルの終わりに達した場合です。 スキップされた実際のバイト数が返されます。 nが負の場合、InputStreamクラスのskipメソッドは常に0を返し、バイトはスキップされません。 サブクラスは負の値を異なる方法で処理できます。

このクラスのskipメソッドの実装では、バイト配列が作成され、nバイトが読み込まれるかストリームの終わりに達するまで繰り返し読み込まれます。 サブクラスでこのメソッドを実装する場合は、より効率的に実装してください。 たとえば、実装はシークの機能に依存する可能性があります。

パラメータ:

n - スキップされるバイト数。

戻り値:

スキップされた実際のバイト数。ゼロになる可能性があります。

例外:

IOException - 入出力エラーが発生した場合。

関連項目:

skipNBytes(long)

skipNBytes

public void skipNBytes(long n) throws IOException

この入力ストリームからのデータのnバイトに正確にスキップし、破棄します。 nが0の場合、バイトはスキップされません。 nが負の場合、バイトはスキップされません。 サブクラスは負の値を異なる方法で処理できます。

このメソッドは、リクエストされたバイト数がスキップされるか、ファイルの終わりに到達するか、または例外がスローされるまでブロックします。

ストリームが所定の位置に到達する前にストリームの終わりに到達すると、EOFExceptionがスローされます。

I/Oエラーが発生した場合、入力ストリームの状態が矛盾している可能性があります。 I/Oエラーが発生した場合は、ストリームを即座にクローズすることを強くお勧めします。

実装要件:

nが0または負の場合、バイトはスキップされません。 nが正の場合、このメソッドのデフォルト実装は、リクエストされたバイト数がスキップされるか、エラー状態が発生するまで、スキップする残りのバイト数と等しいパラメータでskip()を繰り返し呼び出します。 いずれかの時点で、skip()の戻り値が負であるか、スキップされる残りのバイト数より大きい場合は、IOExceptionがスローされます。 skip()がゼロを返すと、read()が呼び出されてシングルバイトが読み取られ、-1が返されると、EOFExceptionがスローされます。 skip()またはread()によってスローされた例外はすべて伝播されます。

実装上のノート:

サブクラスでこのメソッドを実装する場合は、より効率的に実装してください。

パラメータ:

n - スキップされるバイト数。

例外:

EOFException - ストリームの終わりが検出された後で、このメソッドが呼び出されたときの位置よりnバイトが先に配置される場合。

IOException - ストリームを適切に配置できない場合や、I/Oエラーが発生した場合。

導入されたバージョン:

12

関連項目:

skip(long)

available

public int available() throws IOException

ブロックせずにこの入力ストリームから(またはスキップ)を読み取ることができるバイト数の見積りを返します(0またはストリームの終わりが検出された場合は0)。 この読取りは、同じスレッド上にあっても、別のスレッド上にあってもかまいません。 このような多数のバイトを1回で読み込んだりスキップしたりすることでブロックすることはありませんが、読み込むまたはスキップするバイト数が少なくなることがあります。

InputStreamの実装には、ストリームの合計バイト数を返すものもありますが、多くの実装は返さないことに注意してください。 このストリームのデータをすべて保持するためのバッファを割り当てるのに、このメソッドの戻り値を使用することは、適切ではありません。

このメソッドのサブクラス実装は、close()メソッドを呼び出してこの入力ストリームが閉じられた場合にIOExceptionをスローするように選択できます。

InputStreamのavailableメソッドは常に0を返します。

サブクラスはこのメソッドをオーバーライドする必要があります。

戻り値:

ブロックせずにこの入力ストリームから読み込むことができる(またはスキップできる)推定バイト数、または入力ストリームの終わりに達した場合は0。

例外:

IOException - 入出力エラーが発生した場合。

close

public void close() throws IOException

この入力ストリームを閉じて、そのストリームに関連するすべてのシステム・リソースを解放します。

InputStreamのcloseメソッドは何も行いません。

定義:

close、インタフェース: AutoCloseable

定義:

close、インタフェース: Closeable

例外:

IOException - 入出力エラーが発生した場合。

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メソッドの以降の呼出し側に供給されるバイトは、入力ストリームの特定のタイプに依存する。

InputStreamクラスのresetメソッドはIOExceptionをスローする以外何も行いません。

例外:

IOException - ストリームにマークが設定されていなかった場合、またはマークが無効になっていた場合。

関連項目:

mark(int)、IOException

markSupported

public boolean markSupported()

この入力ストリームがmarkおよびresetメソッドをサポートしているかどうかを判定します。 markおよびresetがサポートされているかどうかは、入力ストリーム・インスタンスごとに異なります。 InputStreamのmarkSupportedメソッドはfalseを返します。

戻り値:

このストリーム・インスタンスがmarkおよびresetメソッドをサポートしている場合はtrue、それ以外の場合はfalse。

関連項目:

mark(int), reset()

transferTo

public long transferTo(OutputStream out) throws IOException

この入力ストリームからすべてのバイトを読み込んで、指定された出力ストリームに読み込まれた順序でバイトを書き込みます。 戻り時に、この入力ストリームはストリームの終わりにあります。 このメソッドはいずれのストリームも閉じません。

このメソッドは、入力ストリームから無期限に読み込み、または出力ストリームに書き込むのをブロックすることがあります。 入力ストリームおよび/または出力ストリームが「非同期クローズ」であるか、または転送中に割り込みが発生した場合の動作は、入出力ストリーム固有のものであり、したがって指定されていません。

I/Oエラーが入力ストリームから読み取ったり、出力ストリームに書き込んだりすると、いくつかのバイトが読み書きされた後にエラーが発生する可能性があります。 その結果、入力ストリームはストリームの終わりになく、一方または両方のストリームは不整合な状態になる可能性があります。 I/Oエラーが発生した場合、両方のストリームを即時に閉じることを強くお勧めします。

パラメータ:

out - 出力ストリーム、非null

戻り値:

転送されたバイト数

例外:

IOException - 読み取りまたは書込み中に入出力エラーが発生した場合。

NullPointerException - outがnullである場合

導入されたバージョン:

9