Filter
object. This Filter
object may be used
to match a ServiceReference
object or a Dictionary
object.
If the filter cannot be parsed, an
will be
thrown with a human readable message where the filter became unparsable.
InvalidSyntaxException
This method returns a Filter implementation which may not perform as well
as the framework implementation-specific Filter implementation returned
by
.
BundleContext.createFilter(java.lang.String)
filter
The filter string.Filter
object encapsulating the filter string.InvalidSyntaxException
If filter
contains an invalid
filter string that cannot be parsed.java.lang.NullPointerException
If filter
is null.Filter
'*'
\u002A) replaces all
possible values. Due to the structure of the DN, the comparison is more
complicated than string-based wildcard matching.
A wildcard can stand for zero or more DNs in a chain, a number of relative distinguished names (RDNs) within a DN, or the value of a single RDN. The DNs in the chain and the matching pattern are canonicalized before processing. This means, among other things, that spaces must be ignored, except in values.
The format of a wildcard match pattern is:
matchPattern ::= dn-match ( ';' dn-match ) * dn-match ::= ( '*' | rdn-match ) ( ',' rdn-match ) * | '-' rdn-match ::= name '=' value-match value-match ::= '*' | value-star value-star ::= < value, requires escaped '*' and '-' >
The most simple case is a single wildcard; it must match any DN. A wildcard can also replace the first list of RDNs of a DN. The first RDNs are the least significant. Such lists of matched RDNs can be empty.
For example, a match pattern with a wildcard that matches all DNs that end with RDNs of o=ACME and c=US would look like this:
*, o=ACME, c=USThis match pattern would match the following DNs:
cn = Bugs Bunny, o = ACME, c = US ou = Carrots, cn=Daffy Duck, o=ACME, c=US street = 9C\, Avenue St. Drézéry, o=ACME, c=US dc=www, dc=acme, dc=com, o=ACME, c=US o=ACME, c=USThe following DNs would not match:
street = 9C\, Avenue St. Drézéry, o=ACME, c=FR dc=www, dc=acme, dc=com, c=USIf a wildcard is used for a value of an RDN, the value must be exactly *. The wildcard must match any value, and no substring matching must be done. For example:
cn=*,o=ACME,c=*This match pattern with wildcard must match the following DNs:
cn=Bugs Bunny,o=ACME,c=US cn = Daffy Duck , o = ACME , c = US cn=Road Runner, o=ACME, c=NLBut not:
o=ACME, c=NL dc=acme.com, cn=Bugs Bunny, o=ACME, c=US
A match pattern may contain a chain of DN match patterns. The semicolon(
';'
\u003B) must be used to separate DN match patterns in a
chain. Wildcards can also be used to match against a complete DN within a
chain.
The following example matches a certificate signed by Tweety Inc. in the US.
* ; ou=S & V, o=Tweety Inc., c=US
The wildcard ('*') matches zero or one DN in the chain, however,
sometimes it is necessary to match a longer chain. The minus sign (
'-'
\u002D) represents zero or more DNs, whereas the asterisk
only represents a single DN. For example, to match a DN where the Tweety
Inc. is in the DN chain, use the following expression:
- ; *, o=Tweety Inc., c=US
matchPattern
The pattern against which to match the DN chain.dnChain
The DN chain to match against the specified pattern. Each
element of the chain must be of type String
and use the
format defined in RFC 2253.true
If the pattern matches the DN chain; otherwise
false
is returned.java.lang.IllegalArgumentException
If the specified match pattern or DN
chain is invalid.Bundle
for the specified bundle class. The returned
Bundle
is the bundle associated with the bundle class loader
which defined the specified class.
classFromBundle
A class defined by a bundle class loader.Bundle
for the specified bundle class or null
if the specified class was not defined by a bundle class loader.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:
A filter matches a key that has multiple values if it matches at least one of those values. For example,Note: arrays of primitives are also supported.
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
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
.
FrameworkUtil.FilterImpl
object. This filter object may be
used to match a ServiceReference
or a Dictionary.
If the filter cannot be parsed, an
will be thrown with a human readable message where the filter became
unparsable.
InvalidSyntaxException
filterString
the filter string.InvalidSyntaxException
If the filter parameter contains an
invalid filter string that cannot be parsed.
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.
reference
The reference to the service whose properties are
used in the match.true
if the service's properties match this
Filter
; false
otherwise.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.
dictionary
The Dictionary
whose key/value pairs are
used in the match.true
if the Dictionary
's values match this
filter; false
otherwise.java.lang.IllegalArgumentException
If dictionary
contains case
variants of the same key name.Dictionary
. This Filter
is executed
using the specified Dictionary
's keys and values. The keys
are looked up in a normal manner respecting case.
dictionary
The Dictionary
whose key/value pairs are
used in the match.true
if the Dictionary
's values match this
filter; false
otherwise.Map
. This Filter
is executed using the
specified Map
's keys and values. The keys are looked up in a
normal manner respecting case.
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.true
if the Map
's values match this filter;
false
otherwise.Filter
to another Filter
.
This implementation returns the result of calling
this.toString().equals(obj.toString()
.
obj
The object to compare against this Filter
.Filter
object, then returns
the result of calling
this.toString().equals(obj.toString()
; false
otherwise.private booleancompare_PrimitiveArray(int operation, Class<?> type, Object primarray, Object value2) {
return (charval == charval2) || (Character.toUpperCase(charval) == Character.toUpperCase(charval2)) || (Character.toLowerCase(charval) == Character.toLowerCase(charval2));
if (Modifier.isStatic(method.getModifiers()) && target.isAssignableFrom(method.getReturnType())) {
throw new InvalidSyntaxException("Extraneous trailing characters: " + filterstring.substring(pos), filterstring);
return new FilterImpl(FilterImpl.AND, null, operands.toArray(new FilterImpl[operands.size()]));
throw new InvalidSyntaxException("Invalid operator: " + filterstring.substring(pos), filterstring);
throw new InvalidSyntaxException("Missing attr: " + filterstring.substring(pos), filterstring);
throw new InvalidSyntaxException("Invalid value: " + filterstring.substring(pos), filterstring);
throw new InvalidSyntaxException("Missing value: " + filterstring.substring(pos), filterstring);