java.nio

クラス Buffer

java.lang.Object

java.nio.Buffer

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

ByteBuffer, CharBuffer, DoubleBuffer, FloatBuffer, IntBuffer, LongBuffer, ShortBuffer

public abstract class Buffer
extends Object

特定のプリミティブ型データのコンテナです。

バッファーは、特定のプリミティブ型要素のリニアで有限のシーケンスです。内容のほかに、容量、リミット、位置という必須プロパティーがあります。

「容量」は、そのバッファーに含まれる要素数によって決定されます。容量の値は固定で、必ず正の値になります。

「リミット」は、読み込みまたは書き込みを行なってはならない最初の要素のインデックスです。容量以下の正の値になります。

「位置」は、次に読み込みまたは書き込みを行う要素のインデックスです。リミット以下の正の値になります。

非ブール型のプリミティブ型には、このクラスのサブクラスが 1 つずつ割り当てられています。

データの転送

このクラスのサブクラスは、それぞれ次の 2 つのカテゴリに該当する「get」操作および「put」操作を定義します。

「相対」操作。現在位置から 1 個以上の要素の読み込みまたは書き込みを行い、転送された要素の数だけ位置を増加します。要求された転送がリミットを超える場合、相対「get」操作は BufferUnderflowException を、相対「put」操作は BufferOverflowException をスローします。どちらの場合も、データは一切転送されません。

「絶対」操作。明示的な要素インデックスを使用するため、位置は変化しません。インデックス引数がリミットを超える場合、絶対「get」操作および「put」操作は IndexOutOfBoundsException をスローします。

適切なチャネルの入出力操作を行えば、データの転送 (バッファーとのやりとり) は可能です。この操作は、常に現在位置に対して相対的に行われます。

マークとリセット

バッファーの「マーク」は、reset メソッドを呼び出したときに戻る位置を指定するインデックスです。定義されていない場合もありますが、定義されている場合は必ず位置以下の正の値になります。位置やリミットの値がマークの値よりも小さい場合、マークは破棄されます。マークが定義されていない場合、reset メソッドを呼び出すと、InvalidMarkException がスローされます。

インバリアント (不変式)

次のインバリアントは、マーク、位置、リミット、容量の値を表します。

0 <= mark <= position <= limit <= capacity

新しく作成されたバッファーの位置は常にゼロ、マークは未定義です。リミットの初期値はゼロか、バッファーの構築方法や種類によってはそれ以外の値になります。新しく割り当てられたバッファーの各要素はゼロに初期化されます。

クリア、フリップ、リワインド

位置、リミット、容量の値にアクセスするメソッドや、マークやリセットを行うメソッドと同様に、このクラスもバッファーに対する次のような操作を定義します。

• clear() は、新しい一連のチャネル読み込み操作または相対「put」操作のためにバッファーを準備します。リミットを容量の値に設定し、位置をゼロに設定します。

• flip() は、新しい一連のチャネル読み込み操作または相対「get」操作のためにバッファーを準備します。リミットの値を現在位置の値に合わせたあと、位置の値をゼロにします。

• rewind() は、すでにバッファーに格納されているデータを再度読み込めるように、バッファーを準備します。リミットの値はそのままで、位置の値をゼロにします。

読み込み専用バッファー

すべてのバッファーは読み込み可能ですが、書き込みも可能であるとは限りません。各バッファークラスの変異メソッドは「オプションの操作」に指定されており、読み取り専用バッファー上で呼び出されると ReadOnlyBufferException をスローします。読み取り専用バッファーの内容は変更できません。しかし、マーク、位置、リミットの値は変更可能です。バッファーが読み取り専用かどうかは、isReadOnly メソッドの呼び出しによって判断できます。

スレッドの安全性

バッファーは、複数の並行スレッドによる使用において安全ではありません。複数のスレッドで使用する場合は、適切な同期処理によってバッファーへのアクセスを制御する必要があります。

呼び出しの連鎖

このクラスのメソッドのうち戻り値を返さないものは、自身を呼び出したバッファーの情報を返します。これを応用して、メソッド呼び出しを連鎖させることができます。たとえば次のような文があるとしましょう。

 b.flip();
 b.position(23);
 b.limit(42);

これらは、よりコンパクトな形式の一行で置き換えられます。

 b.flip().position(23).limit(42);

導入されたバージョン:

1.4

メソッドのサマリー

メソッド

修飾子と型	メソッドと説明
abstract Object	array() このバッファーを補助する配列を返します (オプションの操作)。
abstract int	arrayOffset() このバッファーの補助配列内にある、このバッファーの最初の要素のオフセットを返します (オプションの操作)。
int	capacity() このバッファーの容量を返します。
Buffer	clear() このバッファーをクリアします。
Buffer	flip() このバッファーをフリップ (反転) します。
abstract boolean	hasArray() このバッファーがアクセス可能な配列に連動するかどうかを判断します。
boolean	hasRemaining() 現在位置からリミットまでに要素が 1 つでも存在するかどうかを判断します。
abstract boolean	isDirect() このバッファーがダイレクトバッファーであるかどうかを判断します。
abstract boolean	isReadOnly() このバッファーが読み取り専用であるかどうかを判断します。
int	limit() このバッファーのリミットを返します。
Buffer	limit(int newLimit) このバッファーのリミットを設定します。
Buffer	mark() このバッファーの現在位置にマークを設定します。
int	position() このバッファーの位置を返します。
Buffer	position(int newPosition) このバッファーの位置を設定します。
int	remaining() 現在位置からリミットまでに存在する要素の数を返します。
Buffer	reset() バッファーの位置を以前にマークした位置に戻します。
Buffer	rewind() このバッファーをリワインド (巻き戻し) します。

クラス java.lang.Object から継承されたメソッド

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

メソッドの詳細

capacity

public final int capacity()

このバッファーの容量を返します。

戻り値:

このバッファーの容量

position

public final int position()

このバッファーの位置を返します。

戻り値:

このバッファーの位置

position

public final Buffer position(int newPosition)

このバッファーの位置を設定します。新しい位置の値よりもマークの値のほうが大きい場合、マークの定義は破棄されます。

パラメータ:

newPosition - 新しい位置の値は、現在のリミット以下の負でない値でなければならない

戻り値:

このバッファー

例外:

IllegalArgumentException - newPosition の前提条件が満たされていない場合

limit

public final int limit()

このバッファーのリミットを返します。

戻り値:

このバッファーのリミット

limit

public final Buffer limit(int newLimit)

このバッファーのリミットを設定します。位置の値が新しいリミットより大きい場合、リミットと同じ値に変更されます。マークの値が新しいリミットより大きい場合、マークの定義は破棄されます。

パラメータ:

newLimit - 新しいリミット値は、このバッファーの容量以下の負でない値でなければならない

戻り値:

このバッファー

例外:

IllegalArgumentException - newLimit の前提条件が満たされていない場合

mark

public final Buffer mark()

このバッファーの現在位置にマークを設定します。

戻り値:

このバッファー

reset

public final Buffer reset()

バッファーの位置を以前にマークした位置に戻します。

このメソッドを呼び出しても、マークの値は変更されません。マークが破棄されることもありません。

戻り値:

このバッファー

例外:

InvalidMarkException - マークが設定されていない場合

clear

public final Buffer clear()

このバッファーをクリアします。バッファーの位置はゼロ、リミットは容量の値に設定されます。マークは破棄されます。

一連のチャネル読み込み操作または「put」操作を使用してこのバッファーにデータを格納する前に、このメソッドを呼び出します。たとえば、

 buf.clear();     // Prepare buffer for reading
 in.read(buf);    // Read data

このメソッドはバッファー内のデータを実際に消去するわけではありません。しかし、そうした状況で使用されるため、クリア (clear) と命名されています。

戻り値:

このバッファー

flip

public final Buffer flip()

このバッファーをフリップ (反転) します。リミットは現在位置の値に設定され、現在位置を表す値はゼロに設定されます。マークが定義されている場合、そのマークは破棄されます。

一連のチャネル読み込み操作 (put) のあと、このメソッドを呼び出してチャネル書き込み操作 (相対「get」) の準備を行います。たとえば、

 buf.put(magic);    // Prepend header
 in.read(buf);      // Read data into rest of buffer
 buf.flip();        // Flip buffer
 out.write(buf);    // Write header + data to channel

ある場所から別の場所にデータを転送する際、このメソッドを compact メソッドと組み合わせて使用することがあります。

戻り値:

このバッファー

rewind

public final Buffer rewind()

このバッファーをリワインド (巻き戻し) します。位置はゼロに設定され、マークは破棄されます。

このメソッドは、リミットを正しく設定したあと、一連のチャネル書き込み操作 (get) の前に呼び出します。たとえば、

 out.write(buf);    // Write remaining data
 buf.rewind();      // Rewind buffer
 buf.get(array);    // Copy data into array

戻り値:

このバッファー

remaining

public final int remaining()

現在位置からリミットまでに存在する要素の数を返します。

戻り値:

このバッファー内に残っている要素数

hasRemaining

public final boolean hasRemaining()

現在位置からリミットまでに要素が 1 つでも存在するかどうかを判断します。

戻り値:

このバッファー内に要素が 1 個以上存在する場合にかぎり true

isReadOnly

public abstract boolean isReadOnly()

このバッファーが読み取り専用であるかどうかを判断します。

戻り値:

このバッファーが読み込み専用である場合にかぎり true

hasArray

public abstract boolean hasArray()

このバッファーがアクセス可能な配列に連動するかどうかを判断します。

このメソッドの戻り値が true であれば、array および arrayOffset メソッドを安全に呼び出すことができます。

戻り値:

このバッファーが配列に連動しており、読み取り専用でない場合にかぎり true

導入されたバージョン:

1.6

array

public abstract Object array()

このバッファーを補助する配列を返します (オプションの操作)。

このメソッドは、配列を利用するバッファーをネイティブコードにより効率よく渡すために使用します。具象サブクラスは、このメソッドの戻り値として、より強く型付けされた値を返します。

このバッファーの内容に変更を加えると、返される配列の内容も変更されます。その逆も同様です。

このメソッドを呼び出す前に hasArray メソッドを呼び出し、このバッファーがアクセス可能な補助配列を持っていることを確認します。

戻り値:

このバッファーを補助する配列

例外:

ReadOnlyBufferException - このバッファーが配列に連動しており、しかも読み込み専用である場合

UnsupportedOperationException - このバッファーがアクセス可能な配列を利用しない場合

導入されたバージョン:

1.6

arrayOffset

public abstract int arrayOffset()

このバッファーの補助配列内にある、このバッファーの最初の要素のオフセットを返します (オプションの操作)。

このバッファーが配列に連動していれば、その位置 p が配列のインデックス p + arrayOffset() と一致します。

このメソッドを呼び出す前に hasArray メソッドを呼び出し、このバッファーがアクセス可能な補助配列を持っていることを確認します。

戻り値:

このバッファーの配列内にある、このバッファーの最初の要素のオフセット

例外:

ReadOnlyBufferException - このバッファーが配列に連動しており、しかも読み込み専用である場合

UnsupportedOperationException - このバッファーがアクセス可能な配列を利用しない場合

導入されたバージョン:

1.6

isDirect

public abstract boolean isDirect()

このバッファーがダイレクトバッファーであるかどうかを判断します。

戻り値:

このバッファーがダイレクトバッファーである場合にかぎり true

導入されたバージョン:

1.6