foundation/org.eclipse.persistence.core/src/main/java/org/eclipse/persistence/config/CacheType.java

/*
 * Copyright (c) 1998, 2020 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 v. 2.0 which is available at
 * http://www.eclipse.org/legal/epl-2.0,
 * or the Eclipse Distribution License v. 1.0 which is available at
 * http://www.eclipse.org/org/documents/edl-v10.php.
 *
 * SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
 */

// Contributors:
//     Oracle - initial API and implementation from Oracle TopLink
package org.eclipse.persistence.config;

/**
 * Cache type persistence property values.
 * The cache type defines the type of cache usage for the entities.
 * Its usage depends on the memory and caching requirements of the entity.
 * If no caching is desired at all the PersistenceUnitProperties.CACHE_SHARED_ should
 * instead be used.
 *
 * <p>JPA persistence property Usage:
 *
 * <p>for all entities append DEFAULT suffix to CACHE_TYPE_ prefix:
 * <p><code>properties.add(PersistenceUnitProperties.CACHE_TYPE_DEFAULT, CacheType.Weak);</code>
 *
 * <p>for a single entity append either entity name or a full class name to CACHE_TYPE_ prefix:
 * <p><code>properties.add(PersistenceUnitProperties.CACHE_TYPE_ + "Employee", CacheType.Weak);</code>
 * <p><code>properties.add(PersistenceUnitProperties.CACHE_TYPE_ + "my.test.Employee", CacheType.Weak);</code>
 *
 * <p>Values are case-insensitive.
 * "" could be used instead of default value CacheType.DEFAULT.
 *
 * @see PersistenceUnitProperties#CACHE_SHARED_
 * @see PersistenceUnitProperties#CACHE_TYPE_
 */
public class CacheType {
    /**
     * A Weak cache holds all objects in use by the application,
     * but allows any un-referenced objects to be free to garbage collection.
     * This guarantees object identity, allows optimal garbage collection, but provides little caching benefit.
     */
    public static final String  Weak = "Weak";

    /**
     * A Soft cache holds all objects read by the application,
     * but allows any un-referenced objects to be free to garbage collection only when the JVM decides memory is low.
     * This guarantees object identity, allows garbage collection when memory is low, and provides optimal caching benefit.
     */
    public static final String  Soft = "Soft";

    /**
     * A SoftWeak cache holds all objects in use by the application,
     * and a fixed size sub-cache of MRU objects using Soft references.
     * It allows any un-referenced objects not in the sub-cache to be free to garbage collection,
     * and the objects in the sub-cache are free to garbage collect only when the JVM decides memory is low.
     * This guarantees object identity, allows configurable garbage collection, and provides configurable caching benefit.
     */
    public static final String  SoftWeak = "SoftWeak";

    /**
     * A HardWeak cache holds all objects in use by the application,
     * and a fixed size sub-cache of MRU objects using normal (hard) references.
     * It allows any un-referenced objects not in the sub-cache to be free to garbage collection,
     * but not objects in the sub-cache.
     * This guarantees object identity, allows configurable garbage collection, and provides configurable caching benefit.
     */
    public static final String  HardWeak = "HardWeak";

    /**
     * A Soft cache holds all objects read by the application.
     * It does not allow any garbage collection.     *
     * This guarantees object identity, allows no garbage collection, and provides complete caching benefit.
     * <p>WARNING: This cache type should only be used for a fixed sized number of objects,
     * otherwise it will lead to an eventual memory leak.
     */
    public static final String  Full = "Full";

    /**
     * NONE does not cache any objects.
     * It allows any un-referenced objects to be free to garbage collection.
     * This provides no object identity, allows complete garbage collection, and provides no caching benefit.
     * <p>WARNING: This cache type should normally not be used.  Instead disable the share cache through PersistenceUnitProperties.CACHE_SHARED_.
     * Lack of object identity can lead to infinite loops for objects that have circular references and no indirection.
     * @see PersistenceUnitProperties#CACHE_SHARED_
     */
    public static final String  NONE = "NONE";

    /**
     * The default cache type is SoftWeak.
     */
    public static final String DEFAULT = SoftWeak;
}