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}