| Title: 2.11 - The FilterBuilder |
| NavPrev: 2.10-ldap-connection-template.html |
| NavPrevText: 2.10 - The LdapConnectionTemplate |
| NavUp: 2-basic-ldap-api-usage.html |
| NavUpText: 2 - Basic LDAP API usage |
| NavNext: 3-advanced-ldap-api-usage.html |
| NavNextText: 3 - Advanced LDAP API Usage |
| Notice: Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| . |
| http://www.apache.org/licenses/LICENSE-2.0 |
| . |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| |
| 2.11 - The FilterBuilder(e) |
| =========================== |
| |
| This class is a builder for constructing well formed search filters according to [RFC 4515](https://tools.ietf.org/html/rfc4515.html). 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](#startswith-filter), [endsWith](#endswith-filter), [contains](#contains-filter), or [substring](#substring-filter), . |
| |
| ## 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)_ |