com.unboundid.ldap.sdk.unboundidds.jsonfilter.JSONObjectFilter

All Implemented Interfaces:: Serializable

Direct Known Subclasses:: ANDJSONObjectFilter, ContainsFieldJSONObjectFilter, EqualsAnyJSONObjectFilter, EqualsJSONObjectFilter, GreaterThanJSONObjectFilter, LessThanJSONObjectFilter, NegateJSONObjectFilter, ObjectMatchesJSONObjectFilter, ORJSONObjectFilter, RegularExpressionJSONObjectFilter, SubstringJSONObjectFilter

@NotExtensible @ThreadSafety(level=INTERFACE_NOT_THREADSAFE) public abstract class JSONObjectFilter extends Object implements Serializable

This class defines the base class for all JSON object filter types, which are used to perform matching against JSON objects stored in a Ping Identity, UnboundID, or Nokia/Alcatel-Lucent 8661 Directory Server via the jsonObjectFilterExtensibleMatch matching rule. The toLDAPFilter(String) method can be used to easily create an LDAP filter from a JSON object filter. This filter will have an attribute type that is the name of an attribute with the JSON object syntax, a matching rule ID of "jsonObjectFilterExtensibleMatch", and an assertion value that is the string representation of the JSON object that comprises the filter.

NOTE: This class, and other classes within the com.unboundid.ldap.sdk.unboundidds package structure, are only supported for use against Ping Identity, UnboundID, and Nokia/Alcatel-Lucent 8661 server products. These classes provide support for proprietary functionality or for external specifications that are not considered stable or mature enough to be guaranteed to work in an interoperable way with other types of LDAP servers.

For example, given the JSON object filter:

   { "filterType" : "equals", "field" : "firstName", "value" : "John" }

the resulting LDAP filter targeting attribute "jsonAttr" would have a string representation as follows (without the line break that has been added for formatting purposes):

   (jsonAttr:jsonObjectFilterExtensibleMatch:={ "filterType" : "equals",
   "field" : "firstName", "value" : "John" })

JSON object filters are themselves expressed in the form of JSON objects. All filters must have a "filterType" field that indicates what type of filter the object represents, and the filter type determines what other fields may be required or optional for that type of filter.

Types of JSON Object Filters

This implementation supports a number of different types of filters to use when matching JSON objects. Supported JSON object filter types are as follows:

Contains Field

This filter can be used to determine whether a JSON object has a specified field, optionally with a given type of value. For example, the following can be used to determine whether a JSON object contains a top-level field named "department" that has any kind of value:

   { "filterType" : "containsField",
     "field" : "department" }

Equals

This filter can be used to determine whether a JSON object has a specific value for a given field. For example, the following can be used to determine whether a JSON object has a top-level field named "firstName" with a value of "John":

   { "filterType" : "equals",
     "field" : "firstName",
     "value" : "John" }

Equals Any

This filter can be used to determine whether a JSON object has any of a number of specified values for a given field. For example, the following can be used to determine whether a JSON object has a top-level field named "userType" with a value that is either "employee", "partner", or "contractor":

   { "filterType" : "equalsAny",
     "field" : "userType",
     "values" : [  "employee", "partner", "contractor" ] }

Greater Than

This filter can be used to determine whether a JSON object has a specified field with a value that is greater than (or optionally greater than or equal to) a given numeric or string value. For example, the following filter would match any JSON object with a top-level field named "salary" with a numeric value that is greater than or equal to 50000:

   { "filterType" : "greaterThan",
     "field" : "salary",
     "value" : 50000,
     "allowEquals" : true }

Less Than

This filter can be used to determine whether a JSON object has a specified field with a value that is less than (or optionally less than or equal to) a given numeric or string value. For example, the following filter will match any JSON object with a "loginFailureCount" field with a numeric value that is less than or equal to 3.

   { "filterType" : "lessThan",
     "field" : "loginFailureCount",
     "value" : 3,
     "allowEquals" : true }

Substring

This filter can be used to determine whether a JSON object has a specified field with a string value that starts with, ends with, and/or contains a particular substring. For example, the following filter will match any JSON object with an "email" field containing a value that ends with "@example.com":

   { "filterType" : "substring",
     "field" : "email",
     "endsWith" : "@example.com" }

Regular Expression

This filter can be used to determine whether a JSON object has a specified field with a string value that matches a given regular expression. For example, the following filter can be used to determine whether a JSON object has a "userID" value that starts with an ASCII letter and contains only ASCII letters and numeric digits:

   { "filterType" : "regularExpression",
     "field" : "userID",
     "regularExpression" : "^[a-zA-Z][a-zA-Z0-9]*$" }

Object Matches

This filter can be used to determine whether a JSON object has a specified field with a value that is itself a JSON object that matches a given JSON object filter. For example, the following filter can be used to determine whether a JSON object has a "contact" field with a value that is a JSON object with a "type" value of "home" and an "email" field with any kind of value:

   { "filterType" : "objectMatches",
     "field" : "contact",
     "filter" : {
       "filterType" : "and",
       "andFilters" : [
         { "filterType" : "equals",
           "field" : "type",
           "value" : "home" },
         { "filterType" : "containsField",
           "field" : "email" } ] } }

AND

This filter can be used to perform a logical AND across a number of filters, so that the AND filter will only match a JSON object if each of the encapsulated filters matches that object. For example, the following filter could be used to match any JSON object with both a "firstName" field with a value of "John" and a "lastName" field with a value of "Doe":

   { "filterType" : "and",
     "andFilters" : [
       { "filterType" : "equals",
          "field" : "firstName",
          "value" : "John" },
       { "filterType" : "equals",
          "field" : "lastName",
          "value" : "Doe" } ] }

OR

This filter can be used to perform a logical OR (or optionally, a logical exclusive OR) across a number of filters so that the filter will only match a JSON object if at least one of the encapsulated filters matches that object. For example, the following filter could be used to match a JSON object that has either or both of the "homePhone" or "workPhone" field with any kind of value:

   { "filterType" : "or",
     "orFilters" : [
       { "filterType" : "containsField",
          "field" : "homePhone" },
       { "filterType" : "containsField",
          "field" : "workPhone" } ] }

Negate

This filter can be used to negate the result of an encapsulated filter, so that it will only match a JSON object that the encapsulated filter does not match. For example, the following filter will only match JSON objects that do not have a "userType" field with a value of "employee":

   { "filterType" : "negate",
     "negateFilter" : {
       "filterType" : "equals",
       "field" : "userType",
       "value" : "employee" } }

Targeting Fields in JSON Objects

Many JSON object filter types need to specify a particular field in the JSON object that is to be used for the matching. Unless otherwise specified in the Javadoc documentation for a particular filter type, the target field should be specified either as a single string (to target a top-level field in the object) or a non-empty array of strings (to provide the complete path to the target field). In the case the target field is specified in an array, the first (leftmost in the string representation) element of the array will specify a top-level field in the JSON object. If the array contains a second element, then that indicates that one of the following should be true:

The top-level field specified by the first element should have a value that is itself a JSON object, and the second element specifies the name of a field in that JSON object.
The top-level field specified by the first element should have a value that is an array, and at least one element of the array is a JSON object with a field whose name matches the second element of the field path array.

Each additional element of the field path array specifies an additional level of hierarchy in the JSON object. For example, consider the following JSON object:

   { "field1" : "valueA",
     "field2" : {
       "field3" : "valueB",
       "field4" : {
         "field5" : "valueC" } } }

In the above example, the field whose value is "valueA" can be targeted using either "field1" or [ "field1" ]. The field whose value is "valueB" can be targeted as [ "field2", "field3" ]. The field whose value is "valueC" can be targeted as [ "field2", "field4", "field5" ].

Note that the mechanism outlined here cannot always be used to uniquely identify each field in a JSON object. In particular, if an array contains multiple JSON objects, then it is possible that some of those JSON objects could have field names in common, and therefore the same field path reference could apply to multiple fields. For example, in the JSON object:

   {
     "contact" : [
       { "type" : "Home",
         "email" : "jdoe@example.net",
         "phone" : "123-456-7890" },
       { "type" : "Work",
         "email" : "john.doe@example.com",
         "phone" : "789-456-0123" } ] }

The field specifier [ "contact", "type" ] can reference either the field whose value is "Home" or the field whose value is "Work". The field specifier [ "contact", "email" ] can reference the field whose value is "jdoe@example.net" or the field whose value is "john.doe@example.com". And the field specifier [ "contact", "phone" ] can reference the field with value "123-456-7890" or the field with value "789-456-0123". This ambiguity is intentional for values in arrays because it makes it possible to target array elements without needing to know the order of elements in the array.

Thread Safety of JSON Object Filters

JSON object filters are not guaranteed to be threadsafe. Because some filter types support a number of configurable options, it is more convenient and future-proof to provide minimal constructors to specify values for the required fields and setter methods for the optional fields. These filters will be mutable, and any filter that may be altered should not be accessed concurrently by multiple threads. However, if a JSON object filter is not expected to be altered, then it may safely be shared across multiple threads. Further, LDAP filters created using the toLDAPFilter(java.lang.String) method and JSON objects created using the toJSONObject() method will be threadsafe under all circumstances.

See Also:

Field Summary

Fields

Modifier and Type

Field

Description

static final String

FIELD_FILTER_TYPE

The name of the JSON field that is used to specify the filter type for the JSON object filter.

static final String

JSON_OBJECT_FILTER_MATCHING_RULE_NAME

The name of the matching rule that may be used to determine whether an attribute value matches a JSON object filter.

static final String

JSON_OBJECT_FILTER_MATCHING_RULE_OID

The numeric OID of the matching rule that may be used to determine whether an attribute value matches a JSON object filter.
Constructor Summary

Constructors

Constructor

Description

JSONObjectFilter()
Method Summary

Modifier and Type

Method

Description

static JSONObjectFilter

decode(JSONObject o)

Decodes the provided JSON object as a JSON object filter.

protected abstract JSONObjectFilter

decodeFilter(JSONObject o)

Decodes the provided JSON object as a filter of this type.

final boolean

equals(Object o)

Indicates whether the provided object is considered equal to this JSON object filter.

protected boolean

getBoolean(JSONObject o, String fieldName, Boolean defaultValue)

Retrieves the value of the specified field from the provided JSON object as a boolean.

protected List<JSONObjectFilter>

getFilters(JSONObject o, String fieldName)

Retrieves the value of the specified field from the provided JSON object as a list of JSON object filters.

abstract String

getFilterType()

Retrieves the value that must appear in the filterType field for this filter.

protected abstract Set<String>

getOptionalFieldNames()

Retrieves the names of all fields that may optionally be present but are not required in the JSON object representing a filter of this type.

protected abstract Set<String>

getRequiredFieldNames()

Retrieves the names of all fields (excluding the filterType field) that must be present in the JSON object representing a filter of this type.

protected String

getString(JSONObject o, String fieldName, String defaultValue, boolean required)

Retrieves the value of the specified field from the provided JSON object as a strings.

protected List<String>

getStrings(JSONObject o, String fieldName, boolean allowEmpty, List<String> defaultValues)

Retrieves the value of the specified field from the provided JSON object as a list of strings.

protected static List<JSONValue>

getValues(JSONObject o, List<String> fieldName)

Retrieves the set of values that match the provided field name specifier.

final int

hashCode()

Retrieves a hash code for this JSON object filter.

abstract boolean

matchesJSONObject(JSONObject o)

Indicates whether this JSON object filter matches the provided JSON object.

protected static void

registerFilterType(JSONObjectFilter... impl)

Registers the provided filter type(s) so that this class can decode filters of that type.

abstract JSONObject

toJSONObject()

Retrieves a JSON object that represents this filter.

final Filter

toLDAPFilter(String attributeDescription)

Constructs an LDAP extensible matching filter that may be used to identify entries with one or more values for a specified attribute that represent JSON objects matching this JSON object filter.

abstract JSONObject

toNormalizedJSONObject()

Retrieves a JSON object that represents a normalized version of this filter.

final String

toNormalizedString()

Retrieves a normalized string representation of the JSON object that represents this filter.

final void

toNormalizedString(StringBuilder buffer)

Appends a normalized string representation of the JSON object that represents this filter to the provided buffer.

final String

toString()

Retrieves a string representation of the JSON object that represents this filter.

final void

toString(StringBuilder buffer)

Appends a string representation of the JSON object that represents this filter to the provided buffer.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Details
- JSON_OBJECT_FILTER_MATCHING_RULE_NAME
  
  @NotNull public static final String JSON_OBJECT_FILTER_MATCHING_RULE_NAME
  
  The name of the matching rule that may be used to determine whether an attribute value matches a JSON object filter.
  See Also:
  
  Constant Field Values
- JSON_OBJECT_FILTER_MATCHING_RULE_OID
  
  @NotNull public static final String JSON_OBJECT_FILTER_MATCHING_RULE_OID
  
  The numeric OID of the matching rule that may be used to determine whether an attribute value matches a JSON object filter.
  See Also:
  
  Constant Field Values
- FIELD_FILTER_TYPE
  
  @NotNull public static final String FIELD_FILTER_TYPE
  
  The name of the JSON field that is used to specify the filter type for the JSON object filter.
  See Also:
  
  Constant Field Values
Constructor Details
- JSONObjectFilter
  
  public JSONObjectFilter()
Method Details
- getFilterType
  
  @NotNull public abstract String getFilterType()
  
  Retrieves the value that must appear in the filterType field for this filter.
  
  Returns:
  
  The value that must appear in the filterType field for this filter.
- getRequiredFieldNames
  
  @NotNull protected abstract Set<String> getRequiredFieldNames()
  
  Retrieves the names of all fields (excluding the filterType field) that must be present in the JSON object representing a filter of this type.
  
  Returns:
  
  The names of all fields (excluding the filterType field) that must be present in the JSON object representing a filter of this type.
- getOptionalFieldNames
  
  @NotNull protected abstract Set<String> getOptionalFieldNames()
  
  Retrieves the names of all fields that may optionally be present but are not required in the JSON object representing a filter of this type.
  
  Returns:
  
  The names of all fields that may optionally be present but are not required in the JSON object representing a filter of this type.
- matchesJSONObject
  
  public abstract boolean matchesJSONObject(@NotNull JSONObject o)
  
  Indicates whether this JSON object filter matches the provided JSON object.
  
  Parameters:
  
  o - The JSON object for which to make the determination.
  
  Returns:
  
  true if this JSON object filter matches the provided JSON object, or false if not.
- toJSONObject
  
  @NotNull public abstract JSONObject toJSONObject()
  
  Retrieves a JSON object that represents this filter.
  
  Returns:
  
  A JSON object that represents this filter.
- toNormalizedJSONObject
  
  @NotNull public abstract JSONObject toNormalizedJSONObject()
  
  Retrieves a JSON object that represents a normalized version of this filter.
  
  Returns:
  
  A JSON object that represents a normalized version of this filter.
- getStrings
  
  @NotNull protected List<String> getStrings(@NotNull JSONObject o, @NotNull String fieldName, boolean allowEmpty, @Nullable List<String> defaultValues) throws JSONException
  
  Retrieves the value of the specified field from the provided JSON object as a list of strings. The specified field must be a top-level field in the JSON object, and it must have a value that is a single string or an array of strings.
  
  Parameters:
  
  o - The JSON object to examine. It must not be null.
  
  fieldName - The name of a top-level field in the JSON object that is expected to have a value that is a string or an array of strings. It must not be null. It will be treated in a case-sensitive manner.
  
  allowEmpty - Indicates whether the value is allowed to be an empty array.
  
  defaultValues - The list of default values to return if the field is not present. If this is null, then a JSONException will be thrown if the specified field is not present.
  
  Returns:
  
  The list of strings retrieved from the JSON object, or the default list if the field is not present in the object.
  
  Throws:
  
  JSONException - If the object doesn't have the specified field and no set of default values was provided, or if the value of the specified field was not a string or an array of strings.
- getString
  
  @Nullable protected String getString(@NotNull JSONObject o, @NotNull String fieldName, @Nullable String defaultValue, boolean required) throws JSONException
  
  Retrieves the value of the specified field from the provided JSON object as a strings. The specified field must be a top-level field in the JSON object, and it must have a value that is a single string.
  
  Parameters:
  
  o - The JSON object to examine. It must not be null.
  
  fieldName - The name of a top-level field in the JSON object that is expected to have a value that is a string. It must not be null. It will be treated in a case-sensitive manner.
  
  defaultValue - The default values to return if the field is not present. If this is null and required is true, then a JSONException will be thrown if the specified field is not present.
  
  required - Indicates whether the field is required to be present in the object.
  
  Returns:
  
  The string retrieved from the JSON object, or the default value if the field is not present in the object.
  
  Throws:
  
  JSONException - If the object doesn't have the specified field, the field is required, and no default value was provided, or if the value of the specified field was not a string.
- getBoolean
  
  protected boolean getBoolean(@NotNull JSONObject o, @NotNull String fieldName, @Nullable Boolean defaultValue) throws JSONException
  
  Retrieves the value of the specified field from the provided JSON object as a boolean. The specified field must be a top-level field in the JSON object, and it must have a value that is either true or false.
  
  Parameters:
  
  o - The JSON object to examine. It must not be null.
  
  fieldName - The name of a top-level field in the JSON object that that is expected to have a value that is either true or false.
  
  defaultValue - The default value to return if the specified field is not present in the JSON object. If this is null, then a JSONException will be thrown if the specified field is not present.
  
  Returns:
  
  The value retrieved from the JSON object, or the default value if the field is not present in the object.
  
  Throws:
  
  JSONException - If the object doesn't have the specified field and no default value was provided, or if the value of the specified field was neither true nor false.
- getFilters
  
  @NotNull protected List<JSONObjectFilter> getFilters(@NotNull JSONObject o, @NotNull String fieldName) throws JSONException
  
  Retrieves the value of the specified field from the provided JSON object as a list of JSON object filters. The specified field must be a top-level field in the JSON object and it must have a value that is an array of JSON objects that represent valid JSON object filters.
  
  Parameters:
  
  o - The JSON object to examine. It must not be null.
  
  fieldName - The name of a top-level field in the JSON object that is expected to have a value that is an array of JSON objects that represent valid JSON object filters. It must not be null.
  
  Returns:
  
  The list of JSON object filters retrieved from the JSON object.
  
  Throws:
  
  JSONException - If the object doesn't have the specified field, or if the value of that field is not an array of JSON objects that represent valid JSON object filters.
- getValues
  
  @NotNull protected static List<JSONValue> getValues(@NotNull JSONObject o, @NotNull List<String> fieldName)
  
  Retrieves the set of values that match the provided field name specifier.
  
  Parameters:
  
  o - The JSON object to examine.
  
  fieldName - The field name specifier for the values to retrieve.
  
  Returns:
  
  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.
- decode
  
  @NotNull public static JSONObjectFilter decode(@NotNull JSONObject o) throws JSONException
  
  Decodes the provided JSON object as a JSON object filter.
  
  Parameters:
  
  o - The JSON object to be decoded as a JSON object filter.
  
  Returns:
  
  The JSON object filter decoded from the provided JSON object.
  
  Throws:
  
  JSONException - If the provided JSON object cannot be decoded as a JSON object filter.
- decodeFilter
  
  @NotNull protected abstract JSONObjectFilter decodeFilter(@NotNull JSONObject o) throws JSONException
  
  Decodes the provided JSON object as a filter of this type.
  
  Parameters:
  
  o - The JSON object to be decoded. The caller will have already validated that all required fields are present, and that it does not have any fields that are neither required nor optional.
  
  Returns:
  
  The decoded JSON object filter.
  
  Throws:
  
  JSONException - If the provided JSON object cannot be decoded as a valid filter of this type.
- registerFilterType
  
  protected static void registerFilterType(@NotNull JSONObjectFilter... impl)
  
  Registers the provided filter type(s) so that this class can decode filters of that type.
  
  Parameters:
  
  impl - The filter type implementation(s) to register.
- toLDAPFilter
  
  @NotNull public final Filter toLDAPFilter(@NotNull String attributeDescription)
  
  Constructs an LDAP extensible matching filter that may be used to identify entries with one or more values for a specified attribute that represent JSON objects matching this JSON object filter.
  
  Parameters:
  
  attributeDescription - The attribute description (i.e., the attribute name or numeric OID plus zero or more attribute options) for the LDAP attribute to target with this filter. It must not be null.
  
  Returns:
  
  The constructed LDAP extensible matching filter.
- hashCode
  
  public final int hashCode()
  
  Retrieves a hash code for this JSON object filter.
  
  Overrides:
  
  hashCode in class Object
  
  Returns:
  
  A hash code for this JSON object filter.
- equals
  
  public final boolean equals(@Nullable Object o)
  
  Indicates whether the provided object is considered equal to this JSON object filter.
  
  Overrides:
  
  equals in class Object
  
  Parameters:
  
  o - The object for which to make the determination.
  
  Returns:
  
  true if the provided object is considered equal to this JSON object filter, or false if not.
- toString
  
  @NotNull public final String toString()
  
  Retrieves a string representation of the JSON object that represents this filter.
  
  Overrides:
  
  toString in class Object
  
  Returns:
  
  A string representation of the JSON object that represents this filter.
- toString
  
  public final void toString(@NotNull StringBuilder buffer)
  
  Appends a string representation of the JSON object that represents this filter to the provided buffer.
  
  Parameters:
  
  buffer - The buffer to which the information should be appended.
- toNormalizedString
  
  @NotNull public final String toNormalizedString()
  
  Retrieves a normalized string representation of the JSON object that represents this filter.
  
  Returns:
  
  A normalized string representation of the JSON object that represents this filter.
- toNormalizedString
  
  public final void toNormalizedString(@NotNull StringBuilder buffer)
  
  Appends a normalized string representation of the JSON object that represents this filter to the provided buffer.
  
  Parameters:
  
  buffer - The buffer to which the information should be appended.

Class JSONObjectFilter

Types of JSON Object Filters

Contains Field

Equals

Equals Any

Greater Than

Less Than

Substring

Regular Expression

Object Matches

AND

OR

Negate

Targeting Fields in JSON Objects

Thread Safety of JSON Object Filters

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Details

JSON_OBJECT_FILTER_MATCHING_RULE_NAME

JSON_OBJECT_FILTER_MATCHING_RULE_OID

FIELD_FILTER_TYPE

Constructor Details

JSONObjectFilter

Method Details

getFilterType

getRequiredFieldNames

getOptionalFieldNames

matchesJSONObject

toJSONObject

toNormalizedJSONObject

getStrings

getString

getBoolean

getFilters

getValues

decode

decodeFilter

registerFilterType

toLDAPFilter

hashCode

equals

toString

toString

toNormalizedString

toNormalizedString