2.11 - The FilterBuilder(e)

This class is a builder for constructing well formed search filters according to RFC 4515. This builder is most convenient when using static imports. For example:

 import static org.apache.directory.ldap.client.api.search.FilterBuilder.and;
 import static org.apache.directory.ldap.client.api.search.FilterBuilder.equal;
 import static org.apache.directory.ldap.client.api.search.FilterBuilder.or;
 
 ...
 
         String filter = 
                 or(
                     and( 
                         equal( "givenName", "kermit" ), 
                         equal( "sn", "the frog" ) ),
                     and( 
                         equal( "givenName", "miss" ), 
                         equal( "sn", "piggy" ) ) )
                 .toString()

And filter

Returns a new FilterBuilder that will combine all of the supplied filters with a logical AND (&). For example:

and( equal( "givenName", "kermit" ), equal( "sn", "the frog" ) ).toString()

would result in the string: (&(givenName=kermit)(sn=the frog))

Which would match all entries with a given name of kermit and a surname the frog.

Or filter

Returns a new FilterBuilder that will combine all of the supplied filters with a logical OR (|). For example:

or( equal( "givenName", "kermit" ), equal( "givenName", "walter" ) ).toString()

would result in the string: (|(givenName=kermit)(givenName=walter))

Which would match any entry with the givenName of either kermit or walter.

Not filter

Returns a new FilterBuilder for negating another filter (!). For example:

not( present( "givenName" ) ).toString();

would result in the string: _(!(givenName=*))_

Present Filter

Returns a new FilterBuilder for testing the presence of an attributes. For example:

present( "givenName" ).toString();

would result in the string: _(givenName=*)_

Which would match any entry that has a givenName attribute.

Equal Filter

Returns a new FilterBuilder for testing equality of an attribute. For example:

equal( "cn", "Kermit The Frog" ).toString();

would result in the string: (cn=Kermit The Frog)

Which would match entries with the common name Kermit The Frog. Be careful when using the equal filter as it is an EXACT MATCH filter. While it may seem natural to use * as a wildcard, it will actually be escaped using this filter. If you meant to use a wildcard in your filter, you should use one of startsWith, endsWith, contains, or substring, .

Extensible Filter

Returns a new FilterBuilder for testing equality using specified matching rules. For example:

extensible( "cn", "Kermit The Frog" ).toString();

would result in the string: (cn:=Kermit The Frog)

Which would match entries with the common name Kermit The Frog.

extensible( "cn", "Kermit The Frog" )
    .useDnAttributes()
    .toString();

would result in the string: (cn:dn:=Kermit The Frog)

Which would match entries with the common name Kermit The Frog even if the common name was only specified as part of the dn.

extensible( "cn", "Kermit The Frog" )
    .setMatchingRule( "caseExactMatch" )
    .toString();

would result in the string: (cn:caseExactMatch:=Kermit The Frog)

Which would match entries with the common name Kermit The Frog, using a case sensitive matcher.

extensible( "cn", "Kermit The Frog" )
    .useDnAttributes()
    .setMatchingRule( "caseExactMatch" )
    .toString();

would result in the string: (cn:dn:caseExactMatch:=Kermit The Frog)

Which would match entries with the common name Kermit The Frog, using a case sensitive matcher even if the name was only specified as part of the dn.

extensible( "Kermit The Frog" )
    .setMatchingRule( "1.2.3.4.5.6.7" )
    .toString();

would result in the string: (:1.2.3.4.5.6.7:=Kermit The Frog)

Which would match entries with any attribute whose value is Kermit The Frog, using the hypothetical matching rule indicated by the oid 1.2.3.4.5.6.7.

Less Or Equal Filter

Returns a new FilterBuilder for testing lexicographical less than. For example:

lessThanOrEqual( "sn", "mzzzzzz" ).toString();

would result in the string: (sn<=mzzzzzz)

which would match results whose surname starts with the first half of the alphabet. Note, this is not perfect, but if you know anybody with a last name that starts with an m followed by six z’s_…

Greater Or Equal Filter

Returns a new FilterBuilder for testing lexicographical greater than. For example:

greaterThanOrEqual( "sn", "n" ).toString();

would result in the string: (sn>=n)

which would match results whose surname starts with the second half of the alphabet.

Approximate Filter

Returns a new FilterBuilder for testing the approximate equality of an attribute. For example:

approximatelyEqual( "l", "san fransico" ).toString();

would result in the string: (l~=san fransico)

Which MIGHT match results whose locality is San Francisco. The matching rule used to apply this filter is dependent on the server implementation.

StartsWith Filter

Returns a new FilterBuilder that constructs a SubString filter with an initial part, zero or more any parts, but no final part. For example:

startsWith( "sn", "Th", "Soft", "Foun" )).toString()

would result in the string: (sn=Th*Soft*Foun*)

Which would match any entry with an sn starting with the string ‘Th’, followed by ‘Soft’, then ‘Foun’, like ‘The Apache Software Foundation’.

EndsWith Filter

Returns a new FilterBuilder that constructs a SubString filter with no initial part, zero or more any parts, and a final part. For instance:

endsWith( "sn", "Soft", "Foun", "ion" )).toString()

would result in the string: (sn=*Soft*Foun*ion)

Which would match any entry with an sn containing the string ‘Soft’ followed by ‘Foun’ ending in ‘ion’, like ‘The Apache Software Foundation’.

Contains Filter

Returns a new FilterBuilder that constructs a SubString filter with no initial part, zero or more any parts, and no final part. For instance:

contains( "sn", "Soft", "Foun" )).toString()

would result in the string: (sn=*Soft*Foun*)

Which would match any entry with an sn containing the string ‘Soft’ followed by ‘Foun’, like ‘The Apache Software Foundation’.

Substring Filter

Returns a new FilterBuilder that constructs a SubString filter with an initial part, zero or more any parts, and a final part. For instance:

substring( "sn", "The", "Soft", "Foun", "ion" )).toString()

would result in the string: (sn=The*Soft*Foun*ion)

Which would match any entry with an sn starting with ‘The’, followed by ‘Soft’, then ‘Foun’, and ending with ‘ion’, like ‘The Apache Software Foundation’.

Note that if only two strings are supplied for parts, they will be the initial and the final:

substring( "sn", "The", "ion" )).toString()

would result in the string: (sn=The*ion)