Ensure that a device runs a single instance of your application

Help Center

Search This Document

Download PDF

To improve the efficiency of your application, you should make sure that the BlackBerry® device runs only one instance when search() is invoked in your ExternalSearchProvider implementation.

In your implementation of ExternalSearchProvider, import packages to help you discover which applications are running on the device.

import net.rim.device.api.system.ApplicationDescriptor;
import net.rim.device.api.system.ApplicationManager;
import net.rim.device.api.system.ApplicationManagerException;
import net.rim.device.api.system.CodeModuleManager;

In search(), retrieve a handle for your application.

public void search(String keywords) {
    int modHandle = CodeModuleManager.getModuleHandle("MyApplication");

Retrieve an array of objects that represent the applications that are running on the device.

    ApplicationDescriptor[] allApps = ApplicationManager.getApplicationManager().getVisibleApplications();

Examine each element of the array to determine whether your application is running on the device.

    for(int i = allApps.length -1; i >= 0; --i) {
        if(allApps[i].getModuleHandle() == modHandle) {

If your application is running, send the search keywords to it. Invoke postGlobalEvent() to send your application a message that it should display a screen with the results for the new keywords. You need to detect a global event that is posted to your GUID in your application's constructor, .
```
            int procID = ApplicationManager.getApplicationManager().getProcessId(allApps[i]);
            ApplicationManager.getApplicationManager().postGlobalEvent(procID,
            your application's GUID, 0, 0, keywords, null);
        }
    }
```
If your application is not running on the device, retrieve an ApplicationDescriptor object that represents your application.
```
    ApplicationDescriptor[] myAppDes =  CodeModuleManager.getApplicationDescriptors(modHandle);
```

Start your application. Pass the search keywords as an argument. In your application's constructor, you need to detect whether there is an argument that contains search keywords.

    try {
        ApplicationManager.getApplicationManager().runApplication(new ApplicationDescriptor(myAppDes[0], new String[]{keywords}));
        }
        catch(ApplicationManagerException e)
        {
            // Process the error condition
        }
    }
}

In your application class, import the net.rim.device.api.system.GlobalEventListener package to listen for global events.
```
import net.rim.device.api.system.GlobalEventListener;
```

Import the UiApplication class.

import net.rim.device.api.ui.UiApplication;

Register your application to listen for global events, such as the one that you created in step 5, and display your first screen.

public class MySearchProviderApp extends UiApplication implements GlobalEventListener {

    public MySearchProviderApp(String searchKeywords) {
        addGlobalEventListener(this);
        pushScreen(new MySearchScreen(searchKeywords));
    }

Implement eventOccured() to respond to global events.

    public void eventOccurred(long guid, int data0, int data1, Object object0, Object object1) {

If your application is running on the device, close the existing screen and display another screen.

        if(guid == G53DDE84S97JHVEK390) {
            if(object0 instanceof String) {
                popScreen();
                pushScreeen(new MySearchScreen((String) object0));
                requestForeground();
            }
        }
    }

Test for search keywords in the arguments for the main method. Start your application with the keywords that are given, or with an empty string if no keywords are given.

    public static void main(String[] args) {
        String searchKeywords = "";
        if(args != null  && args.length > 0) {
            searchKeywords = args[0];
        }
        MySearchProviderApp app = new MySearchProviderApp(searchKeywords);
        app.enterEventDispatcher();
    }
}

Next topic: Inserting data when a device starts

Previous topic: Using other search engines

Was this information helpful? Send us your comments.

Global Navigation

Help Center

Local Navigation

Ensure that a device runs a single instance of your application