org.osgi.framework
Interface Filter

public interface Filter

An RFC 1960-based Filter.

Filter objects can be created by calling BundleContext.createFilter(java.lang.String) with the chosen filter string.

A Filter object can be used 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) supercedes RFC 1960 but only adds extensible matching and is not applicable for this OSGi Framework API.

The string representation of an LDAP search filter uses a prefix format, and is defined with the following grammar.

 <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 services registered in the Framework. Attribute names are not case sensitive; that is, cn and CN both refer to the same attribute. <attr> should contain no spaces though white space is allowed between the initial parenthesis "(" and the start of the key, and between the end of the key and the equal sign "=". <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. Spaces are significant in <value>. Space charactes are defined by java.lang.Character.isWhiteSpace(). 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 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
 Vector   			  Recursively applied to elements
 

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.

Since:

1.1

Method Summary

boolean	equals(java.lang.Object obj) Compares this Filter object to another object.
int	hashCode() Returns the hashCode for this Filter object.
boolean	match(java.util.Dictionary dictionary) Filter using a Dictionary object.
boolean	match(ServiceReference reference) Filter using a service's properties.
java.lang.String	toString() Returns this Filter object's filter string.

Method Detail

match

public boolean match(ServiceReference reference)

Filter using a service's properties.

The filter is executed using properties of the referenced service.

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 dictionary)

Filter using a Dictionary object. The Filter is executed using the Dictionary object's keys and values.

Parameters:

dictionary - The Dictionary object whose keys are used in the match.

Returns:

true if the Dictionary object's keys and values match this filter; false otherwise.

Throws:

java.lang.IllegalArgumentException - If dictionary contains case variants of the same key name.

toString

public java.lang.String toString()

Returns this Filter object's filter string.

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

Returns:

Filter string.

equals

public boolean equals(java.lang.Object obj)

Compares this Filter object to another object.

Parameters:

obj - The object to compare against this Filter object.

Returns:

If the other object is a Filter object, then returns this.toString().equals(obj.toString(); false otherwise.

hashCode

public int hashCode()

Returns the hashCode for this Filter object.

Returns:

The hashCode of the filter string; that is, this.toString().hashCode().