openjpa-kernel/src/main/java/org/apache/openjpa/datacache/DataCache.java

/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you 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.apache.openjpa.datacache;

import java.util.BitSet;
import java.util.Collection;
import java.util.List;
import java.util.Map;
import java.util.Set;

import org.apache.openjpa.lib.util.Clearable;
import org.apache.openjpa.lib.util.Closeable;

/**
 * Interface that must be implemented by any level 2 cache used by
 * OpenJPA. Most data caches will choose to implement the
 * {@link org.apache.openjpa.lib.conf.Configurable} interface as well so that
 * they will be given the system configuration just after construction.
 *  Implementations should take care not to return timed out data.
 *
 * @see AbstractDataCache
 * @see DataCachePCData#isTimedOut
 * @author Patrick Linskey
 * @author Abe White
 * @author Pinaki Poddar
 */
public interface DataCache
    extends Closeable, Clearable {

    /**
     * The name of the default data cache: <code>default</code>
     */
    String NAME_DEFAULT = "default";

    /**
     * Returns a string name that can be used by end-user-visible
     * code to identify this cache.
     *
     * @since 0.2.5.0
     */
    String getName();

    /**
     * Sets a string name to be used to identify this cache to end-user needs.
     *
     * @since 0.2.5.0
     */
    void setName(String name);

    /**
     * Initialize any resources associated with the given
     * {@link DataCacheManager}.
     */
    void initialize(DataCacheManager manager);

    /**
     * Perform a batch update of the cache. Add all {@link DataCachePCData}
     * objects in <code>additions</code> and in
     * <code>newUpdates</code>, make the appropriate modifications to
     * all DataCachePCDatas in <code>existingUpdates</code>, and delete all
     * OIDs in <code>deletes</code>.
     *  All changes made to cached data must be made via this
     * method. It is this method that is responsible for performing
     * any side-effects that should happen on meaningful cache changes.
     *  Implementations should bear in mind that the
     * <code>deletes</code> collection may contain oids that are also
     * in the <code>additions</code> map. This is possible because it
     * is valid for a user to delete an object with a particular oid
     * and then add that object in the same batch.
     *
     * @param additions A collection of {@link DataCachePCData} objects.
     * These represent data that have been newly created,
     * and thus must be added to the cache.
     * @param newUpdates A collection of {@link DataCachePCData} objects.
     * These represent data that have been modified but
     * were not originally in the cache, and thus must be added to the cache.
     * @param existingUpdates A collection of {@link DataCachePCData} objects.
     * These represent data that have been modified and
     * were originally loaded from the cache. It is
     * up to the cache implementation to decide if
     * these values must be re-enlisted in the cache.
     * Some caches may return live data from {@link #get}
     * invocations, in which case these values need not be re-enlisted.
     * @param deletes A collection of object IDs that have been deleted
     * and must therefore be dropped from the cache.
     */
    void commit(Collection<DataCachePCData> additions, Collection<DataCachePCData> newUpdates,
        Collection<DataCachePCData> existingUpdates, Collection<Object> deletes);

    /**
     * Returns <code>true</code> if this cache contains data
     * corresponding to <code>oid</code>; otherwise returns
     * <code>false</code>.
     */
    boolean contains(Object oid);

    /**
     * Returns the indexes of the oids in this cache.
     */
    BitSet containsAll(Collection<Object> oids);

    /**
     * Return the cached object for the given oid. Modifying the returned
     * object may or may not change the cached value; the {@link #update}
     * method should be used to re-cache any changed objects.
     *
     * @return the object matching the given oid, or null if none
     */
    DataCachePCData get(Object oid);

    /**
     * Set the cached value for the given instance. This does <em>not</em>
     * result in an update of other caches. Rather, it should only be
     * used for loading clean data into the cache. Meaningful changes
     * to the state of the cache should be made via the {@link #commit} method.
     *
     * @return The previously cached value, or <code>null</code> if
     * the value was not previously cached. See {@link Map#put}
     * for more information.
     */
    DataCachePCData put(DataCachePCData value);

    /**
     * Update the cached value for the given instance. This does
     * <em>not</em> result in an update of other caches. Rather, it should
     * only be used for loading clean data into the cache. Meaningful changes
     * to the state of the cache should be made via the {@link #commit} method.
     *  A cache implementation may or may not return a live object
     * from {@link #get} invocations. If an object retrieved from a
     * {@link #get} operation needs to be updated, this method can be
     * invoked instead of invoking {@link #put}. The DataCache implementation
     * can then make optimizations based on how its {@link #get} method works.
     */
    void update(DataCachePCData value);

    /**
     * Remove the value stored under the given oid. This does
     * <em>not</em> result in an update of other caches. Rather, it
     * should only be used for removing data in the cache.
     * Meaningful changes to the state of the cache should be made
     * via the {@link #commit} method.
     *
     * @return The previously cached value, or <code>null</code> if
     * the oid was not previously cached. See {@link Map#remove}
     * for more information.
     */
    DataCachePCData remove(Object oid);

    /**
     * Remove the values stored under the given oids.
     *
     * @return the indexes of the removed oids
     * @see #remove
     */
    BitSet removeAll(Collection<Object> oids);

    /**
     * Evict all values of a specified type.
     */
    void removeAll(Class<?> cls, boolean subclasses);

    /**
     * Remove all data from this cache. This does <em>not</em> result
     * in an update of other caches. Rather, it should only be used
     * for clearing the cache. Meaningful changes to the state of the
     * cache should be made via the {@link #commit} method.
     */
    @Override void clear();

    /**
     * Pin the value stored under <code>oid</code> into the cache.
     * This method guarantees that <code>oid</code>'s value will not
     * be dropped by the caching algorithm. This method does not
     * affect the behavior of {@link #remove}.
     *
     * @return <code>true</code> if <code>oid</code>'s value was
     * pinned into the cache; <code>false</code> if the oid is not in the cache.
     */
    boolean pin(Object oid);

    /**
     * Pin all oids to the cache.
     *
     * @return the indexes of the pinned oids
     * @see #pin
     */
    BitSet pinAll(Collection<Object> oids);

    /**
     * Pin all oids for the given type.
     * @param subs Whether to include subclasses.
     */
    void pinAll(Class<?> cls, boolean subs);

    /**
     * Unpin the value stored under <code>oid</code> from the cache.
     * This method reverses a previous invocation of {@link #pin}.
     * This method does not remove anything from the cache; it merely
     * makes <code>oid</code>'s value a candidate for flushing from the cache.
     *
     * @return <code>true</code> if <code>oid</code>'s value was
     * unpinned from the cache; <code>false</code> if the
     * oid is not in the cache.
     */
    boolean unpin(Object oid);

    /**
     * Unpin all oids from the cache.
     *
     * @return the indexes of the unpinned oids
     * @see #unpin
     */
    BitSet unpinAll(Collection<Object> oids);

    /**
     * Unpin all oids associaed with the given type from the cache.
     * @param subs Whether to include subclasses.
     */
    void unpinAll(Class<?> cls, boolean subs);

    /**
     * Obtain a write lock on the cache.
     */
    void writeLock();

    /**
     * Release the write lock on the cache.
     */
    void writeUnlock();

    /**
     * Add a new expiration event listener to this cache.
     *
     * @since 0.2.5.0
     */
    void addExpirationListener(ExpirationListener listen);

    /**
     * Remove an expiration event listener from this cache.
     *
     * @since 0.2.5.0
     */
    boolean removeExpirationListener(ExpirationListener listen);

    /**
     * Free the resources used by this cache.
	 */
	@Override void close ();

    /**
	 * Gets objects from the caches for a given list of keys.
	 * The returned map has the same keys as the given keys.
	 * If the cache does not contain data for a specific key,
	 * the returned map still contains the key with a null value.
	 *
     */
    Map<Object,DataCachePCData> getAll(List<Object> keys);

    /**
     * Gets the named partition. Note that a partition itself is another cache.
     *
     * @param name name of the given partition.
     *
     * @param create if true optionally create a new partition.
     *
     * @return a partition of the given name. Or null, if either no such partition exists or can not be created.
     * @since 2.0.0
     */
    DataCache getPartition(String name, boolean create);

    /**
     * Gets the name of the known partitions.
     *
     * @return empty set if no partition exists.
     *
     * @since 2.0.0
     */
    Set<String> getPartitionNames();

    /**
     * Affirms if this cache maintains partitions.
     *
     * @since 2.0.0
     */
    boolean isPartitioned();

    /**
     * Returns number of read/write request and cache hit ratio data.
     */
    CacheStatistics getStatistics();

    /**
     * Returns whether the the cache needs to be updated when bulk updates as executed. Defaults to true.
     */
    boolean getEvictOnBulkUpdate();
}