/*
* 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.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;
}
}
