netscape.ldap.util
Class LDAPFilter

java.lang.Object
  extended by netscape.ldap.util.LDAPFilter
All Implemented Interfaces:
java.lang.Cloneable

public class LDAPFilter
extends java.lang.Object
implements java.lang.Cloneable

Represents an LDAP search filter, which includes the string-based representation of the filter and other information retrieved from the LDAP filter configuration file (or from a buffer in memory or from a URL).

Although this class provides methods to create and modify LDAP filters, in most cases, you do not need to use these methods. In most situations, these classes are used to access individual filters from filter configuration files.

For example, you might do the following:

  1. Connect to the LDAP server and accept a set of search criteria.
  2. Create an LDAP filter configuration file.
  3. Call the LDAPFilterDescriptor constructor to read the filter configuration file into memory.
  4. Call the getFilters method to get a list of filters that match the search criteria. This list of filters is represented by an LDAPFilterList object.
  5. Iterate through the list of filters (each filter is represented by an LDAPFilter object), and apply the filter to a search.

For an example of using an object of this class and for more information on the filter configuration file syntax, see the documentation for LDAPFilterDescriptor.

Version:
1.0
See Also:
LDAPFilterDescriptor, LDAPFilterList

Constructor Summary
LDAPFilter(java.lang.String strMatchPattern, java.lang.String strDelimiter, java.lang.String strFilterTemplate, java.lang.String strDescription, int nScope)
          Constructs an LDAPFilter object.
LDAPFilter(java.lang.String strMatchPattern, java.lang.String strDelimiter, java.lang.String strFilterTemplate, java.lang.String strDescription, java.lang.String strScope)
          Constructs an LDAPFilter object.
 
Method Summary
 java.lang.Object clone()
          Makes a copy of this LDAPFilter object.
(package private)  java.lang.String convertMatchPattern(java.lang.String strMatchPattern)
          The ldapfilter.conf specifies match patterns in a funny way.
(package private)  void createFilterString(java.lang.String strValue, java.lang.String strPrefix, java.lang.String strSuffix)
          Create the filter string which can be used in LDAPConnection.search() and others given the parameter strValue.
 java.lang.String getDelimiter()
          Return this filter's delimiter.
 java.lang.String getDescription()
          Return this filter's description.
 java.lang.String getFilter()
          Returns the filter string.
 java.lang.String getFilter(java.lang.String strValue)
          Create a filter string given a string value.
 java.lang.String getFilter(java.lang.String strValue, java.lang.String strPrefix, java.lang.String strSuffix)
          Create a filter string given a string value.
 java.lang.String getFilterTemplate()
          Return this filter's filter template.
 java.lang.String getLineNumber()
          Return this filter's line number.
 java.lang.String getMatchPattern()
          Return this filter's match pattern.
 java.lang.String getScope()
          Return this filter's scope.
 void setFilterAffixes(java.lang.String strPrefix, java.lang.String strSuffix)
           
(package private)  void setLine(int nLine)
          Set the line number from which this filter was created.
 void setupFilter(java.lang.String strValue)
          Sets up the filter string, given the string strValue.
 void setupFilter(java.lang.String strValue, java.lang.String strPrefix, java.lang.String strSuffix)
          Sets up the filter string, given the string strValue.
 java.lang.String toString()
          Print out a string representation of the LDAPFilter.
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

LDAPFilter

public LDAPFilter(java.lang.String strMatchPattern,
                  java.lang.String strDelimiter,
                  java.lang.String strFilterTemplate,
                  java.lang.String strDescription,
                  int nScope)
           throws java.lang.IllegalArgumentException
Constructs an LDAPFilter object. In most situations, you do not need to construct an LDAPFilter object. Instead, you work with LDAPFilter objects created from the LDAPFilter objects and LDAPFilterDescriptor objects.

This constructor uses the integer value for a search scope in addition to other information to construct an LDAPFilter object. The integer value of the search scope can be one of the following:

If an invalid scope is specified, the constructor throws an illegalArgumentException.

Throws:
java.lang.IllegalArgumentException

LDAPFilter

public LDAPFilter(java.lang.String strMatchPattern,
                  java.lang.String strDelimiter,
                  java.lang.String strFilterTemplate,
                  java.lang.String strDescription,
                  java.lang.String strScope)
           throws java.lang.IllegalArgumentException
Constructs an LDAPFilter object. In most situations, you do not need to construct an LDAPFilter object. Instead, you work with LDAPFilter objects created from the LDAPFilter objects and LDAPFilterDescriptor objects.

This constructor uses the string value for a search scope in addition to other information to construct an LDAPFilter object. The string value of the search scope can be one of the following:

If an invalid scope is specified, the constructor throws an illegalArgumentException.

Throws:
java.lang.IllegalArgumentException
Method Detail

toString

public java.lang.String toString()
Print out a string representation of the LDAPFilter. Basically, it prints out the appropriate fields.

For example, suppose you called the method in this way:

System.out.println(filter.toString());
The resulting output might look like this:

      matchPtn: "@"
      delim:    " "
      filttmpl: "(mail=%v*)"
      descript: "start of email address"
      scope: "LDAPConnection.SCOPE_SUB"
      line:     "32"
      FILTER:   "(mail=babs@aceindustry.com*)"
 

Overrides:
toString in class java.lang.Object

setupFilter

public void setupFilter(java.lang.String strValue,
                        java.lang.String strPrefix,
                        java.lang.String strSuffix)
Sets up the filter string, given the string strValue. If the strPrefix and strSuffix arguments are non-null strings, they are prepended and appended to the filter string (respectively).

This string, which is available through the getFilter() method, should be suitable for use as search criteria when calling the LDAPConnection.search() method.

Notes:

See Also:
LDAPFilterDescriptor.setFilterAffixes(java.lang.String, java.lang.String), setFilterAffixes(java.lang.String, java.lang.String)

setupFilter

public void setupFilter(java.lang.String strValue)
Sets up the filter string, given the string strValue. This string, which is available through the getFilter() method, should be suitable for use as search criteria when calling the LDAPConnection.search() method.

Note: If you want to specify a filter prefix and suffix, you need to explicitly define them by calling the setFilterAffixes() method.

See Also:
LDAPFilterDescriptor.setFilterAffixes(java.lang.String, java.lang.String), setFilterAffixes(java.lang.String, java.lang.String)

createFilterString

void createFilterString(java.lang.String strValue,
                        java.lang.String strPrefix,
                        java.lang.String strSuffix)
Create the filter string which can be used in LDAPConnection.search() and others given the parameter strValue. If strPrefix and strSuffix are non-null strings, prepend strPrefix and append strSuffix.


clone

public java.lang.Object clone()
Makes a copy of this LDAPFilter object.

Overrides:
clone in class java.lang.Object

setLine

void setLine(int nLine)
Set the line number from which this filter was created. This is used only when the LDAPFilter is created when an LDAPFilterDescriptor is initialized from a file/URL/buffer.


convertMatchPattern

java.lang.String convertMatchPattern(java.lang.String strMatchPattern)
The ldapfilter.conf specifies match patterns in a funny way. A "." means "any character" except when used inside of a set of square brackets "[]", in which case, the "." means just a plain old period (not a * special character). This function converts periods inside of a set of square brackets into a "\." as per normal regexp code.


getFilter

public java.lang.String getFilter()
Returns the filter string. This method will return null if the filter string has not been calculated by the setupFilter(), getFilter (strValue), or getFilter (strValue, strPrefix, strSuffix ) methods.

See Also:
setupFilter(java.lang.String, java.lang.String, java.lang.String), getFilter()

getFilter

public java.lang.String getFilter(java.lang.String strValue)
Create a filter string given a string value. This method uses any Prefixes or Suffixes that have been set by the setFilterAffixes() method.

This is the same as doing:

   setupFilter ( strValue );
   getFilter();
 


getFilter

public java.lang.String getFilter(java.lang.String strValue,
                                  java.lang.String strPrefix,
                                  java.lang.String strSuffix)
Create a filter string given a string value. If strPrefix and/or strSuffix is non-null, these values are prepended and appended to the returned string.

This is the same as doing:

   setupFilter ( strValue, strPrefix, strSuffix );
   getFilter();
 


getMatchPattern

public java.lang.String getMatchPattern()
Return this filter's match pattern. The match pattern is found as the first token in a filter configuration line in the ldapfilter.conf file.


getDelimiter

public java.lang.String getDelimiter()
Return this filter's delimiter. The delmimeter is found as the second token in a filter configuration line in the ldapfilter.conf file.


getFilterTemplate

public java.lang.String getFilterTemplate()
Return this filter's filter template. The filter template is found as the third token in a filter configuration line in the ldapfilter.conf file.


getDescription

public java.lang.String getDescription()
Return this filter's description. The description is found as the fourth token in a filter configuration line in the ldapfilter.conf file.


getScope

public java.lang.String getScope()
Return this filter's scope. The scope is found as the fifth (optional) token in a filter configuration line in the ldapfilter.conf file.


getLineNumber

public java.lang.String getLineNumber()
Return this filter's line number. The line number is mostly a debugging variable to let the developer know which filter from the filter configuration file is being used.


setFilterAffixes

public void setFilterAffixes(java.lang.String strPrefix,
                             java.lang.String strSuffix)