モジュール java.base
パッケージ 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がスローされます。

    Invariants

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

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

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

    その他の操作

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

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

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

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

    • slice()はバッファのサブシーケンスを作成: 限界と位置は変更されません。

    • duplicate()はバッファの浅いコピーを作成: 限界と位置は変更されません。

    読込み専用バッファ

    すべてのバッファは読込み可能ですが、書き込みも可能であるとは限りません。 各バッファ・クラスの変異メソッドは「オプションの操作」に指定されており、読取り専用バッファ上で呼び出されると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()
      このバッファをクリアします。
      abstract Buffer duplicate()
      このバッファの内容を共有する新しいバッファを作成します。
      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()
      このバッファをリワインド(巻き戻し)します。
      abstract Buffer slice()
      内容がこのバッファ内容の共有されたサブシーケンスである新しいバッファを作成します。

    • メソッドの詳細

      • capacity

        public final int capacity()
        このバッファの容量を返します。
        戻り値:
        このバッファの容量

      • position

        public final int position()
        このバッファの位置を返します。
        戻り値:
        このバッファの位置

      • position

        public Buffer position​(int newPosition)
        このバッファの位置を設定します。 新しい位置の値よりもマークの値のほうが大きい場合、マークの定義は破棄されます。
        パラメータ:
        newPosition - 新しい位置の値は、現在のリミット以下の負でない値でなければならない
        戻り値:
        このバッファ
        例外:
        IllegalArgumentException - newPositionの前提条件が満たされていない場合

      • limit

        public final int limit()
        このバッファのリミットを返します。
        戻り値:
        このバッファのリミット

      • limit

        public Buffer limit​(int newLimit)
        このバッファのリミットを設定します。 位置の値が新しいリミットより大きい場合、リミットと同じ値に変更されます。 マークの値が新しいリミットより大きい場合、マークの定義は破棄されます。
        パラメータ:
        newLimit - 新しいリミット値は、このバッファの容量以下の負でない値でなければならない
        戻り値:
        このバッファ
        例外:
        IllegalArgumentException - newLimitの前提条件が満たされていない場合

      • mark

        public Buffer mark()
        このバッファの現在位置にマークを設定します。
        戻り値:
        このバッファ

      • reset

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

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

        戻り値:
        このバッファ
        例外:
        InvalidMarkException - マークが設定されていない場合

      • clear

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

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

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

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

        戻り値:
        このバッファ

      • flip

        public 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 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

      • slice

        public abstract Buffer slice()
        内容がこのバッファ内容の共有されたサブシーケンスである新しいバッファを作成します。

        新しいバッファの内容は、このバッファの現在位置から始まります。 このバッファの内容に変更を加えると、その内容が新しいバッファに反映されます。新しいバッファの内容に変更を加えると、その内容がこのバッファに反映されます。2つのバッファの位置、リミット、マークの値はそれぞれ異なります。

        新しいバッファの位置は0になり、その容量とその制限はこのバッファに残っている要素の数になり、そのマークは未定義になります。 新しいバッファは、このバッファがダイレクト・バッファである場合にかぎりダイレクト・バッファになります。また、このバッファが読取り専用バッファである場合にかぎり読取り専用バッファになります。

        戻り値:
        新しいバッファ
        導入されたバージョン:
        9

      • duplicate

        public abstract Buffer duplicate()
        このバッファの内容を共有する新しいバッファを作成します。

        新しいバッファの内容は、このバッファの内容と同じになります。 このバッファの内容に変更を加えると、その内容が新しいバッファに反映されます。新しいバッファの内容に変更を加えると、その内容がこのバッファに反映されます。2つのバッファの位置、リミット、マークの値はそれぞれ異なります。

        新しいバッファの容量、限界、位置、およびマークの値は、このバッファのものと同一です。 新しいバッファは、このバッファがダイレクト・バッファである場合にかぎりダイレクト・バッファになります。また、このバッファが読取り専用バッファである場合にかぎり読取り専用バッファになります。

        戻り値:
        新しいバッファ
        導入されたバージョン:
        9