Filter
Date: 2016-06-24

org.osgi.framework

## Interface Filter

-     @ProviderType
      public interface Filter

  An RFC 1960-based Filter.

  `Filter`s can be created by calling `BundleContext.createFilter(String)` or `FrameworkUtil.createFilter(String)` with a filter string.

  A `Filter` can be used numerous times to determine if the match argument matches the filter string that was used to create the `Filter`.

  Some examples of LDAP filters are:

        "(cn=Babs Jensen)"
        "(!(cn=Tim Howes))"
        "(&(" + Constants.OBJECTCLASS + "=Person)(|(sn=Jensen)(cn=Babs J*)))"
        "(o=univ*of*mich*)"

  Since:
    1.1
  See Also:
    "Core Specification, Filters, for a description of the filter string syntax."

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `equals(java.lang.Object obj)` Compares this `Filter` to another `Filter`.
    `int` | `hashCode()` Returns the hashCode for this `Filter`.
    `boolean` | `match(java.util.Dictionary<java.lang.String,?> dictionary)` Filter using a `Dictionary` with case insensitive key lookup.
    `boolean` | `match(ServiceReference<?> reference)` Filter using a service's properties.
    `boolean` | `matchCase(java.util.Dictionary<java.lang.String,?> dictionary)` Filter using a `Dictionary`.
    `boolean` | `matches(java.util.Map<java.lang.String,?> map)` Filter using a `Map`.
    `java.lang.String` | `toString()` Returns this `Filter`'s filter string.

- - ### Method Detail

    - #### match

          boolean match(ServiceReference<?> reference)

      Filter using a service's properties.

      This `Filter` is executed using the keys and values of the referenced service's properties. The keys are looked up in a case insensitive manner.

      Parameters:
        `reference` - The reference to the service whose properties are used in the match.
      Returns:
        `true` if the service's properties match this `Filter`; `false` otherwise.

    - #### match

          boolean match(java.util.Dictionary<java.lang.String,?> dictionary)

      Filter using a `Dictionary` with case insensitive key lookup. This `Filter` is executed using the specified `Dictionary`'s keys and values. The keys are looked up in a case insensitive manner.
      Parameters:
        `dictionary` - The `Dictionary` whose key/value pairs are used in the match.
      Returns:
        `true` if the `Dictionary`'s values match this filter; `false` otherwise.
      Throws:
        `java.lang.IllegalArgumentException` - If `dictionary` contains case variants of the same key name.

    - #### toString

          java.lang.String toString()

      Returns this `Filter`'s filter string.

      The filter string is normalized by removing whitespace which does not affect the meaning of the filter.

      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        This `Filter`'s filter string.

    - #### equals

          boolean equals(java.lang.Object obj)

      Compares this `Filter` to another `Filter`.

      This implementation returns the result of calling `this.toString().equals(obj.toString())`.

      Overrides:
        `equals` in class `java.lang.Object`
      Parameters:
        `obj` - The object to compare against this `Filter`.
      Returns:
        If the other object is a `Filter` object, then returns the result of calling `this.toString().equals(obj.toString())`; `false` otherwise.

    - #### hashCode

          int hashCode()

      Returns the hashCode for this `Filter`.

      This implementation returns the result of calling `this.toString().hashCode()`.

      Overrides:
        `hashCode` in class `java.lang.Object`
      Returns:
        The hashCode of this `Filter`.

    - #### matchCase

          boolean matchCase(java.util.Dictionary<java.lang.String,?> dictionary)

      Filter using a `Dictionary`. This `Filter` is executed using the specified `Dictionary`'s keys and values. The keys are looked up in a normal manner respecting case.
      Parameters:
        `dictionary` - The `Dictionary` whose key/value pairs are used in the match.
      Returns:
        `true` if the `Dictionary`'s values match this filter; `false` otherwise.
      Since:
        1.3

    - #### matches

          boolean matches(java.util.Map<java.lang.String,?> map)

      Filter using a `Map`. This `Filter` is executed using the specified `Map`'s keys and values. The keys are looked up in a normal manner respecting case.
      Parameters:
        `map` - The `Map` whose key/value pairs are used in the match. Maps with `null` key or values are not supported. A `null` value is considered not present to the filter.
      Returns:
        `true` if the `Map`'s values match this filter; `false` otherwise.
      Since:
        1.6