SAMZA-1268: Javadoc cleanup for public APIs for 0.13 release
[samza.git] / samza-api / src / main / java / org / apache / samza / operators / windows / Window.java
1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 */
19 package org.apache.samza.operators.windows;
20
21 import org.apache.samza.annotation.InterfaceStability;
22 import org.apache.samza.operators.triggers.Trigger;
23
24 /**
25 * Groups incoming messages in the {@link org.apache.samza.operators.MessageStream} into finite windows for processing.
26 *
27 * <p> A window is uniquely identified by its {@link WindowKey}. A window can have one or more associated
28 * {@link Trigger}s that determine when results from the {@link Window} are emitted.
29 *
30 * <p> Each emitted result contains one or more messages in the window and is called a {@link WindowPane}.
31 * A pane can include all messages collected for the window so far or only the new messages
32 * since the last emitted pane. (as determined by the {@link AccumulationMode})
33 *
34 * <p> A window can have early triggers that allow emitting {@link WindowPane}s speculatively before all data for the
35 * window has arrived, or late triggers that allow handling late arrivals of data.
36 *
37 * <p> A {@link Window} is said to be as "keyed" when the incoming {@link org.apache.samza.operators.MessageStream}
38 * is first grouped based on the provided key, and windowing is applied on the grouped stream.
39 *
40 * window wk1 (with its triggers)
41 * +--------------------------------+
42 * ------------+--------+-----------+
43 * | | | |
44 * | pane 1 |pane2 | pane3 |
45 * +-----------+--------+-----------+
46 *
47 * -----------------------------------
48 * incoming message stream ------+
49 * -----------------------------------
50 * window wk2
51 * +---------------------+---------+
52 * | pane 1| pane 2 | pane 3 |
53 * | | | |
54 * +---------+-----------+---------+
55 *
56 * window wk3
57 * +----------+-----------+---------+
58 * | | | |
59 * | pane 1 | pane 2 | pane 3|
60 * | | | |
61 * +----------+-----------+---------+
62 *
63 *
64 * <p> Use {@link Windows} to create various windows and {@link org.apache.samza.operators.triggers.Triggers}
65 * to create their triggers.
66 *
67 * @param <M> the type of the input message
68 * @param <K> the type of the key in the message
69 * @param <WV> the type of the value in the window
70 */
71 @InterfaceStability.Unstable
72 public interface Window<M, K, WV> {
73
74 /**
75 * Set the early triggers for this {@link Window}.
76 * <p> Use the {@link org.apache.samza.operators.triggers.Triggers} APIs to create instances of {@link Trigger}
77 *
78 * @param trigger the early trigger
79 * @return the {@link Window} function with the early trigger
80 */
81 Window<M, K, WV> setEarlyTrigger(Trigger<M> trigger);
82
83 /**
84 * Set the late triggers for this {@link Window}.
85 * <p> Use the {@link org.apache.samza.operators.triggers.Triggers} APIs to create instances of {@link Trigger}
86 *
87 * @param trigger the late trigger
88 * @return the {@link Window} function with the late trigger
89 */
90 Window<M, K, WV> setLateTrigger(Trigger<M> trigger);
91
92 /**
93 * Specify how a {@link Window} should process its previously emitted {@link WindowPane}s.
94 * <p> There are two types of {@link AccumulationMode}s:
95 * <ul>
96 * <li> ACCUMULATING: Specifies that window panes should include all messages collected for the window so far,
97 * even if they were included in previously emitted window panes.
98 * <li> DISCARDING: Specifies that window panes should only include messages collected for this window since
99 * the last emitted window pane.
100 * </ul>
101 *
102 * @param mode the accumulation mode
103 * @return the {@link Window} function with {@code mode} set as its {@link AccumulationMode}.
104 */
105 Window<M, K, WV> setAccumulationMode(AccumulationMode mode);
106
107 }