Chapter 7 Using Filter Configuration Files

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.

• "Understanding Filter Configuration Files"
• "Understanding the Configuration File Syntax"
• "Understanding Filter Parameters"
• "Loading a Filter Configuration File"
• "Retrieving Filters"
• "Adding Filter Prefixes and Suffixes"

bjensen@airius.com

(mail=bjensen@airius.com)

555-1212

(telephoneNumber=555-1212)

tag

     pattern1     delimiters     filter1-1     desc1-1     [scope1]

                                 filter1-2     desc1-2     [scope2]

     pattern2     delimiters     filter2-1     desc2-1     [scope3]

     ...

• tag identifies a group of filters. You can use different tags to distinguish filters for different types of objects. For example, you can use a tag to represent filters for person entries, a tag to represent filters for organization entries, and so on:

      "people"

         ... (filters for searching "person" entries) ...

      "organization"

         ... (filters for "organization" entries) ...

You can specify a tag (or part of a tag) as a parameter. The tag narrows the list of filters that the function can retrieve.

• pattern1 and pattern2 are regular expressions used to determine which filter is selected, based on the search criteria. For example, if you specify "^[0-9]" as the pattern for a filter, the filter is selected for all search criteria beginning with a number.

      "people"

         "^[0-9]"         ...

For more information on regular expressions, consult your UNIX documentation (for example, documentation on the ed command contains some information on regular expressions).

• delimiters specifies the delimiters used to distinguish one field from another within the search criteria. For example, if the search criteria consists of a city name and state abbreviation separated by a comma, specify "," as the delimiter.
• filter1-1, filter1-2, and filter2-1 are filters. Use %v to represent the search criteria. For example, to search e-mail addresses, use the filter (mail=%v). During runtime, if the search criteria bjensen@airius.com is entered, the filter becomes (mail=bjensen@airius.com).

If the search criteria consists of a number of delimited fields (for example, a "last name, first name" format like "Jensen, Barbara"), use %v1, %v2, ... , %vn to represent the different fields within the search criteria. For example:

      "people"

         "^[A-Z]*,"         ","      (&(sn=%v1)(givenName=%v2))

In this example, the delimiter is a comma. The word before the delimiter replaces %v1 in the filter, and the word after the delimiter replaces %v2 in the filter. If the user searches for:

      Jensen, Barbara

the resulting filter is:

      (&(sn=Jensen)(givenName=Barbara))

You can also specify ranges of fields. For example, to specify the values in the first three fields, use %v1-3. To specify values from the third field to the last field, use %v3-. To specify the value in the last field, use %v$.

• desc1-1, desc1-2, and desc2-1 are phrases briefly describing the filters.
• scope1, scope2, and scope3 specify the scope of each search. This field is optional and can have the values "base", "onelevel", or "subtree".

"people"

     "^[0-9][0-9-]*$"     " "     "(telephoneNumber=*%v))"     "phone number ends with"

     "@"                  " "     "(mail=%v)"                  "email address is"

                                  "(mail=%v*)"                 "email address starts with"

• %v

This parameter means that the entire search criteria is inserted in place of %v. For example, if the filter is (mail=%v), entering the word jensen results in the filter (mail=jensen).

• %v$

This parameter means that the last word in the search criteria is inserted in place of %v. For example, if the filter is (sn=%v$), entering the words Barbara Jensen results in the filter (sn=Jensen).

• %vN (Note: N is a single digit between 1 and 9)

This parameter means that the Nth word in the search criteria is inserted in place of %vN. For example, if the filter is (sn=%v2), entering the words Barbara Jensen results in the filter (sn=Jensen).

• %vM-N (Note: M and N are single digits between 1 and 9)

This parameter means that the sequence of the Mth through the Nth words in the search criteria is inserted in place of %vM-N. For example, if the filter is (cn=%v1-2), entering the words Barbara Jensen results in the filter (cn=Barbara Jensen).

• %vN- (Note: N is a single digit between 1 and 9)

This parameter means that the sequence of the Nth through the last words in the search criteria is inserted in place of %vN-. For example, if the filter is (cn=%v2-), entering the words Ms. Barbara Jensen results in the filter (cn=Barbara Jensen).

• a file in the local file system (you can specify the path to the file)
• a file served by a web server (you can specify a URL to the file)
• a location in memory (you can specify a StringBuffer containing the filter configuration information)

...

import netscape.ldap.util.*;

...

LDAPFilterDescriptor filtdesc = null;

try {

   /* Read in the filter configuration file. */

   filtdesc = new LDAPFilterDescriptor( "ldapfilter.conf" );

} catch ( Exception e ) {

   System.out.println( "Error: " + e.toString() );

}

...

1. Invoke the LDAPFilterDescriptor constructor to read in the filter configuration file.
2. Invoke the getFilters method of the LDAPFilterDescriptor object.

Specify the tag of the section that you want to use in the filter configuration file.

This method returns an LDAPFilterList object, which is an enumeration of LDAPFilter objects containing the filters for the specified search term.

1. Invoke the next method of the LDAPFilterList object to iterate through the LDAPFilter objects.
2. For each LDAPFilter object, get the filter by invoking the getFilter method, passing no arguments.

"people"

     "^[0-9][0-9-]*$"     " "     "(telephoneNumber=*%v))"     "phone number ends with"

     "@"                  " "     "(mail=%v)"                  "email address is"

                                  "(mail=%v*)"                 "email address starts with"

...

import netscape.ldap.util.*;

import java.util.*;



...

String searchTerm = "bjensen@airius.com";

LDAPFilterDescriptor filtdesc = null;

try {

   /* Read in the filter configuration file. */

   filtdesc = new LDAPFilterDescriptor( "ldapfilt.conf" );



   /* Get filters from the section "people" for the search term. */

   LDAPFilterList filtlist = null;

   try {

      filtlist = filtdesc.getFilters( "people", searchTerm );

   } catch ( Exception e ) {

      System.out.println( "No matching tag section or filter found." );

      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() );

}

System.exit( 0 );

...

java GetFilter bjensen@airius.com

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@airius.com)



Filter #2

  Description: email address starts with

  Line #: 4

  Matches pattern: @

  Filter template: (mail=%v*)

  Delimiter: 

  Scope: subtree

  Generated filter string: (mail=bjensen@airius.com*)

   (&(l=Sunnyvale)

   )

   (sn=Jensen)

(&(l=Sunnyvale)(sn=Jensen))

• To set these for all filters generated from the filter configuration file, invoke the setFilterAffixes method of the LDAPFilterDescriptor object. See "Adding Affixes for All Filters" for an example.
• To set the prefix or suffix for a specific filter, do one of the following:

• Invoke the setFilterAffixes methodof the LDAPFilter object, then invoke the getFilter method, passing in the search term again. This builds the filter again, using the specified search term with the prefix and suffix. See "Adding Affixes By Using setFilterAffixes" for an example.
• Invoke the getFilter method, passing in the search term, the prefix, and the suffix. See "Adding Affixes By Using getFilter" for an example.
• Invoke the setupFilter method, passing the search term, the prefix, and the suffix. See "Adding Affixes By Using setupFilter" for an example.

Note that setting the prefix and suffix for an individual filter will override any prefix or suffix set for the entire filter configuration file.

• "Adding Affixes for All Filters"
• "Adding Affixes By Using setFilterAffixes"
• "Adding Affixes By Using getFilter"
• "Adding Affixes By Using setupFilter"

...

import netscape.ldap.util.*;

...

LDAPFilterDescriptor filtdesc = null;

try {

   /* Read in the filter configuration file. */

   filtdesc = new LDAPFilterDescriptor( "myfilter.conf" );



   /* Add the specified prefix and suffix to all filters. */

   String prefix = "(&(l=Sunnyvale)";

   String suffix = ")";

   filtdesc.setFilterAffixes( prefix, suffix );



   /* Get filters from the section "people" for the search term. */

   LDAPFilterList filtlist = null;

   try {

      filtlist = filtdesc.getFilters( "people", searchTerm );

   } catch ( Exception e ) {

      System.out.println( "No matching tag section or filter found." );

      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() );

}

...

   bjensen@airius.com

   (mail=bjensen@airius.com)

   (&(l=Sunnyvale)(mail=bjensen@airius.com))

...

import netscape.ldap.util.*;

...

LDAPFilterDescriptor filtdesc = null;

try {

   /* Read in the filter configuration file. */

   filtdesc = new LDAPFilterDescriptor( "myfilter.conf" );



   /* Get filters from the section "people" for the search term. */

   LDAPFilterList filtlist = null;

   try {

      filtlist = filtdesc.getFilters( "people", searchTerm );

   } catch ( Exception e ) {

      System.out.println( "No matching tag section or filter found." );

      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 = "(&(l=Sunnyvale)";

      String suffix = ")";

      filtline.setFilterAffixes( prefix, suffix );

      String filterString = filtline.getFilter( searchTerm );

      System.out.println( "  Generated filter string: " + filterString + 

         "\n" );

   }

} catch ( Exception e ) {

   System.out.println( "Error: " + e.toString() );

}

...

   bjensen@airius.com

   (mail=bjensen@airius.com)

   (&(l=Sunnyvale)(mail=bjensen@airius.com))

...

import netscape.ldap.util.*;

...

LDAPFilterDescriptor filtdesc = null;

try {

   /* Read in the filter configuration file. */

   filtdesc = new LDAPFilterDescriptor( "myfilter.conf" );



   /* Get filters from the section "people" for the search term. */

   LDAPFilterList filtlist = null;

   try {

      filtlist = filtdesc.getFilters( "people", searchTerm );

   } catch ( Exception e ) {

      System.out.println( "No matching tag section or filter found." );

      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 = "(&(l=Sunnyvale)";

      String suffix = ")";

      String filterString = filtline.getFilter( searchTerm, prefix, 

         suffix );

      System.out.println( "  Generated filter string: " + filterString + 

         "\n" );

   }

} catch ( Exception e ) {

   System.out.println( "Error: " + e.toString() );

}

...

   bjensen@airius.com

   (mail=bjensen@airius.com)

   (&(l=Sunnyvale)(mail=bjensen@airius.com))

...

import netscape.ldap.util.*;

...

LDAPFilterDescriptor filtdesc = null;

try {

   /* Read in the filter configuration file. */

   filtdesc = new LDAPFilterDescriptor( "myfilter.conf" );



   /* Get filters from the section "people" for the search term. */

   LDAPFilterList filtlist = null;

   try {

      filtlist = filtdesc.getFilters( "people", searchTerm );

   } catch ( Exception e ) {

      System.out.println( "No matching tag section or filter found." );

      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 = "(&(l=Sunnyvale)";

      String suffix = ")";

      filtline.setupFilter( searchTerm, prefix, suffix );

      String filterString = filtline.getFilter();      System.out.println( "  
Generated filter string: " + filterString + 

         "\n" );

   }

} catch ( Exception e ) {

   System.out.println( "Error: " + e.toString() );

}

...

   bjensen@airius.com

   (mail=bjensen@airius.com)

   (&(l=Sunnyvale)(mail=bjensen@airius.com))