Package com.norconex.commons.lang.map

# Class PropertyMatcher

java.lang.Object
com.norconex.commons.lang.map.PropertyMatcher

All Implemented Interfaces:
  `Predicate<Properties>`

public final class PropertyMatcher extends Object implements Predicate<Properties>

Convenient way of matching values and/or fields (key) in a given `Properties`.

Since:
  1.8.0
See Also:
  - `TextMatcher`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `PropertyMatcher(TextMatcher fieldMatcher)`
  A property matcher that will only match present fields, regardless of values.
  `PropertyMatcher(TextMatcher fieldMatcher, TextMatcher valueMatcher)`
  A property matcher matching both fields and values.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `equals(Object o)`
  `TextMatcher`
  `getFieldMatcher()`
  Gets the field matcher (copy) or `null` if the field matcher is `null`.
  `TextMatcher`
  `getValueMatcher()`
  Gets the value matcher (copy) or `null` if the value matcher is `null`.
  `int`
  `hashCode()`
  `Properties`
  `match(Properties properties)`
  Returns matching field/values in the given `Properties`.
  `boolean`
  `matches(Properties properties)`
  Tests whether this property matcher matches at least one value for the key in the given `Properties`.
  `Properties`
  `replace(Properties properties, String replacement)`
  Replaces all matching values of the matching keys in the given `Properties` with the given replacement.
  `boolean`
  `test(Properties properties)`
  For compatibility with `Predicate`.
  `String`
  `toString()`

  ### Methods inherited from class java.lang.Object

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

  ### Methods inherited from interface java.util.function.Predicate

  `and, negate, or`

- ## Constructor Details

  - ### PropertyMatcher

    public PropertyMatcher(TextMatcher fieldMatcher)
    A property matcher that will only match present fields, regardless of values. Use `PropertyMatcher(TextMatcher, TextMatcher)` to match both fields and values.
    Parameters:
      `fieldMatcher` - field matcher
    Since:
      2.0.0

  - ### PropertyMatcher

    public PropertyMatcher(TextMatcher fieldMatcher, TextMatcher valueMatcher)

    A property matcher matching both fields and values. Only a single value of multi-valued fields need to match to generate a positive match on values.

    Either or both the field matcher and value matcher can be `null`. A `null` matcher is equivalent to matching fields or value, respectively.

    Parameters:
      `fieldMatcher` - field matcher
      `valueMatcher` - value matcher
    Since:
      2.0.0

- ## Method Details

  - ### getValueMatcher

    public TextMatcher getValueMatcher()
    Gets the value matcher (copy) or `null` if the value matcher is `null`.
    Returns:
      value matcher
    Since:
      2.0.0

  - ### getFieldMatcher

    public TextMatcher getFieldMatcher()
    Gets the field matcher (copy) or `null` if the field matcher is `null`.
    Returns:
      field matcher
    Since:
      2.0.0

  - ### matches

    public boolean matches(Properties properties)
    Tests whether this property matcher matches at least one value for the key in the given `Properties`. To get all matches instead, use `match(Properties)`. `null` text field or value matchers are considered to be matching all fields or values, respectively.
    Parameters:
      `properties` - the properties to look for a match
    Returns:
      `true` if at least one value for the key matches the matcher's expression
    See Also:
      - `match(Properties)`

  - ### test

    public boolean test(Properties properties)
    For compatibility with `Predicate`. Same as invoking `matches(Properties)`.
    Specified by:
      `test` in interface `Predicate<Properties>`
    Parameters:
      `properties` - the properties to look for a match
    Returns:
      `true` if at least one value for the key matches the list of valueMatcher regular expressions

  - ### match

    public Properties match(Properties properties)
    Returns matching field/values in the given `Properties`. For multi-valued fields, only the matching values are returned. `null` text field or value matchers are considered to be matching all fields or values, respectively. To simply get whether there is a match instead, use the predicate `test(Properties)` method instead.
    Parameters:
      `properties` - the properties to look for a match
    Returns:
      a list of matching values, or an empty list (never `null`)
    Since:
      2.0.0
    See Also:
      - `test(Properties)`

  - ### replace

    public Properties replace(Properties properties, String replacement)
    Replaces all matching values of the matching keys in the given `Properties` with the given replacement. If this property matcher has a `null` field matcher, it will replace all matching values, for all fields. If it has a `null` value matcher, it will replace all values of matching fields. If both are `null`, all values will be replaced for all keys.
    Parameters:
      `properties` - the properties to look for a match and replace
      `replacement` - text replacement
    Returns:
      original fields/values that were replaced (or empty).
    Since:
      2.0.0

  - ### toString

    public String toString()
    Overrides:
      `toString` in class `Object`

  - ### equals

    public boolean equals(Object o)
    Overrides:
      `equals` in class `Object`

  - ### hashCode

    public int hashCode()
    Overrides:
      `hashCode` in class `Object`