diff options
Diffstat (limited to 'subprojects/viatra-runtime/src/main/java/tools/refinery/viatra/runtime/matchers/psystem/aggregations/IMultisetAggregationOperator.java')
-rw-r--r-- | subprojects/viatra-runtime/src/main/java/tools/refinery/viatra/runtime/matchers/psystem/aggregations/IMultisetAggregationOperator.java | 106 |
1 files changed, 106 insertions, 0 deletions
diff --git a/subprojects/viatra-runtime/src/main/java/tools/refinery/viatra/runtime/matchers/psystem/aggregations/IMultisetAggregationOperator.java b/subprojects/viatra-runtime/src/main/java/tools/refinery/viatra/runtime/matchers/psystem/aggregations/IMultisetAggregationOperator.java new file mode 100644 index 00000000..3bc22274 --- /dev/null +++ b/subprojects/viatra-runtime/src/main/java/tools/refinery/viatra/runtime/matchers/psystem/aggregations/IMultisetAggregationOperator.java | |||
@@ -0,0 +1,106 @@ | |||
1 | /******************************************************************************* | ||
2 | * Copyright (c) 2010-2016, Gabor Bergmann, IncQueryLabs Ltd. | ||
3 | * This program and the accompanying materials are made available under the | ||
4 | * terms of the Eclipse Public License v. 2.0 which is available at | ||
5 | * http://www.eclipse.org/legal/epl-v20.html. | ||
6 | * | ||
7 | * SPDX-License-Identifier: EPL-2.0 | ||
8 | *******************************************************************************/ | ||
9 | package tools.refinery.viatra.runtime.matchers.psystem.aggregations; | ||
10 | |||
11 | import java.util.Collection; | ||
12 | import java.util.stream.Stream; | ||
13 | |||
14 | import tools.refinery.viatra.runtime.matchers.aggregators.ExtremumOperator; | ||
15 | |||
16 | /** | ||
17 | * A single column aggregator is used to incrementally compute the aggregate of a multiset of values according to an aggregator operator. | ||
18 | * | ||
19 | * <p> The operator provides two methods of computation: <ul> | ||
20 | * <li>Stateless aggregation of an explicit multiset, provided by {@link #aggregateStatelessly(Collection)}.</li> | ||
21 | * <li>Incremental aggregation, provided by {@link #createNeutral()}, {@link #update(Object, Object, boolean)}, {@link #isNeutral(Object)}, {@link #getAggregate(Object)}. | ||
22 | * </ul> | ||
23 | * | ||
24 | * <p> In case of incremental computation, the aggregable multiset is conceptual; it is not represented by an explicit Collection<Domain> object, but its update operations are tracked. | ||
25 | * | ||
26 | * <p> In case of incremental computation, internal results, potentially distinct from the final aggregate result, may be stored in a helper data structure called <b>accumulator</b>. | ||
27 | * The goal of this distinction is that the final result may not be sufficient for incremental updates (see e.g. {@link ExtremumOperator}). | ||
28 | * | ||
29 | * @author Gabor Bergmann | ||
30 | * | ||
31 | * @param <Domain> the type of elements to be aggregated. | ||
32 | * @param <Accumulator> the type used to store the interim results of the aggregate computation, | ||
33 | * that may be incrementally refreshed upon updates to the multiset, and that can easily yield the final result. | ||
34 | * @param <AggregateResult> the type of the final result of the aggregation to be output. | ||
35 | * | ||
36 | * @since 1.4 | ||
37 | */ | ||
38 | public interface IMultisetAggregationOperator<Domain, Accumulator, AggregateResult> { | ||
39 | |||
40 | /** | ||
41 | * A textual description of the operator. | ||
42 | */ | ||
43 | String getShortDescription(); | ||
44 | |||
45 | /** | ||
46 | * A name or identifier of the operator. | ||
47 | */ | ||
48 | String getName(); | ||
49 | |||
50 | /** | ||
51 | * @return the neutral element, i.e. the interim result of aggregating an empty multiset. | ||
52 | */ | ||
53 | Accumulator createNeutral(); | ||
54 | |||
55 | /** | ||
56 | * @return true if the interim result is equivalent to the neutral element, as if there are no values in the multiset. | ||
57 | * Must return true if the multiset is empty. | ||
58 | */ | ||
59 | boolean isNeutral(Accumulator result); | ||
60 | |||
61 | /** | ||
62 | * @return an updated intermediate result, | ||
63 | * changed to reflect that a given object was added to / removed from the multiset | ||
64 | * (as indicated by the parameter isInsertion) | ||
65 | */ | ||
66 | Accumulator update(Accumulator oldResult, Domain updateValue, boolean isInsertion); | ||
67 | |||
68 | /** | ||
69 | * @return the aggregate result obtained from the given intermediate result. | ||
70 | * May be null to indicate that the current multiset cannot be aggregated (e.g. 0 elements have no minimum). | ||
71 | */ | ||
72 | AggregateResult getAggregate(Accumulator result); | ||
73 | |||
74 | /** | ||
75 | * Calculates the aggregate results from a given stream of values; all values are considered as inserted | ||
76 | * @return the aggregate result, or null if no result can be calculated (e.g. because of an empty stream) | ||
77 | * @since 2.0 | ||
78 | */ | ||
79 | AggregateResult aggregateStream(Stream<Domain> stream); | ||
80 | |||
81 | /** | ||
82 | * Clones the given accumulator (with all its internal contents). | ||
83 | */ | ||
84 | default Accumulator clone(Accumulator original) { | ||
85 | throw new UnsupportedOperationException(); | ||
86 | } | ||
87 | |||
88 | /** | ||
89 | * Combines the given aggregate result and accumulator into a single aggregate result. | ||
90 | */ | ||
91 | default AggregateResult combine(AggregateResult left, Accumulator right) { | ||
92 | throw new UnsupportedOperationException(); | ||
93 | } | ||
94 | |||
95 | default boolean contains(Domain value, Accumulator accumulator) { | ||
96 | throw new UnsupportedOperationException(); | ||
97 | } | ||
98 | |||
99 | /** | ||
100 | * Pretty prints the contents of the given accumulator. | ||
101 | */ | ||
102 | default String prettyPrint(final Accumulator accumulator) { | ||
103 | return accumulator.toString(); | ||
104 | } | ||
105 | |||
106 | } | ||