Buffer (Java Platform SE 6)

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

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

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

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

データの転送

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

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

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

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

マークとリセット

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

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

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

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

新しく作成されたバッファーの位置は常に 0、マークは未定義です。リミットの初期値は 0 か、バッファーの構築方法や種類によってはそれ以外の値になります。一般に、バッファーの初期コンテンツは未定義です。

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

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

clear() は、新しい一連のチャネル読み込み操作または相対「put」操作のためにバッファーを準備します。リミットを容量の値に設定し、位置を 0 に設定します。
flip() は、新規チャネル書き込みシーケンス (相対「get」) のためにバッファーを準備します。リミットの値を現在位置の値に合わせたあと、位置の値を 0 にします。
rewind() は、すでにバッファー格納されているデータを再度読み込めるように、バッファーを準備します。リミットの値はそのままで、位置の値を 0 にします。

読み込み専用バッファー

すべてのバッファーは読み込み可能ですが、書き込みも可能であるとは限りません。各バッファークラスの変異メソッドは「省略可能な操作」に指定されており、読み取り専用バッファー上で呼び出されると 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()

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

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

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

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

戻り値:: 現在のバッファー

flip

public final Buffer flip()

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

チャネル読み込み操作 (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()

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

このメソッドは、リミットを正しく設定したあと、チャネル書き込み操作 (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