インタフェースGatherer<T,A,R>

型パラメータ:
T - ギャザラ操作への入力要素のタイプ
A - ギャザラ操作(多くの場合、実装の詳細として非表示)の可変状態タイプ
R - ギャザラ操作からの出力要素のタイプ
public interface Gatherer<T,A,R>
Gathererは、JavaプラットフォームのプレビューAPIです。
プレビュー機能が有効な場合のみ、プログラムでGathererを使用できます。
プレビュー機能は、今後のリリースで削除するか、Javaプラットフォームの永続機能にアップグレードすることができます。
入力要素のストリームを出力要素のストリームに変換する中間操作で、オプションでアップストリームの最後に達したときに最終アクションを適用します。 変換はステートレスまたはステートフルであり、出力を生成する前に入力をバッファリングできます。

Gatherer操作を順次実行することも、パラレル化することもできます。 -- コンビナ関数が指定されている場合。

収集操作には、次のような多くの例があります: 要素をバッチにグループ化 (ウィンドウ関数) ;連続的に類似した要素の複製解除;増分累積関数 (プレフィクス・スキャン) ;増分再順序付け関数などクラスGatherersPREVIEWは、一般的な収集操作の実装を提供します。

APIのノート:

Gathererは、オプションで中間状態を使用して入力要素を処理するために連携する4つの関数によって指定され、オプションで入力の最後に最終的なアクションを実行します。 これらを次に示します。

initializer()、integrator()、combiner()およびfinisher()の各呼出しは、意味的に同じ結果を返す必要があります。

Gathererの実装は、他のスレッド、状態インスタンスまたはダウンストリームGatherer.DownstreamPREVIEWへの参照を取得、保持または公開してはなりません。これは、渡されるメソッドの呼出し期間より長くなります。

Gathererを使用して収集操作を実行すると、次のような結果になります。 

Gatherer.Downstream<? super R> downstream = ...;
A state = gatherer.initializer().get();
for (T t : data) {
    gatherer.integrator().integrate(state, t, downstream);
}
gatherer.finisher().accept(state, downstream);

ただし、ライブラリは自由に入力をパーティション分割し、パーティションに統合を実行してから、コンビナ機能を使用して部分的な結果を結合し、収集操作を実行できます。 (特定の収集操作によっては、インテグレータおよびコンビナ機能の相対コストに応じて、パフォーマンスが向上するか、低下する場合があります。)

GatherersPREVIEWの事前定義済実装に加えて、静的ファクトリ・メソッドof(...)およびofSequential(...)を使用して、ギャザラを構築できます。 たとえば、次を使用してStream.map(java.util.function.Function)と同等のものを実装するギャザラを作成できます。 

public static <T, R> Gatherer<T, ?, R> map(Function<? super T, ? extends R> mapper) {
    return Gatherer.of(
        (unused, element, downstream) -> // integrator
            downstream.push(mapper.apply(element))
    );
}

Gathererはcomposedになるように設計されており、2つ以上のGathererは、andThen(Gatherer)メソッドを使用して1つのGathererに構成できます。 

// using the implementation of `map` as seen above
Gatherer<Integer, ?, Integer> increment = map(i -> i + 1);

Gatherer<Object, ?, String> toString = map(i -> i.toString());

Gatherer<Integer, ?, String> incrementThenToString = increment.andThen(toString);

たとえば、順次プリフィクス・スキャンを実装するGathererは、次のように実行できます。 

public static <T, R> Gatherer<T, ?, R> scan(
    Supplier<R> initial,
    BiFunction<? super R, ? super T, ? extends R> scanner) {

    class State {
        R current = initial.get();
    }

    return Gatherer.<T, State, R>ofSequential(
         State::new,
         Gatherer.Integrator.ofGreedy((state, element, downstream) -> {
             state.current = scanner.apply(state.current, element);
             return downstream.push(state.current);
         })
    );
}

使用の例: 

// will contain: ["1", "12", "123", "1234", "12345", "123456", "1234567", "12345678", "123456789"]
List<String> numberStrings =
    Stream.of(1,2,3,4,5,6,7,8,9)
          .gather(
              scan(() -> "", (string, number) -> string + number)
           )
          .toList();

実装要件:
Stream.gather(Gatherer)PREVIEWなどのGathererに基づいて変換を実装するライブラリ、次の制約に従う必要があります:
  • 初期化子がdefaultInitializer()であるGatherersはステートレスとみなされ、その初期化子の起動はオプションです。
  • インテグレータがGatherer.Integrator.GreedyPREVIEWのインスタンスであるGatherersは、短絡しないことを想定でき、Gatherer.Integrator.integrate(Object, Object, Downstream)PREVIEWを呼び出す戻り値を検査する必要はありません。
  • 統合関数に渡される最初の引数(コンビナ・ファンクションに渡される引数と、フィニッシャ・ファンクションに渡される引数)は、イニシャライザまたはコンビナ・ファンクションの以前の呼出しの結果である必要があります。
  • インテグレータ、コンビナまたはフィニッシャ・ファンクションに再度渡す以外に、初期化子またはコンビナ・ファンクションの結果に対して実装は何もしないでください。
  • 状態オブジェクトがコンビナまたはフィニッシャ関数に渡されると、インテグレータ関数に再度渡されることはありません。
  • インテグレータ関数がfalseを返す場合、これ以上渡す要素がないかのように解釈されます。
  • パラレル評価の場合、収集実装では、入力が適切にパーティション化されていること、パーティションが分離で処理されていること、および両方のパーティションの統合が完了した後にのみ結合が行われることを管理する必要があります。
  • コンビナがdefaultCombiner()であるGatherersは、順次しか評価できません。 他のすべてのコンビナでは、分離して各パーティションを初期化し、falseが返されるまでインテグレータを起動し、コンビナを使用して各パーティションの状態を結合してから、結合状態でフィニッシャを起動することで、操作をパラレル化できます。 以前のパーティションの短絡を処理する場合、入力シーケンス内の後の出力および状態は破棄されます。
  • フィニッシャがdefaultFinisher()のGatherersは、ストリーム終了フックがないとみなされ、フィニッシャの起動はオプションです。
導入されたバージョン:
22
関連項目:

  • メソッドの詳細

    • initializer

      default Supplier<A> initializer()
      この収集操作に使用される中間状態のインスタンスを生成する関数。
      実装要件:
      このインタフェースの実装は、defaultInitializer()を返します。
      戻り値:
      この収集操作に使用される中間状態のインスタンスを生成する関数

    • integrator

      Gatherer.IntegratorPREVIEW<A,T,R> integrator()
      提供されている要素を統合し、提供されている中間状態を使用して、オプションで提供されているGatherer.DownstreamPREVIEWに出力を生成する関数。
      戻り値:
      指定された状態を使用する可能性のある、提供された要素を統合し、オプションで提供されたダウンストリームに出力を生成する関数

    • combiner

      default BinaryOperator<A> combiner()
      2つの中間状態を受け入れ、それらを1つに結合する関数。
      実装要件:
      このインタフェースの実装は、defaultCombiner()を返します。
      戻り値:
      2つの中間状態を受け入れ、それらを1つに結合する関数

    • finisher

      default BiConsumer<A,Gatherer.DownstreamPREVIEW<? super R>> finisher()
      最終的な中間状態およびGatherer.DownstreamPREVIEWオブジェクトを受け入れ、入力要素の最後に最終的なアクションを実行できる関数。
      実装要件:
      このインタフェースの実装は、defaultFinisher()を返します。
      戻り値:
      中間結果をfinalresult(s)に変換し、提供されたダウンストリームに渡される関数

    • andThen

      default <RR> GathererPREVIEW<T,?,RR> andThen(GathererPREVIEW<? super R,?,? extends RR> that)
      このGathererの出力をそのGathererの入力に接続する合成Gathererを返します。
      実装要件:
      このインタフェースの実装では、thisおよびthatギャザラの組合せと意味的に同等の新しいGathererが返されます。
      型パラメータ:
      RR - そのGathererの出力のタイプ
      パラメータ:
      that - 他のギャザラ
      戻り値:
      このGathererの出力をGathererの入力として接続する合成Gathererを返します
      例外:
      NullPointerException - 引数がnullの場合

    • defaultInitializer

      static <A> Supplier<A> defaultInitializer()
      Gathererのデフォルトの初期化子である初期化子を返します。 返されたイニシャライザは、所有者のGathererがステートレスであることを識別します。
      実装要件:
      このメソッドは、常に同じインスタンスを返します。
      型パラメータ:
      A - 返されたイニシャライザの状態のタイプ
      戻り値:
      デフォルトのイニシャライザのインスタンス
      関連項目:

    • defaultCombiner

      static <A> BinaryOperator<A> defaultCombiner()
      Gathererのデフォルトのコンビナであるコンビナを返します。 戻されたコンビナは、所有しているGathererを順次評価する必要があることを識別します。
      実装要件:
      このメソッドは、常に同じインスタンスを返します。
      型パラメータ:
      A - 返されたコンビナの状態のタイプ
      戻り値:
      デフォルト・コンビナのインスタンス
      関連項目:

    • defaultFinisher

      static <A, R> BiConsumer<A,Gatherer.DownstreamPREVIEW<? super R>> defaultFinisher()
      Gathererのデフォルトの終了であるfinisherを返します。 戻された終了は、所有するGathererが入力の最後に追加のアクションを実行しないことを識別します。
      実装要件:
      このメソッドは、常に同じインスタンスを返します。
      型パラメータ:
      A - 返された終了の状態のタイプ
      R - 返された終了のダウンストリームのタイプ
      戻り値:
      デフォルトの終了のインスタンス
      関連項目:

    • ofSequential

      static <T, R> GathererPREVIEW<T,Void,R> ofSequential(Gatherer.IntegratorPREVIEW<Void,T,R> integrator)
      指定されたintegratorによって記述された、新しい順次およびステートレスなGathererを返します。
      型パラメータ:
      T - 新しいギャザラの入力要素のタイプ
      R - 新規ギャザラの結果のタイプ
      パラメータ:
      integrator - 新しいギャザラのインテグレータ関数
      戻り値:
      新しいGatherer
      例外:
      NullPointerException - 引数がnullの場合

    • ofSequential

      static <T, R> GathererPREVIEW<T,Void,R> ofSequential(Gatherer.IntegratorPREVIEW<Void,T,R> integrator, BiConsumer<Void,Gatherer.DownstreamPREVIEW<? super R>> finisher)
      指定されたintegratorおよびfinisherによって記述された、新しい順次およびステートレスなGathererを返します。
      型パラメータ:
      T - 新しいギャザラの入力要素のタイプ
      R - 新規ギャザラの結果のタイプ
      パラメータ:
      integrator - 新しいギャザラのインテグレータ関数
      finisher - 新しいギャザラの終了機能
      戻り値:
      新しいGatherer
      例外:
      NullPointerException - 引数が1つの場合はnull

    • ofSequential

      static <T, A, R> GathererPREVIEW<T,A,R> ofSequential(Supplier<A> initializer, Gatherer.IntegratorPREVIEW<A,T,R> integrator)
      指定されたinitializerおよびintegratorによって記述された、新しい順次Gathererを返します。
      型パラメータ:
      T - 新しいギャザラの入力要素のタイプ
      A - 新しいギャザラの状態のタイプ
      R - 新規ギャザラの結果のタイプ
      パラメータ:
      initializer - 新しいギャザラのイニシャライザ関数
      integrator - 新しいギャザラのインテグレータ関数
      戻り値:
      新しいGatherer
      例外:
      NullPointerException - 引数が1つの場合はnull

    • ofSequential

      static <T, A, R> GathererPREVIEW<T,A,R> ofSequential(Supplier<A> initializer, Gatherer.IntegratorPREVIEW<A,T,R> integrator, BiConsumer<A,Gatherer.DownstreamPREVIEW<? super R>> finisher)
      指定されたinitializer、integratorおよびfinisherによって記述された、新しい順次Gathererを返します。
      型パラメータ:
      T - 新しいギャザラの入力要素のタイプ
      A - 新しいギャザラの状態のタイプ
      R - 新規ギャザラの結果のタイプ
      パラメータ:
      initializer - 新しいギャザラのイニシャライザ関数
      integrator - 新しいギャザラのインテグレータ関数
      finisher - 新しいギャザラの終了機能
      戻り値:
      新しいGatherer
      例外:
      NullPointerException - 引数が1つの場合はnull

    • of

      static <T, R> GathererPREVIEW<T,Void,R> of(Gatherer.IntegratorPREVIEW<Void,T,R> integrator)
      指定されたintegratorによって記述された、新しいパラレル化可能なステートレスなGathererを返します。
      型パラメータ:
      T - 新しいギャザラの入力要素のタイプ
      R - 新規ギャザラの結果のタイプ
      パラメータ:
      integrator - 新しいギャザラのインテグレータ関数
      戻り値:
      新しいGatherer
      例外:
      NullPointerException - 引数が1つの場合はnull

    • of

      static <T, R> GathererPREVIEW<T,Void,R> of(Gatherer.IntegratorPREVIEW<Void,T,R> integrator, BiConsumer<Void,Gatherer.DownstreamPREVIEW<? super R>> finisher)
      指定されたintegratorおよびfinisherによって記述された、新しいパラレル化可能なステートレスなGathererを返します。
      型パラメータ:
      T - 新しいギャザラの入力要素のタイプ
      R - 新規ギャザラの結果のタイプ
      パラメータ:
      integrator - 新しいギャザラのインテグレータ関数
      finisher - 新しいギャザラの終了機能
      戻り値:
      新しいGatherer
      例外:
      NullPointerException - 引数が1つの場合はnull

    • of

      static <T, A, R> GathererPREVIEW<T,A,R> of(Supplier<A> initializer, Gatherer.IntegratorPREVIEW<A,T,R> integrator, BinaryOperator<A> combiner, BiConsumer<A,Gatherer.DownstreamPREVIEW<? super R>> finisher)
      指定されたinitializer, integrator, combinerおよびfinisherによって記述された、パラレル化可能な新しいGathererを返します。
      型パラメータ:
      T - 新しいギャザラの入力要素のタイプ
      A - 新しいギャザラの状態のタイプ
      R - 新規ギャザラの結果のタイプ
      パラメータ:
      initializer - 新しいギャザラのイニシャライザ関数
      integrator - 新しいギャザラのインテグレータ関数
      combiner - 新しいギャザラのためのコンビナ機能
      finisher - 新しいギャザラの終了機能
      戻り値:
      新しいGatherer
      例外:
      NullPointerException - 引数が1つの場合はnull