com.ibm.di.server
Class SearchCriteria

java.lang.Object
  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:

• 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";
        }
 
        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.