Class RegularExpressionJSONObjectFilter

  • All Implemented Interfaces:
    java.io.Serializable

    @Mutable
    @ThreadSafety(level=NOT_THREADSAFE)
    public final class RegularExpressionJSONObjectFilter
    extends JSONObjectFilter
    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.
    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 "regular expression" 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.
    • regularExpression -- The regular expression to use to identify matching values. It must be compatible for use with the Java java.util.regex.Pattern class.
    The fields that may optionally be included in a "regular expression" filter are:
    • matchAllElements -- Indicates whether all elements of an array must match the provided regular expression. If present, this field must have a Boolean value of true (to indicate that all elements of the array must match the regular expression) or false (to indicate that at least one element of the array must match the regular expression). If this is not specified, then the default behavior will be to require only at least one matching element. This field will be ignored for JSON objects in which the specified field has a value that is not an array.

    Example

    The following is an example of a "regular expression" filter that will match any JSON object with a top-level field named "userID" with a 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]*$" }
     
    The above filter can be created with the code:
       RegularExpressionJSONObjectFilter filter =
              new RegularExpressionJSONObjectFilter("userID",
                   "^[a-zA-Z][a-zA-Z0-9]*$");
     
    See Also:
    Serialized Form
    • Constructor Summary

      Constructors 
      Constructor Description
      RegularExpressionJSONObjectFilter​(java.lang.String field, java.lang.String regularExpression)
      Creates a new instance of this filter type with the provided information.
      RegularExpressionJSONObjectFilter​(java.lang.String field, java.util.regex.Pattern regularExpression)
      Creates a new instance of this filter type with the provided information.
      RegularExpressionJSONObjectFilter​(java.util.List<java.lang.String> field, java.lang.String regularExpression)
      Creates a new instance of this filter type with the provided information.
      RegularExpressionJSONObjectFilter​(java.util.List<java.lang.String> field, java.util.regex.Pattern regularExpression)
      Creates a new instance of this filter type with the provided information.
    • Constructor Detail

      • RegularExpressionJSONObjectFilter

        public RegularExpressionJSONObjectFilter​(@NotNull
                                                 java.lang.String field,
                                                 @NotNull
                                                 java.lang.String regularExpression)
                                          throws JSONException
        Creates a new instance of this filter type with the provided information.
        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.
        regularExpression - The regular expression to match. It must not be null, and it must be compatible for use with the java.util.regex.Pattern class.
        Throws:
        JSONException - If the provided string cannot be parsed as a valid regular expression.
      • RegularExpressionJSONObjectFilter

        public RegularExpressionJSONObjectFilter​(@NotNull
                                                 java.lang.String field,
                                                 @NotNull
                                                 java.util.regex.Pattern regularExpression)
        Creates a new instance of this filter type with the provided information.
        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.
        regularExpression - The regular expression pattern to match. It must not be null.
      • RegularExpressionJSONObjectFilter

        public RegularExpressionJSONObjectFilter​(@NotNull
                                                 java.util.List<java.lang.String> field,
                                                 @NotNull
                                                 java.lang.String regularExpression)
                                          throws JSONException
        Creates a new instance of this filter type with the provided information.
        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.
        regularExpression - The regular expression to match. It must not be null, and it must be compatible for use with the java.util.regex.Pattern class.
        Throws:
        JSONException - If the provided string cannot be parsed as a valid regular expression.
      • RegularExpressionJSONObjectFilter

        public RegularExpressionJSONObjectFilter​(@NotNull
                                                 java.util.List<java.lang.String> field,
                                                 @NotNull
                                                 java.util.regex.Pattern regularExpression)
        Creates a new instance of this filter type with the provided information.
        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.
        regularExpression - The regular expression pattern to match. It must not be null.
    • 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.
      • getRegularExpression

        @NotNull
        public java.util.regex.Pattern getRegularExpression()
        Retrieves the regular expression pattern for this filter.
        Returns:
        The regular expression pattern for this filter.
      • setRegularExpression

        public void setRegularExpression​(@NotNull
                                         java.lang.String regularExpression)
                                  throws JSONException
        Specifies the regular expression for this filter.
        Parameters:
        regularExpression - The regular expression to match. It must not be null, and it must be compatible for use with the java.util.regex.Pattern class.
        Throws:
        JSONException - If the provided string cannot be parsed as a valid regular expression.
      • setRegularExpression

        public void setRegularExpression​(@NotNull
                                         java.util.regex.Pattern regularExpression)
        Specifies the regular expression for this filter.
        Parameters:
        regularExpression - The regular expression pattern to match. It must not be null.
      • matchAllElements

        public boolean matchAllElements()
        Indicates whether, if the target field is an array of values, the regular expression will be required to match all elements in the array rather than at least one element.
        Returns:
        true if the regular expression will be required to match all elements of an array, or false if it will only be required to match at least one element.
      • setMatchAllElements

        public void setMatchAllElements​(boolean matchAllElements)
        Specifies whether the regular expression will be required to match all elements of an array rather than at least one element.
        Parameters:
        matchAllElements - Indicates whether the regular expression will be required to match all elements of an array rather than at least one element.
      • 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.