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
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
|
/*
* 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 java.util.Collection;
import java.util.Map;
import java.util.Set;
import java.util.function.BiFunction;
/**
* A distributed, eventually consistent map.
* <p>
* This map does not offer read after writes consistency. Operations are
* serialized via the timestamps issued by the clock service. If two updates
* are in conflict, the update with the more recent timestamp will endure.
* </p><p>
* The interface is mostly similar to {@link java.util.Map} with some minor
* semantic changes and the addition of a listener framework (because the map
* can be mutated by clients on other instances, not only through the local Java
* API).
* </p><p>
* Clients are expected to register an
* {@link EventuallyConsistentMapListener} if they
* are interested in receiving notifications of update to the map.
* </p><p>
* Null values are not allowed in this map.
* </p>
*/
public interface EventuallyConsistentMap<K, V> {
/**
* Returns the number of key-value mappings in this map.
*
* @return number of key-value mappings
*/
int size();
/**
* Returns true if this map is empty.
*
* @return true if this map is empty, otherwise false
*/
boolean isEmpty();
/**
* Returns true if the map contains a mapping for the specified key.
*
* @param key the key to check if this map contains
* @return true if this map has a mapping for the key, otherwise false
*/
boolean containsKey(K key);
/**
* Returns true if the map contains a mapping from any key to the specified
* value.
*
* @param value the value to check if this map has a mapping for
* @return true if this map has a mapping to this value, otherwise false
*/
boolean containsValue(V value);
/**
* Returns the value mapped to the specified key.
*
* @param key the key to look up in this map
* @return the value mapped to the key, or null if no mapping is found
*/
V get(K key);
/**
* Associates the specified value to the specified key in this map.
* <p>
* Note: this differs from the specification of {@link java.util.Map}
* because it does not return the previous value associated with the key.
* Clients are expected to register an
* {@link EventuallyConsistentMapListener} if
* they are interested in receiving notification of updates to the map.
* </p><p>
* Null values are not allowed in the map.
* </p>
*
* @param key the key to add a mapping for in this map
* @param value the value to associate with the key in this map
*/
void put(K key, V value);
/**
* Removes the mapping associated with the specified key from the map.
* <p>
* Clients are expected to register an {@link EventuallyConsistentMapListener} if
* they are interested in receiving notification of updates to the map.
* </p>
*
* @param key the key to remove the mapping for
* @return previous value associated with key, or null if there was no mapping for key.
*/
V remove(K key);
/**
* Removes the given key-value mapping from the map, if it exists.
* <p>
* This actually means remove any values up to and including the timestamp
* given by the map's timestampProvider.
* Any mappings that produce an earlier timestamp than this given key-value
* pair will be removed, and any mappings that produce a later timestamp
* will supersede this remove.
* </p><p>
* Note: this differs from the specification of {@link java.util.Map}
* because it does not return a boolean indication whether a value was removed.
* Clients are expected to register an
* {@link EventuallyConsistentMapListener} if
* they are interested in receiving notification of updates to the map.
* </p>
*
* @param key the key to remove the mapping for
* @param value the value mapped to the key
*/
void remove(K key, V value);
/**
* Attempts to compute a mapping for the specified key and its current mapped
* value (or null if there is no current mapping).
* <p>
* If the function returns null, the mapping is removed (or remains absent if initially absent).
* @param key map key
* @param recomputeFunction function to recompute a new value
* @return new value
*/
V compute(K key, BiFunction<K, V, V> recomputeFunction);
/**
* Adds mappings for all key-value pairs in the specified map to this map.
* <p>
* This will be more efficient in communication than calling individual put
* operations.
* </p>
*
* @param m a map of values to add to this map
*/
void putAll(Map<? extends K, ? extends V> m);
/**
* Removes all mappings from this map.
*/
void clear();
/**
* Returns a set of the keys in this map. Changes to the set are not
* reflected back to the map.
*
* @return set of keys in the map
*/
Set<K> keySet();
/**
* Returns a collections of values in this map. Changes to the collection
* are not reflected back to the map.
*
* @return collection of values in the map
*/
Collection<V> values();
/**
* Returns a set of mappings contained in this map. Changes to the set are
* not reflected back to the map.
*
* @return set of key-value mappings in this map
*/
Set<Map.Entry<K, V>> entrySet();
/**
* Adds the specified listener to the map which will be notified whenever
* the mappings in the map are changed.
*
* @param listener listener to register for events
*/
void addListener(EventuallyConsistentMapListener<K, V> listener);
/**
* Removes the specified listener from the map such that it will no longer
* receive change notifications.
*
* @param listener listener to deregister for events
*/
void removeListener(EventuallyConsistentMapListener<K, V> listener);
/**
* Shuts down the map and breaks communication between different instances.
* This allows the map objects to be cleaned up and garbage collected.
* Calls to any methods on the map subsequent to calling destroy() will
* throw a {@link java.lang.RuntimeException}.
*/
void destroy();
}
|
