com.unboundid.directory.sdk.ds.api.RequestCriteria 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 2013-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.broker.internal.BrokerExtension;
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.OperationContext;
import com.unboundid.directory.sdk.ds.config.RequestCriteriaConfig;
import com.unboundid.directory.sdk.ds.types.DirectoryServerContext;
import com.unboundid.directory.sdk.ds.internal.DirectoryServerExtension;
import com.unboundid.directory.sdk.metrics.internal.MetricsEngineExtension;
import com.unboundid.directory.sdk.proxy.internal.DirectoryProxyServerExtension;
import com.unboundid.directory.sdk.sync.internal.SynchronizationServerExtension;
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 can
 * be used to classify client requests.
 * 

 * Configuring Request Criteria
 * In order to configure a request criteria object created using this API, use a
 * command like:
 *  *      dsconfig create-request-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 request criteria
 * instance, "{class-name}" is the fully-qualified name of the Java class
 * that extends {@code com.unboundid.directory.sdk.ds.api.RequestCriteria}, and
 * "{name=value}" represents name-value pairs for any arguments to
 * provide to the request criteria.  If multiple arguments should be provided to
 * the request criteria instance, then the
 * "--set extension-argument:{name=value}" option should be
 * provided multiple times.
 */
@Extensible()
@DirectoryServerExtension()
@DirectoryProxyServerExtension(appliesToLocalContent=true,
     appliesToRemoteContent=true)
@SynchronizationServerExtension(appliesToLocalContent=true,
     appliesToSynchronizedContent=false)
@MetricsEngineExtension()
@BrokerExtension()
@ThreadSafety(level=ThreadSafetyLevel.INTERFACE_THREADSAFE)
public abstract class RequestCriteria
       implements UnboundIDExtension,
                  Reconfigurable,
                  ExampleUsageProvider
{
  /**
   * Creates a new instance of this request criteria.  All request criteria
   * implementations must include a default constructor, but any initialization
   * should generally be done in the {@code initializeRequestCriteria} method.
   */
  public RequestCriteria()
  {
    // No implementation is required.
  }



  /**
   * {@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 request 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 request criteria.
   * @param  parser         The argument parser which has been initialized from
   *                        the configuration for this request criteria.
   *
   * @throws  LDAPException  If a problem occurs while initializing this request
   *                         criteria.
   */
  public void initializeRequestCriteria(
                   final DirectoryServerContext serverContext,
                   final RequestCriteriaConfig config,
                   final ArgumentParser parser)
         throws LDAPException
  {
    // No initialization will be performed by default.
  }



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



  /**
   * {@inheritDoc}
   */
  public ResultCode applyConfiguration(final RequestCriteriaConfig 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 request " +
                "criteria is disabled and re-enabled or until the server is " +
                "restarted.");
    }

    return ResultCode.SUCCESS;
  }



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



  /**
   * Indicates whether the provided operation matches the criteria for this
   * request criteria object.
   *
   * @param  o  The operation for which to make the determination.
   *
   * @return  {@code true} if the provided operation matches the criteria for
   *          this request criteria object, or {@code false} if not.
   */
  public abstract boolean matches(final OperationContext o);



  /**
   * {@inheritDoc}
   */
  public Map,String> getExamplesArgumentSets()
  {
    return Collections.emptyMap();
  }
}