org.redisson.api.CacheAsync Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of redisson-all Show documentation
Easy Redis Java client and Real-Time Data Platform. Valkey compatible. Sync/Async/RxJava3/Reactive API. Client side caching. Over 50 Redis based Java objects and services: JCache API, Apache Tomcat, Hibernate, Spring, Set, Multimap, SortedSet, Map, List, Queue, Deque, Semaphore, Lock, AtomicLong, Map Reduce, Bloom filter, Scheduler, RPC
There is a newer version: 3.40.2
Show newest version
/**
 * Copyright (c) 2013-2024 Nikita Koksharov
 *
 * 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.redisson.api;

import java.util.Map;
import java.util.Set;

import javax.cache.CacheException;
import javax.cache.event.CacheEntryRemovedListener;
import javax.cache.integration.CacheLoader;
import javax.cache.integration.CacheWriter;

/**
 * Asynchronous interface for JCache
 *
 * @author Nikita Koksharov
 *
 * @param  key type
 * @param  value type
 */
public interface CacheAsync {

    /**
    * This method retrieves an entry from the cache.
    *
    * If the cache uses the read-through pattern, and the method would return null
    * because the entry is not present in the cache, then the cache's {@link CacheLoader}
    * will try to load the entry.
    *
    * @param key the key whose value should be returned
    * @return the element, or null if the entry does not exist.
    * @throws IllegalStateException if the cache is in a closed state
    * @throws NullPointerException if the key is null
    * @throws CacheException if there is a problem retrieving the entry from the cache
    */
    RFuture getAsync(K key);
    
    /**
    * This method accepts a set of requested keys and retrieves a collection of entries from the
    * {@link CacheAsync}, returning them as a {@link Map} of the associated values.
    *
    * If the cache uses the read-through pattern, and the method would return null for a key
    * because an entry is not present in the cache, the Cache's {@link CacheLoader} will try to
    * load the entry. If a key's entry cannot be loaded, the key will not appear in the Map.
    *
    * @param keys The keys whose values should be returned.
    * @return A Map of entries associated with the given keys. If a key is not found
    * in the cache, it will not be in the Map.
    * @throws NullPointerException if keys is null or contains a null
    * @throws IllegalStateException if the cache is in a closed state
    * @throws CacheException if there is a problem retrieving the entries from the cache
    */
    RFuture> getAllAsync(Set keys);
    
    /**
    * This method returns a Boolean true/false value, depending on whether the
    * {@link CacheAsync} has a mapping for a key k such that key.equals(k).
    *
    *
    * @param key the key with a possible mapping in the cache.
    * @return true if such a mapping exists
    * @throws NullPointerException if key is null
    * @throws IllegalStateException if the cache is in a closed state
    * @throws CacheException if there is a problem with the cache
    */
    RFuture containsKeyAsync(K key);
    
    /**
    * This method places the given value V in the cache and associates it with the given key K.
    *
    * If the {@link CacheAsync} already has a mapping for the key, the previous
    * value is replaced by the given value V.
    * This occurs if and only if {@link #containsKeyAsync(Object) c.containsKey(k)}
    * would return true.)
    *
    * @param key the key to place in the cache
    * @param value the value to associate with the given key
    * @return void
    * @throws NullPointerException if the key or value is null
    * @throws IllegalStateException if the cache is in a closed state
    * @throws CacheException if there is a problem with the cache
    */
    RFuture putAsync(K key, V value);
    
    /**
    * This method places the given key and value in the cache.
    * Any value already in the cache is returned and replaced by the new given value.
    * This occurs if and only if {@link #containsKeyAsync(Object) c.containsKey(k)}
    * would return true.)
    * If there was no value already in the cache, the method returns null.
    *
    * @param key the key to place in the cache
    * @param value the value to associate with the given key
    * @return the previous value in the cache, or null if none already existed
    * @throws NullPointerException if the key or value is null
    * @throws IllegalStateException if the cache is in a closed state
    * @throws CacheException if there is a problem with the cache
    */
    RFuture getAndPutAsync(K key, V value);
    
    /**
    * This method copies all of the entries from the given Map to the {@link CacheAsync}.
    *
    * This method is equivalent to calling
    * {@link #putAsync(Object, Object)} on this cache one time for each mapping
    * from key k to value v in the given Map.
    *
    * Individual puts may occur in any order.
    *
    * If entries in the cache corresponding to entries in the Map, or the Map itself, is
    * changed or removed during this operation, then the behavior of this method is
    * not defined.
    *
    * If default consistency mode is enabled, then each put is atomic but not
    * the entire putAll operation. Listeners can observe individual updates.
    *
    * @param map the Map that contains the entries to be copied to the cache
    * @return void
    * @throws NullPointerException if the map is null or contains null keys or values.
    * @throws IllegalStateException if the cache is in a closed state
    * @throws CacheException if there is a problem with the cache.
    */
    RFuture putAllAsync(java.util.Map map);
    
    /**
    * This method places the given key and value in the cache atomically, if the key is
    * not already associated with a value in the cache.
    *
    * @param key the key to place in the cache
    * @param value the value to associate with the given key
    * @return true if the value was successfully placed in the cache
    * @throws NullPointerException if the key or value is null
    * @throws IllegalStateException if the cache is in a closed state
    * @throws CacheException if there is a problem with the cache
    */
    RFuture putIfAbsentAsync(K key, V value);
    
    /**
    * This method deletes the mapping for a given key from the cache, if it is present.
    *
    * This occurs if and only if there is a mapping from key k to
    * value v such that
    * (key==null ? k==null : key.equals(k)).
    *
    *
    This method returns true if the removal was successful,
    * or false if there was no such mapping.
    *
    *
    * @param key the key whose mapping will be deleted
    * @return returns true if successful, or false if there was no mapping
    * @throws NullPointerException if the key is null
    * @throws IllegalStateException if the cache is in a closed state
    * @throws CacheException if there is a problem with the cache
    */
    RFuture removeAsync(K key);
    
    /**
    * This method atomically removes a key's mapping only if it is currently mapped to the
    * provided value.
    *
    * @param key the key whose mapping will be deleted
    * @param oldValue the value that should be mapped to the given key
    * @return returns true if successful, or false if there was no such mapping
    * @throws NullPointerException if the key is null
    * @throws IllegalStateException if the cache is in a closed state
    * @throws CacheException if there is a problem with the cache
    */
    RFuture removeAsync(K key, V oldValue);
    
    /**
    * This method atomically removes the entry for a key only if it is currently mapped to some
    * value.
    *
    * @param key the given key
    * @return the value if it existed, or null if it did not
    * @throws NullPointerException if the key is null.
    * @throws IllegalStateException if the cache is in a closed state
    * @throws CacheException if there is a problem with the cache
    */
    RFuture getAndRemoveAsync(K key);
    
    /**
    * This method atomically replaces an entry only if the key is currently mapped to a
    * given value.
    *
    * @param key the key associated with the given oldValue
    * @param oldValue the value that should be associated with the key
    * @param newValue the value that will be associated with the key
    * @return true if the value was replaced, or false if not
    * @throws NullPointerException if the key or values are null
    * @throws IllegalStateException if the cache is in a closed state
    * @throws CacheException if there is a problem with the cache
    */
    RFuture replaceAsync(K key, V oldValue, V newValue);
    
    /**
    * This method atomically replaces an entry only if the key is currently mapped to some
    * value.
    *
    * @param key the key mapped to the given value
    * @param value the value mapped to the given key
    * @return true if the value was replaced, or false if not
    * @throws NullPointerException if the key or value is null
    * @throws IllegalStateException if the cache is in a closed state
    * @throws CacheException if there is a problem with the cache
    */
    RFuture replaceAsync(K key, V value);
    
    /**
    * This method atomically replaces a given key's value if and only if the key is currently
    * mapped to a value.
    *
    * @param key the key associated with the given value
    * @param value the value associated with the given key
    * @return the previous value mapped to the given key, or
    * null if there was no such mapping.
    * @throws NullPointerException if the key or value is null
    * @throws IllegalStateException if the cache is in a closed state
    * @throws CacheException if there is a problem with the cache
    */
    RFuture getAndReplaceAsync(K key, V value);
    
    /**
    * This method deletes the entries for the given keys.
    *
    * The order in which the individual entries are removed is undefined.
    *
    * For every entry in the key set, the following are called:
    *
    •   any registered {@link CacheEntryRemovedListener}s
    •   if the cache is a write-through cache, the {@link CacheWriter}
    * If the key set is empty, the {@link CacheWriter} is not called.
    *
    * @param keys the keys to remove
    * @return void
    * @throws NullPointerException if keys is null or if it contains a null key
    * @throws IllegalStateException if the cache is in a closed state
    * @throws CacheException if there is a problem with the cache
    */
    RFuture removeAllAsync(Set keys);

    /**
    * This method empties the cache's contents, without notifying listeners or
    * {@link CacheWriter}s.
    *
    * @return void
    * @throws IllegalStateException if the cache is in a closed state
    * @throws CacheException if there is a problem with the cache
    */
    RFuture clearAsync();

    
}