/*******************************************************************************
 * Copyright (c) 1998, 2015 Oracle and/or its affiliates. All rights reserved.
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License v1.0 and Eclipse Distribution License v. 1.0
 * which accompanies this distribution.
 * The Eclipse Public License is available at http://www.eclipse.org/legal/epl-v10.html
 * and the Eclipse Distribution License is available at
 * http://www.eclipse.org/org/documents/edl-v10.php.
 *
 * Contributors:
 *     Oracle - initial API and implementation from Oracle TopLink
 ******************************************************************************/
package org.eclipse.persistence.annotations;

/**
 * The CacheType enum is used with the Cache annotation for a persistent class.
 * It defines the type of cache (IdentityMap) used for the class. By default the
 * SOFT_WEAK cache type is used.
 *
 * @see org.eclipse.persistence.annotations.Cache
 * @author Guy Pelletier
 * @since Oracle TopLink 11.1.1.0.0
 */
public enum CacheType {
    /**
     * Provides full caching and guaranteed identity. Caches all objects
     * and does not remove them.
     * WARNING: This method may be memory intensive when many objects are
     * read.  If used on a large data set it will eventually causes an out of memory error.
     */
    FULL,

    /**
     * Similar to the FULL identity map except that the map holds the
     * objects using weak references. This method allows full garbage
     * collection and guaranteed identity.  It will only hold objects
     * that are referenced by the application so may not provide a large caching benefit.
     */
    WEAK,

    /**
     * Similar to the FULL identity map except that the map holds the
     * objects using soft references. This method allows full garbage
     * collection when memory is low and provides full caching and guaranteed identity.
     */
    SOFT,

    /**
     * Similar to the WEAK identity map except that it maintains a
     * most-frequently-used sub-cache. The size of the sub-cache is
     * proportional to the size of the identity map as specified by
     * {@literal @}Cache size attribute. The sub-cache
     * uses soft references to ensure that these objects are
     * garbage-collected only if the system is low on memory.
     */
    SOFT_WEAK,

    /**
     * Identical to the soft cache weak (SOFT_WEAK) identity map except
     * that it uses hard references in the sub-cache. Use this identity
     * map if soft references do not behave properly on your platform.
     */
    HARD_WEAK,

    /**
     * A cache identity map maintains a fixed number of objects
     * specified by the application. Objects are removed from the cache
     * on a least-recently-used basis. This method allows object
     * identity for the most commonly used objects.
     * WARNING: Furnishes caching and identity, but does not guarantee
     * identity.  This cache type is not recommend and should normally not be used,
     * except for objects that have no relationships to them.
     */
    CACHE,

    /**
     * WARNING: Does not preserve object identity and does not cache
     * objects.  This cache type is not recommend and should normally not be used.
     * This cache type should not be used to disable caching, to properly disable
     * caching set the @Cache isolation attribute to ISOLATED.
     */
    NONE
}