/*
 * CDDL HEADER START
 *
 * The contents of this file are subject to the terms of the
 * Common Development and Distribution License, Version 1.0 only
 * (the "License").  You may not use this file except in compliance
 * with the License.
 *
 * You can obtain a copy of the license at
 * trunk/opends/resource/legal-notices/OpenDS.LICENSE
 * or https://OpenDS.dev.java.net/OpenDS.LICENSE.
 * See the License for the specific language governing permissions
 * and limitations under the License.
 *
 * When distributing Covered Code, include this CDDL HEADER in each
 * file and include the License file at
 * trunk/opends/resource/legal-notices/OpenDS.LICENSE.  If applicable,
 * add the following below this CDDL HEADER, with the fields enclosed
 * by brackets "[]" replaced with your own identifying information:
 *      Portions Copyright [yyyy] [name of copyright owner]
 *
 * CDDL HEADER END
 *
 *
 *      Portions Copyright 2006-2007 Sun Microsystems, Inc.
 */
package org.opends.server.api;



import java.util.List;
import java.util.concurrent.locks.Lock;

import org.opends.server.config.ConfigException;
import org.opends.server.types.DN;
import org.opends.server.types.Entry;
import org.opends.server.types.InitializationException;
import org.opends.server.types.LockType;
import org.opends.server.admin.std.server.EntryCacheCfg;



/**
 * This class defines the set of methods that must be implemented by a
 * Directory Server entry cache.  Note that components accessing the
 * entry cache must not depend on any particular behavior.  For
 * example, if a call is made to <CODE>putEntry</CODE> to store an
 * entry in the cache, there is no guarantee that immediately calling
 * <CODE>getEntry</CODE> will be able to retrieve it.  There are
 * several potential reasons for this, including:
 * <UL>
 *   <LI>The entry may have been deleted or replaced by another thread
 *       between the <CODE>putEntry</CODE> and <CODE>getEntry</CODE>
 *       calls.</LI>
 *   <LI>The entry cache may implement a purging mechanism and the
 *       entry added may have been purged between the
 *       <CODE>putEntry</CODE> and <CODE>getEntry</CODE> calls.</LI>
 *   <LI>The entry cache may implement some kind of filtering
 *       mechanism to determine which entries to store, and entries
 *       not matching the appropriate criteria may not be stored.</LI>
 *   <LI>The entry cache may not actually store any entries (this is
 *       the behavior of the default cache that will be used if none
 *       is configured).</LI>
 * </UL>
 *
 * @param  <T>  The type of configuration handled by this entry
 *              cache.
 */
public abstract class EntryCache
       <T extends EntryCacheCfg>
{
  /**
   * Initializes this entry cache implementation so that it will be
   * available for storing and retrieving entries.
   *
   * @param  configuration  The configuration to use to initialize
   *                        the entry cache.
   *
   * @throws  ConfigException  If there is a problem with the provided
   *                           configuration entry that would prevent
   *                           this entry cache from being used.
   *
   * @throws  InitializationException  If a problem occurs during the
   *                                   initialization process that is
   *                                   not related to the
   *                                   configuration.
   */
  public abstract void initializeEntryCache(T configuration)
         throws ConfigException, InitializationException;



  /**
   * Performs any necessary cleanup work (e.g., flushing all cached
   * entries and releasing any other held resources) that should be
   * performed when the server is to be shut down or the entry cache
   * destroyed or replaced.
   */
  public abstract void finalizeEntryCache();



  /**
   * Indicates whether the entry cache currently contains the entry
   * with the specified DN.  This method may be called without holding
   * any locks if a point-in-time check is all that is required.
   *
   * @param  entryDN  The DN for which to make the determination.
   *
   * @return  <CODE>true</CODE> if the entry cache currently contains
   *          the entry with the specified DN, or <CODE>false</CODE>
   *          if not.
   */
  public abstract boolean containsEntry(DN entryDN);



  /**
   * Retrieves the entry with the specified DN from the cache.  The
   * caller should have already acquired a read or write lock for the
   * entry if such protection is needed.
   *
   * @param  entryDN  The DN of the entry to retrieve.
   *
   * @return  The requested entry if it is present in the cache, or
   *          <CODE>null</CODE> if it is not present.
   */
  public abstract Entry getEntry(DN entryDN);



  /**
   * Retrieves the entry ID for the entry with the specified DN from
   * the cache.  The caller should have already acquired a read or
   * write lock for the entry if such protection is needed.
   *
   * @param  entryDN  The DN of the entry for which to retrieve the
   *                  entry ID.
   *
   * @return  The entry ID for the requested entry, or -1 if it is not
   *          present in the cache.
   */
  public abstract long getEntryID(DN entryDN);



  /**
   * Retrieves the entry with the specified DN from the cache,
   * obtaining a lock on the entry before it is returned.  If the
   * entry is present in the cache, then a lock will be obtained for
   * that entry and appended to the provided list before the entry is
   * returned.  If the entry is not present, then no lock will be
   * obtained.
   *
   * @param  entryDN   The DN of the entry to retrieve.
   * @param  lockType  The type of lock to obtain (it may be
   *                   <CODE>NONE</CODE>).
   * @param  lockList  The list to which the obtained lock will be
   *                   added (note that no lock will be added if the
   *                   lock type was <CODE>NONE</CODE>).
   *
   * @return  The requested entry if it is present in the cache, or
   *          <CODE>null</CODE> if it is not present.
   */
  public abstract Entry getEntry(DN entryDN, LockType lockType,
                                 List<Lock> lockList);



  /**
   * Retrieves the requested entry if it is present in the cache,
   * obtaining a lock on the entry before it is returned.  If the
   * entry is present in the cache, then a lock  will be obtained for
   * that entry and appended to the provided list before the entry is
   * returned.  If the entry is not present, then no lock will be
   * obtained.
   *
   * @param  backend   The backend associated with the entry to
   *                   retrieve.
   * @param  entryID   The entry ID within the provided backend for
   *                   the specified entry.
   * @param  lockType  The type of lock to obtain (it may be
   *                   <CODE>NONE</CODE>).
   * @param  lockList  The list to which the obtained lock will be
   *                   added (note that no lock will be added if the
   *                   lock type was <CODE>NONE</CODE>).
   *
   * @return  The requested entry if it is present in the cache, or
   *          <CODE>null</CODE> if it is not present.
   */
  public abstract Entry getEntry(Backend backend, long entryID,
                                 LockType lockType,
                                 List<Lock> lockList);



  /**
   * Stores the provided entry in the cache.  Note that the mechanism
   * that it uses to achieve this is implementation-dependent, and it
   * is acceptable for the entry to not actually be stored in any
   * cache.
   *
   * @param  entry    The entry to store in the cache.
   * @param  backend  The backend with which the entry is associated.
   * @param  entryID  The entry ID within the provided backend that
   *                  uniquely identifies the specified entry.
   */
  public abstract void putEntry(Entry entry, Backend backend,
                                long entryID);



  /**
   * Stores the provided entry in the cache only if it does not
   * conflict with an entry that already exists.  Note that the
   * mechanism that it uses to achieve this is
   * implementation-dependent, and it is acceptable for the entry to
   * not actually be stored in any cache.  However, this method must
   * not overwrite an existing version of the entry.
   *
   * @param  entry    The entry to store in the cache.
   * @param  backend  The backend with which the entry is associated.
   * @param  entryID  The entry ID within the provided backend that
   *                  uniquely identifies the specified entry.
   *
   * @return  <CODE>false</CODE> if an existing entry or some other
   *          problem prevented the method from completing
   *          successfully, or <CODE>true</CODE> if there was no
   *          conflict and the entry was either stored or the cache
   *          determined that this entry should never be cached for
   *          some reason.
   */
  public abstract boolean putEntryIfAbsent(Entry entry,
                                           Backend backend,
                                           long entryID);



  /**
   * Removes the specified entry from the cache.
   *
   * @param  entryDN  The DN of the entry to remove from the cache.
   */
  public abstract void removeEntry(DN entryDN);



  /**
   * Removes all entries from the cache.  The cache should still be
   * available for future use.
   */
  public abstract void clear();



  /**
   * Removes all entries from the cache that are associated with the
   * provided backend.
   *
   * @param  backend  The backend for which to flush the associated
   *                  entries.
   */
  public abstract void clearBackend(Backend backend);



  /**
   * Removes all entries from the cache that are below the provided
   * DN.
   *
   * @param  baseDN  The base DN below which all entries should be
   *                 flushed.
   */
  public abstract void clearSubtree(DN baseDN);



  /**
   * Attempts to react to a scenario in which it is determined that
   * the system is running low on available memory.  In this case, the
   * entry cache should attempt to free some memory if possible to try
   * to avoid out of memory errors.
   */
  public abstract void handleLowMemory();
}