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

java.lang.Object
  extended by 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

NOTE: This class is part of the Commercial Edition of the UnboundID LDAP SDK for Java. It is not available for use in applications that include only the Standard Edition of the LDAP SDK, and is not supported for use in conjunction with non-UnboundID products.
This class defines the base class for all JSON object filter types, which are used to perform matching against JSON objects stored in an UnboundID 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. 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: 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
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
JSONObjectFilter()
           
 
Method Summary
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.
 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

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

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

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

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

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

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(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

public abstract JSONObject toJSONObject()
Retrieves a JSON object that represents this filter.

Returns:
A JSON object that represents this filter.

getStrings

protected java.util.List<java.lang.String> getStrings(JSONObject o,
                                                      java.lang.String fieldName,
                                                      boolean allowEmpty,
                                                      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

protected java.lang.String getString(JSONObject o,
                                     java.lang.String fieldName,
                                     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(JSONObject o,
                             java.lang.String fieldName,
                             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

protected java.util.List<JSONObjectFilter> getFilters(JSONObject o,
                                                      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

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.

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

public static JSONObjectFilter decode(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

protected abstract JSONObjectFilter decodeFilter(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(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

public final 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.

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(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

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(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.