com.unboundid.ldap.sdk.unboundidds.jsonfilter

Class JSONObjectFilter

java.lang.Object

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

All Implemented Interfaces:

java.io.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 java.lang.Object
implements java.io.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:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	FIELD_FILTER_TYPE The name of the JSON field that is used to specify the filter type for the JSON object filter.
static java.lang.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 java.lang.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 and Description
JSONObjectFilter()

Method Summary

Modifier and Type	Method and 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.
boolean	equals(java.lang.Object o) Indicates whether the provided object is considered equal to this JSON object filter.
protected boolean	getBoolean(JSONObject o, java.lang.String fieldName, java.lang.Boolean defaultValue) Retrieves the value of the specified field from the provided JSON object as a boolean.
protected java.util.List<JSONObjectFilter>	getFilters(JSONObject o, java.lang.String fieldName) Retrieves the value of the specified field from the provided JSON object as a list of JSON object filters.
abstract java.lang.String	getFilterType() Retrieves the value that must appear in the filterType field for this filter.
protected abstract java.util.Set<java.lang.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 java.util.Set<java.lang.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 java.lang.String	getString(JSONObject o, java.lang.String fieldName, java.lang.String defaultValue, boolean required) Retrieves the value of the specified field from the provided JSON object as a strings.
protected java.util.List<java.lang.String>	getStrings(JSONObject o, java.lang.String fieldName, boolean allowEmpty, java.util.List<java.lang.String> defaultValues) Retrieves the value of the specified field from the provided JSON object as a list of strings.
protected static java.util.List<JSONValue>	getValues(JSONObject o, java.util.List<java.lang.String> fieldName) Retrieves the set of values that match the provided field name specifier.
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.
Filter	toLDAPFilter(java.lang.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.
java.lang.String	toNormalizedString() Retrieves a normalized string representation of the JSON object that represents this filter.
void	toNormalizedString(java.lang.StringBuilder buffer) Appends a normalized string representation of the JSON object that represents this filter to the provided buffer.
java.lang.String	toString() Retrieves a string representation of the JSON object that represents this filter.
void	toString(java.lang.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 Detail

JSON_OBJECT_FILTER_MATCHING_RULE_NAME

@NotNull
public static final java.lang.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 java.lang.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 java.lang.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 Detail

JSONObjectFilter

public JSONObjectFilter()

Method Detail

getFilterType

@NotNull
public abstract java.lang.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 java.util.Set<java.lang.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 java.util.Set<java.lang.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 java.util.List<java.lang.String> getStrings(@NotNull
                                                               JSONObject o,
                                                               @NotNull
                                                               java.lang.String fieldName,
                                                               boolean allowEmpty,
                                                               @Nullable
                                                               java.util.List<java.lang.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 java.lang.String getString(@NotNull
                                               JSONObject o,
                                               @NotNull
                                               java.lang.String fieldName,
                                               @Nullable
                                               java.lang.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
                             java.lang.String fieldName,
                             @Nullable
                             java.lang.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 java.util.List<JSONObjectFilter> getFilters(@NotNull
                                                               JSONObject o,
                                                               @NotNull
                                                               java.lang.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 java.util.List<JSONValue> getValues(@NotNull
                                                              JSONObject o,
                                                              @NotNull
                                                              java.util.List<java.lang.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
                                          java.lang.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 java.lang.Object

Returns:

A hash code for this JSON object filter.

equals

public final boolean equals(@Nullable
                            java.lang.Object o)

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

Overrides:

equals in class java.lang.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 java.lang.String toString()

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

Overrides:

toString in class java.lang.Object

Returns:

A string representation of the JSON object that represents this filter.

toString

public final void toString(@NotNull
                           java.lang.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 java.lang.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
                                     java.lang.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.