java.lang.Object
- aQute.bnd.osgi.resource.FilterImpl

All Implemented Interfaces:: org.osgi.framework.Filter

Direct Known Subclasses:: FilterImpl.And, FilterImpl.Item, FilterImpl.Not, FilterImpl.Or

abstract class FilterImpl
extends java.lang.Object
implements org.osgi.framework.Filter

RFC 1960-based Filter. Filter objects can be created by calling the constructor with the desired filter string. A Filter object can be called numerous times to determine if the match argument matches the filter string that was used to create the Filter object.

The syntax of a filter string is the string representation of LDAP search filters as defined in RFC 1960: A String Representation of LDAP Search Filters (available at http://www.ietf.org/rfc/rfc1960.txt). It should be noted that RFC 2254: A String Representation of LDAP Search Filters (available at http://www.ietf.org/rfc/rfc2254.txt) supersedes RFC 1960 but only adds extensible matching and is not applicable for this API.

The string representation of an LDAP search filter is defined by the following grammar. It uses a prefix format.

   <filter> ::= '(' <filtercomp> ')'
   <filtercomp> ::= <and> | <or> | <not> | <item>
   <and> ::= '&' <filterlist>
   <or> ::= '|' <filterlist>
   <not> ::= '!' <filter>
   <filterlist> ::= <filter> | <filter> <filterlist>
   <item> ::= <simple> | <present> | <substring>
   <simple> ::= <attr> <filtertype> <value>
   <filtertype> ::= <equal> | <approx> | <greater> | <less>
   <equal> ::= '='
   <approx> ::= '˜='
   <greater> ::= '>='
   <less> ::= '<='
   <present> ::= <attr> '=*'
   <substring> ::= <attr> '=' <initial> <any> <final>
   <initial> ::= NULL | <value>
   <any> ::= '*' <starval>
   <starval> ::= NULL | <value> '*' <starval>
   <final> ::= NULL | <value>

<attr> is a string representing an attribute, or key, in the properties objects of the registered services. Attribute names are not case sensitive; that is cn and CN both refer to the same attribute. <value> is a string representing the value, or part of one, of a key in the properties objects of the registered services. If a <value> must contain one of the characters ' *' or '(' or ')', these characters should be escaped by preceding them with the backslash '\' character. Note that although both the <substring> and <present> productions can produce the 'attr=*' construct, this construct is used only to denote a presence filter.

Examples of LDAP filters are:

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

The approximate match (~=) is implementation specific but should at least ignore case and white space differences. Optional are codes like soundex or other smart "closeness" comparisons.

Comparison of values is not straightforward. Strings are compared differently than numbers and it is possible for a key to have multiple values. Note that that keys in the match argument must always be strings. The comparison is defined by the object type of the key's value. The following rules apply for comparison:

Property Value Type Comparison Type

String String comparison

Integer, Long, Float, Double, Byte, Short, BigInteger, BigDecimal numerical comparison

Character character comparison

Boolean equality comparisons only

[] (array) recursively applied to values

Collection recursively applied to values

Note: arrays of primitives are also supported.

A filter matches a key that has multiple values if it matches at least one of those values. For example,

 Dictionary d = new Hashtable();
 d.put("cn", new String[] {
        "a", "b", "c"
 });

d will match (cn=a) and also (cn=b)

A filter component that references a key having an unrecognizable data type will evaluate to false .

Nested Class Summary

Nested Classes
Modifier and Type	Class	Description
`(package private) static class`	`FilterImpl.And`
`(package private) static class`	`FilterImpl.Approx`
`private static class`	`FilterImpl.CaseInsensitiveMap`	This Map is used for case-insensitive key lookup during filter evaluation.
`private static class`	`FilterImpl.DictionaryMap`	This Map is used for key lookup during filter evaluation.
`(package private) static class`	`FilterImpl.Equal`
`(package private) static class`	`FilterImpl.GreaterEqual`
`(package private) static class`	`FilterImpl.Item`
`(package private) static class`	`FilterImpl.LessEqual`
`(package private) static class`	`FilterImpl.Not`
`(package private) static class`	`FilterImpl.Or`
`private static class`	`FilterImpl.Parser`	Parser class for OSGi filter strings.
`(package private) static class`	`FilterImpl.Present`
`private static class`	`FilterImpl.ServiceReferenceMap`	This Map is used for key lookup from a ServiceReference during filter evaluation.
`(package private) static class`	`FilterImpl.Substring`

Field Summary

Fields
Modifier and Type Field Description

private java.lang.String filterString

Constructor Summary

Constructors
Constructor Description

FilterImpl()

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method	Description
`(package private) static FilterImpl`	`createFilter(java.lang.String filterString)`	Creates a `FilterImpl` object.
`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(org.osgi.framework.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`.
`(package private) abstract boolean`	`matches0(java.util.Map<java.lang.String,?> map)`
`(package private) abstract java.lang.StringBuilder`	`normalize(java.lang.StringBuilder sb)`	Returns this `Filter`'s normalized filter string.
`java.lang.String`	`toString()`	Returns this `Filter`'s filter string.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Field Detail
  - filterString
```
private transient java.lang.String filterString
```
- Constructor Detail
  - FilterImpl
```
FilterImpl()
```
- Method Detail
  - createFilter
```
static FilterImpl createFilter(java.lang.String filterString)
                        throws org.osgi.framework.InvalidSyntaxException
```
    Creates a FilterImpl object. This filter object may be used to match a ServiceReference or a Dictionary.
    If the filter cannot be parsed, an InvalidSyntaxException will be thrown with a human readable message where the filter became unparsable.
    
    Parameters:
    
    filterString - the filter string.
    
    Throws:
    
    org.osgi.framework.InvalidSyntaxException - If the filter parameter contains an invalid filter string that cannot be parsed.
  - match
```
public boolean match(org.osgi.framework.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.
    
    Specified by:
    
    match in interface org.osgi.framework.Filter
    
    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
```
public 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.
    
    Specified by:
    
    match in interface org.osgi.framework.Filter
    
    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.
  - matchCase
```
public 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.
    
    Specified by:
    
    matchCase in interface org.osgi.framework.Filter
    
    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
```
public 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.
    
    Specified by:
    
    matches in interface org.osgi.framework.Filter
    
    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
  - matches0
```
abstract boolean matches0(java.util.Map<java.lang.String,?> map)
```
  - toString
```
public 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.
    
    Specified by:
    
    toString in interface org.osgi.framework.Filter
    
    Overrides:
    
    toString in class java.lang.Object
    
    Returns:
    
    This Filter's filter string.
  - normalize
```
abstract java.lang.StringBuilder normalize(java.lang.StringBuilder sb)
```
    Returns this Filter's normalized filter string.
    The filter string is normalized by removing whitespace which does not affect the meaning of the filter.
    
    Returns:
    
    This Filter's filter string.
  - equals
```
public boolean equals(java.lang.Object obj)
```
    Compares this Filter to another Filter.
    This implementation returns the result of calling this.toString().equals(obj.toString().
    
    Specified by:
    
    equals in interface org.osgi.framework.Filter
    
    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
```
public int hashCode()
```
    Returns the hashCode for this Filter.
    This implementation returns the result of calling this.toString().hashCode().
    
    Specified by:
    
    hashCode in interface org.osgi.framework.Filter
    
    Overrides:
    
    hashCode in class java.lang.Object
    
    Returns:
    
    The hashCode of this Filter.

Property Value Type	Comparison Type
String	String comparison
Integer, Long, Float, Double, Byte, Short, BigInteger, BigDecimal	numerical comparison
Character	character comparison
Boolean	equality comparisons only
[] (array)	recursively applied to values
Collection	recursively applied to values

Class FilterImpl

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

filterString

Constructor Detail

FilterImpl

Method Detail

createFilter

match

match

matchCase

matches

matches0

toString

normalize

equals

hashCode