@NotMutable @ThreadSafety(level=COMPLETELY_THREADSAFE) public final class Filter extends java.lang.Object implements java.io.Serializable
create(String)
method, using the syntax described in RFC 4515.
For example:
Filter f1 = Filter.create("(objectClass=*)"); Filter f2 = Filter.create("(uid=john.doe)"); Filter f3 = Filter.create("(|(givenName=John)(givenName=Johnathan))");
Filter f1 = Filter.createPresenceFilter("objectClass"); Filter f2 = Filter.createEqualityFilter("uid", "john.doe"); Filter f3 = Filter.createORFilter( Filter.createEqualityFilter("givenName", "John"), Filter.createEqualityFilter("givenName", "Johnathan"));In general, it is recommended to avoid creating filters from their string representations if any of that string representation may include user-provided data or special characters including non-ASCII characters, parentheses, asterisks, or backslashes.
Modifier and Type | Field and Description |
---|---|
static byte |
FILTER_TYPE_AND
The BER type for AND search filters.
|
static byte |
FILTER_TYPE_APPROXIMATE_MATCH
The BER type for approximate match search filters.
|
static byte |
FILTER_TYPE_EQUALITY
The BER type for equality search filters.
|
static byte |
FILTER_TYPE_EXTENSIBLE_MATCH
The BER type for extensible match search filters.
|
static byte |
FILTER_TYPE_GREATER_OR_EQUAL
The BER type for greaterOrEqual search filters.
|
static byte |
FILTER_TYPE_LESS_OR_EQUAL
The BER type for lessOrEqual search filters.
|
static byte |
FILTER_TYPE_NOT
The BER type for NOT search filters.
|
static byte |
FILTER_TYPE_OR
The BER type for OR search filters.
|
static byte |
FILTER_TYPE_PRESENCE
The BER type for presence search filters.
|
static byte |
FILTER_TYPE_SUBSTRING
The BER type for substring search filters.
|
Modifier and Type | Method and Description |
---|---|
static Filter |
create(java.lang.String filterString)
Creates a new search filter from the provided string representation.
|
static Filter |
createANDFilter(java.util.Collection<Filter> andComponents)
Creates a new AND search filter with the provided components.
|
static Filter |
createANDFilter(Filter... andComponents)
Creates a new AND search filter with the provided components.
|
static Filter |
createANDFilter(java.util.List<Filter> andComponents)
Creates a new AND search filter with the provided components.
|
static Filter |
createApproximateMatchFilter(java.lang.String attributeName,
byte[] assertionValue)
Creates a new approximate match search filter with the provided
information.
|
static Filter |
createApproximateMatchFilter(java.lang.String attributeName,
java.lang.String assertionValue)
Creates a new approximate match search filter with the provided
information.
|
static Filter |
createEqualityFilter(java.lang.String attributeName,
byte[] assertionValue)
Creates a new equality search filter with the provided information.
|
static Filter |
createEqualityFilter(java.lang.String attributeName,
java.lang.String assertionValue)
Creates a new equality search filter with the provided information.
|
static Filter |
createExtensibleMatchFilter(java.lang.String attributeName,
java.lang.String matchingRuleID,
boolean dnAttributes,
byte[] assertionValue)
Creates a new extensible match search filter with the provided
information.
|
static Filter |
createExtensibleMatchFilter(java.lang.String attributeName,
java.lang.String matchingRuleID,
boolean dnAttributes,
java.lang.String assertionValue)
Creates a new extensible match search filter with the provided
information.
|
static Filter |
createGreaterOrEqualFilter(java.lang.String attributeName,
byte[] assertionValue)
Creates a new greater-or-equal search filter with the provided information.
|
static Filter |
createGreaterOrEqualFilter(java.lang.String attributeName,
java.lang.String assertionValue)
Creates a new greater-or-equal search filter with the provided information.
|
static Filter |
createLessOrEqualFilter(java.lang.String attributeName,
byte[] assertionValue)
Creates a new less-or-equal search filter with the provided information.
|
static Filter |
createLessOrEqualFilter(java.lang.String attributeName,
java.lang.String assertionValue)
Creates a new less-or-equal search filter with the provided information.
|
static Filter |
createNOTFilter(Filter notComponent)
Creates a new NOT search filter with the provided component.
|
static Filter |
createORFilter(java.util.Collection<Filter> orComponents)
Creates a new OR search filter with the provided components.
|
static Filter |
createORFilter(Filter... orComponents)
Creates a new OR search filter with the provided components.
|
static Filter |
createORFilter(java.util.List<Filter> orComponents)
Creates a new OR search filter with the provided components.
|
static Filter |
createPresenceFilter(java.lang.String attributeName)
Creates a new presence search filter with the provided information.
|
static Filter |
createSubstringFilter(java.lang.String attributeName,
byte[] subInitial,
byte[][] subAny,
byte[] subFinal)
Creates a new substring search filter with the provided information.
|
static Filter |
createSubstringFilter(java.lang.String attributeName,
java.lang.String subInitial,
java.lang.String[] subAny,
java.lang.String subFinal)
Creates a new substring search filter with the provided information.
|
static Filter |
decode(ASN1Element filterElement)
Decodes the provided ASN.1 element as a search filter.
|
ASN1Element |
encode()
Encodes this search filter to an ASN.1 element suitable for inclusion in an
LDAP search request protocol op.
|
static java.lang.String |
encodeValue(byte[] value)
Encodes the provided value into a form suitable for use as the assertion
value in the string representation of a search filter.
|
static java.lang.String |
encodeValue(java.lang.String value)
Encodes the provided value into a form suitable for use as the assertion
value in the string representation of a search filter.
|
boolean |
equals(java.lang.Object o)
Indicates whether the provided object is equal to this search filter.
|
java.lang.String |
getAssertionValue()
Retrieves the string representation of the assertion value for this search
filter.
|
byte[] |
getAssertionValueBytes()
Retrieves the binary representation of the assertion value for this search
filter.
|
java.lang.String |
getAttributeName()
Retrieves the name of the attribute type for this search filter.
|
Filter[] |
getComponents()
Retrieves the set of filter components used in this AND or OR filter.
|
boolean |
getDNAttributes()
Retrieves the dnAttributes flag for this extensible match filter.
|
byte |
getFilterType()
Retrieves the filter type for this filter.
|
java.lang.String |
getMatchingRuleID()
Retrieves the matching rule ID for this extensible match filter.
|
Filter |
getNOTComponent()
Retrieves the filter component used in this NOT filter.
|
ASN1OctetString |
getRawAssertionValue()
Retrieves the raw assertion value for this search filter as an ASN.1
octet string.
|
ASN1OctetString[] |
getRawSubAnyValues()
Retrieves the raw subAny values for this substring filter.
|
ASN1OctetString |
getRawSubFinalValue()
Retrieves the raw subFinal element for this filter as an ASN.1 octet
string.
|
ASN1OctetString |
getRawSubInitialValue()
Retrieves the raw subInitial element for this filter as an ASN.1 octet
string.
|
byte[][] |
getSubAnyBytes()
Retrieves the binary representations of the subAny elements for this
substring filter.
|
java.lang.String[] |
getSubAnyStrings()
Retrieves the string representations of the subAny elements for this
substring filter.
|
byte[] |
getSubFinalBytes()
Retrieves the binary representation of the subFinal element for this
substring filter.
|
java.lang.String |
getSubFinalString()
Retrieves the string representation of the subFinal element for this
substring filter.
|
byte[] |
getSubInitialBytes()
Retrieves the binary representation of the subInitial element for this
substring filter.
|
java.lang.String |
getSubInitialString()
Retrieves the string representation of the subInitial element for this
substring filter.
|
int |
hashCode()
Generates a hash code for this search filter.
|
boolean |
matchesEntry(Entry entry)
Indicates whether this filter matches the provided entry.
|
boolean |
matchesEntry(Entry entry,
Schema schema)
Indicates whether this filter matches the provided entry.
|
static Filter |
readFrom(ASN1StreamReader reader)
Reads and decodes a search filter from the provided ASN.1 stream reader.
|
static Filter |
simplifyFilter(Filter filter,
boolean reOrderElements)
Attempts to simplify the provided filter to allow it to be more efficiently
processed by the server.
|
void |
toCode(java.util.List<java.lang.String> lineList,
int indentSpaces,
java.lang.String firstLinePrefix,
java.lang.String lastLineSuffix)
Appends a number of lines comprising the Java source code that can be used
to recreate this filter to the given list.
|
java.lang.String |
toNormalizedString()
Retrieves a normalized string representation of this search filter.
|
void |
toNormalizedString(java.lang.StringBuilder buffer)
Appends a normalized string representation of this search filter to the
provided buffer.
|
java.lang.String |
toString()
Retrieves a string representation of this search filter.
|
void |
toString(java.lang.StringBuilder buffer)
Appends a string representation of this search filter to the provided
buffer.
|
void |
writeTo(ASN1Buffer buffer)
Writes an ASN.1-encoded representation of this filter to the provided ASN.1
buffer.
|
public static final byte FILTER_TYPE_AND
public static final byte FILTER_TYPE_OR
public static final byte FILTER_TYPE_NOT
public static final byte FILTER_TYPE_EQUALITY
public static final byte FILTER_TYPE_SUBSTRING
public static final byte FILTER_TYPE_GREATER_OR_EQUAL
public static final byte FILTER_TYPE_LESS_OR_EQUAL
public static final byte FILTER_TYPE_PRESENCE
public static final byte FILTER_TYPE_APPROXIMATE_MATCH
public static final byte FILTER_TYPE_EXTENSIBLE_MATCH
public static Filter createANDFilter(Filter... andComponents)
andComponents
- The set of filter components to include in the AND
filter. It must not be null
.public static Filter createANDFilter(java.util.List<Filter> andComponents)
andComponents
- The set of filter components to include in the AND
filter. It must not be null
.public static Filter createANDFilter(java.util.Collection<Filter> andComponents)
andComponents
- The set of filter components to include in the AND
filter. It must not be null
.public static Filter createORFilter(Filter... orComponents)
orComponents
- The set of filter components to include in the OR
filter. It must not be null
.public static Filter createORFilter(java.util.List<Filter> orComponents)
orComponents
- The set of filter components to include in the OR
filter. It must not be null
.public static Filter createORFilter(java.util.Collection<Filter> orComponents)
orComponents
- The set of filter components to include in the OR
filter. It must not be null
.public static Filter createNOTFilter(Filter notComponent)
notComponent
- The filter component to include in this NOT filter.
It must not be null
.public static Filter createEqualityFilter(java.lang.String attributeName, java.lang.String assertionValue)
attributeName
- The attribute name for this equality filter. It
must not be null
.assertionValue
- The assertion value for this equality filter. It
must not be null
.public static Filter createEqualityFilter(java.lang.String attributeName, byte[] assertionValue)
attributeName
- The attribute name for this equality filter. It
must not be null
.assertionValue
- The assertion value for this equality filter. It
must not be null
.public static Filter createSubstringFilter(java.lang.String attributeName, java.lang.String subInitial, java.lang.String[] subAny, java.lang.String subFinal)
null
.attributeName
- The attribute name for this substring filter. It
must not be null
.subInitial
- The subInitial component for this substring filter.subAny
- The set of subAny components for this substring
filter.subFinal
- The subFinal component for this substring filter.public static Filter createSubstringFilter(java.lang.String attributeName, byte[] subInitial, byte[][] subAny, byte[] subFinal)
null
.attributeName
- The attribute name for this substring filter. It
must not be null
.subInitial
- The subInitial component for this substring filter.subAny
- The set of subAny components for this substring
filter.subFinal
- The subFinal component for this substring filter.public static Filter createGreaterOrEqualFilter(java.lang.String attributeName, java.lang.String assertionValue)
attributeName
- The attribute name for this greater-or-equal
filter. It must not be null
.assertionValue
- The assertion value for this greater-or-equal
filter. It must not be null
.public static Filter createGreaterOrEqualFilter(java.lang.String attributeName, byte[] assertionValue)
attributeName
- The attribute name for this greater-or-equal
filter. It must not be null
.assertionValue
- The assertion value for this greater-or-equal
filter. It must not be null
.public static Filter createLessOrEqualFilter(java.lang.String attributeName, java.lang.String assertionValue)
attributeName
- The attribute name for this less-or-equal
filter. It must not be null
.assertionValue
- The assertion value for this less-or-equal
filter. It must not be null
.public static Filter createLessOrEqualFilter(java.lang.String attributeName, byte[] assertionValue)
attributeName
- The attribute name for this less-or-equal
filter. It must not be null
.assertionValue
- The assertion value for this less-or-equal
filter. It must not be null
.public static Filter createPresenceFilter(java.lang.String attributeName)
attributeName
- The attribute name for this presence filter. It
must not be null
.public static Filter createApproximateMatchFilter(java.lang.String attributeName, java.lang.String assertionValue)
attributeName
- The attribute name for this approximate match
filter. It must not be null
.assertionValue
- The assertion value for this approximate match
filter. It must not be null
.public static Filter createApproximateMatchFilter(java.lang.String attributeName, byte[] assertionValue)
attributeName
- The attribute name for this approximate match
filter. It must not be null
.assertionValue
- The assertion value for this approximate match
filter. It must not be null
.public static Filter createExtensibleMatchFilter(java.lang.String attributeName, java.lang.String matchingRuleID, boolean dnAttributes, java.lang.String assertionValue)
attributeName
- The attribute name for this extensible match
filter.matchingRuleID
- The matching rule ID for this extensible match
filter.dnAttributes
- Indicates whether the match should be performed
against attributes in the target entry's DN.assertionValue
- The assertion value for this extensible match
filter. It must not be null
.public static Filter createExtensibleMatchFilter(java.lang.String attributeName, java.lang.String matchingRuleID, boolean dnAttributes, byte[] assertionValue)
attributeName
- The attribute name for this extensible match
filter.matchingRuleID
- The matching rule ID for this extensible match
filter.dnAttributes
- Indicates whether the match should be performed
against attributes in the target entry's DN.assertionValue
- The assertion value for this extensible match
filter. It must not be null
.public static Filter create(java.lang.String filterString) throws LDAPException
filterString
- The string representation of the filter to create.
It must not be null
.LDAPException
- If the provided string cannot be decoded as a valid
LDAP search filter.public void writeTo(ASN1Buffer buffer)
buffer
- The ASN.1 buffer to which the encoded representation should
be written.public ASN1Element encode()
public static Filter readFrom(ASN1StreamReader reader) throws LDAPException
reader
- The ASN.1 stream reader from which to read the filter.LDAPException
- If an error occurs while reading or parsing the
search filter.public static Filter decode(ASN1Element filterElement) throws LDAPException
filterElement
- The ASN.1 element containing the encoded search
filter.LDAPException
- If the provided ASN.1 element cannot be decoded as
a search filter.public byte getFilterType()
public Filter[] getComponents()
public Filter getNOTComponent()
null
if
this is some other type of filter.public java.lang.String getAttributeName()
null
if it is not applicable for this type of filter.public java.lang.String getAssertionValue()
null
if it is not applicable for this type of
filter.public byte[] getAssertionValueBytes()
null
if it is not applicable for this type of
filter.public ASN1OctetString getRawAssertionValue()
null
if it is not applicable for this type of
filter.public java.lang.String getSubInitialString()
null
if this is some other type of
filter, or if it is a substring filter with no subInitial element.public byte[] getSubInitialBytes()
null
if this is some other type of
filter, or if it is a substring filter with no subInitial element.public ASN1OctetString getRawSubInitialValue()
null
if this is not a substring filter, or if
it is a substring filter with no subInitial element.public java.lang.String[] getSubAnyStrings()
public byte[][] getSubAnyBytes()
public ASN1OctetString[] getRawSubAnyValues()
public java.lang.String getSubFinalString()
null
if this is some other type of
filter, or if it is a substring filter with no subFinal element.public byte[] getSubFinalBytes()
null
if this is some other type of
filter, or if it is a substring filter with no subFinal element.public ASN1OctetString getRawSubFinalValue()
null
if this is not a substring filter, or if
it is a substring filter with no subFinal element.public java.lang.String getMatchingRuleID()
null
if this is some other type of filter, or if this
extensible match filter does not have a matching rule ID.public boolean getDNAttributes()
public boolean matchesEntry(Entry entry) throws LDAPException
entry
- The entry for which to make the determination. It must not
be null
.true
if this filter appears to match the provided entry,
or false
if not.LDAPException
- If a problem occurs while trying to make the
determination.public boolean matchesEntry(Entry entry, Schema schema) throws LDAPException
entry
- The entry for which to make the determination. It must not
be null
.schema
- The schema to use when making the determination. If this
is null
, then all matching will be performed using
a case-ignore matching rule.true
if this filter appears to match the provided entry,
or false
if not.LDAPException
- If a problem occurs while trying to make the
determination.public static Filter simplifyFilter(Filter filter, boolean reOrderElements)
reOrderElements
is true, then this method will attempt to
re-order the elements inside AND and OR filters in an attempt to
ensure that the components which are likely to be the most efficient
come earlier than those which are likely to be the least efficient.
This can speed up processing in servers that process filter
components in a left-to-right order.filter
- The filter to attempt to simplify.reOrderElements
- Indicates whether this method may re-order the
elements in the filter so that, in a server that
evaluates the components in a left-to-right order,
the components which are likely to be more
efficient to process will be listed before those
which are likely to be less efficient.public int hashCode()
hashCode
in class java.lang.Object
public boolean equals(java.lang.Object o)
equals
in class java.lang.Object
o
- The object for which to make the determination.true
if the provided object can be considered equal to
this search filter, or false
if not.public java.lang.String toString()
toString
in class java.lang.Object
public void toString(java.lang.StringBuilder buffer)
buffer
- The buffer to which to append a string representation of
this search filter.public java.lang.String toNormalizedString()
public void toNormalizedString(java.lang.StringBuilder buffer)
buffer
- The buffer to which to append a normalized string
representation of this search filter.public static java.lang.String encodeValue(java.lang.String value)
value
- The value to be encoded. It must not be null
.public static java.lang.String encodeValue(byte[] value)
value
- The value to be encoded. It must not be null
.public void toCode(java.util.List<java.lang.String> lineList, int indentSpaces, java.lang.String firstLinePrefix, java.lang.String lastLineSuffix)
lineList
- The list to which the source code lines should be
added.indentSpaces
- The number of spaces that should be used to indent
the generated code. It must not be negative.firstLinePrefix
- An optional string that should precede the static
method call (e.g., it could be used for an
attribute assignment, like "Filter f = "). It may
be null
or empty if there should be no
first line prefix.lastLineSuffix
- An optional suffix that should follow the closing
parenthesis of the static method call (e.g., it
could be a semicolon to represent the end of a
Java statement). It may be null
or empty
if there should be no last line suffix.