Package com.ibm.di.server

Class SearchCriteria

  • public class SearchCriteria
extends java.lang.Object
    This class contains a list of generic search criteria and methods to generate them. The search criteria is e.g. attr equals value. The class also has a number of methods to convert the generic criteria to standard expressions like LDAP search filters, SQL select statements etc.

    The class also provides a means to define templates which can be expanded using a com.ibm.di.entry.Entry object. The expanded templates can then be accessed through the criteria methods.

    The typical use of this class is to:

    • Create an instance of this class
    • Populate the templates array (addTemplate method)
    Then for every entry you can use the buildCriteria method to expand the templates into the criteria array and use the getLDAPFilter etc to construct a search filter usable with specific connectors. The connectors themselves will use the getXXFilter methods to obtain the search filter in order to search for entries. However, if you write your own connector or for some other reason need to get hold of the expanded filters you can always use the getXX>Filter methods. These methods only build a string from the criteria array so no changes are done to the class variables.

    All getXXXFilter methods first check if the class was created with a user defined script to return the search string. Thus, if you create an instance of this class with a script/ScriptEngine and use for example the LDAP connector, the search filter used by the LDAP connector will be the result of the script evaluation rather than the getLDAPFilter method.

    Here is an example Before Lookup Hook which displays all Link Criteria set.

    Example : 

     var criteria = search.getCriteria();
 var matchstr;

 task.logmsg("Link Criteria set: ");
 for (i = 0; i < criteria.size(); i++) {
        var crit = criteria.get(i);

  if (crit.match == com.ibm.di.server.SearchCriteria.EXACT) {
                matchstr = "equals";
        } else if (crit.match == com.ibm.di.server.SearchCriteria.LESS_THAN) {
                matchstr = "less than";
        } else if (crit.match == com.ibm.di.server.SearchCriteria.LESS_THAN_OR_EQUAL) {
                matchstr = "less than or equal";
        } else if (crit.match == com.ibm.di.server.SearchCriteria.GREATER_THAN) {
                matchstr = "greater than";
        } else if (crit.match == com.ibm.di.server.SearchCriteria.GREATER_THAN_OR_EQUAL) {
                matchstr = "greater than or equal";
        } else if (crit.match == com.ibm.di.server.SearchCriteria.SUBSTRING) {
                matchstr = "contains";
        } else if (crit.match == com.ibm.di.server.SearchCriteria.INITIAL_STRING) {
                matchstr = "starts with";
        } else if (crit.match == com.ibm.di.server.SearchCriteria.FINAL_STRING) {
                matchstr = "end with";
        } else if (crit.match == com.ibm.di.server.SearchCriteria.NOT_STRING) {
                matchstr = "not equals";
        }

        main.logmsg("name: " + crit.name + "\nmatch: " + matchstr + "\nvalue: "
                        + crit.value);
 }
    Instead of using the constant com.ibm.di.server.SearchCriteria.EXACT the value 61 (the character code for '=') could have been used. Here is a list of the constants used for the match operator, and their values: 
            EXACT = 61
        LESS_THAN = 60
        LESS_THAN_OR_EQUAL = 8804
        GREATER_THAN = 62
        GREATER_THAN_OR_EQUAL = 8805
        SUBSTRING = 126
        INITIAL_STRING = 94
        FINAL_STRING = 36
        NOT_STRING = 33

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  SearchCriteria.rscSearch
      This class is used internally.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static int EXACT
      This is the character that represents the binary operation equals.
      static int EXCACT
      Deprecated. 
      java.lang.String filter  
      static int FINAL_STRING
      This is the character that represents the binary operator that tells that the left operand should end with the value of the right operand.
      static int GREATER_THAN
      The binary operator greater than.
      static int GREATER_THAN_OR_EQUAL
      The binary operator greater than or equal.
      static int INITIAL_STRING
      This is the character that represents the binary operator that tells that the left operand should start with the value of the right operand.
      static int LESS_THAN
      The binary operator less than.
      static int LESS_THAN_OR_EQUAL
      The binary operator less than or equal.
      static int NOT_STRING
      This is the character that represents the binary operator that tells that both operands should be different from each other.
      ParameterSubstitutionCache psc  
      static int SEARCH_AND
      This is the character that represents the binary operator AND.
      static int SEARCH_NOT
      This is the character that represents the unary operator NOT.
      static int SEARCH_OR
      This is the character that represents the binary operator OR.
      static int SUBSTRING
      This is the character that represents the binary operator that tells that the right operand should be contained somewhere in the left operand.

    • Field Detail

      • EXACT

        public static final int EXACT
        This is the character that represents the binary operation equals.
        See Also:
        Constant Field Values

      • EXCACT

        public static final int EXCACT
        Deprecated.
        Misspelling, kept for backwards compatibility
        See Also:
        Constant Field Values

      • SUBSTRING

        public static final int SUBSTRING
        This is the character that represents the binary operator that tells that the right operand should be contained somewhere in the left operand.
        See Also:
        Constant Field Values

      • INITIAL_STRING

        public static final int INITIAL_STRING
        This is the character that represents the binary operator that tells that the left operand should start with the value of the right operand.
        See Also:
        Constant Field Values

      • FINAL_STRING

        public static final int FINAL_STRING
        This is the character that represents the binary operator that tells that the left operand should end with the value of the right operand.
        See Also:
        Constant Field Values

      • NOT_STRING

        public static final int NOT_STRING
        This is the character that represents the binary operator that tells that both operands should be different from each other.
        See Also:
        Constant Field Values

      • LESS_THAN

        public static final int LESS_THAN
        The binary operator less than.
        Since:
        7.0
        See Also:
        Constant Field Values

      • LESS_THAN_OR_EQUAL

        public static final int LESS_THAN_OR_EQUAL
        The binary operator less than or equal.
        Since:
        7.0
        See Also:
        Constant Field Values

      • GREATER_THAN

        public static final int GREATER_THAN
        The binary operator greater than.
        Since:
        7.0
        See Also:
        Constant Field Values

      • GREATER_THAN_OR_EQUAL

        public static final int GREATER_THAN_OR_EQUAL
        The binary operator greater than or equal.
        Since:
        7.0
        See Also:
        Constant Field Values

      • SEARCH_AND

        public static final int SEARCH_AND
        This is the character that represents the binary operator AND.
        See Also:
        Constant Field Values

      • SEARCH_OR

        public static final int SEARCH_OR
        This is the character that represents the binary operator OR.
        See Also:
        Constant Field Values

      • SEARCH_NOT

        public static final int SEARCH_NOT
        This is the character that represents the unary operator NOT.
        See Also:
        Constant Field Values

      • filter

        public java.lang.String filter

    • Constructor Detail

      • SearchCriteria

        public SearchCriteria​(int matchtype)
        Creates an object of type SearchCriteria.
        Parameters:
        matchtype - - this is one of the following:
        SEARCH_AND
        SEARCH_OR

      • SearchCriteria

        public SearchCriteria​(java.lang.String name,
                      int match,
                      java.lang.Object value)
        Creates an object of type SearchCriteria and adds an initial expression to criteria array.
        Parameters:
        name - is the attribute name
        match - is the match operator
        value - is the matching value.

      • SearchCriteria

        public SearchCriteria​(java.lang.String criteriaScript,
                      ScriptEngine engine)
        Creates an object of type SearchCriteria and prepares the object for interpreting a Criteria script.
        Parameters:
        criteriaScript - is the script string.
        engine - is the ScriptEngine used for interpreting the script.
        See Also:
        buildCriteriaScript(Entry)

    • Method Detail

      • size

        public int size()
        Return number of templates.
        Returns:
        Number of entries in the templates array

      • getCriteria

        public SearchCriteria.rscSearch getCriteria​(int index)
        Return criteria class at specified index.
        Parameters:
        index - the position of the rscSearc object in the array.
        Returns:
        The rscSearch class at the specified index

      • getCriteria

        public java.util.Vector<?> getCriteria()
        This method exposes the Vector object used for storing the criteria objects (usually of type SearchCriteria.rscSearch) which are result of the building the criteria templates.
        Note: Some of the elements in the Vector could be of type SearchCriteria
        Returns:
        The Vector object in which the SearchCriteria object stores the built criteria objects.
        Note: This is not an immutable object! On the next call of the buildCriteria(Entry) method all of its values will be removed from the Vector.
        See Also:
        buildCriteria(Entry)

      • addCriteria

        public void addCriteria​(java.lang.String name,
                        int match,
                        java.lang.Object value)
        Add expression to criteria array.
        Parameters:
        name - The attribute name
        match - The match operator (e.g. EXACT, FINAL_STRING ..)
        value - The matching value.

      • addCriteria

        public void addCriteria​(java.lang.String name,
                        int match,
                        java.lang.Object value,
                        boolean negate)
        Add expression to criteria array.
        Parameters:
        name - The attribute name
        match - The match operator (e.g. EXACT, FINAL_STRING ..)
        value - The matching value.
        negate - Specify true to negate the expression

      • replaceCriteria

        public void replaceCriteria​(java.lang.String name,
                            java.lang.Object value)
        Add expression to criteria array, replacing all previous occurrences with the same attribute name. The match operator will always be EXACT.
        Parameters:
        name - The attribute name
        value - The matching value.

      • getFirstCriteriaName

        public java.lang.String getFirstCriteriaName()
        Return the name of the first criteria entry.
        Returns:
        The name contained in the first criteria entry

      • getFirstCriteriaValue

        public java.lang.String getFirstCriteriaValue()
        Return the value of the first criteria entry.
        Returns:
        The value contained in the first criteria entry

      • getFirstCriteriaMatch

        public int getFirstCriteriaMatch()
        Return the match operator of the first criteria entry.
        Returns:
        The match operator contained in the first criteria entry

      • setType

        public void setType​(int type)
        Set type (SEARCH_AND, SEARCH_OR) for the search criteria. This governs how multiple criteria objects are constructed.
        Parameters:
        type - SEARCH_AND, SEARCH_OR

      • getType

        public int getType()
        Returns the search type.
        Returns:
        SEARCH_AND or SEARCH_OR
        See Also:
        setType(int)

      • getTemplate

        public SearchCriteria.rscSearch getTemplate​(int index)
        Returns the criteria template at a specific location.
        Parameters:
        index - The index into the templates array
        Returns:
        The SearchCriteria.rscSearch class at location index

      • addTemplate

        public void addTemplate​(java.lang.String name,
                        int match,
                        java.lang.String defvalue)
        Add a criteria to the templates array.
        Parameters:
        name - The attribute name
        match - The match operator (e.g. EXACT, FINAL_STRING ..)
        defvalue - The value to match

      • addTemplate

        public void addTemplate​(java.lang.String name,
                        int match,
                        java.lang.String defvalue,
                        boolean negate)
        Add a criteria to the templates array.
        Parameters:
        name - The attribute name
        match - The match operator (e.g. EXACT, FINAL_STRING ..)
        defvalue - The value to match
        negate - Specify true to negate the expression
        Since:
        7.2

      • addTemplate

        public void addTemplate​(java.lang.String name,
                        java.lang.String match,
                        java.lang.String defvalue)
        Add a criteria to the templates array.
        Parameters:
        name - The attribute name
        match - The match operator as a String, e.g. '=','~', '^', '$' or '!'.
        defvalue - The value to match

      • getLDAPFilter

        public java.lang.String getLDAPFilter()
        Return complete LDAP filter from criteria array.
        Returns:
        The complete LDAP filter from the values in the criteria array.

      • getSQLFilter

        public java.lang.String getSQLFilter()
        Return complete SQL search expression from criteria array.
        Returns:
        The complete SQL search expression from the values in the criteria array.

      • getSimpleFilter

        public java.lang.String getSimpleFilter()
        Get a string representation of the Criteria array.
        Returns:
        a simple string representation of the search criteria objects in the criteria array, or an error message if all of the objects in the criteria array are not of type SearchCriteria.rscSearch.

      • getNotesFilter

        public java.lang.String getNotesFilter()
        Return complete Notes search expression from criteria array.
        Returns:
        The complete Notes search expression from the values in the criteria array.

      • getNotesFTFilter

        public java.lang.String getNotesFTFilter()
        Return complete Notes FullText search expression from criteria array.
        Returns:
        The complete Notes FullText search expression from the values in the criteria array.

      • getSearchString

        public java.lang.String getSearchString​(int i)
        Get the string representation of the search criteria in the criteria array.
        Note: This method will throw an exception of type ClassCastException if the criteria array contains objects of type other than SearchCriteria.rscSearch.
        Parameters:
        i - the position of the SearchCriteria.rscSearch object in the criteria array.
        Returns:
        the string representation of the search criteria object or null if the specified index is out of the criteria array bounds.

      • getCurrentEntry

        public Entry getCurrentEntry()
        Return the working entry used to generate the criteria array from the templates array.
        This is the entry passed to the buildCriteria(Entry) method.
        Returns:
        The working entry
        See Also:
        Entry, buildCriteria(Entry)

      • buildCriteria

        public void buildCriteria​(Entry e)
                   throws java.lang.Exception
        Build the criteria array using provided entry. This method uses the templates array to generate the criteria array. Each criteria in the template array holds an attribute name, a matching operator and a value. The value, if prefixed by a dollar sign, causes this method to substitute the value with the corresponding attribute value in the work entry. The attribute name is derived from the value by removing the first dollar sign using the remainder as the attribute name. For example, "$test" becomes "test".

        When the method completes the criteria array has been built so it contains a copy of the templates array with expanded values.

        You typically create an instance of this class and then add the templates. Then for each entry you are using in a search you can call the buildCriteria method to populate the criteria array. Then, having done that you can use the getLDAPFilter, getNotesFilter etc to obtain the search filter as a string.
        This method reuses the functionality of the buildCriteria(Entry, BaseConfiguration, Object) method.

        Parameters:
        e - The work entry used in parameter substitution.
        Throws:
        com.ibm.jscript.InterpretException - If the provided script could not be interpreted correctly.
        java.lang.Exception - If the current SearchCriteria object does not have any templates to build from.

      • buildCriteriaScript

        public void buildCriteriaScript​(Entry entry)
                         throws java.lang.Exception
        Call user defined script to build the search filter. The filter has access to the entry object as a scriptable object called work. The class instance (this) is available as ret. The script is expected at some point to assign a value to the ret.filter property. The value of that property will be returned to the caller.
        Parameters:
        entry - The work entry used in parameter substitution
        Throws:
        com.ibm.jscript.InterpretException - If the provided script could not be interpreted correctly.
        java.lang.Exception

      • getScriptFilter

        public java.lang.String getScriptFilter()
        This method executes a script that returns a user-defined search filter.
        Returns:
        The search filter

      • isConfigured

        public boolean isConfigured()
        Check if the object has some kind of configuration set.
        Returns:
        true if the current SearchCriteria object has templates to build from or has a script string to interpret, returns false otherwise.