org.chronos.chronodb.internal.api.cache.CacheGetResult Maven / Gradle / Ivy
Show all versions of org.chronos.chronodb.api Show documentation
package org.chronos.chronodb.internal.api.cache;
import org.chronos.chronodb.api.exceptions.CacheGetResultNotPresentException;
import org.chronos.chronodb.internal.impl.cache.CacheGetResultImpl;
/**
* A {@link CacheGetResult} represents the result of calling
* {@link ChronoDBCache#get(String, long, org.chronos.chronodb.api.key.QualifiedKey)}.
*
*
* An instance of this class may either represent a cache hit, in which case {@link #isHit()} returns
* true and {@link #getValue()} delivers the actual result data, or it may represent a cache miss ,
* in which case {@link #isHit()} returns false and {@link #getValue()} will always throw a
* {@link CacheGetResultNotPresentException}.
*
* @author [email protected] -- Initial Contribution and API
*
* @param
* The type of the actual result data contained in this cache get result. Used for the return type of
* {@link #getValue()}.
*/
public interface CacheGetResult {
/**
* Returns the singleton {@link CacheGetResult} instance representing a cache miss.
*
*
* Calling {@link #isHit()} on the returned instance will always return false. Calling
* {@link #getValue()} on the returned instance will always throw a {@link CacheGetResultNotPresentException}.
*
* @return The singleton instance representing a cache miss. Never null.
*
* @param
* The data type of the value returned by {@link #getValue()}. In this case, this parameter is never
* used, as {@link #getValue()} always throws a {@link CacheGetResultNotPresentException}.
*/
public static CacheGetResult miss() {
return CacheGetResultImpl.getMiss();
}
/**
* Creates a new {@link CacheGetResult} instance representing a cache hit.
*
*
* An instance created by this method will never throw a {@link CacheGetResultNotPresentException} on
* {@link #getValue()}.
*
* @param value
* The result value to return in {@link #getValue()} in the new instance.
* @param validFrom
* The insertion timestamp of the given value into the store, i.e. the greatest change timestamp of the
* request key that is less than or equal to the transaction timestamp. Must not be negative.
*
* @return The newly created cache get result instance. Never null.
*
* @param
* The data type of the value returned by {@link #getValue()}.
*/
public static CacheGetResult hit(final T value, final long validFrom) {
return CacheGetResultImpl.getHit(value, validFrom);
}
/**
* Checks if this cache result represents a "cache hit".
*
*
* If this method returns true, then {@link #getValue()} returns the actual result value. If this
* method returns false, then {@link #getValue()} will always throw a
* {@link CacheGetResultNotPresentException}.
*
* @return true if this result represents a cache hit, or false if it represents a cache
* miss.
*
* @see #isMiss()
*/
public boolean isHit();
/**
* Returns the value associated with this cache query result.
*
*
* If {@link #isHit()} returns true, then this method will return the actual result value. If
* {@link #isHit()} returns false, this method will always throw a
* {@link CacheGetResultNotPresentException}.
*
* @return The actual query result.
*
* @throws CacheGetResultNotPresentException
* Thrown if this instance represents a cache miss (this.{@link #isHit()} returns
* false) and this.{@link #getValue()} is called.
*/
public T getValue() throws CacheGetResultNotPresentException;
/**
* Returns the timestamp from which onward the {@link #getValue() value} was valid in the store.
*
*
* Please note that the returned value will always be less than or equal to the timestamp of your current
* transaction; newer values may have been set on this key after the transaction timestamp. Those newer timestamps
* will not be reflected here. In other words, this method returns the greatest change timestamp of the request key
* which is less than or equal to the transaction timestamp.
*
* @return The "valid from" timestamp of the key-value pair.
* @throws CacheGetResultNotPresentException
* Thrown if this instance represents a cache miss (this.{@link #isHit()} returns
* false) and this.{@link #getValidFrom()} is called.
*/
public long getValidFrom() throws CacheGetResultNotPresentException;
/**
* Checks if this cache result represents a "cache miss".
*
*
* If this method returns true, then {@link #getValue()} will always throw a
* {@link CacheGetResultNotPresentException}. If this method returns false, then {@link #getValue()}
* will return the actual result data.
*
* @return true if this result represents a cache miss, or false if it represents a cache
* hit.
*
* @see #isHit()
*/
public default boolean isMiss() {
return this.isHit() == false;
}
}