Class 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 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.
    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      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.
      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
    • 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.
      • 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<JSONObjectFiltergetFilters​(@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<JSONValuegetValues​(@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.