ICollector Interface
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
A mutable reduction operation that accumulates input elements into a mutable result container, optionally transforming the accumulated result into a final representation after all input elements have been processed.
[Android.Runtime.Register("java/util/stream/Collector", "", "Java.Util.Streams.ICollectorInvoker", ApiSince=24)]
[Java.Interop.JavaTypeParameters(new System.String[] { "T", "A", "R" })]
public interface ICollector : Android.Runtime.IJavaObject, IDisposable, Java.Interop.IJavaPeerable[<Android.Runtime.Register("java/util/stream/Collector", "", "Java.Util.Streams.ICollectorInvoker", ApiSince=24)>]
[<Java.Interop.JavaTypeParameters(new System.String[] { "T", "A", "R" })>]
type ICollector = interface
interface IJavaObject
interface IDisposable
interface IJavaPeerable- Attributes
- Implements
Remarks
A mutable reduction operation that accumulates input elements into a mutable result container, optionally transforming the accumulated result into a final representation after all input elements have been processed. Reduction operations can be performed either sequentially or in parallel.
Examples of mutable reduction operations include: accumulating elements into a Collection; concatenating strings using a StringBuilder; computing summary information about elements such as sum, min, max, or average; computing "pivot table" summaries such as "maximum valued transaction by seller", etc. The class Collectors provides implementations of many common mutable reductions.
A Collector is specified by four functions that work together to accumulate entries into a mutable result container, and optionally perform a final transform on the result. They are: <ul> <li>creation of a new result container (#supplier())</li> <li>incorporating a new data element into a result container (#accumulator())</li> <li>combining two result containers into one (#combiner())</li> <li>performing an optional final transform on the container (#finisher())</li> </ul>
Collectors also have a set of characteristics, such as Characteristics#CONCURRENT, that provide hints that can be used by a reduction implementation to provide better performance.
A sequential implementation of a reduction using a collector would create a single result container using the supplier function, and invoke the accumulator function once for each input element. A parallel implementation would partition the input, create a result container for each partition, accumulate the contents of each partition into a subresult for that partition, and then use the combiner function to merge the subresults into a combined result.
To ensure that sequential and parallel executions produce equivalent results, the collector functions must satisfy an <em>identity</em> and an associativity constraints.
The identity constraint says that for any partially accumulated result, combining it with an empty result container must produce an equivalent result. That is, for a partially accumulated result a that is the result of any series of accumulator and combiner invocations, a must be equivalent to combiner.apply(a, supplier.get()).
The associativity constraint says that splitting the computation must produce an equivalent result. That is, for any input elements t1 and t2, the results r1 and r2 in the computation below must be equivalent:
{@code
A a1 = supplier.get();
accumulator.accept(a1, t1);
accumulator.accept(a1, t2);
R r1 = finisher.apply(a1); // result without splitting
A a2 = supplier.get();
accumulator.accept(a2, t1);
A a3 = supplier.get();
accumulator.accept(a3, t2);
R r2 = finisher.apply(combiner.apply(a2, a3)); // result with splitting
}
For collectors that do not have the UNORDERED characteristic, two accumulated results a1 and a2 are equivalent if finisher.apply(a1).equals(finisher.apply(a2)). For unordered collectors, equivalence is relaxed to allow for non-equality related to differences in order. (For example, an unordered collector that accumulated elements to a List would consider two lists equivalent if they contained the same elements, ignoring order.)
Libraries that implement reduction based on Collector, such as Stream#collect(Collector), must adhere to the following constraints: <ul> <li>The first argument passed to the accumulator function, both arguments passed to the combiner function, and the argument passed to the finisher function must be the result of a previous invocation of the result supplier, accumulator, or combiner functions.</li> <li>The implementation should not do anything with the result of any of the result supplier, accumulator, or combiner functions other than to pass them again to the accumulator, combiner, or finisher functions, or return them to the caller of the reduction operation.</li> <li>If a result is passed to the combiner or finisher function, and the same object is not returned from that function, it is never used again.</li> <li>Once a result is passed to the combiner or finisher function, it is never passed to the accumulator function again.</li> <li>For non-concurrent collectors, any result returned from the result supplier, accumulator, or combiner functions must be serially thread-confined. This enables collection to occur in parallel without the Collector needing to implement any additional synchronization. The reduction implementation must manage that the input is properly partitioned, that partitions are processed in isolation, and combining happens only after accumulation is complete.</li> <li>For concurrent collectors, an implementation is free to (but not required to) implement reduction concurrently. A concurrent reduction is one where the accumulator function is called concurrently from multiple threads, using the same concurrently-modifiable result container, rather than keeping the result isolated during accumulation. A concurrent reduction should only be applied if the collector has the Characteristics#UNORDERED characteristics or if the originating data is unordered.</li> </ul>
In addition to the predefined implementations in Collectors, the static factory methods #of(Supplier, BiConsumer, BinaryOperator, Characteristics...) can be used to construct collectors. For example, you could create a collector that accumulates widgets into a TreeSet with:
{@code
Collector<Widget, ?, TreeSet<Widget>> intoSet =
Collector.of(TreeSet::new, TreeSet::add,
(left, right) -> { left.addAll(right); return left; });
}
(This behavior is also implemented by the predefined collector Collectors#toCollection(Supplier)).
Added in 1.8.
Java documentation for java.util.stream.Collector.
Portions of this page are modifications based on work created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License.
Properties
| Handle |
Gets the JNI value of the underlying Android object. (Inherited from IJavaObject) |
| JniIdentityHashCode |
Returns the value of |
| JniManagedPeerState |
State of the managed peer. (Inherited from IJavaPeerable) |
| JniPeerMembers |
Member access and invocation support. (Inherited from IJavaPeerable) |
| PeerReference |
Returns a JniObjectReference of the wrapped Java object instance. (Inherited from IJavaPeerable) |
Methods
| Accumulator() |
A function that folds a value into a mutable result container. |
| Characteristics() |
Returns a |
| Combiner() |
A function that accepts two partial results and merges them. |
| Disposed() |
Called when the instance has been disposed. (Inherited from IJavaPeerable) |
| DisposeUnlessReferenced() |
If there are no outstanding references to this instance, then
calls |
| Finalized() |
Called when the instance has been finalized. (Inherited from IJavaPeerable) |
| Finisher() |
Perform the final transformation from the intermediate accumulation type
|
| Of(ISupplier, IBiConsumer, IBinaryOperator, CollectorCharacteristics[]) |
Returns a new |
| Of(ISupplier, IBiConsumer, IBinaryOperator, IFunction, CollectorCharacteristics[]) |
Returns a new |
| SetJniIdentityHashCode(Int32) |
Set the value returned by |
| SetJniManagedPeerState(JniManagedPeerStates) | (Inherited from IJavaPeerable) |
| SetPeerReference(JniObjectReference) |
Set the value returned by |
| Supplier() |
A function that creates and returns a new mutable result container. |
| UnregisterFromRuntime() |
Unregister this instance so that the runtime will not return it from future Java.Interop.JniRuntime+JniValueManager.PeekValue invocations. (Inherited from IJavaPeerable) |
Extension Methods
| JavaCast<TResult>(IJavaObject) |
Performs an Android runtime-checked type conversion. |
| JavaCast<TResult>(IJavaObject) | |
| GetJniTypeName(IJavaPeerable) | |