UnboundID Server SDK

Ping Identity
UnboundID Server SDK Documentation

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



import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collections;
import java.util.HashSet;
import java.util.List;
import java.util.Map;
import java.util.Set;

import com.unboundid.directory.sdk.common.schema.AttributeType;
import com.unboundid.directory.sdk.common.operation.AddRequest;
import com.unboundid.directory.sdk.common.operation.AddResult;
import com.unboundid.directory.sdk.common.operation.ModifyRequest;
import com.unboundid.directory.sdk.common.operation.ModifyResult;
import com.unboundid.directory.sdk.common.operation.UpdatableAddRequest;
import com.unboundid.directory.sdk.common.operation.UpdatableAddResult;
import com.unboundid.directory.sdk.common.operation.UpdatableModifyRequest;
import com.unboundid.directory.sdk.common.operation.UpdatableModifyResult;
import com.unboundid.directory.sdk.common.types.ActiveOperationContext;
import com.unboundid.directory.sdk.common.types.AlertSeverity;
import com.unboundid.directory.sdk.common.types.CompletedOperationContext;
import com.unboundid.directory.sdk.common.types.Entry;
import com.unboundid.directory.sdk.common.types.InternalConnection;
import com.unboundid.directory.sdk.common.types.OperationContext;
import com.unboundid.directory.sdk.ds.api.Plugin;
import com.unboundid.directory.sdk.ds.config.PluginConfig;
import com.unboundid.directory.sdk.ds.types.DirectoryServerContext;
import com.unboundid.directory.sdk.ds.types.PostResponsePluginResult;
import com.unboundid.directory.sdk.ds.types.PreOperationPluginResult;
import com.unboundid.directory.sdk.ds.types.PreParsePluginResult;
import com.unboundid.ldap.sdk.Attribute;
import com.unboundid.ldap.sdk.DereferencePolicy;
import com.unboundid.ldap.sdk.DN;
import com.unboundid.ldap.sdk.Filter;
import com.unboundid.ldap.sdk.LDAPException;
import com.unboundid.ldap.sdk.LDAPSearchException;
import com.unboundid.ldap.sdk.Modification;
import com.unboundid.ldap.sdk.ModificationType;
import com.unboundid.ldap.sdk.RDN;
import com.unboundid.ldap.sdk.ResultCode;
import com.unboundid.ldap.sdk.SearchRequest;
import com.unboundid.ldap.sdk.SearchResult;
import com.unboundid.ldap.sdk.SearchResultEntry;
import com.unboundid.ldap.sdk.SearchScope;
import com.unboundid.ldap.sdk.unboundidds.jsonfilter.ANDJSONObjectFilter;
import com.unboundid.ldap.sdk.unboundidds.jsonfilter.EqualsAnyJSONObjectFilter;
import com.unboundid.ldap.sdk.unboundidds.jsonfilter.EqualsJSONObjectFilter;
import com.unboundid.ldap.sdk.unboundidds.jsonfilter.JSONObjectFilter;
import com.unboundid.ldap.sdk.unboundidds.jsonfilter.NegateJSONObjectFilter;
import com.unboundid.util.StaticUtils;
import com.unboundid.util.args.ArgumentException;
import com.unboundid.util.args.ArgumentParser;
import com.unboundid.util.args.BooleanValueArgument;
import com.unboundid.util.args.DNArgument;
import com.unboundid.util.args.FilterArgument;
import com.unboundid.util.args.StringArgument;
import com.unboundid.util.json.JSONArray;
import com.unboundid.util.json.JSONObject;
import com.unboundid.util.json.JSONValue;



/**
 * The JSON Field Uniqueness Plugin can be used to enforce uniqueness
 * constraints for values of a specified JSON field stored in a given LDAP
 * attribute.  Uniqueness can be enforced across entries so that the same value
 * will not be allowed to appear in two different entries.  It can also be
 * enforced within the same entry, so that each value of the JSON field (whether
 * in separate values of the LDAP attribute or within a JSON array in the same
 * LDAP attribute value).
 * <BR><BR>
 * This plugin can be used in either the Directory Server or the Directory Proxy
 * Server, although it is not recommended to be configured in both types of
 * servers in the same topology.  In deployments in which each Directory Server
 * instance contains a complete copy of all the data (regardless of whether
 * requests to those instances pass through the Directory Proxy Server), the
 * plugin should be configured in all Directory Server instances as a
 * pre-operation and post-synchronization plugin for add and modify operations,
 * and it should not be configured in any Directory Proxy Server instances.  For
 * each add and modify request received from an external client, the plugin will
 * check to see if that operation includes any changes involving the target JSON
 * field within the appropriate LDAP attribute, and will reject any change that
 * would introduce a conflict with a value that already exists in another entry,
 * or that includes duplicate values within the same entry if that is not
 * allowed.  It will also examine each add and modify operation that is
 * replicated from another server, and if that operation introduced a conflict
 * (which may arise if two conflicting requests are processed by different
 * servers at the same time), the plugin will generate an alert to notify
 * administrators of the conflict so that it can be addressed by manual
 * interaction.
 * <BR><BR>
 * In deployments that use the Directory Proxy Server to separate data across
 * multiple servers, whether through entry balancing or by separating different
 * portions of the DIT across different sets of servers, the plugin should be
 * configured in all Directory Proxy Server instances as a pre-parse and
 * post-response plugin for add and modify operations, and it should not be
 * configured in any of the Directory Server instances.  For each add and modify
 * request received by the Directory Proxy Server, the plugin will reject any
 * request that attempts to introduce a conflicting value for the target JSON
 * field.  It will also check for conflicts after each of those operations have
 * completed (to ensure that no conflicts were introduced by two conflicting
 * requests processed by different servers at the same time), and the plugin
 * will generate an alert to notify administrators of each conflict identified
 * so that they can be addressed by manual interaction.
 */
public class JSONFieldUniquenessPlugin
       extends Plugin
{
  /**
   * The parent DN for all JSON attribute constraints definitions contained in
   * the server configuration.
   */
  private static final DN JSON_ATTRIBUTE_CONSTRAINTS_PARENT_DN = new DN(
       new RDN("cn", "JSON Attribute Constraints"),
       new RDN("cn", "Cluster"),
       new RDN("cn", "config"));



  /**
   * The set of expected plugin types for a plugin that is running in the
   * Directory Server.
   */
  private final Set<String> EXPECTED_DIRECTORY_PLUGIN_TYPES =
       Collections.unmodifiableSet(new HashSet<String>(Arrays.asList(
            "preOperationAdd".toLowerCase(),
            "preOperationModify".toLowerCase(),
            "postSynchronizationAdd".toLowerCase(),
            "postSynchronizationModify".toLowerCase())));



  /**
   * The set of expected plugin types for a plugin that is running in the
   * Directory Proxy Server.
   */
  private final Set<String> EXPECTED_PROXY_PLUGIN_TYPES =
       Collections.unmodifiableSet(new HashSet<String>(Arrays.asList(
            "preParseAdd".toLowerCase(),
            "preParseModify".toLowerCase(),
            "postResponseAdd".toLowerCase(),
            "postResponseModify".toLowerCase())));



  /**
   * The name of the required argument used to specify the name or OID of the
   * LDAP attribute for which uniqueness is to be maintained.
   */
  private static final String ARG_ATTR_NAME = "ldap-attribute-name";



  /**
   * The name of the required argument used to specify the path to the JSON
   * field for which uniqueness is to be maintained.
   */
  private static final String ARG_JSON_FIELD_PATH = "json-field-path";



  /**
   * The name of the optional argument used to indicate whether the plugin
   * should ensure that values of the target field must not conflict with values
   * for the same field across other entries within the branches indicated by
   * the configured base DN(s).
   */
  private static final String ARG_REQUIRE_UNIQUENESS_ACROSS_ENTRIES =
       "require-uniqueness-across-entries";



  /**
   * The name of the optional argument used to indicate whether the plugin
   * should ensure that multiple values of the target field within the same
   * entry will be required to be unique.
   */
  private static final String ARG_REQUIRE_UNIQUENESS_WITHIN_AN_ENTRY =
       "require-uniqueness-within-an-entry";



  /**
   * The name of the optional argument used to specify the base DN(s) that will
   * be used for searches to find conflicting entries.
   */
  private static final String ARG_BASE_DN = "entry-base-dn";



  /**
   * The name of the optional argument used to provide an LDAP search filter
   * that indicates the set of entries for which uniqueness must be enforced.
   */
  private static final String ARG_UNIQUE_ENTRY_LDAP_FILTER =
       "unique-entry-ldap-filter";



  /**
   * The name of the optional argument used to provide a JSON object filter that
   * a JSON object contained in a value of the specified LDAP attribute will
   * be required to match before applying the uniqueness constraint to it.
   */
  private static final String ARG_UNIQUE_VALUE_JSON_OBJECT_FILTER =
       "unique-value-json-object-filter";



  /**
   * The name of the attribute in JSON field constraints definitions that
   * indicates whether the associated JSON field is indexed.
   */
  private static final String ATTR_JSON_FIELD_CONSTRAINTS_INDEX_VALUES =
       "ds-cfg-index-values";



  /**
   * The OID for the JSONObject syntax, which is the required syntax for the
   * configured LDAP attribute type.
   */
  private static final String OID_JSON_OBJECT_SYNTAX =
       "1.3.6.1.4.1.30221.2.3.4";



  // The attribute type for which to enforce uniqueness.
  private volatile AttributeType ldapAttributeType;

  // Indicates whether to require uniqueness across entries.
  private volatile boolean requireUniquenessAcrossEntries;

  // Indicates whether to require uniqueness across multiple values in the same
  // entry.
  private volatile boolean requireUniquenessWithinAnEntry;

  // The server context to use during processing.
  private volatile DirectoryServerContext serverContext;

  // An LDAP filter that identifies which entries should be subject to
  // uniqueness constraints.
  private volatile Filter uniqueEntryLDAPFilter;

  // An connection that may be used to perform internal operations within the
  // server.
  private volatile InternalConnection internalConnection;

  // A JSON object filter that identifies which attribute values should be
  // subject to uniqueness constraints.
  private volatile JSONObjectFilter uniqueValueJSONObjectFilter;

  // The base DNs for subtrees in which to enforce uniqueness.
  private volatile List<DN> baseDNs;

  // The path to the JSON field for which to enforce uniqueness.
  private volatile List<String> jsonFieldPath;

  // The configuration for this plugin.
  private volatile PluginConfig config;

  // The string representation of the JSON field path.
  private volatile String jsonFieldPathString;



  /**
   * Creates a new instance of this plugin.
   */
  public JSONFieldUniquenessPlugin()
  {
    ldapAttributeType = null;
    jsonFieldPath = null;
    jsonFieldPathString = null;
    requireUniquenessWithinAnEntry = true;
    requireUniquenessAcrossEntries = true;
    baseDNs = null;
    uniqueEntryLDAPFilter = null;
    uniqueValueJSONObjectFilter = null;

    serverContext = null;
    internalConnection = null;
    config = null;
  }



  /**
   * Retrieves the name for this extension.
   *
   * @return  The name for this extension.
   */
  @Override()
  public String getExtensionName()
  {
    return "JSON Field Uniqueness Plugin";
  }



  /**
   * Retrieves a description for this extension.
   *
   * @return  A description for this extension.
   */
  @Override()
  public String[] getExtensionDescription()
  {
    return new String[]
    {
      "The JSON Field Uniqueness Plugin can be used to enforce uniqueness " +
           "constraints for values of a specified JSON field stored in a " +
           "given LDAP attribute.  Uniqueness can be enforced across entries " +
           "so that the same value will not be allowed to appear in two " +
           "different entries.  It can also be enforced within the same " +
           "entry, so that each value of the JSON field (whether in separate " +
           "values of the LDAP attribute or within a JSON array in the same " +
           "LDAP attribute value).",

      "This plugin can be used in either the Directory Server or the " +
           "Directory Proxy Server, although it is not recommended to be " +
           "configured in both types of servers in the same topology.  In " +
           "deployments in which each Directory Server instance contains a " +
           "complete copy of all the data (regardless of whether requests to " +
           "those instances pass through the Directory Proxy Server), the " +
           "plugin should be configured in all Directory Server instances as " +
           "a pre-operation and post-synchronization plugin for add and " +
           "modify operations, and it should not be configured in any " +
           "Directory Proxy Server instances.  For each add and modify " +
           "request received from an external client, the plugin will check " +
           "to see if that operation includes any changes involving the " +
           "target JSON field within the appropriate LDAP attribute, and " +
           "will reject any change that would introduce a conflict with a " +
           "value that already exists in another entry, or that includes " +
           "duplicate values within the same entry if that is not allowed.  " +
           "It will also examine each add and modify operation that is " +
           "replicated from another server, and if that operation introduced " +
           "a conflict (which may arise if two conflicting requests are " +
           "processed by different servers at the same time), the plugin " +
           "will generate an alert to notify administrators of the conflict " +
           "so that it can be addressed by manual interaction.",

      "In deployments that use the Directory Proxy Server to separate data " +
           "across multiple servers, whether through entry balancing or by " +
           "separating different portions of the DIT across different sets " +
           "of servers, the plugin should be configured in all Directory " +
           "Proxy Server instances as a pre-parse and post-response plugin " +
           "for add and modify operations, and it should not be configured " +
           "in any of the Directory Server instances.  For each add and " +
           "modify request received by the Directory Proxy Server, the " +
           "plugin will reject any request that attempts to introduce a " +
           "conflicting value for the target JSON field.  It will also check " +
           "for conflicts after each of those operations have completed (to " +
           "ensure that no conflicts were introduced by two conflicting " +
           "requests processed by different servers at the same time), and " +
           "the plugin will generate an alert to notify administrators of " +
           "each conflict identified so that they can be addressed by " +
           "manual interaction."
    };
  }



  /**
   * Updates the provided argument parser to include the arguments for this
   * extension.
   *
   * @param  parser  The argument parser to update.
   */
  @Override()
  public void defineConfigArguments(final ArgumentParser parser)
         throws ArgumentException
  {
    parser.addArgument(new StringArgument(null, ARG_ATTR_NAME, true, 1,
         "{attribute}",
         "The name or OID of the LDAP attribute type whose values will be " +
              "examined for uniqueness conflicts.  This attribute type must " +
              "be defined with a JSON Object syntax (OID " +
              "1.3.6.1.4.1.30221.2.3.4) in the schema for all Directory " +
              "Server and Directory Proxy Server instances in the topology.  " +
              "All Directory Server instances must be configured with a JSON " +
              "object constraints definition for this attribute type.  This " +
              "is a required argument."));

    parser.addArgument(new StringArgument(null, ARG_JSON_FIELD_PATH, true, 1,
         "{path}",
         "The path to the JSON field for which uniqueness will be enforced.  " +
              "For a top-level field, the path should simply be the name of " +
              "that field.  For a nested field (a field contained in a JSON " +
              "object that is itself the value of a field in an outer JSON " +
              "object), the path to the field should be constructed by " +
              "concatenating the names of the fields in that path, in order " +
              "from outermost to innermost, and separating them with " +
              "periods.  For example, if a JSON object has a top-level field " +
              "named \"contact-info\" whose value is a JSON object that may " +
              "contain an \"email-address\" field, then the json-field-path " +
              "value for that field would be " +
              "\"contact-info.email-address\".  If the name of any field " +
              "in the path contains one or more periods, those periods " +
              "should be escaped by preceding them with a backslash so that " +
              "the only unescaped periods are those used as delimiters " +
              "between field names.  All Directory Server instances must be " +
              "configured with a JSON field constraints definition for this " +
              "field, and that definition must have the index-values " +
              "property set to true.  JSON field names will be treated in " +
              "a case-sensitive manner.  This is a required argument."));

    parser.addArgument(new BooleanValueArgument(null,
         ARG_REQUIRE_UNIQUENESS_ACROSS_ENTRIES, false, "{true|false}",
         "Indicates whether the plugin should check for uniqueness conflicts " +
              "across separate entries.  If this is true, or if it is " +
              "omitted from the configuration, then the plugin will reject " +
              "any add or modify request that attempts to set one or more " +
              "values for the target JSON field if any of those values is " +
              "already in use in any other entry, and it will raise an " +
              "administrative alert for each conflict discovered after the " +
              "change has already been applied.  If this is false, then the " +
              "plugin will not attempt to identify uniqueness conflicts in " +
              "separate entries.  At least one of the " +
              "require-uniqueness-across-entries and " +
              "require-uniqueness-within-an-entry properties must be set to " +
              "true.",
         Boolean.TRUE));

    parser.addArgument(new BooleanValueArgument(null,
         ARG_REQUIRE_UNIQUENESS_WITHIN_AN_ENTRY, false, "{true|false}",
         "Indicates whether the plugin should check for uniqueness conflicts " +
              "within the same entry.  If this is true, or if it is omitted " +
              "from the configuration, then the plugin will reject any add " +
              "or modify request that attempts to set one or more values for " +
              "the target JSON field if any of those values is already in " +
              "use in the same entry, whether in separate value for the " +
              "LDAP attribute, or in another value in a JSON array.  If this " +
              "is false, then the plugin will not attempt to identify " +
              "uniqueness conflicts within the same entry.  At least one of " +
              "the require-uniqueness-across-entries and " +
              "require-uniqueness-within-an-entry properties must be set to " +
              "true.",
         Boolean.TRUE));

    parser.addArgument(new DNArgument(null, ARG_BASE_DN, false, 0, "{dn}",
         "The base DN for a subtree in which the plugin will enforce " +
              "uniqueness constraints.  This can be provided multiple times " +
              "to specify multiple base DNs, and if it is not specified, " +
              "then the plugin will use a default set of base DNs that is " +
              "the set of public naming contexts for the server.  The " +
              "plugin will only examine add and modify requests that target " +
              "entries at or below one of these base DNs, and if uniqueness " +
              "is to be enforced across entries, it will ignore any " +
              "conflicts that may be identified outside any of the " +
              "configured base DNs."));

    parser.addArgument(new FilterArgument(null, ARG_UNIQUE_ENTRY_LDAP_FILTER,
         false, 1, "{ldap-filter}",
         "An optional LDAP search filter that may be used to identify the " +
              "set of entries for which uniqueness should be enforced.  If a " +
              "filter is configured, then the plugin will ignore any add or " +
              "modify requests that target entries that do not match this " +
              "filter, and if uniqueness is to be enforced across entries, " +
              "it will ignore conflicts that may be identified in entries " +
              "that do not match this filter."));

    parser.addArgument(new StringArgument(null,
         ARG_UNIQUE_VALUE_JSON_OBJECT_FILTER, false, 1, "{json-object-filter}",
         "An optional JSON object filter that may be used to identify which " +
              "values of a multivalued attribute should be subject to the " +
              "uniqueness constraints.  If a unique value JSON object " +
              "filter is configured, then the plugin will ignore field " +
              "values for JSON objects that do not match this filter."));
  }



  /**
   * Initializes this plugin.
   *
   * @param  serverContext  A handle to the server context for the server in
   *                        which this extension is running.
   * @param  config         The general configuration for this plugin.
   * @param  parser         The argument parser which has been initialized from
   *                        the configuration for this plugin.
   *
   * @throws  LDAPException  If a problem occurs while initializing this plugin.
   */
  @Override()
  public void initializePlugin(final DirectoryServerContext serverContext,
                               final PluginConfig config,
                               final ArgumentParser parser)
         throws LDAPException
  {
    this.serverContext = serverContext;
    this.config = config;


    // Make sure that we have an internal connection to use for processing
    // internal operations.
    if (internalConnection == null)
    {
      internalConnection = serverContext.getInternalRootConnection();
    }


    // Use the applyConfiguration method to set up the plugin.
    final ArrayList<String> adminActionsRequired = new ArrayList<String>(5);
    final ArrayList<String> messages = new ArrayList<String>(5);

    final ResultCode resultCode = applyConfiguration(config, parser,
         adminActionsRequired, messages);
    if (resultCode != ResultCode.SUCCESS)
    {
      throw new LDAPException(resultCode,
           "One or more errors occurred while trying to initialize the JSON " +
                "field uniqueness plugin using the configuration contained " +
                "in '" + config.getConfigObjectDN() + "':  " +
                StaticUtils.concatenateStrings(messages));
    }
  }



  /**
   * Performs any processing which may be necessary before the server starts
   * processing for an add request.  This will be invoked only for add
   * operations requested directly by clients, but not for add operations
   * received from another server via replication.
   *
   * @param  operationContext  The context for the add operation.
   * @param  request           The add request to be processed.  It may be
   *                           altered if desired.
   * @param  result            The result that will be returned to the client if
   *                           the plugin result indicates that processing on
   *                           the operation should be interrupted.  It may be
   *                           altered if desired.
   *
   * @return  Information about the result of the plugin processing.
   */
  @Override()
  public PreParsePluginResult doPreParse(
              final ActiveOperationContext operationContext,
              final UpdatableAddRequest request,
              final UpdatableAddResult result)
  {
    try
    {
      ensureUniqueness(request.getEntry().toLDAPSDKEntry(), serverContext,
           operationContext, config, internalConnection, ldapAttributeType,
           jsonFieldPathString, jsonFieldPath, requireUniquenessWithinAnEntry,
           requireUniquenessAcrossEntries, baseDNs, uniqueEntryLDAPFilter,
           uniqueValueJSONObjectFilter);

      return PreParsePluginResult.SUCCESS;
    }
    catch (final LDAPException le)
    {
      serverContext.debugCaught(le);
      result.setResultData(le);

      return new PreParsePluginResult(false, false, true, true);
    }
  }



  /**
   * Performs any processing which may be necessary before the server actually
   * attempts to add an entry to the appropriate backend.  This will be invoked
   * only for add operations requested directly by clients, but not for add
   * operations received from another server via replication.
   *
   * @param  operationContext  The context for the add operation.
   * @param  request           The add request to be processed.
   * @param  result            The result that will be returned to the client if
   *                           the plugin result indicates that processing on
   *                           the operation should be interrupted.  It may be
   *                           altered if desired.
   *
   * @return  Information about the result of the plugin processing.
   */
  @Override()
  public PreOperationPluginResult doPreOperation(
              final ActiveOperationContext operationContext,
              final AddRequest request, final UpdatableAddResult result)
  {
    try
    {
      ensureUniqueness(request.getEntry().toLDAPSDKEntry(), serverContext,
           operationContext, config, internalConnection, ldapAttributeType,
           jsonFieldPathString, jsonFieldPath, requireUniquenessWithinAnEntry,
           requireUniquenessAcrossEntries, baseDNs, uniqueEntryLDAPFilter,
           uniqueValueJSONObjectFilter);

      return PreOperationPluginResult.SUCCESS;
    }
    catch (final LDAPException le)
    {
      serverContext.debugCaught(le);
      result.setResultData(le);

      return new PreOperationPluginResult(false, false, true, true);
    }
  }



  /**
   * Performs any processing which may be necessary after all other processing
   * has been completed for an add operation and the response has been sent to
   * the client.  This will be invoked only for add operations requested
   * directly by clients, but not for add operations received from another
   * server via replication.
   *
   * @param  operationContext  The context for the add operation.
   * @param  request           The add request that was processed.
   * @param  result            The result that was returned to the client.
   *
   * @return  Information about the result of the plugin processing.
   */
  @Override()
  public PostResponsePluginResult doPostResponse(
              final CompletedOperationContext operationContext,
              final AddRequest request, final AddResult result)
  {
    try
    {
      ensureUniqueness(request.getEntry().toLDAPSDKEntry(), serverContext,
           operationContext, config, internalConnection, ldapAttributeType,
           jsonFieldPathString, jsonFieldPath, requireUniquenessWithinAnEntry,
           requireUniquenessAcrossEntries, baseDNs, uniqueEntryLDAPFilter,
           uniqueValueJSONObjectFilter);
    }
    catch (final LDAPException le)
    {
      serverContext.debugCaught(le);

      // This means that a replicated operation generated a conflict.  We can't
      // do anything to prevent this, but we can generate an administrative
      // alert to notify administrators of the problem.
      serverContext.sendAlert(AlertSeverity.ERROR, le.getMessage());
    }

    return PostResponsePluginResult.SUCCESS;
  }



  /**
   * Performs any processing which may be necessary after all other processing
   * has been completed for an add operation which has been received from
   * another server via replication.
   *
   * @param  operationContext  The context for the add operation.
   * @param  request           The add request that was processed.
   * @param  result            The result that was returned to the client.
   */
  @Override()
  public void doPostReplication(
                   final CompletedOperationContext operationContext,
                   final AddRequest request, final AddResult result)
  {
    try
    {
      ensureUniqueness(request.getEntry().toLDAPSDKEntry(), serverContext,
           operationContext, config, internalConnection, ldapAttributeType,
           jsonFieldPathString, jsonFieldPath, requireUniquenessWithinAnEntry,
           requireUniquenessAcrossEntries, baseDNs, uniqueEntryLDAPFilter,
           uniqueValueJSONObjectFilter);
    }
    catch (final LDAPException le)
    {
      serverContext.debugCaught(le);

      // This means that a replicated operation generated a conflict.  We can't
      // do anything to prevent this, but we can generate an administrative
      // alert to notify administrators of the problem.
      serverContext.sendAlert(AlertSeverity.ERROR, le.getMessage());
    }
  }



  /**
   * Performs any processing which may be necessary before the server starts
   * processing for a modify request.  This will be invoked only for modify
   * operations requested directly by clients, but not for modify operations
   * received from another server via replication.
   *
   * @param  operationContext  The context for the modify operation.
   * @param  request           The modify request to be processed.  It may be
   *                           altered if desired.
   * @param  result            The result that will be returned to the client if
   *                           the plugin result indicates that processing on
   *                           the operation should be interrupted.  It may be
   *                           altered if desired.
   *
   * @return  Information about the result of the plugin processing.
   */
  @Override()
  public PreParsePluginResult doPreParse(
              final ActiveOperationContext operationContext,
              final UpdatableModifyRequest request,
              final UpdatableModifyResult result)
  {
    // We aren't given access to the entry (either before or after the changes
    // are applied), so we'll need to fetch it from a backend server and apply
    // the changes to it so we'll have a representation of the updated entry for
    // examination.  But we'll only do that if the request could result in a
    // conflict, since otherwise retrieving the entry would be wasted effort.
    //
    // First, we want to make sure that we're dealing with a consistent
    // configuration, so get all of the configuration properties first.
    final AttributeType attributeType = ldapAttributeType;
    final List<String> fieldPath = jsonFieldPath;
    final String fieldPathString = jsonFieldPathString;
    final boolean uniqueWithinEntry = requireUniquenessWithinAnEntry;
    final boolean uniqueAcrossEntries = requireUniquenessAcrossEntries;
    final Filter uniqueEntryFilter = uniqueEntryLDAPFilter;
    final JSONObjectFilter uniqueValueFilter = uniqueValueJSONObjectFilter;

    if (! couldCreateConflict(request, attributeType, baseDNs, fieldPath))
    {
      return PreParsePluginResult.SUCCESS;
    }


    // Retrieve the entry from a backend server.
    final SearchResultEntry currentEntry;
    try
    {
      currentEntry = internalConnection.getEntry(request.getDN(), "*", "+");
      if (currentEntry == null)
      {
        result.setResultCode(ResultCode.NO_SUCH_OBJECT);
        result.setDiagnosticMessage("Could not find entry " + request.getDN());
        return new PreParsePluginResult(false, false, true, true);
      }
    }
    catch (final LDAPException le)
    {
      serverContext.debugCaught(le);
      result.setResultData(le);
      return new PreParsePluginResult(false, false, true, true);
    }


    // Update the entry with the modifications from the request.
    final com.unboundid.ldap.sdk.Entry updatedEntry;
    try
    {
      updatedEntry = com.unboundid.ldap.sdk.Entry.applyModifications(
           currentEntry, false, request.getModifications());
    }
    catch (final LDAPException le)
    {
      serverContext.debugCaught(le);
      result.setResultData(le);
      return new PreParsePluginResult(false, false, true, true);
    }


    try
    {
      ensureUniqueness(updatedEntry, serverContext, operationContext, config,
           internalConnection, attributeType, fieldPathString, fieldPath,
           uniqueWithinEntry, uniqueAcrossEntries, baseDNs, uniqueEntryFilter,
           uniqueValueFilter);

      return PreParsePluginResult.SUCCESS;
    }
    catch (final LDAPException le)
    {
      serverContext.debugCaught(le);
      result.setResultData(le);
      return new PreParsePluginResult(false, false, true, true);
    }
  }



  /**
   * Performs any processing which may be necessary before the server actually
   * attempts to update the entry in the backend.  This will be invoked only for
   * modify operations requested directly by clients, but not for modify
   * operations received from another server via replication.
   *
   * @param  operationContext  The context for the modify operation.
   * @param  request           The modify request to be processed.
   * @param  result            The result that will be returned to the client if
   *                           the plugin result indicates that processing on
   *                           the operation should be interrupted.  It may be
   *                           altered if desired.
   * @param  oldEntry          The entry as it appeared before the modifications
   *                           were applied.
   * @param  newEntry          The updated entry as it will appear after the
   *                           modifications have been applied.
   *
   * @return  Information about the result of the plugin processing.
   */
  @Override()
  public PreOperationPluginResult doPreOperation(
              final ActiveOperationContext operationContext,
              final ModifyRequest request, final UpdatableModifyResult result,
              final Entry oldEntry, final Entry newEntry)
  {
    try
    {
      ensureUniqueness(newEntry.toLDAPSDKEntry(), serverContext,
           operationContext, config, internalConnection, ldapAttributeType,
           jsonFieldPathString, jsonFieldPath, requireUniquenessWithinAnEntry,
           requireUniquenessAcrossEntries, baseDNs, uniqueEntryLDAPFilter,
           uniqueValueJSONObjectFilter);

      return PreOperationPluginResult.SUCCESS;
    }
    catch (final LDAPException le)
    {
      serverContext.debugCaught(le);
      result.setResultData(le);

      return new PreOperationPluginResult(false, false, true, true);
    }
  }



  /**
   * Performs any processing which may be necessary after all other processing
   * has been completed for a modify operation and the response has been sent
   * to the client.  This will be invoked only for modify operations requested
   * directly by clients, but not for modify operations received from another
   * server via replication.
   *
   * @param  operationContext  The context for the modify operation.
   * @param  request           The modify request that was processed.
   * @param  result            The result that was returned to the client.
   *
   * @return  Information about the result of the plugin processing.
   */
  @Override()
  public PostResponsePluginResult doPostResponse(
              final CompletedOperationContext operationContext,
              final ModifyRequest request, final ModifyResult result)
  {
    // We aren't given access to the updated entry, so we'll need to fetch it
    // from a backend server.  But we'll only do that if the request could
    // result in a conflict, since otherwise retrieving the entry would be
    // wasted effort.
    //
    // First, we want to make sure that we're dealing with a consistent
    // configuration, so get all of the configuration properties first.
    final AttributeType attributeType = ldapAttributeType;
    final List<String> fieldPath = jsonFieldPath;
    final String fieldPathString = jsonFieldPathString;
    final boolean uniqueWithinEntry = requireUniquenessWithinAnEntry;
    final boolean uniqueAcrossEntries = requireUniquenessAcrossEntries;
    final Filter uniqueEntryFilter = uniqueEntryLDAPFilter;
    final JSONObjectFilter uniqueValueFilter = uniqueValueJSONObjectFilter;

    if (! couldCreateConflict(request, attributeType, baseDNs, fieldPath))
    {
      return PostResponsePluginResult.SUCCESS;
    }


    // Retrieve the entry.
    final SearchResultEntry entry;
    try
    {
      entry = internalConnection.getEntry(request.getDN(), "*", "+");
      if (entry == null)
      {
        if (serverContext.debugEnabled())
        {
          serverContext.debugWarning("The JSON field uniqueness plugin " +
               "defined in configuration entry '" + config.getConfigObjectDN() +
               "' could not find entry '" + request.getDN() +
               "' targeted by proxied modify operation conn=" +
               operationContext.getConnectionID() + " op=" +
               operationContext.getOperationID() +
               ".  This likely indicates that the entry was deleted shortly " +
               "after the modification.  At any rate, no uniqueness conflict " +
               "processing can be performed for this entry.");
        }

        return PostResponsePluginResult.SUCCESS;
      }
    }
    catch (final Exception e)
    {
      if (serverContext.debugEnabled())
      {
        serverContext.debugCaught(e);
        serverContext.debugError("The JSON field uniqueness plugin " +
             "defined in configuration entry '" + config.getConfigObjectDN() +
             "' encountered an error while trying to retrieve entry '" +
             request.getDN() + "' targeted by proxied modify operation " +
             "conn=" + operationContext.getConnectionID() + " op=" +
             operationContext.getOperationID() +
             ":  " + StaticUtils.getExceptionMessage(e) +
             ".  No uniqueness conflict processing can be performed for this " +
             "entry.");
      }

      return PostResponsePluginResult.SUCCESS;
    }


    try
    {
      ensureUniqueness(entry, serverContext, operationContext, config,
           internalConnection, attributeType, fieldPathString, fieldPath,
           uniqueWithinEntry, uniqueAcrossEntries, baseDNs, uniqueEntryFilter,
           uniqueValueFilter);
    }
    catch (final LDAPException le)
    {
      serverContext.debugCaught(le);

      // This means that a proxied operation generated a conflict.  We can't do
      // anything to prevent this, but we can generate an administrative alert
      // to notify administrators of the problem.
      serverContext.sendAlert(AlertSeverity.ERROR, le.getMessage());
    }

    return PostResponsePluginResult.SUCCESS;
  }



  /**
   * Performs any processing which may be necessary after all other processing
   * has been completed for a modify operation which has been received from
   * another server via replication.
   *
   * @param  operationContext  The context for the modify operation.
   * @param  request           The modify request that was processed.
   * @param  result            The result that was returned to the client.
   */
  @Override()
  public void doPostReplication(
                   final CompletedOperationContext operationContext,
                   final ModifyRequest request, final ModifyResult result)
  {
    // We aren't given access to the updated entry, so we'll need to fetch it
    // from the backend.  But we'll only do that if the request could result
    // in a conflict, since otherwise retrieving the entry would be wasted
    // effort.
    //
    // First, we want to make sure that we're dealing with a consistent
    // configuration, so get all of the configuration properties first.
    final AttributeType attributeType = ldapAttributeType;
    final List<String> fieldPath = jsonFieldPath;
    final String fieldPathString = jsonFieldPathString;
    final boolean uniqueWithinEntry = requireUniquenessWithinAnEntry;
    final boolean uniqueAcrossEntries = requireUniquenessAcrossEntries;
    final Filter uniqueEntryFilter = uniqueEntryLDAPFilter;
    final JSONObjectFilter uniqueValueFilter = uniqueValueJSONObjectFilter;

    if (! couldCreateConflict(request, attributeType, baseDNs, fieldPath))
    {
      return;
    }


    // Retrieve the entry.
    final SearchResultEntry entry;
    try
    {
      entry = internalConnection.getEntry(request.getDN(), "*", "+");
      if (entry == null)
      {
        if (serverContext.debugEnabled())
        {
          serverContext.debugWarning("The JSON field uniqueness plugin " +
               "defined in configuration entry '" + config.getConfigObjectDN() +
               "' could not find entry '" + request.getDN() +
               "' targeted by replicated modify operation conn=" +
               operationContext.getConnectionID() + " op=" +
               operationContext.getOperationID() +
               ".  This likely indicates that the entry was deleted shortly " +
               "after the modification.  At any rate, no uniqueness conflict " +
               "processing can be performed for this entry.");
        }
        return;
      }
    }
    catch (final Exception e)
    {
      if (serverContext.debugEnabled())
      {
        serverContext.debugCaught(e);
        serverContext.debugError("The JSON field uniqueness plugin " +
             "defined in configuration entry '" + config.getConfigObjectDN() +
             "' encountered an error while trying to retrieve entry '" +
             request.getDN() + "' targeted by replicated modify operation " +
             "conn=" + operationContext.getConnectionID() + " op=" +
             operationContext.getOperationID() +
             ":  " + StaticUtils.getExceptionMessage(e) +
             ".  No uniqueness conflict processing can be performed for this " +
             "entry.");
      }
      return;
    }


    try
    {
      ensureUniqueness(entry, serverContext, operationContext, config,
           internalConnection, attributeType, fieldPathString, fieldPath,
           uniqueWithinEntry, uniqueAcrossEntries, baseDNs, uniqueEntryFilter,
           uniqueValueFilter);
    }
    catch (final LDAPException le)
    {
      serverContext.debugCaught(le);

      // This means that a replicated operation generated a conflict.  We can't
      // do anything to prevent this, but we can generate an administrative
      // alert to notify administrators of the problem.
      serverContext.sendAlert(AlertSeverity.ERROR, le.getMessage());
    }
  }



  /**
   * Attempts to determine whether the provided modify request could create a
   * uniqueness conflict.
   *
   * @param  request        The modify request being processed.
   * @param  attributeType  The LDAP attribute type for which uniqueness will be
   *                        enforced.
   * @param  baseDNList     The list of base DNs for which uniqueness will be
   *                        enforced.
   * @param  fieldPath      The path to the JSON field for which uniqueness will
   *                        be enforced.
   *
   * @return  {@code true} if the provided modify request could create a
   *          uniqueness conflict, or {@code false} if not.
   */
  private boolean couldCreateConflict(final ModifyRequest request,
                                      final AttributeType attributeType,
                                      final List<DN> baseDNList,
                                      final List<String> fieldPath)
  {
    // See if the target entry is within any of the configured base DNs.  If
    // not, then we don't care about it.
    try
    {
      final DN parsedEntryDN = new DN(request.getDN());

      boolean withinBaseDN = false;
      for (final DN baseDN : baseDNList)
      {
        if (parsedEntryDN.isDescendantOf(baseDN, true))
        {
          withinBaseDN = true;
          break;
        }
      }

      if (! withinBaseDN)
      {
        return false;
      }
    }
    catch (final Exception e)
    {
      serverContext.debugCaught(e);
    }


    // Now, iterate through the modifications to see if any of them could
    // generate a conflict.
    for (final Modification m : request.getModifications())
    {
      // We only care about modification types of ADD or REPLACE.
      if (! ((m.getModificationType() == ModificationType.ADD) ||
             (m.getModificationType() == ModificationType.REPLACE)))
      {
        continue;
      }

      // We only care about modifications that have values.  A REPLACE
      // modification might not have any values if it's intended to remove
      // the attribute from the entry.
      final String[] values = m.getValues();
      if ((values == null) || (values.length == 0))
      {
        continue;
      }

      // See if the modification targets the right attribute type.
      //
      // NOTE:  It's possible that the modification targeted an attribute with
      // options, so we need to check the base name without any options.
      final String baseName = Attribute.getBaseName(m.getAttributeName());
      if (! attributeType.hasNameOrOID(baseName))
      {
        continue;
      }

      // Try to parse each of the values as a JSON object and see if any of
      // them contains the target field.  That'll be enough to convince us
      // that we need to get the entry.
      for (final String value : values)
      {
        try
        {
          final JSONObject o = new JSONObject(value);
          final List<JSONValue> fieldValues = getValues(o, fieldPath);
          if (fieldValues.isEmpty())
          {
            continue;
          }

          return true;
        }
        catch (final Exception e)
        {
          serverContext.debugCaught(e);
        }
      }
    }


    // If we've gotten here, then the modification couldn't have introduced a
    // conflict.
    return false;
  }



  /**
   * Performs all necessary uniqueness processing for the provided entry.
   *
   * @param  entry                The entry to examine.
   * @param  serverContext        The server context.
   * @param  operationContext     The operation context.
   * @param  config               The configuration for the plugin.
   * @param  internalConnection   The internal connection to use to perform
   *                              internal searches.
   * @param  attributeType        The target attribute type.
   * @param  fieldPathString      The string representation of the JSON field
   *                              path.
   * @param  fieldPath            The components that comprise the path to the
   *                              target JSON field.
   * @param  uniqueWithinEntry    Indicates whether to enforce uniqueness across
   *                              multiple values within the same entry.
   * @param  uniqueAcrossEntries  Indicates whether to enforce uniqueness across
   *                              entries within the specified set of base DNs.
   * @param  baseDNs              The set of base DNs below which to enforce
   *                              uniqueness.
   * @param  uniqueEntryFilter    An optional filter that entries must match.
   * @param  uniqueValueFilter    An optional filter that values must match.
   *
   * @throws  LDAPException  If a conflict is found.
   */
  private static void ensureUniqueness(final com.unboundid.ldap.sdk.Entry entry,
                           final DirectoryServerContext serverContext,
                           final OperationContext operationContext,
                           final PluginConfig config,
                           final InternalConnection internalConnection,
                           final AttributeType attributeType,
                           final String fieldPathString,
                           final List<String> fieldPath,
                           final boolean uniqueWithinEntry,
                           final boolean uniqueAcrossEntries,
                           final List<DN> baseDNs,
                           final Filter uniqueEntryFilter,
                           final JSONObjectFilter uniqueValueFilter)
          throws LDAPException
  {
    // See if the entry is below a base DN that we care about.
    try
    {
      final DN parsedEntryDN = entry.getParsedDN();
      boolean withinBaseDN = false;
      for (final DN baseDN : baseDNs)
      {
        if (parsedEntryDN.isDescendantOf(baseDN, true))
        {
          withinBaseDN = true;
          break;
        }
      }

      if (! withinBaseDN)
      {
        if (serverContext.debugEnabled())
        {
          serverContext.debugInfo("The JSON field uniqueness plugin " +
               "defined in configuration entry '" + config.getConfigObjectDN() +
               " is skipping uniqueness processing for entry '" +
               entry.getDN() + "' for conn=" +
               operationContext.getConnectionID() + " op=" +
               operationContext.getOperationID() + " because it is not " +
               "within any of the configured base DNs " + baseDNs);
        }
        return;
      }
    }
    catch (final Exception e)
    {
      if (serverContext.debugEnabled())
      {
        serverContext.debugCaught(e);
        serverContext.debugWarning("The JSON field uniqueness plugin " +
             "defined in configuration entry '" + config.getConfigObjectDN() +
             "' could not parse DN '" + entry.getDN() +
             "' encountered while processing operation conn=" +
             operationContext.getConnectionID() + " op=" +
             operationContext.getOperationID() + ":  " +
             StaticUtils.getExceptionMessage(e) + ".  Going to assume that " +
             "the entry is within a base DN for which uniqueness should be " +
             "enforced.");
      }
    }


    // If there is a unique entry filter, then see if the entry matches it.
    if (uniqueEntryFilter != null)
    {
      try
      {
        if (! uniqueEntryFilter.matchesEntry(entry))
        {
          if (serverContext.debugEnabled())
          {
            serverContext.debugInfo("The JSON field uniqueness plugin " +
                 "defined in configuration entry '" +
                 config.getConfigObjectDN() + " is skipping uniqueness " +
                 "processing for entry '" + entry.getDN() + "' for conn=" +
                 operationContext.getConnectionID() + " op=" +
                 operationContext.getOperationID() + " because it does not " +
                 "match " + ARG_UNIQUE_ENTRY_LDAP_FILTER + " value " +
                 uniqueEntryFilter);
          }
          return;
        }
      }
      catch (final Exception e)
      {
        if (serverContext.debugEnabled())
        {
          serverContext.debugCaught(e);
          serverContext.debugWarning("The JSON field uniqueness plugin " +
               "defined in configuration entry '" + config.getConfigObjectDN() +
               "' encountered an error while evaluating " +
               ARG_UNIQUE_ENTRY_LDAP_FILTER + " value " + uniqueEntryFilter +
               " against entry '" + entry.getDN() + "' for conn=" +
               operationContext.getConnectionID() + " op=" +
               operationContext.getOperationID() + ":  " +
               StaticUtils.getExceptionMessage(e) + ".  Going to assume that " +
               "the entry matches the filter.");
        }
      }
    }


    // Iterate through the attributes in the entry to get a list of all values
    // for the target field from the target attribute type.
    final ArrayList<JSONValue> fieldValues = new ArrayList<JSONValue>(10);
    for (final Attribute a : entry.getAttributes())
    {
      // See if the attribute has the appropriate attribute type.
      //
      // NOTE:  The attribute could have options, so make sure to check the
      // base name.
      if (! attributeType.hasNameOrOID(a.getBaseName()))
      {
        continue;
      }


      // Iterate through the values of the attribute and try to parse them as
      // JSON objects.
      for (final String value : a.getValues())
      {
        final JSONObject o;
        try
        {
          o = new JSONObject(value);
        }
        catch (final Exception e)
        {
          if (serverContext.debugEnabled())
          {
            serverContext.debugCaught(e);
            serverContext.debugWarning("The JSON field uniqueness plugin " +
                 "defined in configuration entry '" +
                 config.getConfigObjectDN() + "' encountered " + a.getName() +
                 " value '" + value + "' in entry '" + entry.getDN() +
                 "' that could not be parsed as a valid JSON object for conn=" +
                 operationContext.getConnectionID() + " op=" +
                 operationContext.getOperationID() + ":  " +
                 StaticUtils.getExceptionMessage(e));
          }
          continue;
        }

        // If we have a uniqueValueFilter, then see if the provided object
        // matches that filter.  If not, then skip this value.
        if ((uniqueValueFilter != null) &&
            (! uniqueValueFilter.matchesJSONObject(o)))
        {
          continue;
        }


        // Extract the values of the target field from the object.  Iterate
        // through them and see if any of them match a value that we've already
        // found.  At the very least, we only want to do the processing for each
        // value once, but we might also want to reject conflicts in the same
        // entry.
        for (final JSONValue jsonValue : getValues(o, fieldPath))
        {
          boolean conflictFound = false;
          for (final JSONValue v : fieldValues)
          {
            if (v.equals(jsonValue, false, true, false))
            {
              conflictFound = true;
              break;
            }
          }

          if (conflictFound)
          {
            if (uniqueWithinEntry)
            {
              throw new LDAPException(ResultCode.UNWILLING_TO_PERFORM,
                   "Entry '" + entry.getDN() + "' has duplicate values for " +
                        "JSON field " + fieldPathString +
                        " but the server is configured to require all values " +
                        "for that field to be unique, even within the same " +
                        "entry.");
            }
          }
          else
          {
            fieldValues.add(jsonValue);
          }
        }
      }
    }


    // If we shouldn't check for conflicts across other entries, or if we didn't
    // find any field values, then we're done.
    if (fieldValues.isEmpty())
    {
      if (serverContext.debugEnabled())
      {
        serverContext.debugInfo("The JSON field uniqueness plugin " +
             "defined in configuration entry '" + config.getConfigObjectDN() +
             "' did not find any " + attributeType.getNameOrOID() +
             " values for field " + fieldPathString + " in entry '" +
             entry.getDN() + "' for conn=" +
             operationContext.getConnectionID() + " op=" +
             operationContext.getOperationID());
      }

      return;
    }

    if (! uniqueAcrossEntries)
    {
      if (serverContext.debugEnabled())
      {
        serverContext.debugInfo("The JSON field uniqueness plugin " +
             "defined in configuration entry '" + config.getConfigObjectDN() +
             "' is only configured to look for duplicate " + fieldPathString +
             " values in attribute " + attributeType.getNames() +
             " within the same entry, and entry '" + entry.getDN() +
             "' for conn=" + operationContext.getConnectionID() + " op=" +
             operationContext.getOperationID() +
             " did not have any such conflicts.");
      }

      return;
    }

    if (serverContext.debugEnabled())
    {
      serverContext.debugInfo("The JSON field uniqueness plugin defined in " +
           "configuration entry '" + config.getConfigObjectDN() +
           "' found one or more values for JSON field " + fieldPathString +
           " in attribute " + attributeType.getNameOrOID() +
           " in entry '" + entry.getDN() + " for operation conn=" +
           operationContext.getConnectionID() + " op=" +
           operationContext.getOperationID() + "':  " + fieldValues +
           ".  Going to search for entries with conflicting values.");
    }


    // We need to look for conflicts across other entries.  First, generate the
    // equals or equalsAny filter to use to identify entries with conflicting
    // values.
    JSONObjectFilter jsonObjectFilter;
    if (fieldValues.size() == 1)
    {
      jsonObjectFilter =
           new EqualsJSONObjectFilter(fieldPath, fieldValues.get(0));
    }
    else
    {
      jsonObjectFilter = new EqualsAnyJSONObjectFilter(fieldPath, fieldValues);
    }

    // If we have a unique value filter, then we'll need to AND the JSON object
    // filter we just created with a NOT of that value filter so that we exclude
    // objects that don't match that filter.
    if (uniqueValueFilter != null)
    {
      jsonObjectFilter = new ANDJSONObjectFilter(jsonObjectFilter,
           new NegateJSONObjectFilter(uniqueValueFilter));
    }


    // Get an LDAP filter that will allow us to process the JSON object filter.
    Filter ldapFilter =
         jsonObjectFilter.toLDAPFilter(attributeType.getNameOrOID());


    // If we have a unique entry filter, then we'll need to AND the LDAP filter
    // we just created with that unique entry filter so that we only check
    // entries that match that filter.
    if (uniqueEntryFilter != null)
    {
      ldapFilter = Filter.createANDFilter(ldapFilter, uniqueEntryFilter);
    }


    // Iterate through the configured base DNs and search beneath them for
    // conflicting entries.
    //
    // NOTE:  Use a size limit of 1 for the search request so that we don't
    // waste time finding all the matches once we know that there are at least
    // two matching entries.  One matching entry may be okay if it's the entry
    // that we're currently validating, and we should only report a conflict for
    // one match if it doesn't match the DN of the entry we're currently
    // validating.  But any more than one match (which should trigger a
    // SIZE_LIMIT_EXCEEDED result) means that there's definitely a conflict.
    final SearchRequest searchRequest = new SearchRequest("", SearchScope.SUB,
         DereferencePolicy.NEVER, 1, 0, false, ldapFilter, "1.1");
    for (final DN baseDN : baseDNs)
    {
      searchRequest.setBaseDN(baseDN);

      SearchResult searchResult;
      try
      {
        searchResult = internalConnection.search(searchRequest);
      }
      catch (final LDAPSearchException lse)
      {
        searchResult = lse.getSearchResult();
      }

      if (serverContext.debugEnabled())
      {
        serverContext.debugInfo("The JSON field uniqueness plugin " +
             "defined in configuration entry '" + config.getConfigObjectDN() +
             "' got search result " + searchResult + " for internal search " +
             searchRequest);
      }

      switch (searchResult.getResultCode().intValue())
      {
        case ResultCode.SUCCESS_INT_VALUE:
          // The search completed successfully, but we need to check the entries
          // that were returned to see if it matched any entry other than the
          // target entry.
          switch (searchResult.getEntryCount())
          {
            case 0:
              break;
            case 1:
              final DN parsedThisDN = entry.getParsedDN();
              final DN parsedFoundDN =
                   searchResult.getSearchEntries().get(0).getParsedDN();
              if (! parsedThisDN.equals(parsedFoundDN))
              {
                throw new LDAPException(ResultCode.UNWILLING_TO_PERFORM,
                     "Entry '" + entry.getDN() + "' has one or more values " +
                          "for JSON field '" + fieldPathString + "' that " +
                          "already exist in at least one other entry in " +
                          "the server, but the server is configured to " +
                          "require all values for that field to be unique.");
              }
              break;
            default:
              throw new LDAPException(ResultCode.UNWILLING_TO_PERFORM,
                   "Entry '" + entry.getDN() + "' has one or more values for " +
                        "JSON field '" + fieldPathString +
                        "' that already exist in at least one other entry in " +
                        "the server, but the server is configured to " +
                        "require all values for that field to be unique.");
          }
          break;

        case ResultCode.NO_SUCH_OBJECT_INT_VALUE:
          // This means that the search base didn't exist.  This definitely
          // means no conflict.
          break;

        case ResultCode.SIZE_LIMIT_EXCEEDED_INT_VALUE:
          // This means that there was definitely a conflict.
          throw new LDAPException(ResultCode.UNWILLING_TO_PERFORM,
               "Entry '" + entry.getDN() + "' has one or more values for " +
                    "JSON field '" + fieldPathString +
                    "' that already exist in at least one other entry in " +
                    "the server, but the server is configured to " +
                    "require all values for that field to be unique.");

        default:
          // This indicates that some other error occurred that prevented the
          // search from succeeding.  We'll treat this like a conflict in that
          // we'll throw an exception to reject the operation (or alert if it's
          // a replicated operation that's already been applied somewhere else)
          // but use a different message for the exception.
          throw new LDAPException(ResultCode.UNWILLING_TO_PERFORM,
               "An error occurred while looking for uniqueness conflicts " +
                    "for values of the '" + fieldPathString +
                    "' field in attribute " + attributeType.getNameOrOID() +
                    " (result code " + searchResult.getResultCode() +
                    ", diagnostic message '" +
                    searchResult.getDiagnosticMessage() + "'.");
      }
    }


    // If we've gotten here, then there are no conflicts.
    if (serverContext.debugEnabled())
    {
      serverContext.debugInfo("The JSON field uniqueness plugin defined in " +
           "configuration entry '" + config.getConfigObjectDN() +
           "' did not find any conflicts for values of JSON field " +
           fieldPathString + " in attribute " + attributeType.getNameOrOID() +
           " in entry '" + entry.getDN() + " for operation conn=" +
           operationContext.getConnectionID() + " op=" +
           operationContext.getOperationID());
    }
  }



  /**
   * Retrieves a list of the values for the specified field from the provided
   * object.
   *
   * @param  o          The JSON object to examine.
   * @param  fieldPath  The path to the JSON field for which to retrieve the
   *                    values.
   *
   * @return  The set of values that match the provided field name specifier, or
   *          an empty list if the provided JSON object does not have any fields
   *          matching the provided specifier.
   */
  private static List<JSONValue> getValues(final JSONObject o,
                                           final List<String> fieldPath)
  {
    final ArrayList<JSONValue> values = new ArrayList<JSONValue>(10);
    getValues(o, fieldPath, 0, values);
    return values;
  }



  /**
   * Adds all values for the specified field to the provided list.
   *
   * @param  o               The JSON object to examine.
   * @param  fieldPath       The path to the JSON field for which to retrieve
   *                         the values.
   * @param  fieldNameIndex  The current index into the field name specifier.
   * @param  values          The list into which matching values should be
   *                         added.
   */
  private static void getValues(final JSONObject o,
                                final List<String> fieldPath,
                                final int fieldNameIndex,
                                final List<JSONValue> values)
  {
    final JSONValue v = o.getField(fieldPath.get(fieldNameIndex));
    if (v == null)
    {
      return;
    }

    final int nextIndex = fieldNameIndex + 1;
    if (nextIndex < fieldPath.size())
    {
      // This indicates that there are more elements in the field name
      // specifier.  The value must either be a JSON object that we can look
      // further into, or it must be an array containing one or more JSON
      // objects.
      if (v instanceof JSONObject)
      {
        getValues((JSONObject) v, fieldPath, nextIndex, values);
      }
      else if (v instanceof JSONArray)
      {
        getValuesFromArray((JSONArray) v, fieldPath, nextIndex, values);
      }

      return;
    }

    // If we've gotten here, then there is no more of the field specifier, so
    // the value we retrieved matches the specifier.  Add it to the list of
    // values.
    values.add(v);
  }



  /**
   * Calls {@code getValues} for any elements of the provided array that are
   * JSON objects, recursively descending into any nested arrays.
   *
   * @param  a               The array to process.
   * @param  fieldPath       The path to the JSON field for which to retrieve
   *                         the values.
   * @param  fieldNameIndex  The current index into the field name specifier.
   * @param  values          The list into which matching values should be
   *                         added.
   */
  private static void getValuesFromArray(final JSONArray a,
                                         final List<String> fieldPath,
                                         final int fieldNameIndex,
                                         final List<JSONValue> values)
  {
    for (final JSONValue v : a.getValues())
    {
      if (v instanceof JSONObject)
      {
        getValues((JSONObject) v, fieldPath, fieldNameIndex, values);
      }
      else if (v instanceof JSONArray)
      {
        getValuesFromArray((JSONArray) v, fieldPath, fieldNameIndex, values);
      }
    }
  }



  /**
   * Indicates whether the configuration represented by the provided argument
   * parser is acceptable for use by this extension.  The parser will have been
   * used to parse any configuration available for this extension, and any
   * automatic validation will have been performed.  This method may be used to
   * perform any more complex validation which cannot be performed automatically
   * by the argument parser.
   *
   * @param  config               The general configuration for this extension.
   * @param  parser               The argument parser that has been used to
   *                              parse the proposed configuration for this
   *                              extension.
   * @param  unacceptableReasons  A list to which messages may be added to
   *                              provide additional information about why the
   *                              provided configuration is not acceptable.
   *
   * @return  {@code true} if the configuration in the provided argument parser
   *          appears to be acceptable, or {@code false} if not.
   */
  @Override()
  public boolean isConfigurationAcceptable(final PluginConfig config,
                      final ArgumentParser parser,
                      final List<String> unacceptableReasons)
  {
    // If the server context is null, then get an instance from the provided
    // configuration.
    if (serverContext == null)
    {
      serverContext = config.getServerContext();
    }


    // Get an internal connection to use for processing internal operations.
    if (internalConnection == null)
    {
      internalConnection = serverContext.getInternalRootConnection();
    }


    // Make sure that the plugin is configured with the appropriate set of
    // plugin types based on the type of product in which it is running.
    boolean acceptable = true;
    final boolean isDirectoryServer;
    final Set<String> pluginTypes = config.getPluginTypes();
    if (serverContext.isDirectoryFunctionalityAvailable())
    {
      isDirectoryServer = true;
      if (! pluginTypes.equals(EXPECTED_DIRECTORY_PLUGIN_TYPES))
      {
        acceptable = false;
        unacceptableReasons.add("When the " + getExtensionName() +
             " is used in the Directory Server, it must be configured with " +
             "the following plugin types:  " + EXPECTED_DIRECTORY_PLUGIN_TYPES +
             '.');
      }
    }
    else if (serverContext.isDirectoryProxyFunctionalityAvailable())
    {
      isDirectoryServer = false;
      if (! pluginTypes.equals(EXPECTED_PROXY_PLUGIN_TYPES))
      {
        acceptable = false;
        unacceptableReasons.add("When the " + getExtensionName() +
             " is used in the Directory Proxy Server, it must be configured " +
             "with the following plugin types:  " +
             EXPECTED_PROXY_PLUGIN_TYPES + '.');
      }
    }
    else
    {
      isDirectoryServer = false;
      acceptable = false;
      unacceptableReasons.add("The " + getExtensionName() +
           " can only be used in the Directory Server or Directory Proxy " +
           "Server.");
    }


    // Get the configured LDAP attribute type.  It must be defined in the server
    // schema.
    final AttributeType attrType;
    final StringArgument attrNameArg = parser.getStringArgument(ARG_ATTR_NAME);
    if ((attrNameArg == null) || (! attrNameArg.isPresent()))
    {
      // The argument parser should ensure that this never happens.
      acceptable = false;
      unacceptableReasons.add("No value was provided for the required " +
           ARG_ATTR_NAME + " argument.");
      attrType = null;
    }
    else
    {
      attrType = serverContext.getSchema().getAttributeType(
           attrNameArg.getValue(), false);
      if (attrType == null)
      {
        acceptable = false;
        unacceptableReasons.add("Value '" + attrNameArg.getValue() +
             "' for argument " + ARG_ATTR_NAME + " does not represent the " +
             "name or OID for any attribute type defined in the server " +
             "schema.");
      }
    }


    DN jsonAttributeConstraintsDN = null;
    if (attrType != null)
    {
      // The attribute type must have a JSONObject syntax.
      if ((attrType.getSyntax() == null) ||
          (! attrType.getSyntax().getOID().equals(OID_JSON_OBJECT_SYNTAX)))
      {
        acceptable = false;
        unacceptableReasons.add("Attribute type " + attrNameArg.getValue() +
             " is not defined with a JSONObject syntax (OID " +
             OID_JSON_OBJECT_SYNTAX + ").");
      }


      // If the plugin is being run in the Directory Server, then make sure that
      // the server is configured with a JSON attribute constraints definition
      // for the specified attribute type.  Note that it's possible that the
      // definition was created with an alternate name for the attribute type,
      // so we'll see if the entry exists with any of the names (or OID) for
      // that attribute type.
      if (isDirectoryServer)
      {
        for (final String name : getNamesAndOID(attrType))
        {
          final DN dn = new DN(
               new RDN("ds-cfg-attribute-type", name),
               JSON_ATTRIBUTE_CONSTRAINTS_PARENT_DN);

          try
          {
            if (internalConnection.getEntry(dn.toString(), "1.1") != null)
            {
              jsonAttributeConstraintsDN = dn;
              break;
            }
          }
          catch (final Exception e)
          {
            serverContext.debugCaught(e);
            acceptable = false;
            unacceptableReasons.add("An error occurred while attempting to " +
                 "determine whether a JSON attribute constraints definition " +
                 "exists in entry '" + dn + "':  " +
                 StaticUtils.getExceptionMessage(e));
            break;
          }
        }

        if (jsonAttributeConstraintsDN == null)
        {
          acceptable = false;
          unacceptableReasons.add("The server is not configured with a JSON " +
               "attribute constraints definition for attribute " +
               attrNameArg.getValue() + '.');
        }
      }
    }


    // Retrieve and validate the configured JSON field path.
    final String fieldPathStr;
    final StringArgument fieldPathArg =
         parser.getStringArgument(ARG_JSON_FIELD_PATH);
    if ((fieldPathArg == null) || (! fieldPathArg.isPresent()))
    {
      // The argument parser should ensure that this never happens.
      acceptable = false;
      unacceptableReasons.add("No value was provided for the required " +
           ARG_JSON_FIELD_PATH + " argument.");
      fieldPathStr = null;
    }
    else
    {
      fieldPathStr = fieldPathArg.getValue();
      final List<String> fieldPath =
           parseFieldPath(fieldPathStr, unacceptableReasons);
      if (fieldPath == null)
      {
        // The unacceptable reasons will have already been updated by the
        // parseFieldPath method.
        acceptable = false;
      }
    }


    // If the plugin is being run in the Directory Server, then make sure that
    // the server is configured with a JSON field constraints definition for the
    // target field, and that it has a ds-cfg-index-values attribute with a
    // value of true.
    if (acceptable && isDirectoryServer)
    {
      final DN jsonFieldConstraintParentDN = new DN(
           new RDN("cn", "JSON Field Constraints"),
           jsonAttributeConstraintsDN);
      final DN jsonFieldConstraintsDN = new DN(
           new RDN("ds-cfg-json-field", fieldPathStr),
           jsonFieldConstraintParentDN);

      try
      {
        final SearchResultEntry jsonFieldConstraintsEntry =
             internalConnection.getEntry(jsonFieldConstraintsDN.toString(),
                  ATTR_JSON_FIELD_CONSTRAINTS_INDEX_VALUES);
        if (jsonFieldConstraintsEntry == null)
        {
          acceptable = false;
          unacceptableReasons.add("The server is not configured with a JSON " +
               "field constraints definition for field " + fieldPathStr +
               " for attribute " + attrNameArg.getValue() + '.');
        }
        else if (! jsonFieldConstraintsEntry.hasAttributeValue(
             ATTR_JSON_FIELD_CONSTRAINTS_INDEX_VALUES, "true"))
        {
          acceptable = false;
          unacceptableReasons.add("The JSON field constraints definition in " +
               "entry '" + jsonFieldConstraintsDN + "' does not have a " +
               ATTR_JSON_FIELD_CONSTRAINTS_INDEX_VALUES + " value of true.");
        }
      }
      catch (final Exception e)
      {
        serverContext.debugCaught(e);
        acceptable = false;
        unacceptableReasons.add("An error occurred while attempting to " +
             "retrieve the JSON field constraints definition contained in " +
             "entry '" + jsonFieldConstraintsDN + "':  " +
             StaticUtils.getExceptionMessage(e));
      }
    }


    // If a unique value JSON object filter was provided, then make sure that
    // it's a valid JSON object filter.
    final StringArgument jsonFilterArg =
         parser.getStringArgument(ARG_UNIQUE_VALUE_JSON_OBJECT_FILTER);
    if ((jsonFilterArg != null) && jsonFilterArg.isPresent())
    {
      final JSONObjectFilter f = parseJSONObjectFilter(jsonFilterArg.getValue(),
           unacceptableReasons, serverContext);
      if (f == null)
      {
        // The unacceptable reasons will have already been updated by the
        // parseJSONObjectFilter method.
        acceptable = false;
      }
    }


    // At least one of the require-uniqueness-within-an-entry and
    // require-uniqueness-across-entries properties must have a value of true.
    final BooleanValueArgument uniqueWithEntryArg =
         parser.getBooleanValueArgument(ARG_REQUIRE_UNIQUENESS_WITHIN_AN_ENTRY);
    if ((uniqueWithEntryArg != null) && uniqueWithEntryArg.isPresent() &&
        (uniqueWithEntryArg.getValue() == Boolean.FALSE))
    {
      final BooleanValueArgument uniqueAcrossEntriesArg =
           parser.getBooleanValueArgument(
                ARG_REQUIRE_UNIQUENESS_ACROSS_ENTRIES);
      if ((uniqueAcrossEntriesArg != null) &&
          uniqueAcrossEntriesArg.isPresent() &&
          (uniqueAcrossEntriesArg.getValue() == Boolean.FALSE))
      {
        acceptable = false;
        unacceptableReasons.add("The configuration cannot have both " +
             ARG_REQUIRE_UNIQUENESS_WITHIN_AN_ENTRY + " and " +
             ARG_REQUIRE_UNIQUENESS_ACROSS_ENTRIES +
             " arguments set to false.");
      }
    }


    return acceptable;
  }



  /**
   * Attempts to apply the configuration from the provided argument parser to
   * this extension.
   *
   * @param  config                The general configuration for this extension.
   * @param  parser                The argument parser that has been used to
   *                               parse the new configuration for this
   *                               extension.
   * @param  adminActionsRequired  A list to which messages may be added to
   *                               provide additional information about any
   *                               additional administrative actions that may
   *                               be required to apply some of the
   *                               configuration changes.
   * @param  messages              A list to which messages may be added to
   *                               provide additional information about the
   *                               processing performed by this method.
   *
   * @return  A result code providing information about the result of applying
   *          the configuration change.  A result of {@code SUCCESS} should be
   *          used to indicate that all processing completed successfully.  Any
   *          other result will indicate that a problem occurred during
   *          processing.
   */
  @Override()
  public ResultCode applyConfiguration(final PluginConfig config,
                                       final ArgumentParser parser,
                                       final List<String> adminActionsRequired,
                                       final List<String> messages)
  {
    // If the server context is null, then get an instance from the provided
    // configuration.
    if (serverContext == null)
    {
      serverContext = config.getServerContext();
    }


    // Get an internal connection to use for processing internal operations.
    if (internalConnection == null)
    {
      internalConnection = serverContext.getInternalRootConnection();
    }


    // Get the configured LDAP attribute type.
    final StringArgument attrNameArg = parser.getStringArgument(ARG_ATTR_NAME);
    final AttributeType attrType = serverContext.getSchema().getAttributeType(
         attrNameArg.getValue(), false);

    boolean valid = true;
    if (attrType == null)
    {
      valid = false;
      messages.add("Unable to retrieve attribute type " +
           attrNameArg.getValue() + " from the server schema.");
    }


    // Get the configured JSON field path.
    final StringArgument fieldPathArg =
         parser.getStringArgument(ARG_JSON_FIELD_PATH);
    final String fieldPathString = fieldPathArg.getValue();
    final List<String> fieldPath = parseFieldPath(fieldPathString, messages);
    if (fieldPath == null)
    {
      valid = false;
    }


    // Determine whether to require uniqueness within an entry.
    boolean uniqueWithinEntry = true;
    final BooleanValueArgument uniqueWithinEntryArg =
         parser.getBooleanValueArgument(ARG_REQUIRE_UNIQUENESS_WITHIN_AN_ENTRY);
    if (uniqueWithinEntryArg != null)
    {
      uniqueWithinEntry = uniqueWithinEntryArg.getValue();
    }


    // Determine whether to require uniqueness across entries.
    boolean uniqueAcrossEntries = true;
    final BooleanValueArgument uniqueAcrossEntriesArg =
         parser.getBooleanValueArgument(ARG_REQUIRE_UNIQUENESS_ACROSS_ENTRIES);
    if (uniqueAcrossEntriesArg != null)
    {
      uniqueAcrossEntries = uniqueAcrossEntriesArg.getValue();
    }


    // Get the set of base DNs.  If no values are provided in the configuration,
    // then get the set of naming contexts from the root DSE.
    List<DN> baseDNList = null;
    final DNArgument baseDNArg = parser.getDNArgument(ARG_BASE_DN);
    if ((baseDNArg != null) && baseDNArg.isPresent())
    {
      baseDNList = baseDNArg.getValues();
    }

    if ((baseDNList == null) || baseDNList.isEmpty())
    {
      try
      {
        final String[] namingContextDNs =
             internalConnection.getRootDSE().getNamingContextDNs();
        final ArrayList<DN> dnList = new ArrayList<DN>(namingContextDNs.length);
        for (final String dn : namingContextDNs)
        {
          dnList.add(new DN(dn));
        }
        baseDNList = Collections.unmodifiableList(dnList);
      }
      catch (final Exception e)
      {
        serverContext.debugCaught(e);
      }

      if ((baseDNList == null) || baseDNList.isEmpty())
      {
        valid = false;
        messages.add("No base DNs are configured, and the public naming " +
             "context DNs could not be obtained from the server root DSE.");
      }
    }


    // Get the unique entry filter.
    Filter entryFilter = null;
    final FilterArgument filterArg =
         parser.getFilterArgument(ARG_UNIQUE_ENTRY_LDAP_FILTER);
    if ((filterArg != null) && filterArg.isPresent())
    {
      entryFilter = filterArg.getValue();
    }


    // Get the unique object filter.
    JSONObjectFilter objectFilter = null;
    final StringArgument objectFilterArg =
         parser.getStringArgument(ARG_UNIQUE_VALUE_JSON_OBJECT_FILTER);
    if ((objectFilterArg != null) && objectFilterArg.isPresent())
    {
      objectFilter = parseJSONObjectFilter(objectFilterArg.getValue(), messages,
           serverContext);
      if (objectFilter == null)
      {
        valid = false;
      }
    }


    // If the configuration is valid, then apply it.
    if (valid)
    {
      ldapAttributeType              = attrType;
      jsonFieldPathString            = fieldPathString;
      jsonFieldPath                  = fieldPath;
      requireUniquenessWithinAnEntry = uniqueWithinEntry;
      requireUniquenessAcrossEntries = uniqueAcrossEntries;
      baseDNs                        = baseDNList;
      uniqueEntryLDAPFilter          = entryFilter;
      uniqueValueJSONObjectFilter    = objectFilter;

      this.config = config;

      return ResultCode.SUCCESS;
    }
    else
    {
      return ResultCode.OTHER;
    }
  }



  /**
   * Retrieves a list containing all of the names and the OID for the provided
   * attribute type.
   *
   * @param  attrType  The attribute type for which to obtain the names and OID.
   *
   * @return  A list containing all of the names and the OID for the provided
   *          attribute type.
   */
  private static List<String> getNamesAndOID(final AttributeType attrType)
  {
    final ArrayList<String> namesAndOID = new ArrayList<String>(5);
    namesAndOID.addAll(attrType.getNames());
    namesAndOID.add(attrType.getOID());
    return namesAndOID;
  }



  /**
   * Parses the provided string to extract the path to the target field as a
   * list.  Levels of hierarchy will be separated by periods.  Any periods
   * contained in field names must be escaped with backslashes.
   *
   * @param  fieldPathStr         The string representation of the field path.
   * @param  unacceptableReasons  A list that should be updated to include any
   *                              reason that the provided string is not a valid
   *                              path.
   *
   * @return  The list containing the path to the field name, or {@code null} if
   *          the provided field path string does not represent a valid path.
   */
  private static List<String> parseFieldPath(final String fieldPathStr,
                                   final List<String> unacceptableReasons)
  {
    boolean escaped = false;
    final ArrayList<String> fieldList = new ArrayList<String>(5);
    final StringBuilder buffer = new StringBuilder(fieldPathStr.length());
    for (final char c :  fieldPathStr.toCharArray())
    {
      if (escaped)
      {
        buffer.append(c);
        escaped = false;
      }
      else if (c == '\\')
      {
        escaped = true;
      }
      else if (c == '.')
      {
        if (buffer.length() > 0)
        {
          fieldList.add(buffer.toString());
          buffer.setLength(0);
        }
        else
        {
          unacceptableReasons.add("Value '" + fieldPathStr + "' is not a " +
                    "valid JSON field path because it includes an empty " +
               "field name component.");
          return null;
        }
      }
      else
      {
        buffer.append(c);
      }
    }

    if (buffer.length() == 0)
    {
      unacceptableReasons.add("Value '" + fieldPathStr + "' is not a valid " +
           "JSON field path because it includes an empty field name " +
           "component.");
      return null;
    }
    else
    {
      fieldList.add(buffer.toString());
    }

    return Collections.unmodifiableList(fieldList);
  }



  /**
   * Parses the provided string as a JSON object filter.
   *
   * @param  filterStr            The string to be parsed as a JSON object
   *                              filter.
   * @param  unacceptableReasons  A list that should be updated to include any
   *                              reason that the provided string is not a valid
   *                              JSON object filter.
   * @param  serverContext        The server context to use for debugging
   *                              purposes.
   *
   * @return  The parsed JSON object filter, or {@code null} if the provided
   *          string does not represent a valid JSON object filter.
   */
  private static JSONObjectFilter parseJSONObjectFilter(final String filterStr,
                      final List<String> unacceptableReasons,
                      final DirectoryServerContext serverContext)
  {
    final JSONObject filterObject;
    try
    {
      filterObject = new JSONObject(filterStr);
    }
    catch (final Exception e)
    {
      serverContext.debugCaught(e);
      unacceptableReasons.add(ARG_UNIQUE_VALUE_JSON_OBJECT_FILTER +
           " value '" + filterStr + "' is not a valid JSON object:  " +
           StaticUtils.getExceptionMessage(e));
      return null;
    }

    try
    {
      return JSONObjectFilter.decode(filterObject);
    }
    catch (final Exception e)
    {
      serverContext.debugCaught(e);
      unacceptableReasons.add(ARG_UNIQUE_VALUE_JSON_OBJECT_FILTER +
           " value '" + filterStr + "' does not represent a valid JSON " +
           "object filter:  " + StaticUtils.getExceptionMessage(e));
      return null;
    }
  }



  /**
   * 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 List<String> exampleArgs = Arrays.asList(
         ARG_ATTR_NAME + "=my-json-attribute",
         ARG_JSON_FIELD_PATH + "=my-json-field",
         ARG_REQUIRE_UNIQUENESS_WITHIN_AN_ENTRY + "=true",
         ARG_REQUIRE_UNIQUENESS_ACROSS_ENTRIES + "=true",
         ARG_BASE_DN + "=dc=example,dc=com");

    final String exampleDescription = "Configure the " + getExtensionName() +
         " to ensure that all values of the 'my-json-field' field in the " +
         "'my-json-attribute' attribute are unique across all entries below " +
         "'dc=example,dc=com', including across multiple values within the " +
         "same entry.";

    return Collections.singletonMap(exampleArgs, exampleDescription);
  }
}