モジュール 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バイトが読み取られる前にストリームの終わりに達した場合、実際の読取りバイト数が戻されます。 このストリームがストリームの最後に到達すると、このメソッドをさらに呼び出すとゼロが返されます。

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の一部(すべてではない)のバイトが入力ストリームからのデータで更新された後、これが実行される可能性があります。 したがって、入力ストリームと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をスローするように選択できます。

APIのノート:

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

実装要件:

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

戻り値:

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

例外:

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

close

public void close() throws IOException

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

定義:

close、インタフェースAutoCloseable

定義:

close、インタフェースCloseable

実装要件:

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

例外:

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

この入力ストリームからすべてのバイトを読み取り、指定された出力ストリームに読み込まれた順序でバイトを書き込みます。 戻り時に、この入力ストリームはストリームの最後にあります。 このメソッドはどちらのストリームもクローズしません。

このメソッドは、入力ストリームからの無期限の読取りまたは出力ストリームへの書込みをブロックできます。 入力ストリームまたは出力ストリーム(あるいはその両方)が「非同期クローズ」の場合、または転送中に中断されたスレッドの動作は、入力ストリームおよび出力ストリームに固有であるため、指定されません。

転送された合計バイト数がLong.MAX_VALUEより大きい場合、Long.MAX_VALUEが返されます。

入力ストリームからの読取りまたは出力ストリームへの書込み中にI/Oエラーが発生した場合は、一部のバイトの読取りまたは書込み後にエラーが発生する可能性があります。 したがって、入力ストリームがストリームの最後でない場合があり、ストリームの1つまたは両方が一貫性のない状態である可能性があります。 I/Oエラーが発生した場合は、両方のストリームをすぐに閉じることを強くお薦めします。

パラメータ:

out - 出力ストリーム、null以外

戻り値:

転送されたバイト数

例外:

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

NullPointerException - outがnullである場合

導入されたバージョン:

9