com.hazelcast.internal.nearcache.NearCache Maven / Gradle / Ivy
/*
* Copyright (c) 2008-2017, Hazelcast, Inc. All Rights Reserved.
*
* 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 com.hazelcast.internal.nearcache;
import com.hazelcast.config.InMemoryFormat;
import com.hazelcast.config.NearCachePreloaderConfig;
import com.hazelcast.internal.adapter.DataStructureAdapter;
import com.hazelcast.monitor.NearCacheStats;
import com.hazelcast.nio.serialization.Data;
import com.hazelcast.spi.InitializingObject;
/**
* {@link NearCache} is the contract point to store keys and values in underlying
* {@link NearCacheRecordStore}.
*
* @param the type of the key
* @param the type of the value
*/
public interface NearCache extends InitializingObject {
/**
* Default expiration task initial delay time as seconds
*/
int DEFAULT_EXPIRATION_TASK_INITIAL_DELAY_IN_SECONDS = 5;
/**
* Default expiration task delay time as seconds
*/
int DEFAULT_EXPIRATION_TASK_DELAY_IN_SECONDS = 5;
/**
* NULL Object
*/
Object CACHED_AS_NULL = new Object();
/**
* NOT_CACHED Object
*/
Object NOT_CACHED = new Object();
/**
* Gets the name of this {@link NearCache} instance.
*
* @return the name of this {@link NearCache} instance
*/
String getName();
/**
* Gets the value associated with the given {@code key}.
*
* @param key the key of the requested value
* @return the value associated with the given {@code key}
*/
V get(K key);
/**
* Puts (associates) a value with the given {@code key}.
*
* @param key the key of the value will be stored
* @param value the value will be stored
*/
void put(K key, V value);
/**
* Removes the value associated with the given {@code key}.
*
* @param key the key of the value will be removed
*/
boolean remove(K key);
/**
* Checks if values are invalidated on changes.
*
* @return {@code true} if values are invalidated on changes, {@code false} otherwise
*/
boolean isInvalidatedOnChange();
/**
* Removes all stored values.
*/
void clear();
/**
* Clears the record store and destroys it.
*/
void destroy();
/**
* Gets the {@link com.hazelcast.config.InMemoryFormat} of the storage for internal records.
*
* @return the {@link com.hazelcast.config.InMemoryFormat} of the storage for internal records
*/
InMemoryFormat getInMemoryFormat();
/**
* Gets the {@link com.hazelcast.config.NearCachePreloaderConfig} of this Near Cache.
*
* @return the {@link NearCachePreloaderConfig} of this Near Cache
*/
NearCachePreloaderConfig getPreloaderConfig();
/**
* Get the {@link com.hazelcast.monitor.NearCacheStats} instance to monitor this store.
*
* @return the {@link com.hazelcast.monitor.NearCacheStats} instance to monitor this store
*/
NearCacheStats getNearCacheStats();
/**
* Selects the best candidate object to store from the given {@code candidates}.
*
* @param candidates the candidates from which the best candidate object will be selected.
* @return the best candidate object to store, selected from the given {@code candidates}.
*/
Object selectToSave(Object... candidates);
/**
* Gets the count of stored records.
*
* @return the count of stored records
*/
int size();
/**
* Executes the Near Cache pre-loader on the given {@link DataStructureAdapter}.
*/
void preload(DataStructureAdapter adapter);
/**
* Stores the keys of the Near Cache.
*/
void storeKeys();
/**
* Checks if the pre-loading of the Near Cache is done.
*
* @return {@code true} if the pre-loading is done, {@code false} otherwise.
*/
boolean isPreloadDone();
/**
* Used to access non-standard methods of an implementation.
*
* If this method is called on a wrapper object, result is wrapped object.
*
* @param clazz the type of returning object.
* @param the type of the class modeled by this Class object
* @return an instance of the supplied clazz type.
* @throws IllegalArgumentException if no implementation found for the supplied clazz type.
*/
T unwrap(Class clazz);
/**
* Tries to reserve supplied key for update.
*
* If one thread takes reservation, only that thread can update the key.
*
* @param key key to be reserved for update
* @return reservation id if reservation succeeds, else returns {@link NearCacheRecord#NOT_RESERVED}
*/
long tryReserveForUpdate(K key);
/**
* Tries to update reserved key with supplied value. If update happens, value is published.
* Publishing means making the value readable to all threads. If update fails, record is not updated.
*
* @param key reserved key for update
* @param value value to be associated with reserved key
* @param reservationId id for this reservation
* @param deserialize eagerly deserialize returning value
* @return associated value if deserialize is {@code true} and update succeeds, otherwise returns null
*/
V tryPublishReserved(K key, V value, long reservationId, boolean deserialize);
}