001/*
002 * (C) Copyright 2017 Nuxeo (http://nuxeo.com/) and others.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *     http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 *
016 * Contributors:
017 *     Florent Guillaume
018 */
019package org.nuxeo.runtime.kv;
020
021import java.util.Collection;
022import java.util.Map;
023
024/**
025 * Key/Value Store.
026 * <p>
027 * This is the interface for a Key/Value store, which stores simple values associated to keys.
028 * <p>
029 * A Key/Value store is thread-safe.
030 *
031 * @since 9.1
032 */
033public interface KeyValueStore {
034
035    /**
036     * Sets the value associated to the key.
037     *
038     * @param key the key
039     * @param value the value, which may be {@code null}
040     */
041    void put(String key, byte[] value);
042
043    /**
044     * Sets the value associated to the key.
045     *
046     * @param key the key
047     * @param value the value, which may be {@code null}
048     * @since 9.3
049     */
050    void put(String key, String value);
051
052    /**
053     * Sets the value associated to the key.
054     *
055     * @param key the key
056     * @param value the value, which may be {@code null}
057     * @since 10.2
058     */
059    void put(String key, Long value);
060
061    /**
062     * Sets the value associated to the key, and a TTL.
063     *
064     * @param key the key
065     * @param value the value, which may be {@code null}
066     * @param ttl the TTL, in seconds (0 for infinite)
067     * @since 9.3
068     */
069    void put(String key, byte[] value, long ttl);
070
071    /**
072     * Sets the value associated to the key, and a TTL.
073     *
074     * @param key the key
075     * @param value the value, which may be {@code null}
076     * @param ttl the TTL, in seconds (0 for infinite)
077     * @since 9.3
078     */
079    void put(String key, String value, long ttl);
080
081    /**
082     * Sets the value associated to the key.
083     *
084     * @param key the key
085     * @param value the value, which may be {@code null}
086     * @param ttl the TTL, in seconds (0 for infinite)
087     * @since 10.2
088     */
089    void put(String key, Long value, long ttl);
090
091    /**
092     * Sets the TTL for an existing key.
093     *
094     * @param key the key
095     * @param ttl the TTL, in seconds (0 for infinite)
096     * @return {@code true} if the TTL has been set, or {@code false} if the key does not exist
097     * @since 9.3
098     */
099    boolean setTTL(String key, long ttl);
100
101    /**
102     * Retrieves the value associated to the key.
103     *
104     * @param key the key
105     * @return the value, or {@code null} if there is no value
106     */
107    byte[] get(String key);
108
109    /**
110     * Retrieves the value associated to the key.
111     *
112     * @param key the key
113     * @return the value, or {@code null} if there is no value
114     * @throws IllegalArgumentException if the value cannot be returned as a {@link String}
115     * @since 9.3
116     */
117    String getString(String key);
118
119    /**
120     * Retrieves the value associated to the key.
121     *
122     * @param key the key
123     * @return the value, or {@code null} if there is no value
124     * @throws NumberFormatException if the value cannot be returned as a {@link Long}
125     * @since 10.2
126     */
127    Long getLong(String key) throws NumberFormatException; // NOSONAR
128
129    /**
130     * Retrieves the key/value map associated with the keys.
131     *
132     * @param keys the keys
133     * @return the key/value map
134     * @since 9.10
135     */
136    Map<String, byte[]> get(Collection<String> keys);
137
138    /**
139     * Retrieves the key/value map associated with the  keys.
140     *
141     * @param keys the keys
142     * @return the key/value map
143     * @throws IllegalArgumentException if one of the values cannot be returned as a {@link String}
144     * @since 9.10
145     */
146    Map<String, String> getStrings(Collection<String> keys);
147
148    /**
149     * Retrieves the key/value map associated with the  keys.
150     *
151     * @param keys the keys
152     * @return the key/value map
153     * @throws NumberFormatException if one of the values cannot be returned as a {@link Long}
154     * @since 10.2
155     */
156    Map<String, Long> getLongs(Collection<String> keys) throws NumberFormatException; // NOSONAR
157
158    /**
159     * Atomically sets the value associated to the key to the given value if the current value is the expected value.
160     * <p>
161     * Note value comparison is done by value and not by reference.
162     *
163     * @param key the key
164     * @param expected the expected value, which may be {@code null}
165     * @param value the updated value, which may be {@code null}
166     * @return {@code true} if the value was updated, or {@code false} if not (the expected value was not found)
167     */
168    boolean compareAndSet(String key, byte[] expected, byte[] value);
169
170    /**
171     * Atomically sets the value associated to the key to the given value, with the given TTL, if the current value is
172     * the expected value.
173     * <p>
174     * Note value comparison is done by value and not by reference.
175     *
176     * @param key the key
177     * @param expected the expected value, which may be {@code null}
178     * @param value the updated value, which may be {@code null}
179     * @param ttl the TTL, in seconds (0 for infinite)
180     * @return {@code true} if the value was updated, or {@code false} if not (the expected value was not found)
181     * @since 9.3
182     */
183    boolean compareAndSet(String key, byte[] expected, byte[] value, long ttl);
184
185    /**
186     * Atomically sets the value associated to the key to the given value if the current value is the expected value.
187     * <p>
188     * Note value comparison is done by value and not by reference.
189     *
190     * @param key the key
191     * @param expected the expected value, which may be {@code null}
192     * @param value the updated value, which may be {@code null}
193     * @return {@code true} if the value was updated, or {@code false} if not (the expected value was not found)
194     * @since 9.3
195     */
196    boolean compareAndSet(String key, String expected, String value);
197
198    /**
199     * Atomically sets the value associated to the key to the given value, with the given TTL, if the current value is
200     * the expected value.
201     * <p>
202     * Note value comparison is done by value and not by reference.
203     *
204     * @param key the key
205     * @param expected the expected value, which may be {@code null}
206     * @param value the updated value, which may be {@code null}
207     * @param ttl the TTL, in seconds (0 for infinite)
208     * @return {@code true} if the value was updated, or {@code false} if not (the expected value was not found)
209     * @since 9.3
210     */
211    boolean compareAndSet(String key, String expected, String value, long ttl);
212
213    /**
214     * Atomically adds the delta to the value associated to the key, interpreted as a long represented as a string.
215     * <p>
216     * If the value does not exist (if {@link #get} would return {@code null}), it is interpreted as {@code 0}.
217     *
218     * @param key the key
219     * @param delta the delta to add
220     * @return the new value
221     * @throws NumberFormatException if the existing value cannot be interpreted as a {@code long}
222     * @since 10.2
223     */
224    long addAndGet(String key, long delta);
225
226}