com.unboundid.directory.sdk.ds.api.UncachedAttributeCriteria 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
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
PingDirectory Server, PingDirectoryProxy Server, PingDataSync Server,
PingDataMetrics Server, and PingAuthorize Server.
The 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 2010-2024 Ping Identity Corporation
*/
package com.unboundid.directory.sdk.ds.api;
import java.util.Collections;
import java.util.List;
import java.util.Map;
import com.unboundid.directory.sdk.common.internal.ExampleUsageProvider;
import com.unboundid.directory.sdk.common.internal.Reconfigurable;
import com.unboundid.directory.sdk.common.internal.UnboundIDExtension;
import com.unboundid.directory.sdk.common.types.Entry;
import com.unboundid.directory.sdk.ds.config.UncachedAttributeCriteriaConfig;
import com.unboundid.directory.sdk.ds.scripting.
ScriptedUncachedAttributeCriteria;
import com.unboundid.directory.sdk.ds.types.DirectoryServerContext;
import com.unboundid.directory.sdk.ds.internal.DirectoryServerExtension;
import com.unboundid.ldap.sdk.Attribute;
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 extensions which have
* the ability to determine which attributes should be stored in the
* uncached-id2entry database of a local DB backend, while the remainder of the
* entry is stored in the id2entry database. In environments with data sets too
* large to fit in available memory, and in which entries have a significant
* amount of space consumed by attributes which are not frequently accessed,
* this can help the server better use the memory it does have for attributes
* that are more likely to be accessed.
*
* Configuring Uncached Attribute Criteria
* In order to configure an uncached attribute criteria object created using
* this API, use a command like:
*
* dsconfig create-uncached-attribute-criteria \
* --criteria-name "{criteria-name}" \
* --type third-party \
* --set enabled:true \
* --set "extension-class:{class-name}" \
* --set "extension-argument:{name=value}"
*
* where "{criteria-name}" is the name to use for the uncached attribute
* criteria instance, "{class-name}" is the fully-qualified name of the
* Java class that extends
* {@code com.unboundid.directory.sdk.ds.api.UncachedAttributeCriteria},
* and "{name=value}" represents name-value pairs for any arguments to
* provide to the uncached attribute criteria. If multiple arguments
* should be provided to the criteria, then the
* "--set extension-argument:{name=value}" option should be
* provided multiple times.
*
*
* @see ScriptedUncachedAttributeCriteria
*/
@Extensible()
@DirectoryServerExtension()
@ThreadSafety(level=ThreadSafetyLevel.INTERFACE_THREADSAFE)
public abstract class UncachedAttributeCriteria
implements UnboundIDExtension,
Reconfigurable,
ExampleUsageProvider
{
/**
* Creates a new instance of this uncached attribute criteria. All uncached
* attribute criteria implementations must include a default constructor, but
* any initialization should generally be done in the
* {@code initializeUncachedAttributeCriteria} method.
*/
public UncachedAttributeCriteria()
{
// No implementation is required. However, we need to reference the
// scripted uncached attribute criteria so that checkstyle is satisfied
// with the import.
final ScriptedUncachedAttributeCriteria scriptedCriteria = null;
}
/**
* {@inheritDoc}
*/
public abstract String getExtensionName();
/**
* {@inheritDoc}
*/
public abstract String[] getExtensionDescription();
/**
* {@inheritDoc}
*/
public void defineConfigArguments(final ArgumentParser parser)
throws ArgumentException
{
// No arguments will be allowed by default.
}
/**
* Initializes this uncached attribute 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
* attribute criteria.
* @param parser The argument parser which has been initialized from
* the configuration for this uncached attribute
* criteria.
*
* @throws LDAPException If a problem occurs while initializing this
* uncached attribute criteria.
*/
public void initializeUncachedAttributeCriteria(
final DirectoryServerContext serverContext,
final UncachedAttributeCriteriaConfig config,
final ArgumentParser parser)
throws LDAPException
{
// No initialization will be performed by default.
}
/**
* {@inheritDoc}
*/
public boolean isConfigurationAcceptable(
final UncachedAttributeCriteriaConfig config,
final ArgumentParser parser,
final List unacceptableReasons)
{
// No extended validation will be performed by default.
return true;
}
/**
* {@inheritDoc}
*/
public ResultCode applyConfiguration(
final UncachedAttributeCriteriaConfig 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 " +
"attribute 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 attribute
* criteria instance is to be taken out of service.
*/
public void finalizeUncachedAttributeCriteria()
{
// No implementation is required.
}
/**
* Indicates whether the provided attribute should be written into the
* uncached-id2entry database rather than into id2entry.
*
* @param attribute A read-only representation of the attribute for which to
* make the determination.
* @param entry A read-only representation of the full entry to be
* encoded.
*
* @return {@code true} if the attribute 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 Attribute attribute,
final Entry entry);
/**
* {@inheritDoc}
*/
public Map,String> getExamplesArgumentSets()
{
return Collections.emptyMap();
}
}