1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
|
/*
* Copyright 2015 Open Networking Laboratory
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.onosproject.store.service;
import org.onlab.util.KryoNamespace;
import org.onosproject.cluster.NodeId;
import org.onosproject.store.Timestamp;
import java.util.Collection;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.ScheduledExecutorService;
import java.util.concurrent.TimeUnit;
import java.util.function.BiFunction;
/**
* Builder for eventually consistent maps.
*
* @param <K> type for map keys
* @param <V> type for map values
*/
public interface EventuallyConsistentMapBuilder<K, V> {
/**
* Sets the name of the map.
* <p>
* Each map is identified by a string map name. EventuallyConsistentMapImpl
* objects in different JVMs that use the same map name will form a
* distributed map across JVMs (provided the cluster service is aware of
* both nodes).
* </p>
* <p>
* Note: This is a mandatory parameter.
* </p>
*
* @param name name of the map
* @return this EventuallyConsistentMapBuilder
*/
EventuallyConsistentMapBuilder<K, V> withName(String name);
/**
* Sets a serializer builder that can be used to create a serializer that
* can serialize both the keys and values put into the map. The serializer
* builder should be pre-populated with any classes that will be put into
* the map.
* <p>
* Note: This is a mandatory parameter.
* </p>
*
* @param serializerBuilder serializer builder
* @return this EventuallyConsistentMapBuilder
*/
EventuallyConsistentMapBuilder<K, V> withSerializer(
KryoNamespace.Builder serializerBuilder);
/**
* Sets the function to use for generating timestamps for map updates.
* <p>
* The client must provide an {@code BiFunction<K, V, Timestamp>}
* which can generate timestamps for a given key. The function is free
* to generate timestamps however it wishes, however these timestamps will
* be used to serialize updates to the map so they must be strict enough
* to ensure updates are properly ordered for the use case (i.e. in some
* cases wallclock time will suffice, whereas in other cases logical time
* will be necessary).
* </p>
* <p>
* Note: This is a mandatory parameter.
* </p>
*
* @param timestampProvider provides a new timestamp
* @return this EventuallyConsistentMapBuilder
*/
EventuallyConsistentMapBuilder<K, V> withTimestampProvider(
BiFunction<K, V, Timestamp> timestampProvider);
/**
* Sets the executor to use for processing events coming in from peers.
*
* @param executor event executor
* @return this EventuallyConsistentMapBuilder
*/
EventuallyConsistentMapBuilder<K, V> withEventExecutor(
ExecutorService executor);
/**
* Sets the executor to use for sending events to peers.
*
* @param executor event executor
* @return this EventuallyConsistentMapBuilder
*/
EventuallyConsistentMapBuilder<K, V> withCommunicationExecutor(
ExecutorService executor);
/**
* Sets the executor to use for background anti-entropy tasks.
*
* @param executor event executor
* @return this EventuallyConsistentMapBuilder
*/
EventuallyConsistentMapBuilder<K, V> withBackgroundExecutor(
ScheduledExecutorService executor);
/**
* Sets a function that can determine which peers to replicate updates to.
* <p>
* The default function replicates to all nodes.
* </p>
*
* @param peerUpdateFunction function that takes a K, V input and returns
* a collection of NodeIds to replicate the event
* to
* @return this EventuallyConsistentMapBuilder
*/
EventuallyConsistentMapBuilder<K, V> withPeerUpdateFunction(
BiFunction<K, V, Collection<NodeId>> peerUpdateFunction);
/**
* Prevents this map from writing tombstones of items that have been
* removed. This may result in zombie items reappearing after they have
* been removed.
* <p>
* The default behavior is tombstones are enabled.
* </p>
*
* @return this EventuallyConsistentMapBuilder
*/
EventuallyConsistentMapBuilder<K, V> withTombstonesDisabled();
/**
* Configures how often to run the anti-entropy background task.
* <p>
* The default anti-entropy period is 5 seconds.
* </p>
*
* @param period anti-entropy period
* @param unit time unit for the period
* @return this EventuallyConsistentMapBuilder
*/
EventuallyConsistentMapBuilder<K, V> withAntiEntropyPeriod(
long period, TimeUnit unit);
/**
* Configure anti-entropy to converge faster at the cost of doing more work
* for each anti-entropy cycle. Suited to maps with low update rate where
* convergence time is more important than throughput.
* <p>
* The default behavior is to do less anti-entropy work at the cost of
* slower convergence.
* </p>
*
* @return this EventuallyConsistentMapBuilder
*/
EventuallyConsistentMapBuilder<K, V> withFasterConvergence();
/**
* Configure the map to persist data to disk.
* <p>
* The default behavior is no persistence
* </p>
*
* @return this EventuallyConsistentMapBuilder
*/
EventuallyConsistentMapBuilder<K, V> withPersistence();
/**
* Builds an eventually consistent map based on the configuration options
* supplied to this builder.
*
* @return new eventually consistent map
* @throws java.lang.RuntimeException if a mandatory parameter is missing
*/
EventuallyConsistentMap<K, V> build();
}
|
