com.unboundid.directory.sdk.ds.scripting.ScriptedUncachedEntryCriteria Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of server-sdk Show documentation
The UnboundID Server SDK is a library that may be used to develop various types of extensions to Ping Identity server products, including the Directory Server, Directory Proxy Server, Data Sync Server, Data Metrics Server, and Data Governance Broker.
There is a newer version: 6.2.0.0
Show newest version
/*
 * 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
 * docs/licenses/cddl.txt
 * or http://www.opensource.org/licenses/cddl1.php.
 * 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
 * docs/licenses/cddl.txt.  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 2012-2024 Ping Identity Corporation
 */
package com.unboundid.directory.sdk.ds.scripting;



import java.util.List;

import com.unboundid.directory.sdk.common.internal.Reconfigurable;
import com.unboundid.directory.sdk.common.types.Entry;
import com.unboundid.directory.sdk.ds.config.UncachedEntryCriteriaConfig;
import com.unboundid.directory.sdk.ds.internal.DirectoryServerExtension;
import com.unboundid.directory.sdk.ds.types.DirectoryServerContext;
import com.unboundid.ldap.sdk.LDAPException;
import com.unboundid.ldap.sdk.ResultCode;
import com.unboundid.util.Extensible;
import com.unboundid.util.ThreadSafety;
import com.unboundid.util.ThreadSafetyLevel;
import com.unboundid.util.args.ArgumentException;
import com.unboundid.util.args.ArgumentParser;



/**
 * This class defines an API that must be implemented by scripted extensions
 * which have the ability to determine which entries should be stored in the
 * uncached-id2entry database of a local DB backend, rather than in the id2entry
 * database.  In environments with data sets too large to fit in available
 * memory, this can help the server better use the memory it does have for
 * entries that are more likely to be accessed.
 * 

 * Configuring Groovy-Scripted Uncached Entry Criteria
 * In order to configure a scripted uncached entry criteria object based on
 * this API and written in the Groovy scripting language, use a command like:
 *  *      dsconfig create-uncached-entry-criteria \
 *           --criteria-name "{criteria-name}" \
 *           --type groovy-scripted \
 *           --set enabled:true \
 *           --set "script-class:{class-name}" \
 *           --set "script-argument:{name=value}"
 * 
 * where "{handler-name}" is the name to use for the uncached entry
 * criteria instance, "{class-name}" is the fully-qualified name of the
 * Groovy class written using this API, and "{name=value}" represents
 * name-value pairs for any arguments to provide to the uncached entry criteria
 * object.  If multiple arguments should be provided to the uncached entry
 * criteria, then the "--set script-argument:{name=value}"
 * option should be provided multiple times.
 *
 * @see  com.unboundid.directory.sdk.ds.api.UncachedEntryCriteria
 */
@Extensible()
@DirectoryServerExtension()
@ThreadSafety(level=ThreadSafetyLevel.INTERFACE_THREADSAFE)
public abstract class ScriptedUncachedEntryCriteria
       implements Reconfigurable
{
  /**
   * Creates a new instance of this uncached entry criteria.  All uncached entry
   * criteria implementations must include a default constructor, but any
   * initialization should generally be done in the
   * {@code initializeUncachedEntryCriteria} method.
   */
  public ScriptedUncachedEntryCriteria()
  {
    // No implementation is required.
  }



  /**
   * {@inheritDoc}
   */
  public void defineConfigArguments(final ArgumentParser parser)
         throws ArgumentException
  {
    // No arguments will be allowed by default.
  }



  /**
   * Initializes this uncached entry criteria.
   *
   * @param  serverContext  A handle to the server context for the server in
   *                        which this extension is running.
   * @param  config         The general configuration for this uncached entry
   *                        criteria.
   * @param  parser         The argument parser which has been initialized from
   *                        the configuration for this uncached entry criteria.
   *
   * @throws  LDAPException  If a problem occurs while initializing this
   *                         uncached entry criteria.
   */
  public void initializeUncachedEntryCriteria(
                   final DirectoryServerContext serverContext,
                   final UncachedEntryCriteriaConfig config,
                   final ArgumentParser parser)
         throws LDAPException
  {
    // No initialization will be performed by default.
  }



  /**
   * {@inheritDoc}
   */
  public boolean isConfigurationAcceptable(
                      final UncachedEntryCriteriaConfig config,
                      final ArgumentParser parser,
                      final List unacceptableReasons)
  {
    // No extended validation will be performed.
    return true;
  }



  /**
   * {@inheritDoc}
   */
  public ResultCode applyConfiguration(
                         final UncachedEntryCriteriaConfig config,
                         final ArgumentParser parser,
                         final List adminActionsRequired,
                         final List messages)
  {
    // By default, no configuration changes will be applied.  If there are any
    // arguments, then add an admin action message indicating that the extension
    // needs to be restarted for any changes to take effect.
    if (! parser.getNamedArguments().isEmpty())
    {
      adminActionsRequired.add(
           "No configuration change has actually been applied.  The new " +
                "configuration will not take effect until this uncached " +
                "entry criteria is disabled and re-enabled or until the " +
                "server is restarted.");
    }

    return ResultCode.SUCCESS;
  }



  /**
   * Performs any cleanup which may be necessary when this uncached entry
   * criteria instance is to be taken out of service.
   */
  public void finalizeUncachedEntryCriteria()
  {
    // No implementation is required.
  }



  /**
   * Indicates whether the provided entry should be written into the
   * uncached-id2entry database rather than into id2entry.  This method may be
   * used both for new entries (e.g., from add operations or LDIF imports) or
   * existing entries (e.g., from modify, modify DN, or soft delete operations,
   * or from re-encode processing).
   *
   * @param  previousEntry  A read-only representation of the entry as it
   *                        existed before the update.  If the entry is
   *                        unchanged or did not previously exist, then this
   *                        will be the same as {@code updatedEntry}.
   * @param  updatedEntry   A read-only representation of the entry as it will
   *                        be written into either the id2entry or
   *                        uncached-id2entry database.
   *
   * @return  {@code true} if the entry should be written into the
   *          uncached-id2entry database, or {@code false} if it should be
   *          written into the id2entry database.
   */
  public abstract boolean shouldBeUncached(final Entry previousEntry,
                                           final Entry updatedEntry);
}