/*
* Copyright Terracotta, Inc.
*
* 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.ehcache.core.spi.store.tiering;
import org.ehcache.config.ResourceType;
import org.ehcache.spi.resilience.StoreAccessException;
import org.ehcache.core.spi.store.Store;
import org.ehcache.spi.service.PluralService;
import org.ehcache.spi.service.Service;
import org.ehcache.spi.service.ServiceConfiguration;
import java.util.Collection;
import java.util.function.Function;
Authoritative tier, that is the lower most tier of a multi tiered store.
By design this tier will always hold all the mappings contained in the Cache
Type parameters:
/**
* Authoritative tier, that is the lower most tier of a multi tiered store.
* <p>
* By design this tier will always hold all the mappings contained in the {@link org.ehcache.Cache}
*
* @param <K> the key type
* @param <V> the value type
*/
public interface AuthoritativeTier<K, V> extends Store<K, V> {
Marks the mapping as not evictable and returns it atomically.
Throws: - StoreAccessException – if the mapping can't be retrieved or updated.
Returns: the value holder
/**
* Marks the mapping as not evictable and returns it atomically.
*
* @return the value holder
*
* @throws StoreAccessException if the mapping can't be retrieved or updated.
*/
ValueHolder<V> getAndFault(K key) throws StoreAccessException;
Marks the mapping as not evictable and performs computeIfAbsent() atomically.
Throws: - StoreAccessException – if the mapping can't be retrieved or updated.
Returns: the value holder.
/**
* Marks the mapping as not evictable and performs computeIfAbsent() atomically.
*
* @return the value holder.
*
* @throws StoreAccessException if the mapping can't be retrieved or updated.
*/
ValueHolder<V> computeIfAbsentAndFault(K key, Function<? super K, ? extends V> mappingFunction) throws StoreAccessException;
This marks a mapping as evictable again if it matches the ValueHolder
received. Throws: - IllegalArgumentException – if the
ValueHolder
is not an instance from the CachingTier
Returns: true
if a mapping exists for that key, the mapping was faulted, and the value of the ValueHolder
is equal to the value of the mapping in the AuthoritativeTier
, false
otherwise
/**
* This marks a mapping as evictable again if it matches the {@link org.ehcache.core.spi.store.Store.ValueHolder}
* received.
*
* @return {@code true} if a mapping exists for that key, the mapping was faulted, and the value of the
* {@code ValueHolder} is equal to the value of the mapping in the {@code AuthoritativeTier}, {@code false} otherwise
*
* @throws IllegalArgumentException if the {@code ValueHolder} is not an instance from the CachingTier
*/
boolean flush(K key, ValueHolder<V> valueHolder);
Sets the InvalidationValve
to be used by this AuthoritativeTier
. The invalidation valve provides a way for the AuthoritativeTier
to force invalidation of CachingTier
entries when that is required.
Params: - valve – the valve to use for triggering invalidations
/**
* Sets the {@link InvalidationValve} to be used by this {@code AuthoritativeTier}.
* <p>
* The invalidation valve provides a way for the {@code AuthoritativeTier} to force invalidation of
* {@link CachingTier} entries when that is required.
*
* @param valve the valve to use for triggering invalidations
*/
void setInvalidationValve(InvalidationValve valve);
Invalidation valve, that is the mechanism through which an AuthoritativeTier
can request invalidations from the CachingTier
. /**
* Invalidation valve, that is the mechanism through which an {@link AuthoritativeTier} can request invalidations
* from the {@link CachingTier}.
*/
interface InvalidationValve {
Requests an invalidation of all CachingTier
mappings. Throws: - StoreAccessException – when en error occurs while invalidating mappings
/**
* Requests an invalidation of all {@link CachingTier} mappings.
*
* @throws StoreAccessException when en error occurs while invalidating mappings
*/
void invalidateAll() throws StoreAccessException;
Requests an invalidation of all CachingTier
mappings whose key's hashcode matches the provided one. Throws: - StoreAccessException – when en error occurs while invalidating mappings
/**
* Requests an invalidation of all {@link CachingTier} mappings whose key's hashcode matches the provided one.
*
* @throws StoreAccessException when en error occurs while invalidating mappings
*/
void invalidateAllWithHash(long hash) throws StoreAccessException;
}
Service
interface for providing AuthoritativeTier
instances. Multiple providers may exist in a given CacheManager
.
/**
* {@link Service} interface for providing {@link AuthoritativeTier} instances.
* <p>
* Multiple providers may exist in a given {@link org.ehcache.CacheManager}.
*/
@PluralService
interface Provider extends Service {
Creates a new AuthoritativeTier
instance using the provided configuration. Params: - storeConfig – the
Store
configuration - serviceConfigs – a collection of service configurations
Type parameters: Returns: the new authoritative tier
/**
* Creates a new {@link AuthoritativeTier} instance using the provided configuration.
*
* @param <K> the key type for this tier
* @param <V> the value type for this tier
*
* @param storeConfig the {@code Store} configuration
* @param serviceConfigs a collection of service configurations
* @return the new authoritative tier
*/
<K, V> AuthoritativeTier<K, V> createAuthoritativeTier(Configuration<K, V> storeConfig, ServiceConfiguration<?>... serviceConfigs);
Releases an AuthoritativeTier
. Params: - resource – the authoritative tier to release
Throws: - IllegalArgumentException – if this provider does not know about this authoritative tier
/**
* Releases an {@link AuthoritativeTier}.
*
* @param resource the authoritative tier to release
*
* @throws IllegalArgumentException if this provider does not know about this authoritative tier
*/
void releaseAuthoritativeTier(AuthoritativeTier<?, ?> resource);
Initialises an AuthoritativeTier
. Params: - resource – the authoritative tier to initialise
/**
* Initialises an {@link AuthoritativeTier}.
*
* @param resource the authoritative tier to initialise
*/
void initAuthoritativeTier(AuthoritativeTier<?, ?> resource);
Gets the internal ranking for the AuthoritativeTier
instances provided by this Provider
of the authority's ability to handle the specified resource. A higher rank value indicates a more capable AuthoritativeTier
.
Params: - authorityResource – the
ResourceType
for the authority to handle - serviceConfigs – the collection of
ServiceConfiguration
instances that may contribute to the ranking
Returns: a non-negative rank indicating the ability of a AuthoritativeTier
created by this Provider
to handle the resource type specified by authorityResource
; a rank of 0 indicates the authority can not handle the type specified in authorityResource
/**
* Gets the internal ranking for the {@link AuthoritativeTier} instances provided by this {@code Provider} of the
* authority's ability to handle the specified resource.
* <p>
* A higher rank value indicates a more capable {@code AuthoritativeTier}.
*
* @param authorityResource the {@code ResourceType} for the authority to handle
* @param serviceConfigs the collection of {@code ServiceConfiguration} instances that may contribute
* to the ranking
*
* @return a non-negative rank indicating the ability of a {@code AuthoritativeTier} created by this {@code Provider}
* to handle the resource type specified by {@code authorityResource}; a rank of 0 indicates the authority
* can not handle the type specified in {@code authorityResource}
*/
int rankAuthority(ResourceType<?> authorityResource, Collection<ServiceConfiguration<?>> serviceConfigs);
}
}