Dec 8, 2007

Integrate the Browser into a Java App - BlackBerry Tips,Trick,Tools & Hacks

Berry 411 is built using a Java client that launches a web browser. This is a powerful and convenient way to build mobile applications.

The Java client provides instant accessibility from the Home screen and a rich native BlackBerry UI. The browser results screen allows for zero-install deployment of new features, easy display of rich text and graphics, and linking to the expanding array of mobile-friendly web content.

The BlackBerry is especially well suited to building this sort of application. The Back button works as expected when going back from a browser page to the client application that launched it. Using the built-in browser network configuration avoids many of the configuration hassles of direct network access, which requires a number of carrier-specific parameters.
Launch the Browser from Java

In this hack, we'll build an application to do reverse phone number lookups, going from a phone number to a name and address. The Java client displays a titlebar and input field, filtered to limit the user's input to 10 digits. When the user selects Search from the menu (see Figure 9-4), the application launches a web page (in this case, an existing Infospace service) to display the results, shown in Figure 9-5.


Figure 9-4. Java client

Figure 9-5. Web results


Even in this very simple form, the hybrid approach has advantages over a pure browser solution. The application launches instantly and has a degree of control over the user's input, which could not be achieved in a browser. It would not be difficult to extend this application to take further advantage of the rich Java client; for example, it could allow the user to select a phone number from his Address Book to look up.
The Code

/**
* Reverse Phone Directory Lookup Application
* This sample uses a Java frontend to prompt the user for a phone
* number, then launches a web page to display the corresponding address.
*/
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.component.*;
import net.rim.device.api.ui.container.*;
import net.rim.device.api.i18n.*;
import net.rim.device.api.system.*;

import net.rim.device.api.collection.util.*;

public class BrowserLauncher extends UiApplication
{
public static void main(String[] args)
{
BrowserLauncher theApp = new BrowserLauncher( );
theApp.enterEventDispatcher( );
}

public BrowserLauncher( )
{
pushScreen(new SearchScreen( ));
}

class SearchScreen extends MainScreen
{
BasicEditField _phoneNumberEntry;

SearchScreen( )
{

super(DEFAULT_MENU | DEFAULT_CLOSE);
setTitle(new LabelField("Reverse phone lookup",
LabelField.ELLIPSIS | LabelField.USE_ALL_WIDTH));

_phoneNumberEntry = new BasicEditField("Phone number: ",
"", 10,
BasicEditField.NO_NEWLINE | BasicEditField.FILTER_INTEGER);
add(_phoneNumberEntry);
addMenuItem(new MenuItem("Search", 1, 1) {
public void run( ) {
String phone = _phoneNumberEntry.getText( );
launchBrowser("http://www.infospace.com/" +
"_1_L5UTTJ03LEBVO_ _infow.sbcw" +
"/x/app/rev/detail.xhtml?top=&area=" +
phone.substring(0,3) + "&exchange=" +
phone.substring(3,6) +
"&phend=" + phone.substring(6,10) +"&ran=24");
}
});
}
}
static private boolean launchBrowser(String baseUrl)
{
boolean retval = true;

int handle =
CodeModuleManager.getModuleHandle("net_rim_bb_browser_daemon");

if (handle <=0 ) {
retval = false;
}
else {
ApplicationDescriptor[] browserDescriptors =
CodeModuleManager.getApplicationDescriptors(handle);

if (browserDescriptors == null )
{
retval = false;
}
else {
if ( browserDescriptors.length <=0 ) {
retval = false;
}
else {
String[] args = {"url", baseUrl};
ApplicationDescriptor descriptor =
new ApplicationDescriptor(browserDescriptors[0],
"url invocation", args,
null, -1, null, -1,
ApplicationDescriptor.FLAG_SYSTEM);
try {
ApplicationManager.getApplicationManager( ).
runApplication(descriptor);
}
catch(ApplicationManagerException e) {
retval = false;
}
}
}
}
return retval;
}
}

Save the code as BrowserLauncher.jav'a: this is the sole class in this application. The key function is launchBrowser( ), which includes some black magic to launch the user's default browser with the requested URL. The code links to the Infospace reverse directory page, providing the user's input as parameters.
Compile and Run the Application

To compile this code, use the Research In Motion JDE, which you can download from the BlackBerry web site. The code has been successfully tested with Versions 3.7 and 4.0 of the JDE.

Create a new workspace and project in the JDE, and add BrowserLauncher. java to the project. (If you'd like to save yourself the typing, you can download a ZIP archive, including the entire project, from http://thebogles.com/browserlauncher.zip.)

Select "Go" from Debug menu, and the JDE will build the application and launch the BlackBerry simulator, including the application. You should also launch the MDS simulator from the JDE Start menu item to allow the application to access the network.

Once the simulator is launched, you can scroll to the BrowserLauncher application on the Home screen and click on it, by using your mouse scroll-wheel. Type in a listed 10-digit phone number, click on "Search in the menu, and you should see the results displayed in the browser.
Sign and Distribute the Application

Launching the browser is considered a "controlled API" by Research In Motion. To run the application on a real BlackBerry, you will also need to register for a code signing key and sign the application [Hack #98].

No comments: