com.genesyslab.ail
Interface SearchContactTemplate


public interface SearchContactTemplate

This class defines the template for contact searches. It is based on:

To get an instance of this class, call the createSearchContactTemplate method of the ContactManager.

First, define a FilterTreeElement object to delimit the contact search. This filter tree uses assignment and logical expressions, for example, (LastName="B*" and FirstName="A*"). Without a filter tree, searching a contact is not possible.

Note: A FilterTreeElement can be either a FilterNode or a FilterLeaf instance.

To activate quick search, set the SearchPrimaryValueOnly flag to true by calling the setSearchPrimaryValueOnly(boolean) method. The search is restricted to attributes' primary values, regardless of the definition of FilterLeaf objects (which are part of the filter tree).

If you deactivate quick search by setting the SearchPrimaryValueOnly flag to false, you can specify for each FilterLeaf object whether or not the search is restricted to the primary value of the attribute.

The attributes you want to search on must be searchable and sortable. Please refer to the Contacts Server documentation.

Then, use this template to tune the returned list of matching contacts. For example, the following code snippet shows how to use the template to sort matching contacts by name, and to then retrieve each contact's last name, first name, and e-mail address.


// Results are sorted by names
mySearchTemplate.addSortAttribute(myLastNameMetadata, false);

// Contacts are returned with their last names,
// their first names, and all their e-mails
mySearchTemplate.addRetrieveAttribute(myLastNameMetadata, false);
mySearchTemplate.addRetrieveAttribute(myFirstNameMetadata, false);
mySearchTemplate.addRetrieveAttribute(myEmailAddressMetadata, false);

Note: If the DATABASE service is not available, that is, if UCS is not connected, you cannot use features associated with UCS, that is, contact search.

See Also:
ContactManager

Method Summary
 void addRetrieveAttribute(ContactAttributeMetaData attributeName, boolean primaryOnly)
          Adds an attribute that will be retrieved in result of the search function.
 void addSortAttribute(ContactAttributeMetaData attributeName, boolean reverse)
          Adds a sortable attribute, you can have many distinct sortable attributes.
 FilterLeaf createFilterLeaf()
          Creates a new simple expression for the filter.
 FilterNode createFilterNode()
          Creates a new complex expression for the filter.
 FilterTreeElement getFilter()
          Gets the filter of the search contact template.
 int getIndex()
          Gets the index of the first search contact item into the Contact Server.
 int getLength()
          Gets the length of the retrieved contact items.
 java.util.Map getRetrieveAttributes()
          Gets the Map of attributes and status options that will be loaded.
 boolean getSearchPrimaryValueOnly()
          Gets the search flag.
 java.util.Collection getSortAttributes()
          Returns a Collection of SortableContactAttribute instances.
 java.lang.String normalizeSearchValue(java.lang.String searchValue)
          Gets the search value, using escape characters that distinguish wildcards from normal characters.
 void removeRetrieveAttribute(ContactAttributeMetaData attributeName)
          Removes one attribute from the set of attributes that will be loaded from the Contact Server.
 void removeSortAttribute(ContactAttributeMetaData attributeName)
          Removes a sortable attribute.
 void setFilter(FilterTreeElement aFilterRoot)
          Sets the filter of the search contact template.
 void setIndex(int index)
          Sets the index of the first search contact item into the Contact Server.
 void setLength(int length)
          Sets the length of the retrieved contact items.
 void setSearchPrimaryValueOnly(boolean primaryOnly)
          Puts the search flag to true in order to look only for primary value, false flag for all values.
 

Method Detail

createFilterNode

FilterNode createFilterNode()
Creates a new complex expression for the filter.

Returns:
a filter tree element as FilterNode

createFilterLeaf

FilterLeaf createFilterLeaf()
Creates a new simple expression for the filter.

Returns:
a filter tree element as FilterLeaf

setFilter

void setFilter(FilterTreeElement aFilterRoot)
Sets the filter of the search contact template. FilterTreeElement can be a simple or complex expression.

Parameters:
aFilterRoot - the root filter element

getFilter

FilterTreeElement getFilter()
Gets the filter of the search contact template. FilterTreeElement can be a simple or complex expression.

Returns:
a filter tree element as FilterTreeElement

addSortAttribute

void addSortAttribute(ContactAttributeMetaData attributeName,
                      boolean reverse)
                      throws InvalidParameterException
Adds a sortable attribute, you can have many distinct sortable attributes. The first sortable attribute is the first main sorted column (second attribute is the second sorted column).

Parameters:
attributeName - as ContactAttributeMetaData.
reverse - as boolean.
Throws:
InvalidParameterException - if attribute name is wrong.

removeSortAttribute

void removeSortAttribute(ContactAttributeMetaData attributeName)
Removes a sortable attribute.

Parameters:
attributeName - as ContactAttributeMetaData.

getSortAttributes

java.util.Collection getSortAttributes()
Returns a Collection of SortableContactAttribute instances.

Returns:
a Collection of SortableContactAttribute.

setIndex

void setIndex(int index)
Sets the index of the first search contact item into the Contact Server.

Parameters:
index - as int (0 for the first item).

getIndex

int getIndex()
Gets the index of the first search contact item into the Contact Server.

Returns:
the index as int.

setLength

void setLength(int length)
Sets the length of the retrieved contact items.

Parameters:
length - as int (-1 for all).

getLength

int getLength()
Gets the length of the retrieved contact items.

Returns:
the length of the retrieved contact items.

addRetrieveAttribute

void addRetrieveAttribute(ContactAttributeMetaData attributeName,
                          boolean primaryOnly)
                          throws InvalidParameterException
Adds an attribute that will be retrieved in result of the search function.

Parameters:
attributeName - as ContactAttributeMetaData.
primaryOnly - for loading primary attribute only.
Throws:
InvalidParameterException - if attribute name is wrong.

removeRetrieveAttribute

void removeRetrieveAttribute(ContactAttributeMetaData attributeName)
Removes one attribute from the set of attributes that will be loaded from the Contact Server.

Parameters:
attributeName - as ContactAttributeMetaData

getRetrieveAttributes

java.util.Map getRetrieveAttributes()
Gets the Map of attributes and status options that will be loaded.

Returns:
a Map(ContactAttributeMetaData, boolean primaryOnly).

setSearchPrimaryValueOnly

void setSearchPrimaryValueOnly(boolean primaryOnly)
Puts the search flag to true in order to look only for primary value, false flag for all values.

Parameters:
primaryOnly - as boolean. default value: false.

getSearchPrimaryValueOnly

boolean getSearchPrimaryValueOnly()
Gets the search flag.

Returns:
true when looking for primary values only.

normalizeSearchValue

java.lang.String normalizeSearchValue(java.lang.String searchValue)
Gets the search value, using escape characters that distinguish wildcards from normal characters.

Use the returned string when calling the FilterLeaf.setValue(java.lang.String) method with wildcards.

Returns:
the normalized escape string.
See Also:
FilterLeaf