com.ibm.di.server
Class SearchCriteria

java.lang.Object
  extended by com.ibm.di.server.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:

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";
        }
 
        main.logmsg("name: " + crit.name + "\nmatch: " + matchstr + "\nvalue: "
                        + crit.value);
 }
 


Nested Class Summary
static class SearchCriteria.rscSearch
          This class is used internally.
 
Field Summary
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.
 
Constructor Summary
SearchCriteria()
          Default constructor for creating an object of type SearchCriteria.
SearchCriteria(int matchtype)
          Creates an object of type SearchCriteria.
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.
SearchCriteria(java.lang.String criteriaScript, ScriptEngine engine)
          Creates an object of type SearchCriteria and prepares the object for interpreting a Criteria script.
 
Method Summary
 void addCriteria(java.lang.String name, int match, java.lang.Object value)
          Add expression to criteria array.
 void addCriteria(java.lang.String name, int match, java.lang.Object value, boolean negate)
          Add expression to criteria array.
 void addTemplate(java.lang.String name, int match, java.lang.String defvalue)
          Add a criteria to the templates array.
 void addTemplate(java.lang.String name, java.lang.String match, java.lang.String defvalue)
          Add a criteria to the templates array.
 void buildCriteria(Entry e)
          Build the criteria array using provided entry.
 void buildCriteria(Entry e, BaseConfiguration config, java.lang.Object task)
           
 void buildCriteriaScript(Entry entry)
          Call user defined script to build the search filter.
 java.lang.String buildLdapFilter(SearchCriteria.rscSearch rs)
          Constructs an LDAP search filter from an SearchCriteria.rscSearch class.
 java.lang.String buildNotesFilter(SearchCriteria.rscSearch rs)
          Constructs an Notes search filter from an SearchCriteria.rscSearch class.
 java.lang.String buildNotesFTFilter(SearchCriteria.rscSearch rs)
          Constructs an Notes FullText search filter from an SearchCriteria.rscSearch class.
 java.lang.String buildSQLFilter(SearchCriteria.rscSearch rs)
          Constructs an SQL where expression from an SearchCriteria.rscSearch class.
 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.
 SearchCriteria.rscSearch getCriteria(int index)
          Return criteria class at specified index.
 Entry getCurrentEntry()
          Return the working entry used to generate the criteria array from the templates array.
 int getFirstCriteriaMatch()
          Return the match operator of the first criteria entry.
 java.lang.String getFirstCriteriaName()
          Return the name of the first criteria entry.
 java.lang.String getFirstCriteriaValue()
          Return the value of the first criteria entry.
 java.lang.String getLDAPFilter()
          Return complete LDAP filter from criteria array.
 java.lang.String getNotesFilter()
          Return complete Notes search expression from criteria array.
 java.lang.String getNotesFTFilter()
          Return complete Notes FullText search expression from criteria array.
 java.lang.String getScriptFilter()
          This method executes a script that returns a user-defined search filter.
 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.
 java.lang.String getSimpleFilter()
          Get a string representation of the Criteria array.
 java.lang.String getSQLFilter()
          Return complete SQL search expression from criteria array.
 SearchCriteria.rscSearch getTemplate(int index)
          Returns the criteria template at a specific location.
 int getType()
          Returns the search type.
 boolean isConfigured()
          Check if the object has some kind of configuration set.
 void replaceCriteria(java.lang.String name, java.lang.Object value)
          Add expression to criteria array, replacing all previous occurrences with the same attribute name.
 void setType(int type)
          Set type (SEARCH_AND, SEARCH_OR) for the search criteria.
 int size()
          Return number of templates.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

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

psc

public ParameterSubstitutionCache psc
Constructor Detail

SearchCriteria

public SearchCriteria()
Default constructor for creating an object of type SearchCriteria.
The match type by default is set to SEARCH_AND

See Also:
SearchCriteria(int)

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,
                        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

buildLdapFilter

public java.lang.String buildLdapFilter(SearchCriteria.rscSearch rs)
Constructs an LDAP search filter from an SearchCriteria.rscSearch class.

Parameters:
rs - the SearchCriteria.rscSearch object which properties to use during the filter construction process.
Returns:
The LDAP search filter

buildSQLFilter

public java.lang.String buildSQLFilter(SearchCriteria.rscSearch rs)
Constructs an SQL where expression from an SearchCriteria.rscSearch class.

Parameters:
rs - the SearchCriteria.rscSearch object which properties to use during the filter construction process.
Returns:
The SQL where expression

buildNotesFilter

public java.lang.String buildNotesFilter(SearchCriteria.rscSearch rs)
Constructs an Notes search filter from an SearchCriteria.rscSearch class.

Parameters:
rs - the SearchCriteria.rscSearch object which properties to use during the filter construction process.
Returns:
The Notes search filter

buildNotesFTFilter

public java.lang.String buildNotesFTFilter(SearchCriteria.rscSearch rs)
Constructs an Notes FullText search filter from an SearchCriteria.rscSearch class.

Parameters:
rs - the SearchCriteria.rscSearch object which properties to use during the filter construction process.
Returns:
The Notes FullText search filter

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.

buildCriteria

public void buildCriteria(Entry e,
                          BaseConfiguration config,
                          java.lang.Object task)
                   throws java.lang.Exception
Parameters:
e - the work entry used in parameter substitution.
config - the component's config object, could be null.
task - usually a reference to the AssemblyLine instance calling this method, could be null.
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.
See Also:
for general information.
This method will also check if the user have provided a script string and will attempt to interpret it instead of building any templates.

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.