001package org.cache2k.processor;
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.CacheEntry;
024import org.cache2k.integration.CacheLoader;
025
026/**
027 * A mutable entry is used inside the {@link EntryProcessor} to perform
028 * updates and retrieve information if the entry is existing in the cache.
029 *
030 * <p>A mutation is only done if a method for mutation is called, e.g.
031 * {@code setValue} or {@code remove}. If multiple mutate methods
032 * are called only the last method will be accounted for.
033 *
034 * <p>One instance is only intended for usage by a single thread. And
035 * shouldn't passed or hold longer than the entry processor call.
036 *
037 * @see EntryProcessor
038 * @author Jens Wilke
039 */
040public interface MutableCacheEntry<K, V> extends CacheEntry<K, V> {
041
042  /**
043   * <p>Returns the value to which the cache associated the key,
044   * or {@code null} if the cache contains no mapping for this key.
045   * {@code null} is also returned if this entry contains an exception.
046   *
047   * <p>If the cache does permit null values, then a return value of
048   * {@code null} does not necessarily indicate that the cache
049   * contained no mapping for the key. It is also possible that the cache
050   * explicitly associated the key to the value {@code null}. Use {@link #exists()}
051   * to check whether an entry is existing instead of a null check.
052   *
053   * <p>If read through operation is enabled and the entry not yet existing
054   * in the cache, the call to this method triggers a call to the cache loader.
055   *
056   * <p>In contrast to the main Cache interface there is no no peekValue method,
057   * since the same effect can be achieved by the combination of {@link #exists()}
058   * and {@link #getValue()}.
059   *
060   * @throws RestartException If the information is not yet available and the cache
061   *                          needs to do an asynchronous operation to supply it.
062   *                          After completion, the entry processor will be
063   *                          executed again.
064   * @see CacheLoader
065   */
066  @Override
067  V getValue();
068
069  /**
070   * True if a mapping exists in the cache, never invokes the loader / cache source.
071   *
072   * <p>After this method returns true, a call to {@code getValue} will always
073   * return the cached value and never invoke the loader. The potential expiry
074   * of the value is only checked once and the return values of this method and
075   * {@code getValue} will be consistent.
076   *
077   * @throws RestartException If the information is not yet available and the cache
078   *                          needs to do an asynchronous operation to supply it.
079   *                          After completion, the entry processor will be
080   *                          executed again.
081   */
082  boolean exists();
083
084  /**
085   * Insert or updates the cache value assigned to this key. After calling this method
086   * {@code exists} will return true and {@code getValue} will return the set value.
087   *
088   * <p>If a writer is registered, the {@link org.cache2k.integration.CacheWriter#write(Object, Object)}
089   * is called.
090   */
091  void setValue(V v);
092
093  /**
094   * Removes an entry from the cache.
095   *
096   * <p>In case a writer is registered, {@link org.cache2k.integration.CacheWriter#delete}
097   * is called. If a remove is performed on a not existing cache entry the writer
098   * method will also be called.
099   *
100   * @see <a href="https://github.com/jsr107/jsr107tck/issues/84">JSR107 TCK issue 84</a>
101   */
102  void remove();
103
104  /**
105   * Insert or update the entry and sets an exception. The exception will be
106   * propagated as {@link org.cache2k.integration.CacheLoaderException}.
107   *
108   * <p>Identical to {@code setValue} an expiry of the exception will be determined
109   * according to the resilience settings. Hint: If no expiry is configured the
110   * default behavior will be that the set exception expires immediately, so
111   * the effect will be similar to {@code remove} in this case.
112   */
113  void setException(Throwable ex);
114
115  /**
116   * Set a new expiry time for the entry. If combined with {@link #setValue} the entry
117   * will be updated or inserted with this expiry time, otherwise just the expiry time
118   * will be updated.
119   *
120   * <p>Special time values are defined and described at {@link org.cache2k.expiry.ExpiryTimeValues}
121   *
122   * @param t Time in millis since epoch.
123   */
124  void setExpiry(long t);
125
126}