UnboundID Server SDK

Ping Identity
UnboundID Server SDK Documentation

ExampleUncachedEntryCriteria.java

/*
 * 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-2023 Ping Identity Corporation
 */
package com.unboundid.directory.sdk.examples;



import java.util.Collections;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;

import com.unboundid.directory.sdk.common.types.Entry;
import com.unboundid.directory.sdk.ds.api.UncachedEntryCriteria;
import com.unboundid.directory.sdk.ds.config.UncachedEntryCriteriaConfig;
import com.unboundid.directory.sdk.ds.types.DirectoryServerContext;
import com.unboundid.ldap.sdk.LDAPException;
import com.unboundid.util.StaticUtils;
import com.unboundid.util.args.ArgumentParser;



/**
 * This class provides a simple example of an uncached entry criteria object
 * that will compute a sum of all bytes contained in the normalized DN of the
 * target entry, and indicate that all sums which are even numbers should be
 * cached while those that are odd should be uncached.  It does not take any
 * arguments.
 * <BR><BR>
 * This uncached entry criteria object isn't intended for real-world use.
 * Rather, it is only provided as an example demonstrating the logic for
 * determining whether an entry should be cached or uncached.  It may also be
 * useful for testing purposes because it does not require any changes to
 * entries, is deterministic so that it is possible to predict its behavior, and
 * will likely result in a large number of uncached entries.
 */
public final class ExampleUncachedEntryCriteria
       extends UncachedEntryCriteria
{
  // The server context for the server in which this extension is running.
  private DirectoryServerContext serverContext = null;



  /**
   * 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 ExampleUncachedEntryCriteria()
  {
    // No implementation required.
  }



  /**
   * Retrieves a human-readable name for this extension.
   *
   * @return  A human-readable name for this extension.
   */
  @Override()
  public String getExtensionName()
  {
    return "Example Uncached Entry Criteria";
  }



  /**
   * Retrieves a human-readable description for this extension.  Each element
   * of the array that is returned will be considered a separate paragraph in
   * generated documentation.
   *
   * @return  A human-readable description for this extension, or {@code null}
   *          or an empty array if no description should be available.
   */
  @Override()
  public String[] getExtensionDescription()
  {
    return new String[]
    {
      "This uncached entry criteria determines whether an entry should be " +
           "stored in id2entry or uncached-id2entry based on a computation " +
           "performed on the normalized DN of the entry.  If the sum of all " +
           "bytes in the normalized DN is even, the entry will be cached, " +
           "but if the sum is odd then it will be uncached."
    };
  }



  /**
   * 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.
   */
  @Override()
  public void initializeUncachedEntryCriteria(
                   final DirectoryServerContext serverContext,
                   final UncachedEntryCriteriaConfig config,
                   final ArgumentParser parser)
         throws LDAPException
  {
    serverContext.debugInfo("Beginning uncached entry criteria initialization");

    this.serverContext = serverContext;
  }



  /**
   * 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.
   */
  @Override()
  public boolean shouldBeUncached(final Entry previousEntry,
                                  final Entry updatedEntry)
  {
    // NOTE:  As stated above, the logic provided in this method is not
    // recommended for use in real-world environments.  It is merely provided
    // for demonstration purposes.

    // Get the normalized representation of the DN.  If this fails, then
    // indicate the DN should be cached.
    final String dn;
    try
    {
      dn = updatedEntry.getParsedDN().toNormalizedString();
    }
    catch (final Exception e)
    {
      serverContext.debugCaught(e);
      return false;
    }

    // Compute a sum of all the bytes in the DN.
    final byte[] dnBytes = StaticUtils.getBytes(dn);
    long sum = 0L;
    for (final byte b : dnBytes)
    {
      sum += (0xFFL & b);
    }

    // If the sum of DN bytes is even, then the entry should be cached.  If it's
    // odd, then the entry should be uncached.
    return ((sum % 2L) != 0);
  }



  /**
   * Retrieves a map containing examples of configurations that may be used for
   * this extension.  The map key should be a list of sample arguments, and the
   * corresponding value should be a description of the behavior that will be
   * exhibited by the extension when used with that configuration.
   *
   * @return  A map containing examples of configurations that may be used for
   *          this extension.  It may be {@code null} or empty if there should
   *          not be any example argument sets.
   */
  @Override()
  public Map<List<String>,String> getExamplesArgumentSets()
  {
    final LinkedHashMap<List<String>,String> exampleMap =
         new LinkedHashMap<List<String>,String>(1);

    exampleMap.put(Collections.<String>emptyList(),
         "Configure the uncached entry criteria without any arguments, as " +
              "none are needed for this implementation.");

    return exampleMap;
  }
}