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. ThetoLDAPFilter(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.
{ "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 thetoLDAPFilter(java.lang.String)
method and JSON objects created using thetoJSONObject()
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.
-
Constructor Summary
Constructors Constructor Description JSONObjectFilter()
-
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 aboolean
.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 thefilterType
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 thefilterType
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.
-
-
-
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 thefilterType
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 thefilterType
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, orfalse
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 benull
.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 benull
. 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 isnull
, then aJSONException
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 benull
.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 benull
. It will be treated in a case-sensitive manner.defaultValue
- The default values to return if the field is not present. If this isnull
andrequired
istrue
, then aJSONException
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 aboolean
. The specified field must be a top-level field in the JSON object, and it must have a value that is eithertrue
orfalse
.- Parameters:
o
- The JSON object to examine. It must not benull
.fieldName
- The name of a top-level field in the JSON object that that is expected to have a value that is eithertrue
orfalse
.defaultValue
- The default value to return if the specified field is not present in the JSON object. If this isnull
, then aJSONException
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 neithertrue
norfalse
.
-
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 benull
.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 benull
.- 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 benull
.- Returns:
- The constructed LDAP extensible matching filter.
-
hashCode
public final int hashCode()
Retrieves a hash code for this JSON object filter.- Overrides:
hashCode
in classjava.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 classjava.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, orfalse
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 classjava.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.
-
-