com.novell.ldap.rfc2251
Class RfcFilter

java.lang.Object
  com.novell.ldap.asn1.ASN1Object
      com.novell.ldap.asn1.ASN1Choice
          com.novell.ldap.rfc2251.RfcFilter

All Implemented Interfaces:

java.io.Serializable

public class RfcFilter

extends ASN1Choice

Represents an LDAP Filter.

This filter object can be created from a String or can be built up programatically by adding filter components one at a time. Existing filter components can be iterated though.

Each filter component has an integer identifier defined in this class. The following are basic filter components: EQUALITY_MATCH, GREATER_OR_EQUAL, LESS_OR_EQUAL, SUBSTRINGS, PRESENT, APPROX_MATCH, EXTENSIBLE_MATCH.

More filters can be nested together into more complex filters with the following filter components: AND, OR, NOT

Substrings can have three components:

       Filter ::= CHOICE {
               and             [0] SET OF Filter,
               or              [1] SET OF Filter,
               not             [2] Filter,
               equalityMatch   [3] AttributeValueAssertion,
               substrings      [4] SubstringFilter,
               greaterOrEqual  [5] AttributeValueAssertion,
               lessOrEqual     [6] AttributeValueAssertion,
               present         [7] AttributeDescription,
               approxMatch     [8] AttributeValueAssertion,
               extensibleMatch [9] MatchingRuleAssertion }

See Also:

Serialized Form

Nested Class Summary

private class	RfcFilter.FilterIterator This inner class wrappers the Search Filter with an iterator.
(package private) class	RfcFilter.FilterTokenizer This inner class will tokenize the components of an RFC 2254 search filter.

Field Summary

static int	AND Identifier for AND component.
static int	ANY Identifier for ANY component.
static int	APPROX_MATCH Identifier for APPROX_MATCH component.
static int	EQUALITY_MATCH Identifier for EQUALITY_MATCH component.
static int	EXTENSIBLE_MATCH Identifier for EXTENSIBLE_MATCH component.
private java.util.Stack	filterStack
static int	FINAL Identifier for FINAL component.
private boolean	finalFound
private RfcFilter.FilterTokenizer	ft
static int	GREATER_OR_EQUAL Identifier for GREATER_OR_EQUAL component.
static int	INITIAL Identifier for INITIAL component.
static int	LESS_OR_EQUAL Identifier for LESS_OR_EQUAL component.
static int	NOT Identifier for NOT component.
static int	OR Identifier for OR component.
static int	PRESENT Identifier for PRESENT component.
static int	SUBSTRINGS Identifier for SUBSTRINGS component.

Fields inherited from class com.novell.ldap.asn1.ASN1Choice

Fields inherited from class com.novell.ldap.asn1.ASN1Object

Constructor Summary

RfcFilter()
Constructs a Filter object that will be built up piece by piece.

RfcFilter(java.lang.String filter)
Constructs a Filter object by parsing an RFC 2254 Search Filter String.

Method Summary

void	addAttributeValueAssertion(int rfcType, java.lang.String attrName, byte[] value) Creates and adds an AttributeValueAssertion to the filter.
void	addExtensibleMatch(java.lang.String matchingRule, java.lang.String attrName, byte[] value, boolean useDNMatching) Adds an extensible match to the filter.
private void	addObject(ASN1Object current) Called by sequential filter building methods to add to a filter component.
void	addPresent(java.lang.String attrName) Creates and adds a present matching to the filter.
void	addSubstring(int type, byte[] value) Adds a Substring component of initial, any or final substring matching.
private static java.lang.String	byteString(byte[] value) Convert a UTF8 encoded string, or binary data, into a String encoded for a string filter.
void	endNestedFilter(int rfcType) Completes a nested filter and checks for the valid filter type.
void	endSubstrings() Completes a SubString filter component.
java.lang.String	filterToString() Creates and returns a String representation of this filter.
java.util.Iterator	getFilterIterator() Creates an iterator over the preparsed segments of a filter.
(package private) static int	hex2int(char c) Convert hex character to an integer.
private ASN1Tagged	parse(java.lang.String filterExpr) Parses an RFC 2251 filter string into an ASN.1 LDAP Filter object.
private ASN1Tagged	parseFilter() Parses an RFC 2254 filter
private ASN1Tagged	parseFilterComp() RFC 2254 filter helper method.
private ASN1SetOf	parseFilterList() Must have 1 or more Filters
void	startNestedFilter(int rfcType) Creates and adds the ASN1Tagged value for a nestedFilter: AND, OR, or NOT.
void	startSubstrings(java.lang.String attrName) Creates and addes a substrings filter component.
private static void	stringFilter(java.util.Iterator itr, java.lang.StringBuffer filter) Uses a filterIterator to create a string representation of a filter.
private byte[]	unescapeString(java.lang.String string) Replace escaped hex digits with the equivalent binary representation.

Methods inherited from class com.novell.ldap.asn1.ASN1Choice

choiceValue, encode, getIdentifier, setChoiceValue, setIdentifier, toString

Methods inherited from class com.novell.ldap.asn1.ASN1Object

getEncoding

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

AND

public static final int AND

Identifier for AND component.

See Also:

Constant Field Values

OR

public static final int OR

Identifier for OR component.

See Also:

Constant Field Values

NOT

public static final int NOT

Identifier for NOT component.

See Also:

Constant Field Values

EQUALITY_MATCH

public static final int EQUALITY_MATCH

Identifier for EQUALITY_MATCH component.

See Also:

Constant Field Values

SUBSTRINGS

public static final int SUBSTRINGS

Identifier for SUBSTRINGS component.

See Also:

Constant Field Values

GREATER_OR_EQUAL

public static final int GREATER_OR_EQUAL

Identifier for GREATER_OR_EQUAL component.

See Also:

Constant Field Values

LESS_OR_EQUAL

public static final int LESS_OR_EQUAL

Identifier for LESS_OR_EQUAL component.

See Also:

Constant Field Values

PRESENT

public static final int PRESENT

Identifier for PRESENT component.

See Also:

Constant Field Values

APPROX_MATCH

public static final int APPROX_MATCH

Identifier for APPROX_MATCH component.

See Also:

Constant Field Values

EXTENSIBLE_MATCH

public static final int EXTENSIBLE_MATCH

Identifier for EXTENSIBLE_MATCH component.

See Also:

Constant Field Values

INITIAL

public static final int INITIAL

Identifier for INITIAL component.

See Also:

Constant Field Values

ANY

public static final int ANY

Identifier for ANY component.

See Also:

Constant Field Values

FINAL

public static final int FINAL

Identifier for FINAL component.

See Also:

Constant Field Values

ft

private RfcFilter.FilterTokenizer ft

filterStack

private java.util.Stack filterStack

finalFound

private boolean finalFound

Constructor Detail

RfcFilter

public RfcFilter(java.lang.String filter)
          throws LDAPException

Constructs a Filter object by parsing an RFC 2254 Search Filter String.

RfcFilter

public RfcFilter()

Constructs a Filter object that will be built up piece by piece.

Method Detail

parse

private final ASN1Tagged parse(java.lang.String filterExpr)
                        throws LDAPException

Parses an RFC 2251 filter string into an ASN.1 LDAP Filter object.

Throws:

LDAPException

parseFilter

private final ASN1Tagged parseFilter()
                              throws LDAPException

Parses an RFC 2254 filter

Throws:

LDAPException

parseFilterComp

private final ASN1Tagged parseFilterComp()
                                  throws LDAPException

RFC 2254 filter helper method. Will Parse a filter component.

Throws:

LDAPException

parseFilterList

private final ASN1SetOf parseFilterList()
                                 throws LDAPException

Must have 1 or more Filters

Throws:

LDAPException

hex2int

static final int hex2int(char c)

Convert hex character to an integer. Return -1 if char is something other than a hex char.

unescapeString

private final byte[] unescapeString(java.lang.String string)
                             throws LDAPException

Replace escaped hex digits with the equivalent binary representation. Assume either V2 or V3 escape mechanisms: V2: \*, \(, \), \\. V3: \2A, \28, \29, \5C, \00.

Parameters:

string - A part of the input filter string to be converted.

Returns:

octet-string encoding of the specified string.

Throws:

LDAPException

addObject

private void addObject(ASN1Object current)
                throws LDAPLocalException

Called by sequential filter building methods to add to a filter component.

Verifies that the specified ASN1Object can be added, then adds the object to the filter.

Parameters:

current - Filter component to be added to the filter

Throws:

LDAPLocalException - Occurs when an invalid component is added, or when the component is out of sequence.

startSubstrings

public void startSubstrings(java.lang.String attrName)
                     throws LDAPLocalException

Creates and addes a substrings filter component.

startSubstrings must be immediatly followed by at least one addSubstring(int, byte[]) method and one endSubstrings() method

Throws:

LDAPLocalException - Occurs when this component is created out of sequence.

addSubstring

public void addSubstring(int type,
                         byte[] value)
                  throws LDAPLocalException

Adds a Substring component of initial, any or final substring matching.

This method can be invoked only if startSubString was the last filter- building method called. A substring is not required to have an 'INITIAL' substring. However, when a filter contains an 'INITIAL' substring only one can be added, and it must be the first substring added. Any number of 'ANY' substrings can be added. A substring is not required to have a 'FINAL' substrings either. However, when a filter does contain a 'FINAL' substring only one can be added, and it must be the last substring added.

Parameters:

type - Substring type: INITIAL | ANY | FINAL]

value - Value to use for matching

Throws:

LDAPLocalException - Occurs if this method is called out of sequence or the type added is out of sequence.

endSubstrings

public void endSubstrings()
                   throws LDAPLocalException

Completes a SubString filter component.

Throws:

LDAPLocalException - Occurs when this is called out of sequence, or the substrings filter is empty.

addAttributeValueAssertion

public void addAttributeValueAssertion(int rfcType,
                                       java.lang.String attrName,
                                       byte[] value)
                                throws LDAPLocalException

Creates and adds an AttributeValueAssertion to the filter.

Parameters:

rfcType - Filter type: EQUALITY_MATCH | GREATER_OR_EQUAL | LESS_OR_EQUAL | APPROX_MATCH ]

attrName - Name of the attribute to be asserted

value - Value of the attribute to be asserted

Throws:

LDAPLocalException - Occurs when the filter type is not a valid attribute assertion.

addPresent

public void addPresent(java.lang.String attrName)
                throws LDAPLocalException

Creates and adds a present matching to the filter.

Parameters:

attrName - Name of the attribute to check for presence.

Throws:

LDAPLocalException - Occurs if addPresent is called out of sequence.

addExtensibleMatch

public void addExtensibleMatch(java.lang.String matchingRule,
                               java.lang.String attrName,
                               byte[] value,
                               boolean useDNMatching)
                        throws LDAPLocalException

Adds an extensible match to the filter.

Parameters:

matchingRule - OID or name of the matching rule to use for comparison

attrName - Name of the attribute to match.

value - Value of the attribute to match against.

useDNMatching - Indicates whether DN matching should be used.

Throws:

LDAPLocalException - Occurs when addExtensibleMatch is called out of sequence.

startNestedFilter

public void startNestedFilter(int rfcType)
                       throws LDAPLocalException

Creates and adds the ASN1Tagged value for a nestedFilter: AND, OR, or NOT.

Note that a Not nested filter can only have one filter, where AND and OR do not

Parameters:

rfcType - Filter type: [AND | OR | NOT]

Throws:

LDAPLocalException

endNestedFilter

public void endNestedFilter(int rfcType)
                     throws LDAPLocalException

Completes a nested filter and checks for the valid filter type.

Parameters:

rfcType - Type of filter to complete.

Throws:

LDAPLocalException - Occurs when the specified type differs from the current filter component.

getFilterIterator

public java.util.Iterator getFilterIterator()

Creates an iterator over the preparsed segments of a filter.

The first object returned by an iterator is an integer indicating the type of filter components. Subseqence values are returned. If a component is of type 'AND' or 'OR' or 'NOT' then the value returned is another iterator. This iterator is used by toString.

Returns:

Iterator over filter segments

filterToString

public java.lang.String filterToString()

Creates and returns a String representation of this filter.

stringFilter

private static void stringFilter(java.util.Iterator itr,
                                 java.lang.StringBuffer filter)

Uses a filterIterator to create a string representation of a filter.

Parameters:

itr - Iterator of filter components

filter - Buffer to place a string representation of the filter

See Also:

getFilterIterator()

byteString

private static java.lang.String byteString(byte[] value)

Convert a UTF8 encoded string, or binary data, into a String encoded for a string filter.