001package org.cache2k;
002
003/*
004 * #%L
005 * cache2k API
006 * %%
007 * Copyright (C) 2000 - 2016 headissue GmbH, Munich
008 * %%
009 * Licensed under the Apache License, Version 2.0 (the "License");
010 * you may not use this file except in compliance with the License.
011 * You may obtain a copy of the License at
012 * 
013 *      http://www.apache.org/licenses/LICENSE-2.0
014 * 
015 * Unless required by applicable law or agreed to in writing, software
016 * distributed under the License is distributed on an "AS IS" BASIS,
017 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
018 * See the License for the specific language governing permissions and
019 * limitations under the License.
020 * #L%
021 */
022
023import org.cache2k.integration.CacheLoaderException;
024
025/**
026 * Object representing a cache entry. With the cache entry, it can be
027 * checked whether a mapping in the cache is present, even if the cache
028 * contains {@code null} or an exception. Entries can be retrieved by
029 * {@link Cache#peekEntry(Object)} or {@link Cache#getEntry(Object)} or
030 * via {@link Cache#iterator()}.
031 *
032 * <p>After retrieved, the entry instance does not change its values, even
033 * if the value for its key is updated in the cache.
034 *
035 * <p>Design note: The cache is generally also aware of the time the
036 * object will be refreshed next or when it will expire. This is not exposed
037 * to applications by intention.
038 *
039 * @author Jens Wilke
040 * @see Cache#peekEntry(Object)
041 * @see Cache#getEntry(Object)
042 * @see Cache#iterator()
043 */
044public interface CacheEntry<K, V> {
045
046  /**
047   * Key associated with this entry.
048   */
049  K getKey();
050
051  /**
052   * Value of the entry. The value may be null if nulls are permitted. If the
053   * entry had a loader exception which is not suppressed, this exception will be
054   * propagated.
055   *
056   * @throws CacheLoaderException if the loading produced an exception .
057   */
058  V getValue();
059
060  /**
061   * The exception happened when the value was loaded and
062   * the exception could not be suppressed. {@code null} if no exception
063   * happened or it was suppressed. If {@code null} then {@link #getValue}
064   * returns a value and does not throw an exception.
065   */
066  Throwable getException();
067
068  /**
069   * Time in millis the entry was last modified either by load or put.
070   */
071  long getLastModification();
072
073}