blob: 6414d6e649e1472324caa42b2d8fbf9f8f64804f [file] [log] [blame]
Jonathan Hartdb3af892015-01-26 13:19:07 -08001/*
2 * Copyright 2015 Open Networking Laboratory
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
Jonathan Hart6ec029a2015-03-24 17:12:35 -070016package org.onosproject.store.service;
Jonathan Hartdb3af892015-01-26 13:19:07 -080017
18import java.util.Collection;
19import java.util.Map;
20import java.util.Set;
21
22/**
23 * A distributed, eventually consistent map.
Jonathan Hart4f397e82015-02-04 09:10:41 -080024 * <p>
Jonathan Hartdb3af892015-01-26 13:19:07 -080025 * This map does not offer read after writes consistency. Operations are
26 * serialized via the timestamps issued by the clock service. If two updates
27 * are in conflict, the update with the more recent timestamp will endure.
Jonathan Hart4f397e82015-02-04 09:10:41 -080028 * </p><p>
Jonathan Hartdb3af892015-01-26 13:19:07 -080029 * The interface is mostly similar to {@link java.util.Map} with some minor
30 * semantic changes and the addition of a listener framework (because the map
31 * can be mutated by clients on other instances, not only through the local Java
32 * API).
Jonathan Hart4f397e82015-02-04 09:10:41 -080033 * </p><p>
Jonathan Hartdb3af892015-01-26 13:19:07 -080034 * Clients are expected to register an
Jonathan Hart77bdd262015-02-03 09:07:48 -080035 * {@link EventuallyConsistentMapListener} if they
Jonathan Hartdb3af892015-01-26 13:19:07 -080036 * are interested in receiving notifications of update to the map.
Jonathan Hart4f397e82015-02-04 09:10:41 -080037 * </p><p>
38 * Null values are not allowed in this map.
39 * </p>
Jonathan Hartdb3af892015-01-26 13:19:07 -080040 */
41public interface EventuallyConsistentMap<K, V> {
42
43 /**
44 * Returns the number of key-value mappings in this map.
45 *
46 * @return number of key-value mappings
47 */
Sho SHIMIZU3310a342015-05-13 12:14:05 -070048 int size();
Jonathan Hartdb3af892015-01-26 13:19:07 -080049
50 /**
51 * Returns true if this map is empty.
52 *
53 * @return true if this map is empty, otherwise false
54 */
Sho SHIMIZU3310a342015-05-13 12:14:05 -070055 boolean isEmpty();
Jonathan Hartdb3af892015-01-26 13:19:07 -080056
57 /**
58 * Returns true if the map contains a mapping for the specified key.
59 *
60 * @param key the key to check if this map contains
61 * @return true if this map has a mapping for the key, otherwise false
62 */
Sho SHIMIZU3310a342015-05-13 12:14:05 -070063 boolean containsKey(K key);
Jonathan Hartdb3af892015-01-26 13:19:07 -080064
65 /**
66 * Returns true if the map contains a mapping from any key to the specified
67 * value.
68 *
69 * @param value the value to check if this map has a mapping for
70 * @return true if this map has a mapping to this value, otherwise false
71 */
Sho SHIMIZU3310a342015-05-13 12:14:05 -070072 boolean containsValue(V value);
Jonathan Hartdb3af892015-01-26 13:19:07 -080073
74 /**
75 * Returns the value mapped to the specified key.
76 *
77 * @param key the key to look up in this map
78 * @return the value mapped to the key, or null if no mapping is found
79 */
Sho SHIMIZU3310a342015-05-13 12:14:05 -070080 V get(K key);
Jonathan Hartdb3af892015-01-26 13:19:07 -080081
82 /**
83 * Associates the specified value to the specified key in this map.
84 * <p>
85 * Note: this differs from the specification of {@link java.util.Map}
86 * because it does not return the previous value associated with the key.
87 * Clients are expected to register an
Jonathan Hart77bdd262015-02-03 09:07:48 -080088 * {@link EventuallyConsistentMapListener} if
Jonathan Hartdb3af892015-01-26 13:19:07 -080089 * they are interested in receiving notification of updates to the map.
Jonathan Hart4f397e82015-02-04 09:10:41 -080090 * </p><p>
91 * Null values are not allowed in the map.
Jonathan Hartdb3af892015-01-26 13:19:07 -080092 * </p>
93 *
94 * @param key the key to add a mapping for in this map
95 * @param value the value to associate with the key in this map
96 */
Sho SHIMIZU3310a342015-05-13 12:14:05 -070097 void put(K key, V value);
Jonathan Hartdb3af892015-01-26 13:19:07 -080098
99 /**
100 * Removes the mapping associated with the specified key from the map.
101 * <p>
Madan Jampani43e9c9c2015-06-26 14:16:46 -0700102 * Clients are expected to register an {@link EventuallyConsistentMapListener} if
Jonathan Hartdb3af892015-01-26 13:19:07 -0800103 * they are interested in receiving notification of updates to the map.
104 * </p>
105 *
106 * @param key the key to remove the mapping for
Madan Jampani43e9c9c2015-06-26 14:16:46 -0700107 * @return previous value associated with key, or null if there was no mapping for key.
Jonathan Hartdb3af892015-01-26 13:19:07 -0800108 */
Madan Jampani43e9c9c2015-06-26 14:16:46 -0700109 V remove(K key);
Jonathan Hartdb3af892015-01-26 13:19:07 -0800110
111 /**
Jonathan Hart5ec32ba2015-02-05 13:33:58 -0800112 * Removes the given key-value mapping from the map, if it exists.
113 * <p>
114 * This actually means remove any values up to and including the timestamp
Madan Jampanibcf1a482015-06-24 19:05:56 -0700115 * given by the map's timestampProvider.
Jonathan Hart5ec32ba2015-02-05 13:33:58 -0800116 * Any mappings that produce an earlier timestamp than this given key-value
117 * pair will be removed, and any mappings that produce a later timestamp
118 * will supersede this remove.
119 * </p><p>
120 * Note: this differs from the specification of {@link java.util.Map}
121 * because it does not return a boolean indication whether a value was removed.
122 * Clients are expected to register an
Jonathan Hart77bdd262015-02-03 09:07:48 -0800123 * {@link EventuallyConsistentMapListener} if
Jonathan Hart5ec32ba2015-02-05 13:33:58 -0800124 * they are interested in receiving notification of updates to the map.
125 * </p>
126 *
127 * @param key the key to remove the mapping for
128 * @param value the value mapped to the key
129 */
Sho SHIMIZU3310a342015-05-13 12:14:05 -0700130 void remove(K key, V value);
Jonathan Hart5ec32ba2015-02-05 13:33:58 -0800131
132 /**
Jonathan Hartdb3af892015-01-26 13:19:07 -0800133 * Adds mappings for all key-value pairs in the specified map to this map.
134 * <p>
135 * This will be more efficient in communication than calling individual put
136 * operations.
137 * </p>
138 *
139 * @param m a map of values to add to this map
140 */
Sho SHIMIZU3310a342015-05-13 12:14:05 -0700141 void putAll(Map<? extends K, ? extends V> m);
Jonathan Hartdb3af892015-01-26 13:19:07 -0800142
143 /**
144 * Removes all mappings from this map.
145 */
Sho SHIMIZU3310a342015-05-13 12:14:05 -0700146 void clear();
Jonathan Hartdb3af892015-01-26 13:19:07 -0800147
148 /**
149 * Returns a set of the keys in this map. Changes to the set are not
150 * reflected back to the map.
151 *
152 * @return set of keys in the map
153 */
Sho SHIMIZU3310a342015-05-13 12:14:05 -0700154 Set<K> keySet();
Jonathan Hartdb3af892015-01-26 13:19:07 -0800155
156 /**
157 * Returns a collections of values in this map. Changes to the collection
158 * are not reflected back to the map.
159 *
160 * @return collection of values in the map
161 */
Sho SHIMIZU3310a342015-05-13 12:14:05 -0700162 Collection<V> values();
Jonathan Hartdb3af892015-01-26 13:19:07 -0800163
164 /**
165 * Returns a set of mappings contained in this map. Changes to the set are
166 * not reflected back to the map.
167 *
168 * @return set of key-value mappings in this map
169 */
Sho SHIMIZU3310a342015-05-13 12:14:05 -0700170 Set<Map.Entry<K, V>> entrySet();
Jonathan Hartdb3af892015-01-26 13:19:07 -0800171
172 /**
173 * Adds the specified listener to the map which will be notified whenever
174 * the mappings in the map are changed.
175 *
176 * @param listener listener to register for events
177 */
Sho SHIMIZU3310a342015-05-13 12:14:05 -0700178 void addListener(EventuallyConsistentMapListener<K, V> listener);
Jonathan Hartdb3af892015-01-26 13:19:07 -0800179
180 /**
181 * Removes the specified listener from the map such that it will no longer
182 * receive change notifications.
183 *
184 * @param listener listener to deregister for events
185 */
Sho SHIMIZU3310a342015-05-13 12:14:05 -0700186 void removeListener(EventuallyConsistentMapListener<K, V> listener);
Jonathan Hartdb3af892015-01-26 13:19:07 -0800187
188 /**
189 * Shuts down the map and breaks communication between different instances.
190 * This allows the map objects to be cleaned up and garbage collected.
191 * Calls to any methods on the map subsequent to calling destroy() will
192 * throw a {@link java.lang.RuntimeException}.
193 */
Sho SHIMIZU3310a342015-05-13 12:14:05 -0700194 void destroy();
Jonathan Hartdb3af892015-01-26 13:19:07 -0800195}