型パラメータ:: T - ギャザラ操作への入力要素のタイプ; A - ギャザラ操作(多くの場合、実装の詳細として非表示)の可変状態タイプ; R - ギャザラ操作からの出力要素のタイプ

public interface Gatherer<T,A,R>

入力要素のストリームを出力要素のストリームに変換する中間操作で、オプションでアップストリームの最後に達したときに最終アクションを適用します。変換はステートレスまたはステートフルであり、出力を生成する前に入力をバッファリングできます。

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

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

APIのノート:

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

新しい、変更可能な状態の作成 (initializer())
新しい入力要素(integrator())の統合
2つの状態を1つの(combiner())に結合
オプションの最終アクション(finisher())の実行

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

Gathererの実装は、他のスレッド、状態インスタンスまたはダウンストリームGatherer.Downstreamへの参照を、渡されるメソッドの起動期間より長く取得、保持または公開しないでください。

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);

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

Gatherersの事前定義済の実装に加えて、静的ファクトリ・メソッド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();

実装要件:

Gathererに基づいて変換を実装するライブラリ(Stream.gather(Gatherer)など)は、次の制約に従う必要があります:

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

導入されたバージョン:

24

関連項目:

ネストされたクラスのサマリー

ネストされたクラス

修飾子と型

インタフェース

説明

static interface

Gatherer.Downstream<T>

ダウンストリーム・オブジェクトは、操作のパイプラインの次のステージで、要素を送信できます。

static interface

Gatherer.Integrator<A,T,R>

Integratorは要素を受信し、必要に応じて指定された状態を使用して要素を処理し、必要に応じて増分結果をダウンストリームに送信します。
メソッドのサマリー

修飾子と型

メソッド

説明

default <RR> Gatherer<T,?,RR>

andThen(Gatherer<? super R, ?, ? extends RR> that)

このGathererの出力をそのGathererの入力に接続する合成Gathererを返します。

default BinaryOperator<A>

combiner()

2つの中間状態を受け入れ、それらを1つに結合する関数。

static <A> BinaryOperator<A>

defaultCombiner()

Gathererのデフォルトのコンビナであるコンビナを返します。

static <A,R> BiConsumer<A, Gatherer.Downstream<? super R>>

defaultFinisher()

Gathererのデフォルトの終了であるfinisherを返します。

static <A> Supplier<A>

defaultInitializer()

Gathererのデフォルトの初期化子である初期化子を返します。

default BiConsumer<A, Gatherer.Downstream<? super R>>

finisher()

最終的な中間状態とGatherer.Downstreamオブジェクトを受け入れる関数で、入力要素の最後に最終的なアクションを実行できます。

default Supplier<A>

initializer()

この収集操作に使用される中間状態のインスタンスを生成する関数。

Gatherer.Integrator<A,T,R>

integrator()

提供されている要素を統合し、提供されている中間状態を使用する可能性があり、オプションで提供されているGatherer.Downstreamへの出力を生成する関数。

static <T,A,R> Gatherer<T,A,R>

of(Supplier<A> initializer, Gatherer.Integrator<A,T,R> integrator, BinaryOperator<A> combiner, BiConsumer<A, Gatherer.Downstream<? super R>> finisher)

指定されたinitializer, integrator, combinerおよびfinisherによって記述された、パラレル化可能な新しいGathererを返します。

static <T,R> Gatherer<T,Void,R>

of(Gatherer.Integrator<Void,T,R> integrator)

指定されたintegratorによって記述された、新しいパラレル化可能なステートレスなGathererを返します。

static <T,R> Gatherer<T,Void,R>

of(Gatherer.Integrator<Void,T,R> integrator, BiConsumer<Void, Gatherer.Downstream<? super R>> finisher)

指定されたintegratorおよびfinisherによって記述された、新しいパラレル化可能なステートレスなGathererを返します。

static <T,A,R> Gatherer<T,A,R>

ofSequential(Supplier<A> initializer, Gatherer.Integrator<A,T,R> integrator)

指定されたinitializerおよびintegratorによって記述された、新しい順次Gathererを返します。

static <T,A,R> Gatherer<T,A,R>

ofSequential(Supplier<A> initializer, Gatherer.Integrator<A,T,R> integrator, BiConsumer<A, Gatherer.Downstream<? super R>> finisher)

指定されたinitializer、integratorおよびfinisherによって記述された、新しい順次Gathererを返します。

static <T,R> Gatherer<T,Void,R>

ofSequential(Gatherer.Integrator<Void,T,R> integrator)

指定されたintegratorによって記述された、新しい順次およびステートレスなGathererを返します。

static <T,R> Gatherer<T,Void,R>

ofSequential(Gatherer.Integrator<Void,T,R> integrator, BiConsumer<Void, Gatherer.Downstream<? super R>> finisher)

指定されたintegratorおよびfinisherによって記述された、新しい順次およびステートレスなGathererを返します。

メソッドの詳細
- initializer
  
  default Supplier<A> initializer()
  
  この収集操作に使用される中間状態のインスタンスを生成する関数。
  
  実装要件:
  
  このインタフェースの実装は、defaultInitializer()を返します。
  
  戻り値:
  
  この収集操作に使用される中間状態のインスタンスを生成する関数
- integrator
  
  Gatherer.Integrator<A,T,R> integrator()
  
  提供されている要素を統合し、提供されている中間状態を使用する可能性があり、オプションで提供されているGatherer.Downstreamへの出力を生成する関数。
  
  戻り値:
  
  指定された状態を使用する可能性のある、提供された要素を統合し、オプションで提供されたダウンストリームに出力を生成する関数
- combiner
  
  default BinaryOperator<A> combiner()
  
  2つの中間状態を受け入れ、それらを1つに結合する関数。
  
  実装要件:
  
  このインタフェースの実装は、defaultCombiner()を返します。
  
  戻り値:
  
  2つの中間状態を受け入れ、それらを1つに結合する関数
- finisher
  
  default BiConsumer<A, Gatherer.Downstream<? super R>> finisher()
  
  最終的な中間状態とGatherer.Downstreamオブジェクトを受け入れる関数で、入力要素の最後に最終的なアクションを実行できます。
  
  実装要件:
  
  このインタフェースの実装は、defaultFinisher()を返します。
  
  戻り値:
  
  中間結果をfinalresult(s)に変換し、提供されたダウンストリームに渡される関数
- andThen
  
  default <RR> Gatherer<T,?,RR> andThen(Gatherer<? 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 - 返されたイニシャライザの状態のタイプ
  
  戻り値:
  
  デフォルトのイニシャライザのインスタンス
  
  関連項目:
  
  initializer()
- defaultCombiner
  static <A> BinaryOperator<A> defaultCombiner()
  
  Gathererのデフォルトのコンビナであるコンビナを返します。戻されたコンビナは、所有しているGathererを順次評価する必要があることを識別します。
  
  実装要件:
  
  このメソッドは、常に同じインスタンスを返します。
  
  型パラメータ:
  
  A - 返されたコンビ・ナの状態のタイプ
  
  戻り値:
  
  デフォルト・コンビナのインスタンス
  
  関連項目:
  
  combiner()
- defaultFinisher
  static <A,R> BiConsumer<A, Gatherer.Downstream<? super R>> defaultFinisher()
  
  Gathererのデフォルトの終了であるfinisherを返します。戻された終了は、所有するGathererが入力の最後に追加のアクションを実行しないことを識別します。
  
  実装要件:
  
  このメソッドは、常に同じインスタンスを返します。
  
  型パラメータ:
  
  A - 返された終了の状態のタイプ
  
  R - 返された終了のダウンストリームのタイプ
  
  戻り値:
  
  デフォルトの終了のインスタンス
  
  関連項目:
  
  finisher()
- ofSequential
  
  static <T,R> Gatherer<T,Void,R> ofSequential(Gatherer.Integrator<Void,T,R> integrator)
  
  指定されたintegratorによって記述された、新しい順次およびステートレスなGathererを返します。
  
  型パラメータ:
  
  T - 新しいギャザラの入力要素のタイプ
  
  R - 新規ギャザラの結果のタイプ
  
  パラメータ:
  
  integrator - 新しいギャザラのインテグレータ関数
  
  戻り値:
  
  新しいGatherer
  
  スロー:
  
  NullPointerException - 引数がnullの場合
- ofSequential
  
  static <T,R> Gatherer<T,Void,R> ofSequential(Gatherer.Integrator<Void,T,R> integrator, BiConsumer<Void, Gatherer.Downstream<? super R>> finisher)
  
  指定されたintegratorおよびfinisherによって記述された、新しい順次およびステートレスなGathererを返します。
  
  型パラメータ:
  
  T - 新しいギャザラの入力要素のタイプ
  
  R - 新規ギャザラの結果のタイプ
  
  パラメータ:
  
  integrator - 新しいギャザラのインテグレータ関数
  
  finisher - 新しいギャザラの終了機能
  
  戻り値:
  
  新しいGatherer
  
  スロー:
  
  NullPointerException - 引数が1つの場合はnull
- ofSequential
  
  static <T,A,R> Gatherer<T,A,R> ofSequential(Supplier<A> initializer, Gatherer.Integrator<A,T,R> integrator)
  
  指定されたinitializerおよびintegratorによって記述された、新しい順次Gathererを返します。
  
  型パラメータ:
  
  T - 新しいギャザラの入力要素のタイプ
  
  A - 新しいギャザラの状態のタイプ
  
  R - 新規ギャザラの結果のタイプ
  
  パラメータ:
  
  initializer - 新しいギャザラのイニシャライザ関数
  
  integrator - 新しいギャザラのインテグレータ関数
  
  戻り値:
  
  新しいGatherer
  
  スロー:
  
  NullPointerException - 引数が1つの場合はnull
- ofSequential
  
  static <T,A,R> Gatherer<T,A,R> ofSequential(Supplier<A> initializer, Gatherer.Integrator<A,T,R> integrator, BiConsumer<A, Gatherer.Downstream<? super R>> finisher)
  
  指定されたinitializer、integratorおよびfinisherによって記述された、新しい順次Gathererを返します。
  
  型パラメータ:
  
  T - 新しいギャザラの入力要素のタイプ
  
  A - 新しいギャザラの状態のタイプ
  
  R - 新規ギャザラの結果のタイプ
  
  パラメータ:
  
  initializer - 新しいギャザラのイニシャライザ関数
  
  integrator - 新しいギャザラのインテグレータ関数
  
  finisher - 新しいギャザラの終了機能
  
  戻り値:
  
  新しいGatherer
  
  スロー:
  
  NullPointerException - 引数が1つの場合はnull
- of
  
  static <T,R> Gatherer<T,Void,R> of(Gatherer.Integrator<Void,T,R> integrator)
  
  指定されたintegratorによって記述された、新しいパラレル化可能なステートレスなGathererを返します。
  
  型パラメータ:
  
  T - 新しいギャザラの入力要素のタイプ
  
  R - 新規ギャザラの結果のタイプ
  
  パラメータ:
  
  integrator - 新しいギャザラのインテグレータ関数
  
  戻り値:
  
  新しいGatherer
  
  スロー:
  
  NullPointerException - 引数が1つの場合はnull
- of
  
  static <T,R> Gatherer<T,Void,R> of(Gatherer.Integrator<Void,T,R> integrator, BiConsumer<Void, Gatherer.Downstream<? super R>> finisher)
  
  指定されたintegratorおよびfinisherによって記述された、新しいパラレル化可能なステートレスなGathererを返します。
  
  型パラメータ:
  
  T - 新しいギャザラの入力要素のタイプ
  
  R - 新規ギャザラの結果のタイプ
  
  パラメータ:
  
  integrator - 新しいギャザラのインテグレータ関数
  
  finisher - 新しいギャザラの終了機能
  
  戻り値:
  
  新しいGatherer
  
  スロー:
  
  NullPointerException - 引数が1つの場合はnull
- of
  
  static <T,A,R> Gatherer<T,A,R> of(Supplier<A> initializer, Gatherer.Integrator<A,T,R> integrator, BinaryOperator<A> combiner, BiConsumer<A, Gatherer.Downstream<? super R>> finisher)
  
  指定されたinitializer, integrator, combinerおよびfinisherによって記述された、パラレル化可能な新しいGathererを返します。
  
  型パラメータ:
  
  T - 新しいギャザラの入力要素のタイプ
  
  A - 新しいギャザラの状態のタイプ
  
  R - 新規ギャザラの結果のタイプ
  
  パラメータ:
  
  initializer - 新しいギャザラのイニシャライザ関数
  
  integrator - 新しいギャザラのインテグレータ関数
  
  combiner - 新しいギャザラのためのコンビナ機能
  
  finisher - 新しいギャザラの終了機能
  
  戻り値:
  
  新しいGatherer
  
  スロー:
  
  NullPointerException - 引数が1つの場合はnull

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

ネストされたクラスのサマリー

メソッドのサマリー

メソッドの詳細

initializer

integrator

combiner

finisher

andThen

defaultInitializer

defaultCombiner

defaultFinisher

ofSequential

ofSequential

ofSequential

ofSequential

of

of

of