<!--

Copyright 2000-2007 Sun Microsystems, Inc. All Rights Reserved.
Portions copyright 1999 Netscape Communications Corporation. All
Rights Reserved.

The contents of this document are subject to the terms of the
Creative Commons Attribution-ShareAlike 2.5 license or any later
version (the "License"). You may not use this document except in
compliance with the License.

See the License for the specific language governing
permissions and limitations under the License. You can obtain
a copy of the License at
http://creativecommons.org/licenses/by-sa/2.5/legalcode.

-->
<chapter id="filter-conf"><title>Using Filter Configuration Files</title>
<highlights>
<para>This chapter explains how to use API function to work with filter configuration
files. Filter configuration files can help simplify the process of selecting the appropriate
search filter for a search request. The chapter contains the following sections:</para>
<itemizedlist>
<listitem><para><olink targetptr="understanding-filter-conf">Understanding Filter
Configuration Files</olink></para></listitem>
<listitem><para><olink targetptr="understanding-filter-conf-syntax">Understanding
the Configuration File Syntax</olink></para></listitem>
<listitem><para><olink targetptr="understanding-filter-parameters">Understanding Filter
Parameters</olink></para></listitem>
<listitem><para><olink targetptr="loading-filter-conf">Loading Filter Configuration
Files</olink></para></listitem>
<listitem><para><olink targetptr="retrieving-filters">Retrieving Filters</olink></para>
</listitem>
<listitem><para><olink targetptr="filter-conf-affixes">Adding Filter Prefixes and
Suffixes</olink></para></listitem>
</itemizedlist>
</highlights>
<sect1 id="understanding-filter-conf"><title>Understanding Filter Configuration Files
</title>
<para>Suppose that you are writing a client that allows users to search the directory.
You might want to use different search filters tailored for specific types of search
criteria. For example, suppose the user wants to search for this:</para>
<literallayout><literal>bjensen@example.com</literal></literallayout>
<para>You might want to use this search filter:</para>
<literallayout><literal>(mail=bjensen@example.com)</literal></literallayout>
<para>Similarly, suppose the search term entered by the user contains numbers, like
this:</para>
<literallayout><literal>555-1212</literal></literallayout>
<para>In this case, you might want to use this search filter:</para>
<literallayout><literal>(telephoneNumber=555-1212)</literal></literallayout>
<para>Rather than write code to construct the search filter explicitly, you can generate
filters using a <firstterm>filter configuration file</firstterm>. A filter configuration
file specifies a list of filters that you can load and use in your searches.</para>
</sect1>
<sect1 id="understanding-filter-conf-syntax"><title>Understanding the Configuration
File Syntax</title>
<indexterm><primary>filter configuration files</primary><secondary>syntax</secondary>
</indexterm>
<para>A filter configuration file has the following format:</para>
<literallayout width="100"><replaceable>tag</replaceable>
    <replaceable>pattern1</replaceable>    <replaceable>delimiters</replaceable>    <replaceable>
filter1-1</replaceable>    <replaceable>desc1-1</replaceable>    [<replaceable>scope1
</replaceable>]
                              <replaceable>filter1-2</replaceable>    <replaceable>
desc1-2</replaceable>    [<replaceable>scope2</replaceable>]

    <replaceable>pattern2</replaceable>    <replaceable>delimiters</replaceable>    <replaceable>
filter2-1</replaceable>    <replaceable>desc2-1</replaceable>    [<replaceable>scope3
</replaceable>]
    &hellip;</literallayout>
<para>Each element in the file is a string, surrounded by quotes (<literal>"</literal>).
Comments consist of lines starting with <literal>#</literal>.</para>
<para>The format supports these elements:</para>
<variablelist>
<varlistentry><term><replaceable>tag</replaceable></term>
<listitem><para>Identifies a group of filters.</para>
<para>You can use different tags to distinguish filters for different types of objects.
For example, you can use a <literal>"person"</literal> tag to identify filters for
person entries, a <literal>"organization"</literal> tag to represent filters for organization
entries, and so forth.</para>
<para>You can specify multiple tags for the same group of filters in the configuration
file using the keyword <literal>and</literal>, such as <literal>"people and organization"
</literal>.</para>
<para>You can specify a tag, or part of a tag, as a parameter. The tag narrows the
list of filters that the function retrieves.</para>
</listitem>
</varlistentry>
<varlistentry><term><replaceable>pattern</replaceable></term>
<listitem><para>Specifies a regular expression used to determine which filter is selected
based on the search criteria.</para>
<para>For example, if you specify <literal>^[0-9]</literal> as the pattern for a filter,
the filter is selected for all search criteria beginning with a number.</para>
</listitem>
</varlistentry>
<varlistentry><term><replaceable>delimiters</replaceable></term>
<listitem><para>Specify what characters separate one field from another within search
criteria.</para>
<para>For example, if the search criteria consists of a city name and state abbreviation
separated by a comma, specify <literal>","</literal> as the delimiter.</para>
</listitem>
</varlistentry>
<varlistentry><term><replaceable>filter</replaceable></term>
<listitem><para>Specifies an LDAP filter including <literal>%v</literal> to represent
the search criteria.</para>
<para>For example, to search email addresses, use the filter <literal>(mail=%v)</literal>.
During runtime, if the search criteria <literal>bjensen@example.com</literal> is entered,
the filter becomes <literal>(mail=bjensen@example.com)</literal>.</para>
<para>If the search criteria consists of a number of delimited fields such as a <replaceable>
surname</replaceable><literal>,</literal> <replaceable>first name</replaceable> format
like <literal>Jensen, Barbara</literal>, use <literal>%v1</literal>, <literal>%v2
</literal>, &hellip;, <literal>%vn</literal> to represent the fields within the search
criteria. For example:</para>
<literallayout><literal>"people"
    "^[A-Z]*,"    ","    "(&amp;(sn=%v1)(givenName=%v2))"</literal></literallayout>
<para>In the example, the delimiter is a comma. The word before the delimiter replaces <literal>
%v1</literal> in the filter, and the word after the delimiter replaces<literal>%v1
</literal>. A search for:</para>
<literallayout><literal>Jensen, Barbara</literal></literallayout><para>results in
a filter:</para>
<literallayout><literal>(&amp;(sn=Jensen)(givenName=Barbara))</literal></literallayout>
<para>You can also specify ranges of fields. For example, to specify the values in
the first three fields, use <literal>%v1-3</literal>. To specify values from the third
field to the last field, use <literal>%v3-</literal>. To specify the value in the
last field, use <literal>%v$</literal>.</para>
</listitem>
</varlistentry>
<varlistentry><term><replaceable>desc</replaceable></term>
<listitem><para>Specify short text descriptions of the filters.</para>
</listitem>
</varlistentry>
<varlistentry><term><replaceable>scope</replaceable></term>
<listitem><para>Specify the scope of each search.</para>
<para>This field is optional. It can take the values <literal>"base"</literal>, <literal>
"onelevel"</literal>, or <literal>"subtree"</literal>.</para>
</listitem>
</varlistentry>
</variablelist>
<para>For example, the following section of a filter configuration file specifies
a filter for telephone numbers and two filters for email addresses. The telephone
number filter is used if the search criteria contains one or more numbers. The email
filters are used if the search criteria contains an at sign (<literal>@</literal>).
</para>
<programlisting role="fragment">"people"
    "^[0-9][0-9-]*$"    " "    "(telephoneNumber=*%v)"    "phone number ends with"
    "@"                 " "    "(mail=%v)"                "email address is"
                               "(mail=%v*)"               "email address starts with"
</programlisting>
<para>Specify the filters in the order that you want them to be used. For example,
if you want to apply the <literal>(mail=%v)</literal> filter before the <literal>
(mail=%v*)</literal> filter, make sure that the filters appear in that order.</para>
</sect1>
<sect1 id="understanding-filter-parameters"><title>Understanding Filter Parameters
</title>
<para>Configuration file filter specifications support the following parameters:</para>
<variablelist>
<varlistentry><term><literal>%v</literal></term>
<listitem><para>Insert the search criterion verbatim in place of <literal>%v</literal>.
</para>
<para>For example, if the filter specification is <literal>(mail=%v)</literal>, entering <literal>
bjensen</literal> results in the filter <literal>(mail=bjensen)</literal>.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>%v$</literal></term>
<listitem><para>Insert the last word of search criterion verbatim in place of <literal>
%v</literal>.</para>
<para>For example, if the filter specification is <literal>(sn=%v$)</literal>, entering <literal>
Barbara Jensen</literal> results in the filter <literal>(sn=Jensen)</literal>.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>%v</literal><replaceable>N</replaceable></term>
<listitem><para>Insert the <replaceable>N</replaceable>th word of the criteria in
place of <literal>%v</literal>, where <replaceable>N</replaceable> is a single digit
between 1 and 9.</para>
<para>For example, if the filter specification is <literal>(sn=%v2)</literal>, entering <literal>
Barbara Jensen</literal> results in the filter <literal>(sn=Jensen)</literal>.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>%v</literal><replaceable>M</replaceable><literal>-</literal><replaceable>
N</replaceable></term>
<listitem><para>Insert the sequence of the <replaceable>M</replaceable>th through <replaceable>
N</replaceable>th words of the criteria in place of <literal>%v</literal>, where <replaceable>
M</replaceable> and <replaceable>N</replaceable> are single digits between 1 and 9.
</para>
<para>For example, if the filter specification is <literal>(cn=%v1-2)</literal>, entering <literal>
Barbara Jensen</literal> results in the filter <literal>(cn=Barbara Jensen)</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>%v</literal><replaceable>N</replaceable><literal>-</literal></term>
<listitem><para>Insert the sequence of th e<replaceable>N</replaceable>th through
last words of the criteria in place of <literal>%v</literal>, where <replaceable>
N</replaceable> is a single digit between 1 and 9.</para>
<para>For example, if the filter specification is <literal>(cn=%v2-)</literal>, entering <literal>
Ms. Barbara Jensen</literal> results in the filter <literal>(cn=Barbara Jensen)</literal>.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect1>
<sect1 id="loading-filter-conf"><title>Loading Filter Configuration Files</title>
<indexterm><primary>filter configuration files</primary><secondary>loading</secondary>
</indexterm>
<indexterm><primary>loading filter configuration files</primary></indexterm>
<para>To use a filter configuration file, you need to create an <classname>LDAPFilterDescriptor
</classname> object. The <literal>LDAPFilterDescriptor</literal> constructor allows
you to read in the filter configuration file from one of the following:</para>
<itemizedlist>
<listitem><para>A file in the local file system to which you specify the path</para>
</listitem>
<listitem><para>A file served by a web server to which you specify the URL</para>
</listitem>
<listitem><para>A location in memory where you specify a <classname>StringBuffer</classname> object
containing the configuration information</para></listitem>
</itemizedlist>
<para>The following section of code reads in a filter configuration file named <filename>
ldapfilter.conf</filename> in the current directory.</para>
<programlisting>import netscape.ldap.util.*;
&hellip;

LDAPFilterDescriptor filtdesc = null;
try {
    /* Read in the filter configuration file. */
    filtdesc = new LDAPFilterDescriptor("ldapfilter.conf");
} catch ( Exception e ) {
    System.out.println( "Error: " + e.toString() );
}</programlisting>
</sect1>
<sect1 id="retrieving-filters"><title>Retrieving Filters</title>
<para>After loading a filter configuration file into memory, you can retrieve filters
based on the search criteria. For example, if the search criteria is an email address
such as <literal>bjensen@example.com</literal>, you can have your client automatically
search for this value in the <literal>mail</literal> attribute.</para>
<task id="retrieving-filters-task"><title>Retrieving Filters Using A Filter Configuration
File</title>
<procedure>
<step><para>Invoke the <literal>LDAPFilterDescriptor</literal> constructor to read
in the filter configuration file.</para></step>
<step><para>Invoke the <literal>getFilters</literal> method of the <classname>LDAPFilterDescriptor
</classname> object.</para><para>Specify the tag of the section that you want to use
in the filter configuration file.</para><para>You do not need to invoke the <literal>
setupFilter</literal> of the <classname>LDAPFilter</classname> object to generate
the filter. The <literal>getFilters</literal> method of the <classname>LDAPFilterDescriptor
</classname> object does this already. You just need to invoke the <literal>getFilter
</literal> method of the <classname>LDAPFilter</classname> object to get the generated
filter.</para><para>This method returns an <classname>LDAPFilterList</classname> object,
which is an enumeration of <classname>LDAPFilter</classname> objects containing the
filters for the specified search term.</para></step>
<step><para>Invoke the <literal>next</literal> method of the <classname>LDAPFilterList
</classname> object to iterate through the <classname>LDAPFilter</classname> objects.
</para></step>
<step><para>For each <classname>LDAPFilter</classname> object, get the filter by invoking
the <literal>getFilter</literal> method, passing no arguments.</para><para>To get
the total number of filter configuration lines that match the specified search term,
invoke the <literal>numFilters</literal> method of the <classname>LDAPFilterList</classname> object.
This number decrements each time you invoke the next or <literal>nextElement</literal> method.
</para></step>
</procedure>
<example id="retrieving-filters-example">
<title>Retrieving Telephone Number and Mail Filters</title>
<para>This example uses a filter configuration file, <filename>ldapfilter.conf</filename>,
with the following specifications:</para>
<programlisting role="fragment">"people"
    "^[0-9][0-9-]*$"    " "    "(telephoneNumber=*%v)"    "phone number ends with"
    "@"                 " "    "(mail=%v)"                "email address is"
                               "(mail=%v*)"               "email address starts with"</programlisting>
<para>The following code retrieves, generates, and prints filters matching the criteria:
</para>
<programlisting>String searchTerm = "bjensen@example.com";
LDAPFilterDescriptor filtdesc = null;
try {
    /* Read in the filter configuration file. */
    filtdesc = new LDAPFilterDescriptor("ldapfilt.conf");

    /* Get filters from the section "people" */
    LDAPFilterList filtlist = null;
    try {
        filtlist = filtdesc.getFilters("people", searchTerm);
    } catch ( Exception e ) {
        System.out.println("No matching tag section or filter");
        System.exit(0);
    }

    int totalFilters = filtlist.numFilters();
    System.out.println("Found " + totalFilters + " applicable filters.\n");

    /* Iterate through the lines in the list. */
    while ( filtlist.hasMoreElements() ) {
        LDAPFilter filtline = filtlist.next();
        System.out.println("Filter #" +
            (totalFilters - filtlist.numFilters()));

        /* Get and print information about the selected line
            of filter configuration information. */
        System.out.println("  Description: " + filtline.getDescription());
        System.out.println("  Line #: " + filtline.getLineNumber());
        System.out.println("  Matches pattern: " +
            filtline.getMatchPattern());
        System.out.println("  Filter template: " +
            filtline.getFilterTemplate());
        System.out.println("  Delimiter: " + filtline.getDelimeter());
        System.out.println("  Scope: " + filtline.getScope());

        /* Get the generated filter. */
        String filterString = filtline.getFilter();
        System.out.println("  Generated filter string: " +
            filterString + "\n");
    }
} catch ( Exception e ) {
    System.out.println("Error: " + e.toString());
}</programlisting>
<para>When built into a program, compiled, and run, this code produces the following
output:</para>
<screen>Found 2 applicable filters.

Filter #1
  Description: email address is
  Line #: 3
  Matches pattern: @
  Filter template: (mail=%v)
  Delimiter: 
  Scope: subtree
  Generated filter string: (mail=bjensen@example.com)

Filter #2
  Description: email address starts with
  Line #: 4
  Matches pattern: @
  Filter template: (mail=%v*)
  Delimiter: 
  Scope: subtree
  Generated filter string: (mail=bjensen@example.com*)</screen>
</example>
</task>
</sect1>
<sect1 id="filter-conf-affixes"><title>Adding Filter Prefixes and Suffixes</title>
<para>If you need to apply a filter to all searches, you can add a filter prefix and
suffix to all filters rather than adding the criteria to all filters. For example,
if your client searches only for person entries, you can add the following filter
prefix to restrict the search:</para>
<literallayout><literal>(&amp;(l=Sunnyvale)</literal></literallayout>
<para>The filter prefix now requires the following suffix to balance the number of
parentheses:</para>
<literallayout><literal>)</literal></literallayout>
<para>For example, given the following filter:</para>
<literallayout><literal>(sn=Jensen)</literal></literallayout>
<para>You can use the filter prefix <literal>(&amp;(l=Sunnyvale</literal> and the
filter suffix <literal>)</literal> to narrow down the search to only the entries matching <literal>
l=Sunnyvale</literal>:</para>
<literallayout><literal>(&amp;(l=Sunnyvale)(sn=Jensen))</literal></literallayout>
<para>You can set up the filter prefix and suffix in several ways:</para>
<itemizedlist>
<listitem><para>To set these for all filters generated from the filter configuration
file, invoke the <literal>setFilterAffixes</literal> method of the <classname>LDAPFilterDescriptor
</classname> object.</para></listitem>
<listitem><para>To set the prefix or suffix for a specific filter, do one of the following:
</para>
<itemizedlist>
<listitem><para>Invoke the <literal>setFilterAffixes</literal> method of the <classname>
LDAPFilter</classname> object, then invoke the <literal>getFilter</literal> method,
passing in the search term again. This builds the filter again, using the specified
search term with the prefix and suffix.</para></listitem>
<listitem><para>Invoke the <literal>getFilter</literal> method, passing in the search
term, the prefix, and the suffix.</para></listitem>
<listitem><para>Invoke the <literal>setupFilter</literal> method, passing the search
term, the prefix, and the suffix.</para></listitem>
</itemizedlist>
<para>Setting the prefix and suffix for an individual filter overrides any prefix
or suffix set for the entire filter configuration file.</para></listitem>
</itemizedlist>
<sect2 id="affixes-all-filters"><title>Adding Affixes for All Filters</title>
<para>The following code loads a filter configuration file <filename>ldapfilter.conf
</filename> into memory, and adds the prefix <literal>(&amp;(l=Sunnyvale</literal> and
suffix <literal>)</literal> to each filter retrieved from the file:</para>
<programlisting>LDAPFilterDescriptor filtdesc = null;
try {
    /* Read in the filter configuration file. */
    filtdesc = new LDAPFilterDescriptor("ldapfilter.conf");

    /* Add the specified prefix and suffix to all filters. */
    String prefix = "(&amp;(l=Sunnyvale)";
    String suffix = ")";
    <emphasis>filtdesc.setFilterAffixes(prefix, suffix);</emphasis>

    /* Get filters from the section "people" */
    LDAPFilterList filtlist = null;
    try {
        filtlist = filtdesc.getFilters("people", searchTerm);
    } catch (Exception e) {
        System.out.println("No matching tag section or filter");
        System.exit(0);
    }

    /* Iterate through the lines in the list. */
    while (filtlist.hasMoreElements()) {
        LDAPFilter filtline = filtlist.next();

        /* Get and print each filter. */
        String filterString = filtline.getFilter();
        System.out.println("  Generated filter string: " +
            filterString + "\n");
    }
} catch (Exception e) {
    System.out.println("Error: " + e.toString());
}</programlisting>
<para>For example, if the following search term is passed to the <literal>LDAPFilterDescriptor.getFilters
</literal> method:</para>
<literallayout><literal>bjensen@example.com</literal></literallayout>
<para>and the corresponding filter, not including the prefix or suffix, is:</para>
<literallayout><literal>(mail=bjensen@example.com)</literal></literallayout>
<para>the entire filter string retrieved by the <literal>LDAPFilter.getFilter</literal> method
is:</para>
<literallayout><literal>(&amp;(l=Sunnyvale)(mail=bjensen@example.com))</literal></literallayout>
</sect2>
<sect2 id="affixes-setFilterAffixes"><title>Adding Affixes Using <literal>setFilterAffixes
</literal></title>
<para>The following code loads a filter configuration file <filename>ldapfilter.conf
</filename> into memory, and uses the <literal>LDAPFilter.setFilterAffixes</literal> method
to add the prefix <literal>(&amp;(l=Sunnyvale</literal> and suffix <literal>)</literal> to
a generated filter:</para>
<programlisting>LDAPFilterDescriptor filtdesc = null;
try {
    /* Read in the filter configuration file. */
    filtdesc = new LDAPFilterDescriptor("ldapfilter.conf");

    /* Get filters from the section "people" */
    LDAPFilterList filtlist = null;
    try {
        filtlist = filtdesc.getFilters("people", searchTerm);
    } catch (Exception e) {
        System.out.println("No matching tag section or filter");
        System.exit(0);
    }

    /* Iterate through the lines in the list. */
    while (filtlist.hasMoreElements()) {
        LDAPFilter filtline = filtlist.next();

        /* Add the prefix and suffix, and generate the filter. */
        String prefix = "(&amp;(l=Sunnyvale)";
        String suffix = ")";
        <emphasis>filtline.setFilterAffixes(prefix, suffix);</emphasis>
        String filterString = filtline.getFilter(searchTerm);
        System.out.println("  Generated filter string: " +
            filterString + "\n");
    }
} catch ( Exception e ) {
    System.out.println( "Error: " + e.toString() );
}</programlisting>
<para>For example, if the following search term is passed to the <literal>LDAPFilterDescriptor.getFilters
</literal> method:</para>
<literallayout><literal>bjensen@example.com</literal></literallayout>
<para>and the corresponding filter, not including the prefix or suffix, is:</para>
<literallayout><literal>(mail=bjensen@example.com)</literal></literallayout>
<para>the entire filter string retrieved by the <literal>LDAPFilter.getFilter</literal> method
is:</para>
<literallayout><literal>(&amp;(l=Sunnyvale)(mail=bjensen@example.com))</literal></literallayout>
</sect2>
<sect2 id="affixes-getFilter"><title>Adding Affixes Using <literal>getFilter</literal></title>
<para>The following code loads a filter configuration file <filename>ldapfilter.conf
</filename> into memory, and uses the <literal>LDAPFilter.getFilter</literal> method
to add the prefix <literal>(&amp;(l=Sunnyvale</literal> and suffix <literal>)</literal> to
a generated filter:</para>
<programlisting>LDAPFilterDescriptor filtdesc = null;
try {
    /* Read in the filter configuration file. */
    filtdesc = new LDAPFilterDescriptor("ldapfilter.conf");

    /* Get filters from the section "people" */
    LDAPFilterList filtlist = null;
    try {
        filtlist = filtdesc.getFilters("people", searchTerm);
    } catch (Exception e) {
        System.out.println("No matching tag section or filter");
        System.exit(0);
    }

    /* Iterate through the lines in the list. */
    while (filtlist.hasMoreElements()) {
        LDAPFilter filtline = filtlist.next();

        /* Add the prefix and suffix, and generate the filter. */
        String prefix = "(&amp;(l=Sunnyvale)";
        String suffix = ")";
        <emphasis>String filterString =
            filtline.getFilter(searchTerm, prefix, suffix);</emphasis>
        System.out.println("  Generated filter string: " +
            filterString + "\n");
    }
} catch ( Exception e ) {
    System.out.println( "Error: " + e.toString() );
}</programlisting>
<para>For example, if the following search term is passed to the <literal>LDAPFilterDescriptor.getFilters
</literal> method:</para>
<literallayout><literal>bjensen@example.com</literal></literallayout>
<para>and the corresponding filter, not including the prefix or suffix, is:</para>
<literallayout><literal>(mail=bjensen@example.com)</literal></literallayout>
<para>the entire filter string retrieved by the <literal>LDAPFilter.getFilter</literal> method
is:</para>
<literallayout><literal>(&amp;(l=Sunnyvale)(mail=bjensen@example.com))</literal></literallayout>
</sect2>
<sect2 id="affixes-setupFilter"><title>Adding Affixes Using <literal>setupFilter</literal></title>
<para>The following code loads a filter configuration file <filename>ldapfilter.conf
</filename> into memory, and uses the <literal>LDAPFilter.setupFilter</literal> method
to add the prefix <literal>(&amp;(l=Sunnyvale</literal> and suffix <literal>)</literal> to
a generated filter:</para>
<programlisting>LDAPFilterDescriptor filtdesc = null;
try {
    /* Read in the filter configuration file. */
    filtdesc = new LDAPFilterDescriptor("ldapfilter.conf");

    /* Get filters from the section "people" */
    LDAPFilterList filtlist = null;
    try {
        filtlist = filtdesc.getFilters("people", searchTerm);
    } catch (Exception e) {
        System.out.println("No matching tag section or filter");
        System.exit(0);
    }

    /* Iterate through the lines in the list. */
    while (filtlist.hasMoreElements()) {
        LDAPFilter filtline = filtlist.next();

        /* Add the prefix and suffix, and generate the filter. */
        String prefix = "(&amp;(l=Sunnyvale)";
        String suffix = ")";
        <emphasis>filtline.setupFilter(searchTerm, prefix, suffix);</emphasis>
        String filterString = filtline.getFilter();
        System.out.println("  Generated filter string: "
            + filterString + "\n");
    }
} catch ( Exception e ) {
    System.out.println( "Error: " + e.toString() );
}</programlisting>
<para>For example, if the following search term is passed to the <literal>LDAPFilterDescriptor.getFilters
</literal> method:</para>
<literallayout><literal>bjensen@example.com</literal></literallayout>
<para>and the corresponding filter, not including the prefix or suffix, is:</para>
<literallayout><literal>(mail=bjensen@example.com)</literal></literallayout>
<para>the entire filter string retrieved by the <literal>LDAPFilter.getFilter</literal> method
is:</para>
<literallayout><literal>(&amp;(l=Sunnyvale)(mail=bjensen@example.com))</literal></literallayout>
</sect2>
</sect1>
</chapter>
