com.unboundid.ldap.sdk.unboundidds.jsonfilter

Class SubstringJSONObjectFilter

java.lang.Object

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

com.unboundid.ldap.sdk.unboundidds.jsonfilter.SubstringJSONObjectFilter

All Implemented Interfaces:

java.io.Serializable

@Mutable
 @ThreadSafety(level=NOT_THREADSAFE)
public final class SubstringJSONObjectFilter
extends JSONObjectFilter

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. At least one of the startsWith, contains, and endsWith components must be included in the filter. If multiple substring components are present, then any matching value must contain all of those components, and the components must not overlap.

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.

The fields that are required to be included in a "substring" filter are:

• field -- A field path specifier for the JSON field for which to make the determination. This may be either a single string or an array of strings as described in the "Targeting Fields in JSON Objects" section of the class-level documentation for JSONObjectFilter.

The fields that may optionally be included in a "substring" filter are:

• startsWith -- A string that must appear at the beginning of matching values.
• contains -- A string, or an array of strings, that must appear in matching values. If this is an array of strings, then a matching value must contain all of these strings in the order provided in the array.
• endsWith -- A string that must appear at the end of matching values.
• caseSensitive -- Indicates whether string values should be treated in a case-sensitive manner. If present, this field must have a Boolean value of either true or false. If it is not provided, then a default value of false will be assumed so that strings are treated in a case-insensitive manner.

Examples

The following is an example of a substring filter that will match any JSON object with a top-level field named "accountCreateTime" with a string value that starts with "2015":

   { "filterType" : "substring",
     "field" : "accountCreateTime",
     "startsWith" : "2015" }
 

The above filter can be created with the code:

   SubstringJSONObjectFilter filter =
        new SubstringJSONObjectFilter("accountCreateTime", "2015", null,
             null);
 

The following is an example of a substring filter that will match any JSON object with a top-level field named "fullName" that contains the substrings "John" and "Doe", in that order, somewhere in the value:

   { "filterType" : "substring",
     "field" : "fullName",
     "contains" : [ "John", "Doe" ] }
 

The above filter can be created with the code:

   SubstringJSONObjectFilter filter =
        new SubstringJSONObjectFilter(Collections.singletonList("fullName"),
             null, Arrays.asList("John", "Doe"), null);
 

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	FIELD_CASE_SENSITIVE The name of the JSON field that is used to indicate whether string matching should be case-sensitive.
static java.lang.String	FIELD_CONTAINS The name of the JSON field that is used to specify one or more strings that must appear somewhere in a matching value.
static java.lang.String	FIELD_ENDS_WITH The name of the JSON field that is used to specify a string that must appear at the end of a matching value.
static java.lang.String	FIELD_FIELD_PATH The name of the JSON field that is used to specify the field in the target JSON object for which to make the determination.
static java.lang.String	FIELD_STARTS_WITH The name of the JSON field that is used to specify a string that must appear at the beginning of a matching value.
static java.lang.String	FILTER_TYPE The value that should be used for the filterType element of the JSON object that represents a "substring" filter.

Fields inherited from class com.unboundid.ldap.sdk.unboundidds.jsonfilter.JSONObjectFilter

FIELD_FILTER_TYPE, JSON_OBJECT_FILTER_MATCHING_RULE_NAME, JSON_OBJECT_FILTER_MATCHING_RULE_OID

Constructor Summary

Constructors

Constructor and Description
SubstringJSONObjectFilter(java.util.List<java.lang.String> field, java.lang.String startsWith, java.util.List<java.lang.String> contains, java.lang.String endsWith) Creates a new instance of this filter type with the provided information.
SubstringJSONObjectFilter(java.lang.String field, java.lang.String startsWith, java.lang.String contains, java.lang.String endsWith) Creates a new instance of this filter type with the provided information.

Method Summary

Modifier and Type	Method and Description
boolean	caseSensitive() Indicates whether string matching should be performed in a case-sensitive manner.
protected SubstringJSONObjectFilter	decodeFilter(JSONObject filterObject) Decodes the provided JSON object as a filter of this type.
java.util.List<java.lang.String>	getContains() Retrieves the list of strings that must appear somewhere in the value (after any defined "starts with" value, and before any defined "ends with" value).
java.lang.String	getEndsWith() Retrieves the substring that must appear at the end of matching values, if defined.
java.util.List<java.lang.String>	getField() Retrieves the field path specifier for this filter.
java.lang.String	getFilterType() Retrieves the value that must appear in the filterType field for this filter.
protected 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 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.
java.lang.String	getStartsWith() Retrieves the substring that must appear at the beginning of matching values, if defined.
boolean	matchesJSONObject(JSONObject o) Indicates whether this JSON object filter matches the provided JSON object.
boolean	matchesString(java.lang.String s) Indicates whether the substring assertion defined in this filter matches the provided string.
void	setCaseSensitive(boolean caseSensitive) Specifies whether string matching should be performed in a case-sensitive manner.
void	setField(java.util.List<java.lang.String> field) Sets the field path specifier for this filter.
void	setField(java.lang.String... field) Sets the field path specifier for this filter.
void	setSubstringComponents(java.lang.String startsWith, java.util.List<java.lang.String> contains, java.lang.String endsWith) Specifies the substring components that must be present in matching values.
void	setSubstringComponents(java.lang.String startsWith, java.lang.String contains, java.lang.String endsWith) Specifies the substring components that must be present in matching values.
JSONObject	toJSONObject() Retrieves a JSON object that represents this filter.
JSONObject	toNormalizedJSONObject() Retrieves a JSON object that represents a normalized version of this filter.

Methods inherited from class com.unboundid.ldap.sdk.unboundidds.jsonfilter.JSONObjectFilter

decode, equals, getBoolean, getFilters, getString, getStrings, getValues, hashCode, registerFilterType, toLDAPFilter, toNormalizedString, toNormalizedString, toString, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

FILTER_TYPE

@NotNull
public static final java.lang.String FILTER_TYPE

The value that should be used for the filterType element of the JSON object that represents a "substring" filter.

See Also:

Constant Field Values

FIELD_FIELD_PATH

@NotNull
public static final java.lang.String FIELD_FIELD_PATH

The name of the JSON field that is used to specify the field in the target JSON object for which to make the determination.

See Also:

Constant Field Values

FIELD_STARTS_WITH

@NotNull
public static final java.lang.String FIELD_STARTS_WITH

The name of the JSON field that is used to specify a string that must appear at the beginning of a matching value.

See Also:

Constant Field Values

FIELD_CONTAINS

@NotNull
public static final java.lang.String FIELD_CONTAINS

The name of the JSON field that is used to specify one or more strings that must appear somewhere in a matching value.

See Also:

Constant Field Values

FIELD_ENDS_WITH

@NotNull
public static final java.lang.String FIELD_ENDS_WITH

The name of the JSON field that is used to specify a string that must appear at the end of a matching value.

See Also:

Constant Field Values

FIELD_CASE_SENSITIVE

@NotNull
public static final java.lang.String FIELD_CASE_SENSITIVE

The name of the JSON field that is used to indicate whether string matching should be case-sensitive.

See Also:

Constant Field Values

Constructor Detail

SubstringJSONObjectFilter

public SubstringJSONObjectFilter(@NotNull
                                 java.lang.String field,
                                 @Nullable
                                 java.lang.String startsWith,
                                 @Nullable
                                 java.lang.String contains,
                                 @Nullable
                                 java.lang.String endsWith)

Creates a new instance of this filter type with the provided information. At least one startsWith, contains, or endsWith value must be present.

Parameters:

field - The name of the top-level field to target with this filter. It must not be null . See the class-level documentation for the JSONObjectFilter class for information about field path specifiers.

startsWith - An optional substring that must appear at the beginning of matching values. This may be null if matching will be performed using only contains and/or endsWith substrings.

contains - An optional substring that must appear somewhere in matching values. This may be null if matching will be performed using only startsWith and/or endsWith substrings.

endsWith - An optional substring that must appear at the end of matching values. This may be null if matching will be performed using only startsWith and/or contains substrings.

SubstringJSONObjectFilter

public SubstringJSONObjectFilter(@NotNull
                                 java.util.List<java.lang.String> field,
                                 @Nullable
                                 java.lang.String startsWith,
                                 @Nullable
                                 java.util.List<java.lang.String> contains,
                                 @Nullable
                                 java.lang.String endsWith)

Creates a new instance of this filter type with the provided information. At least one startsWith, contains, or endsWith value must be present.

Parameters:

field - The field path specifier for this filter. It must not be null or empty. See the class-level documentation for the JSONObjectFilter class for information about field path specifiers.

startsWith - An optional substring that must appear at the beginning of matching values. This may be null if matching will be performed using only contains and/or endsWith substrings.

contains - An optional set of substrings that must appear somewhere in matching values. This may be null or empty if matching will be performed using only startsWith and/or endsWith substrings.

endsWith - An optional substring that must appear at the end of matching values. This may be null if matching will be performed using only startsWith and/or contains substrings.

Method Detail

getField

@NotNull
public java.util.List<java.lang.String> getField()

Retrieves the field path specifier for this filter.

Returns:

The field path specifier for this filter.

setField

public void setField(@NotNull
                     java.lang.String... field)

Sets the field path specifier for this filter.

Parameters:

field - The field path specifier for this filter. It must not be null or empty. See the class-level documentation for the JSONObjectFilter class for information about field path specifiers.

setField

public void setField(@NotNull
                     java.util.List<java.lang.String> field)

Sets the field path specifier for this filter.

Parameters:

field - The field path specifier for this filter. It must not be null or empty. See the class-level documentation for the JSONObjectFilter class for information about field path specifiers.

getStartsWith

@Nullable
public java.lang.String getStartsWith()

Retrieves the substring that must appear at the beginning of matching values, if defined.

Returns:

The substring that must appear at the beginning of matching values, or null if no "starts with" substring has been defined.

getContains

@NotNull
public java.util.List<java.lang.String> getContains()

Retrieves the list of strings that must appear somewhere in the value (after any defined "starts with" value, and before any defined "ends with" value).

Returns:

The list of strings that must appear somewhere in the value, or an empty list if no "contains" substrings have been defined.

getEndsWith

@Nullable
public java.lang.String getEndsWith()

Retrieves the substring that must appear at the end of matching values, if defined.

Returns:

The substring that must appear at the end of matching values, or null if no "starts with" substring has been defined.

setSubstringComponents

public void setSubstringComponents(@Nullable
                                   java.lang.String startsWith,
                                   @Nullable
                                   java.lang.String contains,
                                   @Nullable
                                   java.lang.String endsWith)

Specifies the substring components that must be present in matching values. At least one startsWith, contains, or endsWith value must be present.

Parameters:

startsWith - An optional substring that must appear at the beginning of matching values. This may be null if matching will be performed using only contains and/or endsWith substrings.

contains - An optional substring that must appear somewhere in matching values. This may be null if matching will be performed using only startsWith and/or endsWith substrings.

endsWith - An optional substring that must appear at the end of matching values. This may be null if matching will be performed using only startsWith and/or contains substrings.

setSubstringComponents

public void setSubstringComponents(@Nullable
                                   java.lang.String startsWith,
                                   @Nullable
                                   java.util.List<java.lang.String> contains,
                                   @Nullable
                                   java.lang.String endsWith)

Specifies the substring components that must be present in matching values. At least one startsWith, contains, or endsWith value must be present.

Parameters:

startsWith - An optional substring that must appear at the beginning of matching values. This may be null if matching will be performed using only contains and/or endsWith substrings.

contains - An optional set of substrings that must appear somewhere in matching values. This may be null or empty if matching will be performed using only startsWith and/or endsWith substrings.

endsWith - An optional substring that must appear at the end of matching values. This may be null if matching will be performed using only startsWith and/or contains substrings.

caseSensitive

public boolean caseSensitive()

Indicates whether string matching should be performed in a case-sensitive manner.

Returns:

true if string matching should be case sensitive, or false if not.

setCaseSensitive

public void setCaseSensitive(boolean caseSensitive)

Specifies whether string matching should be performed in a case-sensitive manner.

Parameters:

caseSensitive - Indicates whether string matching should be case sensitive.

getFilterType

@NotNull
public java.lang.String getFilterType()

Retrieves the value that must appear in the filterType field for this filter.

Specified by:

getFilterType in class JSONObjectFilter

Returns:

The value that must appear in the filterType field for this filter.

getRequiredFieldNames

@NotNull
protected 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.

Specified by:

getRequiredFieldNames in class JSONObjectFilter

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

Specified by:

getOptionalFieldNames in class JSONObjectFilter

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 boolean matchesJSONObject(@NotNull
                                 JSONObject o)

Indicates whether this JSON object filter matches the provided JSON object.

Specified by:

matchesJSONObject in class JSONObjectFilter

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.

matchesString

public boolean matchesString(@NotNull
                             java.lang.String s)

Indicates whether the substring assertion defined in this filter matches the provided string.

Parameters:

s - The string for which to make the determination.

Returns:

true if the substring assertion defined in this filter matches the provided string, or false if not.

toJSONObject

@NotNull
public JSONObject toJSONObject()

Retrieves a JSON object that represents this filter.

Specified by:

toJSONObject in class JSONObjectFilter

Returns:

A JSON object that represents this filter.

toNormalizedJSONObject

@NotNull
public JSONObject toNormalizedJSONObject()

Retrieves a JSON object that represents a normalized version of this filter.

Specified by:

toNormalizedJSONObject in class JSONObjectFilter

Returns:

A JSON object that represents a normalized version of this filter.

decodeFilter

@NotNull
protected SubstringJSONObjectFilter decodeFilter(@NotNull
                                                          JSONObject filterObject)
                                                   throws JSONException

Decodes the provided JSON object as a filter of this type.

Specified by:

decodeFilter in class JSONObjectFilter

Parameters:

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