Package com.unboundid.ldap.sdk.unboundidds.jsonfilter
This package provides a number of classes that implement support for
interacting with JSON objects in the Ping Identity, UnboundID, or
Nokia/Alcatel-Lucent 8661 Directory Server. This primarily includes JSON
object filters (which are an UnboundID-proprietary mechanism for performing
advanced matching on JSON object contents), but also contains other classes
in support for interacting with JSON in the Ping Identity, UnboundID, or
Nokia/Alcatel-Lucent 8661 Directory Server.
The Ping Identity, UnboundID, and Nokia/Alcatel-Lucent 8661 Directory Server provides a "JSON Object" attribute syntax, which has an OID of "1.3.6.1.4.1.30221.2.3.4", and can be used for attribute types whose values are valid JSON objects. This attribute type supports equality matching (with the jsonObjectExactMatch matching rule as described below, but does not support substring or ordering matching. To create an attribute type definition that uses the JSON object syntax, use a definition like the following (but with the appropriate attribute type name and a non-example OID):
The jsonObjectExactMatch matching rule will also be used to perform matching for a compare operation that targets attributes with a JSON object syntax, and it will be used internally by the server to prevent an attribute with that syntax from having duplicate values, and to identify which value is targeted by a modification that attempts to delete a specific value.
The constraints that the jsonObjectExactMatch matching rule will use when determining whether two JSON objects are equal are:
The matching performed by the jsonObjectExactMatch matching rule is equivalent to that performed by the multi-argument
All JSON object filters must include a field named "filterType" that indicates the type of matching to be performed. The other fields that are required to be present, or that may optionally be present, vary based on the specified filter type. See the class-level documentation for each of the
NOTE: The classes within this package, and elsewhere 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.
The Ping Identity, UnboundID, and Nokia/Alcatel-Lucent 8661 Directory Server provides a "JSON Object" attribute syntax, which has an OID of "1.3.6.1.4.1.30221.2.3.4", and can be used for attribute types whose values are valid JSON objects. This attribute type supports equality matching (with the jsonObjectExactMatch matching rule as described below, but does not support substring or ordering matching. To create an attribute type definition that uses the JSON object syntax, use a definition like the following (but with the appropriate attribute type name and a non-example OID):
attributeTypes: ( 2.999.1.2.3.4 NAME 'example-json-attribute' EQUALITY jsonObjectExactMatch SYNTAX 1.3.6.1.4.1.30221.2.3.4 )
Matching with the jsonObjectExactMatch Matching Rule
The jsonObjectExactMatch matching rule (OID 1.3.6.1.4.1.30221.2.4.12) is an equality matching rule that can be used to perform exact matching against JSON objects. It can be used in an equality search filter whose attribute description names an attribute with a JSON object syntax and whose assertion value is the string representation of a JSON object to match against values of the specified attribute. For example:(jsonAttr={ "field1" : "value1", "field2":"value2" })
The jsonObjectExactMatch matching rule will also be used to perform matching for a compare operation that targets attributes with a JSON object syntax, and it will be used internally by the server to prevent an attribute with that syntax from having duplicate values, and to identify which value is targeted by a modification that attempts to delete a specific value.
The constraints that the jsonObjectExactMatch matching rule will use when determining whether two JSON objects are equal are:
- The names of the fields in each object must be identical, although the order in which the fields appear in the string representation is not significant. Neither object will be permitted to have a field that is not present in the other object. Field names will be treated in a case-sensitive manner (e.g., a field named "x" will be considered different from a field named "X").
- The values of fields with the same name must be of the same data type.
For example, the string "true" will not match the Boolean
true
, the string "1234" will not match the number 1234, and the string "null" will not match thenull
value. Similarly, a single non-array value will not match an array, even if the array contains only that value (e.g., so a value of "a" will not match ["a"]). - The values of fields with the same name must be logically equivalent.
Logical equivalence is defined as follows for each data type:
null
will only matchnull
.true
will only matchtrue
.false
will only matchfalse
.- Strings will be compared in a case-insensitive manner, but all
spaces will be considered significant. This will use logic
equivalent to the
String.equalsIgnoreCase
method. - Numbers will only match other numbers with equivalent numeric values, even if they are expressed with different string representations. For example, the number 12345 will match the number 12345.0 and the number 1.2345e4. Floating-point numbers with nonzero fractional components will not match integer numbers without fractional components (e.g., 12345 will not match 12345.1).
- Arrays will only match arrays containing logically-equivalent values in the same order.
- JSON objects that appear as field values or inside arrays will use the logic presented here.
The matching performed by the jsonObjectExactMatch matching rule is equivalent to that performed by the multi-argument
JSONObject.equals
method with ignoreFieldNameCase=false
, ignoreValueCase=true
,
and ignoreArrayOrder=false
.
Matching with the jsonObjectFilterExtensibleMatch Matching Rule
The jsonObjectFilterExtensibleMatch matching rule (OID 1.3.6.1.4.1.30221.2.4.13) provides a much greater degree of flexibility for performing matching against JSON objects than the jsonObjectExactMatch matching rule, but it is only expected to be used in LDAP filters that perform extensible matching (NOTE: do not attempt to use the jsonObjectFilterExtensibleMatch matching rule as the default equality matching rule for attribute types). In such filters, the filter should include an attribute description that names an attribute with the JSON object syntax, a matching rule ID of jsonObjectFilterExtensibleMatch (or the numeric OID 1.3.6.1.4.1.30221.2.4.13), and an assertion value that is a JSON object that defines the constraints for identifying which JSON objects to match. For example:(jsonAttr:jsonObjectFilterExtensibleMatch:={ "filterType":"fieldEquals", "fieldName":"field1", "fieldValue":"value1" })
All JSON object filters must include a field named "filterType" that indicates the type of matching to be performed. The other fields that are required to be present, or that may optionally be present, vary based on the specified filter type. See the class-level documentation for each of the
JSONObjectFilter
subclasses for detailed information about the type of matching performed by
that type of filter, as well as the sets of required and optional fields for
that filter type.-
Class Summary Class Description ANDJSONObjectFilter This class provides an implementation of a JSON object filter that can perform a logical AND across the result obtained from a number of filters.ContainsFieldJSONObjectFilter This class provides an implementation of a JSON object filter that can be used to identify JSON objects containing a specified field, optionally restricting it by the data type of the value.EqualsAnyJSONObjectFilter This class provides an implementation of a JSON object filter that can be used to identify JSON objects that have a specified field whose value matches one of specified set of values.EqualsJSONObjectFilter This class provides an implementation of a JSON object filter that can be used to identify JSON objects that have a particular value for a specified field.GreaterThanJSONObjectFilter This class provides an implementation of a JSON object filter that can be used to identify JSON objects that have at least one value for a specified field that is greater than a given value.JSONObjectExactMatchingRule This class provides an implementation of a matching rule that can be used in conjunction with JSON objects.JSONObjectFilter 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.LessThanJSONObjectFilter This class provides an implementation of a JSON object filter that can be used to identify JSON objects that have at least one value for a specified field that is less than a given value.NegateJSONObjectFilter This class provides an implementation of a JSON object filter that can negate the result of a provided filter.ObjectMatchesJSONObjectFilter This class provides an implementation of a JSON object filter that can be used to identify JSON objects that have a field whose value is a JSON object that matches a provided JSON object filter, or a field whose value is an array that contains at least one JSON object that matches the provided filter.ORJSONObjectFilter This class provides an implementation of a JSON object filter that can perform a logical OR across the result obtained from a number of filters.RegularExpressionJSONObjectFilter This class provides an implementation of a JSON object filter that can be used to identify JSON objects that have a particular value for a specified field.SubstringJSONObjectFilter This class provides an implementation of a JSON object filter that can be used to identify JSON objects that have string value that matches a specified substring. -
Enum Summary Enum Description ExpectedValueType An enum that defines the possible values that may be used for theexpectedType
element of aContainsFieldJSONObjectFilter
.