Package net.rim.device.api.unifiedsearch

Provides classes for using the Unified Search Framework.

See:
Description

Class Summary

SearchField	Metadata about the searchable content an application inserts into the Unified Search Framework.
SearchFieldCriteria	Maps search keywords to specific search fields.
SearchFieldCriteriaList	A list of SearchFieldCriteria objects.
SearchResponse	A response the Unified Search Framework returns when an application initiates a search operation.
UnifiedSearchServices	Provides services for an application to initiate a search in the Unified Search Framework.

Package net.rim.device.api.unifiedsearch Description

Provides classes for using the Unified Search Framework.

The Unified Search API helps you register your application data in the Unified Search Framework to make your content discoverable by users. You can control whether your data is searchable by the Universal search app on the Home screen, other applications on the device, or your application only. You can also search for data in other applications that choose to register their content in the Unified Search Framework.

• Content Registration
• Search

Content Registration

Your application communicates with the Unified Search Framework using the AppContentManager and AppContentListener classes. To make your content searchable, wrap your application data in a SearchableEntity and provide entity management through a related EntityBasedSearchable.

1. Wrap your data in SearchableEntity
2. Create an EntityBasedSearchable for your SearchableEntity objects
3. Insert new content using the AppContentManager
4. Listen for results with AppContentListener

Wrap your data in SearchableEntity

A SearchableEntity is the smallest unit of data that an application can submit to the Unified Search Framework. The Framework will index these objects for consideration during search operations. An application that initiates a search will receive the results in the form of SearchableEntity objects.

Before your expose your data, you will need to prepare your metadata:

1. Decide which properties of your object will be searchable.
2. Create an array of SearchField objects. Each SearchField object should name one searchable property of your data.
3. Create a SearchFieldCriteriaList object.
4. Populate your SearchFieldCriteriaList with SearchFieldCriteria objects. Each SearchFieldCriteria pairs a SearchField with the searchable data for that field, for a particular searchable entity.

   For example, if you had "frozen pizza" objects with three toppings each and wanted to index your content based on the toppings, you might write:

               FrozenPizza myfrozenpizza = frozenpizzas[1];
               SearchField searchfields[] = new SearchField[3];
               sfcl = new SearchFieldCriteriaList();
               
               searchfields[0] = new SearchField("First Topping");
               searchfields[1] = new SearchField("Second Topping");
               searchfields[2] = new SearchField("Third Topping");
               
               for (int i = 0; i < 3; i++) {
                   sfcl.addCriteria(new SearchFieldCriteria(searchfields[i], new String[]{myfrozenpizza.getTopping(i)}));
               }
           

5. Optional: Prepare an icon for this entity. See the ImageFactory class for more information on creating icons.

While implementing methods from the SearchableEntity interface, you should note:

• getData should return your application data object.
• getIcon should return an icon for this entity. Applications that receive this SearchableEntity in a search result may choose to display an icon (see the Universal Search feature on the Home screen). You can set an icon in the Searchable that manages this entity to display the same icon for all entities. Implement this method to display a different icon. See the ImageFactory class for more information on creating icons.
• getSearchCriteria should return the SearchFieldCriteriaList you prepared above.
• getUiActions allows you to define what options display on context-menu when a user clicks on your entity in a list of search results.

Create an EntityBasedSearchable for your SearchableEntity objects

Your implementation of the EntityBasedSearchable interface is responsible for managing the interaction between your SearchableEntity objects and the Unified Search Framework. When you register your EntityBasedSearchable, the Unified Search Framework will call the getSearchableEntities method to index your data. If the Framework detects that its content index and your data are not synchronized, your application may be required to resubmit its data using this method as well.

The Framework will request that your application prepare data for submission by calling the EntityBasedSearchable.load method. When your application data is ready for submission, you should invoke the completed method on the NotificaionListener object supplied.

The Framework may need interrupt your load operation. In this case, it will invoke the EntityBasedSearchable.pause method. When the Framework decides that your operation can continue, it will invoke the EntityBasedSearchable.resume method. Your application should respond to these events appropriately. To continue with the frozen pizza example from above:

public class FrozenPizzaSearchable implements EntityBasedSearchable {
    
    private FrozenPizzaEntity _pizzas;
    private final Object _monitor = new Object();
    private boolean _booWait = false;

    ...
    
    public void load(NotificationListener observer, int loadType) {

        Vector frozenpizzas = PizzaManager.getPizzas();
        int size = frozenpizzas.size();
        if (size < 1) {
            _pizzas = new FrozenPizzaEntity[0];
        } else {
            _pizzas = new FrozenPizzaEntity[size];
        }
        
        Enumeration enuPizza = frozenpizzas.elements();
        int count = 0;
        
        while (enuPizza.hasMoreElements()) {
            if (_booWait){
                try {
                    synchronized(_monitor) {
                        observer.partiallyCompleted(this, null, NotificationListener.TYPE_SEARCHABLE);
                        _monitor.wait();
                    }
                } catch (InterruptedException e){
                        observer.error(e);
                        return;
                }
            }
            FrozenPizza pizza = (FrozenPizza) enuPizza.nextElement();
            _pizzas[count++] = new PizzaEntityEntity(pizza, this);
        }
        observer.completed(this, NotificationListener.TYPE_SEARCHABLE);
    }
    

    public void pause() {
        _booWait = true;
 
    }

    public void resume() {
        _booWait = false;
        synchronized(_monitor) {
            _monitor.notifyAll();
        }
    }
}

Once you notify observer that your data is ready for submission, the Framework will call getSearchableEntities to retrieve an array of your searchable entities. At that time, you return an array similar to the _pizzas array populated in the sample above.

Insert content using AppContentManager

You can insert new content into the Unified Search Framework on your own schedule using AppContentManager:

1. Prepare an array of your SearchableEntity objects.
2. Register the EntityBasedSearchable for those searchable entities with the framework using the register method.
3. Invoke the insertContent method on an instance of AppContentManager; supply the array you prepared in step 1, a reference to your implementation of AppContentListener, and the registration token returned to you acquired in step 2.

Listen for results with AppContentListener

The Unified Search Framework will notify your application about the result of content operations (like insertContent; see AppContentManager for others) via your implementation of AppContentListener. The Framework will pass an integer variable representing the number of items entities affected by the operation.

Search

There are two phases to conducting a search using the Unified Search API. First, your application must configure and initiate the search operation. Second, you application processes the results received from the Unified Search Framework.

Configure and initiate a search

Your application will initiate a search using the UnifiedSearchServices class. In the simplest case, you can search all data sources by submitting at least one keyword phrase to the Unified Search Framework. The Framework trims leading and trailing white space in phrases. Keywords within a phrase are combined using a logical AND operation. Search results for multiple phrases are combined using a logical OR operation.

Optionally, you can choose limit the scope of the search by selecting which Searchable data sources, and which search fields within that searchable, to consider.

Note: steps 2 to 5 are optional
1. Gather the keywords for your search.
2. Decide which Searchable data sources to consider. Use the getDeviceSearchables method to retrieve a list of searchables on the device.
3. Decide which fields within each searchable data source to consider. Invoke the defineSupportedSearchFields method on each Searchable to retrieve an array of SearchField objects.
4. Arrange your Searchable objects into an array.
5. Arrange your search fields into a two-dimensional array: the first dimension corresponds to the Searchable objects from the previous step; the second dimension contains your SearchField objects.
6. Retrieve an instance of UnifiedSearchServices using the getInstance method.
7. Invoke the search method.

Note that the UnifiedSearchServices.search method blocks thread execution until it is complete. It should not be run from the main event thread.

Reteive your search results

The search method will return a SearchResponse object that contains your search results. The data returned in SearchResponse is arranged by the Searchable and SearchField that generated matches on the keywords your application submitted. The getSearchResults method allows three ways to retrieve the SearchableEntity objects returned by the Unified Search Framework.

getSearchResults returns:

• an array of SearchableEntity when you pass a Searchable and a SearchField.
• a Hashtable when you pass a Searchable. In the Hashtable returned, the keys are the SearchField objects, and the values are SearchableEntity objects.
• a Hashtable when you pass nothing. In the Hashtable returned, the keys are the Searchable objects, and the values are another Hashtable of SearchField and SearchableEntity objects.

You can retrieve an array of Searchable objects in the search result by invoking the getSearchables method. Similarly, getSearchFields will return an array of SearchField objects for a particular Searchable.

SearchableEntity objects contain metadata (title, summary, time stamp, etc.) to help you decide how to process the data. When you are ready, you can retrieve the raw data using the getData method.