com.alachisoft.ncache.client.Cache Maven / Gradle / Ivy
package com.alachisoft.ncache.client;
// Copyright (c) 2021 Alachisoft
//
// 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
import com.alachisoft.ncache.client.datastructures.DataStructureManager;
import com.alachisoft.ncache.client.services.MessagingService;
import com.alachisoft.ncache.client.services.NotificationService;
import com.alachisoft.ncache.client.services.SearchService;
import com.alachisoft.ncache.runtime.caching.CacheItemAttributes;
import com.alachisoft.ncache.runtime.caching.ReadThruOptions;
import com.alachisoft.ncache.runtime.caching.WriteThruOptions;
import com.alachisoft.ncache.runtime.exceptions.*;
import com.alachisoft.ncache.runtime.util.TimeSpan;
import java.util.Enumeration;
import java.util.Iterator;
import java.util.Map;
import java.util.concurrent.FutureTask;
/**
* This interface contians the services and methods that are used to perform operations on the cache.
*/
public interface Cache extends Enumeration, AutoCloseable {
///#region fields
/**
* Gets the number of items stored in the cache.
* @return The number of items stored in the cache.
* @throws com.alachisoft.ncache.runtime.exceptions.CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
*/
long getCount() throws CacheException;
/**
* Displays the information related to this client.
* @return The information related to this client.
* @throws com.alachisoft.ncache.runtime.exceptions.CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
*/
ClientInfo getClientInfo() throws CacheException;
/**
* Gets the information of all connected clients to the cache.
* @return A list that contains information of all client connected to the cache.
* @throws com.alachisoft.ncache.runtime.exceptions.CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
*/
java.util.List getConnectedClientList() throws CacheException;
///#endregion
///#region services
/**
* Gets an instance of {@link MessagingService}
* @return An instance of {@link com.alachisoft.ncache.client.services.MessagingService}
* @throws com.alachisoft.ncache.runtime.exceptions.CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
*/
MessagingService getMessagingService() throws CacheException;
/**
* Gets an instance of {@link SearchService}.
* @return An instance of {@link com.alachisoft.ncache.client.services.SearchService}
* @throws com.alachisoft.ncache.runtime.exceptions.CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
*/
SearchService getSearchService()throws CacheException;
/**
* Gets an instance of {@link NotificationService}.
* @return An instance of {@link com.alachisoft.ncache.client.services.NotificationService}
* @throws com.alachisoft.ncache.runtime.exceptions.CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
*/
NotificationService getNotificationService() throws CacheException;
/**
* Gets an instance of {@link DataStructureManager}.
* @return An instance of {@link com.alachisoft.ncache.client.datastructures.DataStructureManager}
* @throws com.alachisoft.ncache.runtime.exceptions.CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
*/
DataStructureManager getDataStructuresManager()throws CacheException;
///endregion
// region Add Operations
/**
* Adds an item into the Cache object with a cache key to reference its location.
* @param key Unique key to identify the cache item.
* @param value The item (object) to be stored in the cache.
* @return Represents the version of each cache item.
* @throws com.alachisoft.ncache.runtime.exceptions.CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
* @throws java.lang.IllegalArgumentException
*/
CacheItemVersion add(String key, Object value) throws CacheException,IllegalArgumentException;
/**
* Adds a {@link com.alachisoft.ncache.client.CacheItem} to the cache.
* Using CacheItem, you can also specify properties for the cache items, for e.g., expiration and priority.
* @param key Unique key to identify the cache item.
* @param item {@link com.alachisoft.ncache.client.CacheItem} that is to be stored in the cache.
* @return Represents the version of each cache item.
* @throws com.alachisoft.ncache.runtime.exceptions.CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
* @throws java.lang.IllegalArgumentException
*/
CacheItemVersion add(String key, CacheItem item) throws CacheException,IllegalArgumentException;
/**
* Adds a {@link com.alachisoft.ncache.client.CacheItem} to the cache. It also lets you specify the WriteThruOptions.
* Using CacheItem, you can also specify properties for the cache items, for e.g., expiration and priority.
* @param key Unique key to identify the cache item.
* @param item {@link com.alachisoft.ncache.client.CacheItem} that is to be stored in the cache.
* @param writeThruOptions {@link com.alachisoft.ncache.runtime.caching.WriteThruOptions} regarding updating the data source. This can be either WriteThru, WriteBehind or None.
* @return Represents the version of each cache item.
* @throws com.alachisoft.ncache.runtime.exceptions.CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
* @throws java.lang.IllegalArgumentException
*/
CacheItemVersion add(String key, CacheItem item, WriteThruOptions writeThruOptions) throws CacheException,IllegalArgumentException;
/**
* Adds a Map of cache keys with {@link com.alachisoft.ncache.client.CacheItem} to the cache.
* The CacheItem contains properties to associate with the item, like expiration, dependencies and eviction information.
* @param items {@link java.util.Map} of keys and {@link com.alachisoft.ncache.client.CacheItem}. Keys must be unique.
* @return {@link java.util.Map} of Keys along with Exception that were unable to store in cache.
* @throws com.alachisoft.ncache.runtime.exceptions.CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
* @throws java.lang.IllegalArgumentException
*/
java.util.Map addBulk(java.util.Map items) throws CacheException,IllegalArgumentException;
/**
* Adds a Map of cache keys with {@link com.alachisoft.ncache.client.CacheItem} to the cache with the WriteThruOptions.
* The CacheItem contains properties to associate with the item, like expiration, dependencies and eviction information.
* @param items {@link java.util.Map} of keys and {@link com.alachisoft.ncache.client.CacheItem}. Keys must be unique.
* @param writeThruOptions {@link com.alachisoft.ncache.runtime.caching.WriteThruOptions} regarding updating the data source. This can be either WriteThru, WriteBehind or None.
* @return {@link java.util.Map} of Keys along with Exception that were unable to store in cache.
* @throws com.alachisoft.ncache.runtime.exceptions.CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
* @throws java.lang.IllegalArgumentException
*/
java.util.Map addBulk(java.util.Map items, WriteThruOptions writeThruOptions)throws CacheException,IllegalArgumentException;
/**
* Adds an object into the cache asynchronously with a cache key to reference its location.
* @param key Unique key to identify the cache item.
* @param value The item (object) to be stored in the cache.
* @return
* Future Task that performs an add operation in the background. Once completed returns version of
* cache item that was added in cache. Methods of {@link java.util.concurrent.FutureTask} can be used to determine status
* of the task i.e. isDone(), isCancelled().
* @throws com.alachisoft.ncache.runtime.exceptions.CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
* @throws java.lang.IllegalArgumentException
*/
FutureTask addAsync(String key, Object value) throws CacheException,IllegalArgumentException;
/**
* Adds a {@link com.alachisoft.ncache.client.CacheItem} to the cache asynchronously with a cache key to reference its location.
* @param key Unique key to identify the cache item.
* @param item {@link com.alachisoft.ncache.client.CacheItem} that is to be stored in the cache.
* @return
* Future Task that performs an add operation in the background. Once completed returns version of
* cache item that was added in cache. Methods of {@link java.util.concurrent.FutureTask} can be used to determine status
* of the task i.e. isDone(), isCancelled().
* @throws com.alachisoft.ncache.runtime.exceptions.CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
* @throws java.lang.IllegalArgumentException
*/
FutureTask addAsync(String key, CacheItem item) throws CacheException,IllegalArgumentException;
/**
* Adds a {@link com.alachisoft.ncache.client.CacheItem} to the cache asynchronously with a cache key to reference its location and WriteThruOptions.
* @param key Unique key to identify the cache item.
* @param item {@link com.alachisoft.ncache.client.CacheItem} that is to be stored in the cache.
* @param writeThruOptions {@link com.alachisoft.ncache.runtime.caching.WriteThruOptions} regarding updating the data source. This can be either WriteThru, WriteBehind or None.
* @return
* Future Task that performs an add operation in the background. Once completed returns version of
* cache item that was added in cache. Methods of {@link java.util.concurrent.FutureTask} can be used to determine status
* of the task i.e. isDone(), isCancelled().
* @throws com.alachisoft.ncache.runtime.exceptions.CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
* @throws java.lang.IllegalArgumentException
*/
FutureTask addAsync(String key, CacheItem item, WriteThruOptions writeThruOptions) throws CacheException,IllegalArgumentException;
// endregion
///#region Insert Operations
/**
* Inserts an item (object) into the cache.
* @param key Unique key to identify the cache item.
* @param value The item (object) that is to be inserted into the cache.
* @return Represents the version of each cache item.
* @throws com.alachisoft.ncache.runtime.exceptions.CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
* @throws java.lang.IllegalArgumentException
*/
CacheItemVersion insert(String key, Object value) throws CacheException,IllegalArgumentException;
/**
* Inserts a {@link com.alachisoft.ncache.client.CacheItem} to the cache.
* @param key Unique key to identify the cache item.
* @param item The CacheItem that is to be inserted into the cache.
* @return Represents the version of each cache item.
* @throws com.alachisoft.ncache.runtime.exceptions.CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
* @throws java.lang.IllegalArgumentException
*/
CacheItemVersion insert(String key, CacheItem item) throws CacheException,IllegalArgumentException ;
/**
* Inserts a {@link com.alachisoft.ncache.client.CacheItem} to the cache, allowing to specify the Write-Through options.
* @param key Unique key to identify the cache item.
* @param item The CacheItem that is to be inserted into the cache.
* @param writeThruOptions {@link com.alachisoft.ncache.runtime.caching.WriteThruOptions} regarding updating the data source. This can be either WriteThru, WriteBehind or None.
* @return Represents the version of each cache item.
* @throws com.alachisoft.ncache.runtime.exceptions.CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
* @throws java.lang.IllegalArgumentException
*/
CacheItemVersion insert(String key, CacheItem item, WriteThruOptions writeThruOptions) throws CacheException,IllegalArgumentException ;
/**
* Inserts a {@link com.alachisoft.ncache.client.CacheItem} to the cache, allowing to specify the Write-Through options.
* @param key Unique key to identify the cache item.
* @param item The CacheItem that is to be inserted into the cache.
* @param writeThruOptions {@link com.alachisoft.ncache.runtime.caching.WriteThruOptions} regarding updating the data source. This can be either WriteThru, WriteBehind or None.
* @param lockHandle An instance of {@link LockHandle} that holds the lock information. If the item is locked, then it can only be updated if the correct lockHandle is specified.
* @param releaseLock A flag to determine whether or not the lock should be released after operation is performed.
* @return Represents the version of each cache item.
* @throws com.alachisoft.ncache.runtime.exceptions.CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
* @throws java.lang.IllegalArgumentException
*/
CacheItemVersion insert(String key, CacheItem item, WriteThruOptions writeThruOptions, LockHandle lockHandle, boolean releaseLock) throws CacheException,IllegalArgumentException;
/**
* Inserts a Map of cache keys with {@link com.alachisoft.ncache.client.CacheItem} to the cache.
* The CacheItem contains properties to associate with the item, like expiration, dependencies and eviction information.
* @param items {@link java.util.Map} of keys and {@link com.alachisoft.ncache.client.CacheItem}. Keys must be unique.
* @return {@link java.util.Map} of Keys along with Exception that were unable to store in cache.
* @throws com.alachisoft.ncache.runtime.exceptions.CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
* @throws java.lang.IllegalArgumentException
*/
java.util.Map insertBulk(java.util.Map items) throws CacheException,IllegalArgumentException;
/**
* Inserts a Map of cache keys with {@link com.alachisoft.ncache.client.CacheItem} to the cache with the WriteThruOptions.
* The CacheItem contains properties to associate with the item, like expiration, dependencies and eviction information.
* @param items {@link java.util.Map} of keys and {@link com.alachisoft.ncache.client.CacheItem}. Keys must be unique.
* @param writeThruOptions {@link com.alachisoft.ncache.runtime.caching.WriteThruOptions} regarding updating the data source. This can be either WriteThru, WriteBehind or None.
* @return {@link java.util.Map} of Keys along with Exception that were unable to store in cache.
* @throws com.alachisoft.ncache.runtime.exceptions.CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
* @throws java.lang.IllegalArgumentException
*/
java.util.Map insertBulk(java.util.Map items, WriteThruOptions writeThruOptions) throws CacheException,IllegalArgumentException;
/**
* Inserts an object into the cache asynchronously with a cache key to reference its location.
* @param key Unique key to identify the cache item.
* @param value The item (object) to be stored in the cache.
* @return
* Future Task that performs an insert operation in the background. Once completed returns version of
* cache item that was added in cache. Methods of {@link java.util.concurrent.FutureTask} can be used to determine status
* of the task i.e. isDone(), isCancelled().
* @throws com.alachisoft.ncache.runtime.exceptions.CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
* @throws java.lang.IllegalArgumentException
*/
FutureTask insertAsync(String key, Object value) throws CacheException,IllegalArgumentException;
/**
* Inserts a {@link com.alachisoft.ncache.client.CacheItem} to the cache asynchronously with a cache key to reference its location.
* @param key Unique key to identify the cache item.
* @param item {@link com.alachisoft.ncache.client.CacheItem} that is to be stored in the cache.
* @return
* Future Task that performs an insert operation in the background. Once completed returns version of
* cache item that was added in cache. Methods of {@link java.util.concurrent.FutureTask} can be used to determine status
* of the task i.e. isDone(), isCancelled().
* @throws com.alachisoft.ncache.runtime.exceptions.CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
* @throws java.lang.IllegalArgumentException
*/
FutureTask insertAsync(String key, CacheItem item) throws CacheException,IllegalArgumentException;
/**
* Inserts a {@link com.alachisoft.ncache.client.CacheItem} to the cache asynchronously with a cache key to reference its location and WriteThruOptions.
* @param key Unique key to identify the cache item.
* @param item {@link com.alachisoft.ncache.client.CacheItem} that is to be stored in the cache.
* @param writeThruOptions {@link com.alachisoft.ncache.runtime.caching.WriteThruOptions} regarding updating the data source. This can be either WriteThru, WriteBehind or None.
* @return
* Future Task that performs an insert operation in the background. Once completed returns version of
* cache item that was added in cache. Methods of {@link java.util.concurrent.FutureTask} can be used to determine status
* of the task i.e. isDone(), isCancelled().
* @throws com.alachisoft.ncache.runtime.exceptions.CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
* @throws java.lang.IllegalArgumentException
*/
FutureTask insertAsync(String key, CacheItem item, WriteThruOptions writeThruOptions) throws CacheException,IllegalArgumentException;
/**
* Update {@link com.alachisoft.ncache.runtime.caching.CacheItemAttributes} of an existing item in cache.
* @param key Unique key to identify the cache item.
* @param attributes An instance of {@link com.alachisoft.ncache.runtime.caching.CacheItemAttributes} to update item in the cache.
* @return Flag that determines status of the update operation. True if attributes of
* the item in cache was updated successfully otherwise False .
* @throws com.alachisoft.ncache.runtime.exceptions.CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
* @throws java.lang.IllegalArgumentException
*/
boolean updateAttributes(String key, CacheItemAttributes attributes) throws CacheException, IllegalArgumentException;
///#endregion
///#region Get Operations
/**
* Retrieves the specified item from the Cache object.
* @param key The unique identifier for the cache item to be retrieved.
* @param cls Specifies the class of value obtained from the cache.
* @param Specifies the type of value obtained from the cache.
* @return The retrieved cache item, or a null reference if the key is not found.
* @throws CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
* @throws IllegalArgumentException
* @throws ClassCastException If the object returned form cache is not an instance of the specified class or any of its subclass/subclasses.
*/
T get(String key, Class cls) throws CacheException, IllegalArgumentException, ClassCastException;
/**
* Retrieves the specified item from the Cache object, with read-through caching option available. If the option of read-through has been set, the object will be fetched from the data source if it does not exist in cache.
* @param key The unique identifier for the cache item to be retrieved.
* @param readThruOptions {@link com.alachisoft.ncache.runtime.caching.ReadThruOptions} to read from data source. These can be either ReadThru, ReadThruForced or None.
* @param cls Specifies the class of value obtained from the cache.
* @param Specifies the type of value obtained from the cache.
* @return The retrieved cache item, or a null reference if the key is not found.
* @throws CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
* @throws IllegalArgumentException
* @throws ClassCastException If the object returned form cache is not an instance of the specified class or any of its subclass/subclasses.
*/
T get(String key, ReadThruOptions readThruOptions, Class cls) throws CacheException, IllegalArgumentException, ClassCastException;
/**
* Retrieves the specified item from the Cache if it is not already locked. Otherwise it returns null.This is different from the basic Get operation where an item is returned ignoring the lock altogether.
* @param key Unique identifier for the cache item to be retrieved.
* @param acquireLock A flag to determine whether to acquire a lock or not.
* @param lockTimeout The TimeSpan after which the lock is automatically released.
* @param lockHandle An instance of {@link com.alachisoft.ncache.client.LockHandle} to hold the lock information.
* @param cls Specifies the class of value obtained from the cache.
* @param Specifies the type of value obtained from the cache.
* @return The retrieved cache item, or a null reference if the key is not found.
* @throws CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
* @throws IllegalArgumentException
* @throws ClassCastException If the object returned form cache is not an instance of the specified class or any of its subclass/subclasses.
*/
T get(String key, boolean acquireLock, TimeSpan lockTimeout, LockHandle lockHandle, Class cls) throws CacheException, IllegalArgumentException, ClassCastException;
/**
* Retrieves the specified item from the cache, with read-through caching option available.If the option of read-through has been set, the object will be fetched from the data source if it does not exist in cache.
* @param key Unique identifier for the cache item to be retrieved.
* @param version The version of the object.
* @param readThruOptions {@link com.alachisoft.ncache.runtime.caching.ReadThruOptions} to read from data source. These can be either ReadThru, ReadThruForced or None.
* @param cls Specifies the class of value obtained from the cache.
* @param Specifies the type of value obtained from the cache.
* @return The retrieved cache item, or a null reference if the key is not found.
* @throws CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
* @throws IllegalArgumentException
* @throws ClassCastException If the object returned form cache is not an instance of the specified class or any of its subclass/subclasses.
*/
T get(String key, CacheItemVersion version, ReadThruOptions readThruOptions, Class cls) throws CacheException, IllegalArgumentException, ClassCastException;
/**
* Retrieves the objects from cache for the given keys as key-value pairs in form of a Map.
* @param keys The keys against which items are to be fetched from cache.
* @param cls Specifies the class of value obtained from the cache.
* @param Specifies the type of value obtained from the cache.
* @return The retrieved cache items as Map of key-value pairs.
* @throws CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
* @throws IllegalArgumentException
* @throws ClassCastException If the object returned form cache is not an instance of the specified class or any of its subclass/subclasses.
*/
java.util.Map getBulk(Iterable keys, Class cls) throws CacheException, IllegalArgumentException, ClassCastException;
/**
* Retrieves the objects from cache for the given keys as key-value pairs in form of a Map.
* @param keys The keys against which items are to be fetched from cache.
* @param readThruOptions {@link com.alachisoft.ncache.runtime.caching.ReadThruOptions} to read from data source. These can be either ReadThru, ReadThruForced or None.
* @param cls Specifies the class of value obtained from the cache.
* @param Specifies the type of value obtained from the cache.
* @return The retrieved cache items as Map of key-value pairs.
* @throws CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
* @throws IllegalArgumentException
* @throws ClassCastException If the object returned form cache is not an instance of the specified class or any of its subclass/subclasses.
*/
java.util.Map getBulk(Iterable keys, ReadThruOptions readThruOptions, Class cls) throws CacheException, IllegalArgumentException, ClassCastException;
/**
* Retrieves the specified CacheItem from the cache.
* @param key Unique identifier for the cache item to be retrieved.
* @return The specified CacheItem. If the key does not exist, it returns null.
* @throws CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
* @throws IllegalArgumentException
*/
CacheItem getCacheItem(String key) throws CacheException,IllegalArgumentException;
/**
* Retrieves the specified CacheItem from the cache. This overload also allows specifying the read-through option. If read-through is set and the object does not exist in the cache,the object will be fetched from the data source and added to the cache.
* @param key Unique identifier for the cache item to be retrieved.
* @param readThruOptions {@link com.alachisoft.ncache.runtime.caching.ReadThruOptions} regarding reading from data source. It can be either ReadThru, ReadThruForced or None.
* @return The specified CacheItem. If the key does not exist, it returns null.
* @throws CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
* @throws IllegalArgumentException
*/
CacheItem getCacheItem(String key, ReadThruOptions readThruOptions) throws CacheException, IllegalArgumentException;
/**
* Retrieves the specified CacheItem from the cache.This method also allows specifying the read-through option. if read-through is set and the object does not exist in the cache, the object will be fetched from the data source and added to the cache.
* @param key Unique identifier for the cache item to be retrieved.
* @param version The {@link com.alachisoft.ncache.client.CacheItemVersion} of the object.
* @param readThruOptions {@link com.alachisoft.ncache.runtime.caching.ReadThruOptions} regarding reading from data source. It can be either ReadThru, ReadThruForced or None.
* @return The specified CacheItem. If the key does not exist, it returns null.
* @throws CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
* @throws IllegalArgumentException
*/
CacheItem getCacheItem(String key, CacheItemVersion version, ReadThruOptions readThruOptions) throws CacheException,IllegalArgumentException;
/**
* Get the cache item stored in cache. Loack handle can be given with this and a flag can be set if you want to acquire lock.
* @param key Key used to reference the desired object.
* @param acquireLock A flag to determine whether to acquire a lock or not.
* @param lockTimeout The TimeSpan after which the lock is automatically released.
* @param lockHandle An instance of {@link com.alachisoft.ncache.client.LockHandle} to hold the lock information.
* @return The retrieved cache item. If key is not found, returns null.
* @throws CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
* @throws IllegalArgumentException
*/
CacheItem getCacheItem(String key, boolean acquireLock, TimeSpan lockTimeout, LockHandle lockHandle) throws CacheException,IllegalArgumentException;
/**
* Retrieves the specified CacheItems from the cache object
* @param keys {@link java.lang.Iterable} list of unique identifiers for the cache items to be retrieved.
* @return The retrieved cache items as key-value pairs in a Map.
* @throws CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
* @throws IllegalArgumentException
* @throws ClassCastException If the object returned form cache is not an instance of the specified class or any of its subclass/subclasses.
*/
java.util.Map getCacheItemBulk(Iterable keys) throws CacheException,IllegalArgumentException,ClassCastException;
/**
* Retrieves the specified cacheItems from the cache. This overload also allows specifying the read-through option. If read-through is set and the object does not exist in the cache,the object will be fetched from the data source and added to the cache.
* @param keys {@link java.lang.Iterable} list of unique identifiers for the cache items to be retrieved.
* @param readThruOptions {@link com.alachisoft.ncache.runtime.caching.ReadThruOptions} regarding reading from data source. It can be either ReadThru, ReadThruForced or None.
* @return The retrieved cache items as a Map of key-value pairs.
* @throws CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
* @throws IllegalArgumentException
* @throws ClassCastException If the object returned form cache is not an instance of the specified class or any of its subclass/subclasses.
*/
java.util.Map getCacheItemBulk(Iterable keys, ReadThruOptions readThruOptions) throws CacheException,IllegalArgumentException,ClassCastException;
/**
* Gets an object from the cache only if a newer version of the object exists in cache.
* @param key Unique key used to reference the desired object.
* @param version The {@link com.alachisoft.ncache.client.CacheItemVersion} of the object.
* @param cls Specifies the class of value obtained from the cache.
* @param Specifies the type of value obtained from the cache.
* @return If a newer object exists in the cache, the object is returned. Otherwise, null is returned.
* @throws CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
*/
T getIfNewer(String key, CacheItemVersion version, Class cls) throws CacheException;
///#endregion
///#region Delete Operations
/**
* Deletes the item with the specified key from cache.
* @param key Unique key of the item to be deleted.
* @throws CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
* @throws IllegalArgumentException
*/
void delete(String key) throws CacheException,IllegalArgumentException;
/**
* Deletes the specified item from the {@link com.alachisoft.ncache.client.Cache}. You can also specify the write option such that the item may be removed from both cache and data source.
* @param key Unique key of the item to be deleted.
* @param writeThruOptions {@link com.alachisoft.ncache.runtime.caching.WriteThruOptions} regarding updating the data source. This can be either WriteThru, WriteBehind or None.
* @throws CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
* @throws IllegalArgumentException
*/
void delete(String key, WriteThruOptions writeThruOptions) throws CacheException,IllegalArgumentException;
/**
* Deletes the specified item from the {@link com.alachisoft.ncache.client.Cache}. You can also specify the write option such that the item may be removed from both cache and data source.
* @param key Unique key of the item to be deleted.
* @param lockHandle If the item is locked, it can be removed only if the correct lockHandle is specified. lockHandle should be the same which was used initially to lock the item, otherwise you will get the 'OperationFailedException'.
* @param version The version of the item to be removed. The item is removed from the cache only if this is still the most recent version in the cache.
* @param writeThruOptions {@link com.alachisoft.ncache.runtime.caching.WriteThruOptions} regarding updating the data source. This can be either WriteThru, WriteBehind or None.
* @throws CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
* @throws IllegalArgumentException
*/
void delete(String key, LockHandle lockHandle, CacheItemVersion version, WriteThruOptions writeThruOptions) throws CacheException,IllegalArgumentException;
/**
* Deletes an item from the cache asynchronously with a cache key to reference its location.
* @param key Unique key of the item to be deleted.
* @return
* Future Task that performs an delete operation in the background.Methods of {@link java.util.concurrent.FutureTask} can be used to determine status
* of the task i.e. isDone(), isCancelled().
* @throws CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
* @throws IllegalArgumentException
*/
FutureTask deleteAsync(String key) throws CacheException,IllegalArgumentException;
/**
* Deletes an item from the cache asynchronously with a cache key to reference its location.
* @param key key Unique key of the item to be deleted.
* @param writeThruOptions {@link com.alachisoft.ncache.runtime.caching.WriteThruOptions} regarding updating the data source. This can be either WriteThru, WriteBehind or None.
* @return
* Future Task that performs an delete operation in the background. Methods of {@link java.util.concurrent.FutureTask} can be used to determine status
* of the task i.e. isDone(), isCancelled().
* @throws CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
* @throws IllegalArgumentException
*/
FutureTask deleteAsync(String key, WriteThruOptions writeThruOptions) throws CacheException,IllegalArgumentException;
/**
* Deletes the specified items from the {@link com.alachisoft.ncache.client.Cache}.
* @param keys {@link java.lang.Iterable} list of unique keys to reference the items.
* @throws CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
* @throws IllegalArgumentException
* @throws ClassCastException
*/
void deleteBulk(Iterable keys) throws CacheException, IllegalArgumentException,ClassCastException;
/**
* Deletes the specified items from the {@link com.alachisoft.ncache.client.Cache}. You can also specify the write option such that the items may be removed from both cache and data source.
* @param keys {@link java.lang.Iterable} list of unique keys to reference the items.
* @param writeThruOptions {@link com.alachisoft.ncache.runtime.caching.WriteThruOptions} regarding updating the data source. This can be either WriteThru, WriteBehind or None.
* @throws CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
* @throws IllegalArgumentException
* @throws ClassCastException
*/
void deleteBulk(Iterable keys, WriteThruOptions writeThruOptions) throws CacheException, IllegalArgumentException,ClassCastException;
///#endregion
///#region Remove Operations
/**
* Removes and retrieves the item with the specified key from cache.
* @param key Unique key of the item to be removed.
* @param cls Specifies the class of value obtained from the cache.
* @param Specifies the type of value obtained from the cache.
* @return The removed item if the key exists otherwise null is returned.
* @throws CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
* @throws IllegalArgumentException
* @throws ClassCastException If the object returned form cache is not an instance of the specified class or any of its subclass/subclasses.
*/
T remove(String key, Class cls) throws CacheException, IllegalArgumentException,ClassCastException;
/**
* Removes and retrieves the specified item from the {@link com.alachisoft.ncache.client.Cache}. You can also specify the write option such that the item may be removed from both cache and data source.
* @param key Unique key of the item to be removed.
* @param writeThruOptions {@link com.alachisoft.ncache.runtime.caching.WriteThruOptions} regarding updating the data source. This can be either WriteThru, WriteBehind or None.
* @param cls Specifies the class of value obtained from the cache.
* @param Specifies the type of value obtained from the cache.
* @return The removed item if the key exists otherwise null is returned.
* @throws CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
* @throws IllegalArgumentException
* @throws ClassCastException If the object returned form cache is not an instance of the specified class or any of its subclass/subclasses.
*/
T remove(String key, WriteThruOptions writeThruOptions, Class cls) throws CacheException, IllegalArgumentException,ClassCastException ;
/**
* Removes and retrieves the specified item from the {@link com.alachisoft.ncache.client.Cache}. You can also specify the write option such that the item may be removed from both cache and data source.
* @param key Unique key of the item to be removed.
* @param lockHandle If the item is locked, it can be removed only if the correct lockHandle is specified. lockHandle should be the same which was used initially to lock the item, otherwise you will get the 'OperationFailedException'.
* @param version The version of the item to be removed. The item is removed from the cache only if this is still the most recent version in the cache.
* @param writeThruOptions {@link com.alachisoft.ncache.runtime.caching.WriteThruOptions} regarding updating the data source. This can be either WriteThru, WriteBehind or None.
* @param cls Specifies the class of value obtained from the cache.
* @param Specifies the type of value obtained from the cache.
* @return The removed item if the key exists otherwise null is returned.
* @throws CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
* @throws IllegalArgumentException
* @throws ClassCastException If the object returned form cache is not an instance of the specified class or any of its subclass/subclasses.
*/
T remove(String key, LockHandle lockHandle, CacheItemVersion version, WriteThruOptions writeThruOptions, Class cls) throws CacheException, IllegalArgumentException,ClassCastException ;
/**
* Removes the specified items from the {@link com.alachisoft.ncache.client.Cache} and returns them to the application in the form of a Map.
* @param keys {@link java.lang.Iterable} list of unique keys to reference the items.
* @param cls Specifies the class of value obtained from the cache.
* @param Specifies the type of value obtained from the cache.
* @return The removed items from cache in form of a Map.
* @throws CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
* @throws IllegalArgumentException
* @throws ClassCastException If the object returned form cache is not an instance of the specified class or any of its subclass/subclasses.
*/
Map removeBulk(Iterable keys, Class cls) throws CacheException, IllegalArgumentException,ClassCastException;
/**
* Removes the specified items from the {@link com.alachisoft.ncache.client.Cache} and returns them to the application in the form of a Map.
* @param keys {@link java.lang.Iterable} list of unique keys to reference the items.
* @param writeThruOptions {@link com.alachisoft.ncache.runtime.caching.WriteThruOptions} regarding updating the data source. This can be either WriteThru, WriteBehind or None.
* @param cls Specifies the class of value obtained from the cache.
* @param Specifies the type of value obtained from the cache.
* @return The removed items from cache in form of a Map.
* @throws CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
* @throws IllegalArgumentException
* @throws ClassCastException If the object returned form cache is not an instance of the specified class or any of its subclass/subclasses.
*/
Map removeBulk(Iterable keys, WriteThruOptions writeThruOptions, Class cls) throws CacheException, IllegalArgumentException,ClassCastException;
/**
* Removes an item from the cache asynchronously with a cache key to reference its location.
* @param key Unique key of the item to be removed.
* @param cls Specifies the class of value obtained from the cache.
* @param Specifies the type of value obtained from the cache.
* @return
* Future Task that performs an remove operation in the background. Once completed returns the removed
* cache item that was added in cache. Methods of {@link java.util.concurrent.FutureTask} can be used to determine status
* of the task i.e. isDone(), isCancelled().
* @throws CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
* @throws IllegalArgumentException
* @throws ClassCastException If the object returned form cache is not an instance of the specified class or any of its subclass/subclasses.
*/
FutureTask removeAsync(String key, Class cls)throws CacheException, IllegalArgumentException,ClassCastException;
/**
* Removes an item from the cache asynchronously with a cache key to reference its location.
* @param key Unique key of the item to be removed.
* @param writeThruOptions {@link com.alachisoft.ncache.runtime.caching.WriteThruOptions} regarding updating the data source. This can be either WriteThru, WriteBehind or None.
* @param cls Specifies the class of value obtained from the cache.
* @param Specifies the type of value obtained from the cache.
* @return
* Future Task that performs an remove operation in the background. Once completed returns the removed
* cache item that was added in cache. Methods of {@link java.util.concurrent.FutureTask} can be used to determine status
* of the task i.e. isDone(), isCancelled().
* @throws CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
* @throws IllegalArgumentException
* @throws ClassCastException If the object returned form cache is not an instance of the specified class or any of its subclass/subclasses.
*/
FutureTask removeAsync(String key, WriteThruOptions writeThruOptions, Class cls)throws CacheException, IllegalArgumentException,ClassCastException;
///#endregion
///#region Conatins Operations
/**
* Determines whether the cache contains a specific key.
* @param key The key to locate in the cache.
* @return true if the {@link com.alachisoft.ncache.client.Cache} contains an element with the specified key; otherwise, false.
* @throws com.alachisoft.ncache.runtime.exceptions.CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
* @throws java.lang.IllegalArgumentException
*/
boolean contains(String key) throws CacheException, IllegalArgumentException;
/**
* Determines whether the cache contains specifiec keys.
* @param keys {@link java.lang.Iterable} collection of keys.
* @return Map of Keys with flag to dertermine presence of each key in cache.true if the {@link com.alachisoft.ncache.client.Cache} contains an elementwith the specified key; otherwise, false.
* @throws com.alachisoft.ncache.runtime.exceptions.CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
*/
Map containsBulk(Iterable keys) throws CacheException;
///#endregion
///#region Clear Operations
/**
* Removes all elements from the {@link com.alachisoft.ncache.client.Cache}.
* @throws com.alachisoft.ncache.runtime.exceptions.CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
*/
void clear() throws CacheException;
/**
* Removes all elements from the client cache.
* @throws com.alachisoft.ncache.runtime.exceptions.CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
*/
void clearClientCache() throws CacheException;
///#endregion
///#region Lock Operations
/**
* Forcefully unlocks a locked cached item.
* @param key Key of the cached item to be unlocked.
* @throws com.alachisoft.ncache.runtime.exceptions.CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
* @throws java.lang.IllegalArgumentException
*/
void unlock(String key) throws CacheException,IllegalArgumentException;
/**
* Unlocks a locked cached item if the correct LockHandle is specified.
* If LockHandle is null Forcefully unlocks a locked cached item.
* @param key Key of the cached item to be unlocked.
* @param lockHandle An instance of {@link com.alachisoft.ncache.client.LockHandle} that is generated when the lock is acquired.
* @throws com.alachisoft.ncache.runtime.exceptions.CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
* @throws java.lang.IllegalArgumentException
*/
void unlock(String key, LockHandle lockHandle) throws CacheException,IllegalArgumentException;
/**
* Acquires a lock on an item in the cache.
* @param key key of cached item to be locked.
* @param lockTimeout An instance of {@link com.alachisoft.ncache.runtime.util.TimeSpan} after which the lock is automatically released.
* @param lockHandle An instance of {@link com.alachisoft.ncache.client.LockHandle} that will be filled in with the lock information if lock is acquired successfully.
* @return Whether or not lock was acquired successfully.
* @throws com.alachisoft.ncache.runtime.exceptions.CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
* @throws java.lang.IllegalArgumentException
*/
boolean lock(String key, TimeSpan lockTimeout, LockHandle lockHandle) throws CacheException,IllegalArgumentException;
///#endregion
///#region Streaming
/**
* Gets an instance of {@link com.alachisoft.ncache.client.CacheStream}
* @param key The key used to reference the stream.
* @param cacheStreamAttributes Instance of {@link com.alachisoft.ncache.client.CacheStreamAttributes} to set attributes of the stream.
* @return An instance of CacheStream.
* @throws com.alachisoft.ncache.runtime.exceptions.CacheException So you can catch this exception for all the exceptions thrown from within the NCache.
* @throws java.lang.IllegalArgumentException
*/
CacheStream getCacheStream(String key, CacheStreamAttributes cacheStreamAttributes) throws CacheException,IllegalArgumentException;
///#endregion
///#region JsonEnumeration
/**
* Retrieves a Map iterator used to iterate through the key settings and their values as JSON objects contained in the cache.
* @return An iterator to iterate through {@link com.alachisoft.ncache.client.Cache} as JSON objects.
*/
Iterator asJsonIterator();
///#endregion
} © 2015 - 2025 Weber Informatics LLC | Privacy Policy