org.eclipse.osgi.framework.internal.core
Class FilterImpl

java.lang.Object
  extended by org.eclipse.osgi.framework.internal.core.FilterImpl
All Implemented Interfaces:
Filter

public class FilterImpl
extends java.lang.Object
implements 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
Vectorrecursively applied to elements
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 .


Field Summary
protected static int AND
           
protected static int APPROX
           
protected  java.lang.String attr
          filter attribute or null if operation AND, OR or NOT
protected static java.lang.Class[] constructorType
           
protected static int EQUAL
           
protected  java.lang.String filter
           
protected static int GREATER
           
protected static int LESS
           
protected static int NOT
           
protected  int operation
          filter operation
protected static int OR
           
protected static int PRESENT
           
protected static int SUBSTRING
           
protected  boolean topLevel
           
protected  java.lang.Object value
          filter operands
 
Constructor Summary
protected FilterImpl()
           
  FilterImpl(java.lang.String filter)
          Constructs a FilterImpl object.
 
Method Summary
protected static java.lang.String approxString(java.lang.String input)
          Map a string for an APPROX (~=) comparison.
protected  boolean compare_Boolean(int operation, boolean boolval, java.lang.Object value2)
           
protected  boolean compare_Byte(int operation, byte byteval, java.lang.Object value2)
           
protected  boolean compare_Character(int operation, char charval, java.lang.Object value2)
           
protected  boolean compare_Collection(int operation, java.util.Collection collection, java.lang.Object value2)
           
protected  boolean compare_Comparable(int operation, java.lang.Comparable value1, java.lang.Object value2)
           
protected  boolean compare_Double(int operation, double doubleval, java.lang.Object value2)
           
protected  boolean compare_Float(int operation, float floatval, java.lang.Object value2)
           
protected  boolean compare_Integer(int operation, int intval, java.lang.Object value2)
           
protected  boolean compare_Long(int operation, long longval, java.lang.Object value2)
           
protected  boolean compare_ObjectArray(int operation, java.lang.Object[] array, java.lang.Object value2)
           
protected  boolean compare_PrimitiveArray(int operation, java.lang.Class type, java.lang.Object primarray, java.lang.Object value2)
           
protected  boolean compare_Short(int operation, short shortval, java.lang.Object value2)
           
protected  boolean compare_String(int operation, java.lang.String string, java.lang.Object value2)
           
protected  boolean compare_Unknown(int operation, java.lang.Object value1, java.lang.Object value2)
           
protected  boolean compare(int operation, java.lang.Object value1, java.lang.Object value2)
           
protected static java.lang.String encodeValue(java.lang.String value)
          Encode the value string such that '(', '*', ')' and '\' are escaped.
 boolean equals(java.lang.Object obj)
          Compares this Filter object to another object.
 java.lang.String[] getAttributes()
          Returns all the attributes contained within this filter
static java.lang.String getObjectClassFilterString(java.lang.String objectClass)
          Returns a objectClass filter string for the specified objectClass.
 java.lang.String getRequiredObjectClass()
          Returns the leftmost required objectClass value for the filter to evaluate to true.
 int hashCode()
          Returns the hashCode for this Filter object.
 boolean match(java.util.Dictionary dictionary)
          Filter using a Dictionary.
 boolean match(ServiceReference reference)
          Filter using a service's properties.
protected  boolean match(ServiceReferenceImpl reference)
          Filter using a service's properties.
protected  boolean match0(java.util.Dictionary properties)
          Internal match routine.
 boolean matchCase(java.util.Dictionary dictionary)
          Filter with case sensitivity using a Dictionary object.
protected  void setFilter(int operation, java.lang.String attr, java.lang.Object value)
           
 java.lang.String toString()
          Returns this Filter object's filter string.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

operation

protected int operation
filter operation


EQUAL

protected static final int EQUAL
See Also:
Constant Field Values

APPROX

protected static final int APPROX
See Also:
Constant Field Values

GREATER

protected static final int GREATER
See Also:
Constant Field Values

LESS

protected static final int LESS
See Also:
Constant Field Values

PRESENT

protected static final int PRESENT
See Also:
Constant Field Values

SUBSTRING

protected static final int SUBSTRING
See Also:
Constant Field Values

AND

protected static final int AND
See Also:
Constant Field Values

OR

protected static final int OR
See Also:
Constant Field Values

NOT

protected static final int NOT
See Also:
Constant Field Values

attr

protected java.lang.String attr
filter attribute or null if operation AND, OR or NOT


value

protected java.lang.Object value
filter operands


filter

protected java.lang.String filter

topLevel

protected boolean topLevel

constructorType

protected static final java.lang.Class[] constructorType
Constructor Detail

FilterImpl

public FilterImpl(java.lang.String filter)
           throws InvalidSyntaxException
Constructs a FilterImpl object. This filter object may be used to match a ServiceReferenceImpl 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:
filter - the filter string.
Throws:
InvalidSyntaxException - If the filter parameter contains an invalid filter string that cannot be parsed.

FilterImpl

protected FilterImpl()
Method Detail

match

public boolean match(ServiceReference reference)
Filter using a service's properties. The Filter is executed using the referenced service's properties.

Specified by:
match in interface 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 dictionary)
Filter using a Dictionary. The Filter is executed using the Dictionary's keys.

Specified by:
match in interface Filter
Parameters:
dictionary - the dictionary whose keys are used in the match.
Returns:
true if the Dictionary's keys match this filter; false otherwise.

matchCase

public boolean matchCase(java.util.Dictionary dictionary)
Filter with case sensitivity using a Dictionary object. The Filter is executed using the Dictionary object's keys and values. The keys are case sensitivley matched with the filter.

Specified by:
matchCase in interface Filter
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.
Since:
1.3

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.

Specified by:
toString in interface Filter
Overrides:
toString in class java.lang.Object
Returns:
filter string.

equals

public boolean equals(java.lang.Object obj)
Compares this Filter object to another object.

Specified by:
equals in interface Filter
Overrides:
equals in class java.lang.Object
Parameters:
obj - the object to compare.
Returns:
If the other object is a Filter object, then returns this.toString().equals(obj.toString()), otherwise false.

hashCode

public int hashCode()
Returns the hashCode for this Filter object.

Specified by:
hashCode in interface Filter
Overrides:
hashCode in class java.lang.Object
Returns:
The hashCode of the filter string, i.e. this.toString().hashCode().

setFilter

protected void setFilter(int operation,
                         java.lang.String attr,
                         java.lang.Object value)

match

protected boolean match(ServiceReferenceImpl reference)
Filter using a service's properties. The Filter is executed using the referenced service's properties.

Parameters:
reference - A reference to the service whose properties are used in the match.
Returns:
If the service's properties match the filter, return true. Otherwise, return false.

match0

protected boolean match0(java.util.Dictionary properties)
Internal match routine. Dictionary parameter must support case-insensitive get.

Parameters:
properties - A dictionary whose keys are used in the match.
Returns:
If the Dictionary's keys match the filter, return true. Otherwise, return false.

encodeValue

protected static java.lang.String encodeValue(java.lang.String value)
Encode the value string such that '(', '*', ')' and '\' are escaped.

Parameters:
value - unencoded value string.
Returns:
encoded value string.

compare

protected boolean compare(int operation,
                          java.lang.Object value1,
                          java.lang.Object value2)

compare_Collection

protected boolean compare_Collection(int operation,
                                     java.util.Collection collection,
                                     java.lang.Object value2)

compare_ObjectArray

protected boolean compare_ObjectArray(int operation,
                                      java.lang.Object[] array,
                                      java.lang.Object value2)

compare_PrimitiveArray

protected boolean compare_PrimitiveArray(int operation,
                                         java.lang.Class type,
                                         java.lang.Object primarray,
                                         java.lang.Object value2)

compare_String

protected boolean compare_String(int operation,
                                 java.lang.String string,
                                 java.lang.Object value2)

compare_Integer

protected boolean compare_Integer(int operation,
                                  int intval,
                                  java.lang.Object value2)

compare_Long

protected boolean compare_Long(int operation,
                               long longval,
                               java.lang.Object value2)

compare_Byte

protected boolean compare_Byte(int operation,
                               byte byteval,
                               java.lang.Object value2)

compare_Short

protected boolean compare_Short(int operation,
                                short shortval,
                                java.lang.Object value2)

compare_Character

protected boolean compare_Character(int operation,
                                    char charval,
                                    java.lang.Object value2)

compare_Boolean

protected boolean compare_Boolean(int operation,
                                  boolean boolval,
                                  java.lang.Object value2)

compare_Float

protected boolean compare_Float(int operation,
                                float floatval,
                                java.lang.Object value2)

compare_Double

protected boolean compare_Double(int operation,
                                 double doubleval,
                                 java.lang.Object value2)

compare_Comparable

protected boolean compare_Comparable(int operation,
                                     java.lang.Comparable value1,
                                     java.lang.Object value2)

compare_Unknown

protected boolean compare_Unknown(int operation,
                                  java.lang.Object value1,
                                  java.lang.Object value2)

approxString

protected static java.lang.String approxString(java.lang.String input)
Map a string for an APPROX (~=) comparison. This implementation removes white spaces. This is the minimum implementation allowed by the OSGi spec.

Parameters:
input - Input string.
Returns:
String ready for APPROX comparison.

getRequiredObjectClass

public java.lang.String getRequiredObjectClass()
Returns the leftmost required objectClass value for the filter to evaluate to true.

Returns:
The leftmost required objectClass value or null if none could be determined.

getObjectClassFilterString

public static java.lang.String getObjectClassFilterString(java.lang.String objectClass)
Returns a objectClass filter string for the specified objectClass.

Returns:
A filter string for the specified objectClass or null if the specified objectClass is null.

getAttributes

public java.lang.String[] getAttributes()
Returns all the attributes contained within this filter

Returns:
all the attributes contained within this filter