Welcome to the official BlackBerry Support Community Forums.

This is your resource to discuss support topics with your peers, and learn from each other.

inside custom component

Web and WebWorks Development

Sample Emergency Contact List Application Demonstrating Push Technology in WebWorks

by Retired ‎08-04-2011 03:16 PM - edited ‎11-07-2011 01:23 PM (7,761 Views)



This smartphone application was developed in BlackBerry® WebWorks™ and implements various aspects of Push technology to receive Emergency Contact List data via JSON. Data is stored persistently on the device through HTML5 Database implementation.


The sample is designed to work out-of-the-box with a 5.0+ device/MDS-CS simulator pair running on the same PC as the server-side component but is configurable to push data to live devices as well.


Server-Side Component




Launching the Server-Side Component

The server-side component comes with a pre-compiled, executable JAR file as well as complete source. This leaves the user with a few options for launching the application.


Before you can launch the provided JAR file, you will need an instance of Oracle's JDK installed on your PC. The recommended version at this time is JDK6; it is necessary to use the 32-bit version of the JDK regardless of your operating system. Only one JDK/JRE pair should be installed on a PC at a time.


Additionally, you will need to ensure that your Path environment variable has been configured to point at the bin folder of your JDK.



If your Java runtime is configured as the default JAR handler on your PC, you can simply double-click the provided JAR file to launch the server-side component.


Command Prompt

If your PC has a custom default handler for JAR files, you can open a command prompt window, navigate to the folder housing the JAR file, and execute the following command to launch the server-side component:

java -jar ECLwwServer2.jar


Eclipse IDE

The full source for the server-component has also been provided in Mainframe.java. A Java application can be created in Eclipse (or your preferred Java IDE) and the provided source imported. From there, you can launch the application within Eclipse with the added benefit of being able to make modifications and debug the code.


Configuring MDS and Device Settings

The default values provided in the server-side component are designed to allow a push to be sent to a device/MDS-CS simulator pair running on the same PC as the server-side component.

  • localhost refers to your PC.
  • 28080 is an arbitrary push port for your MDS-CS simulator.
  • 2100000A is the default PIN associated with BlackBerry Device Simulators.
  • 233 is the default push listener port implemented in the client-side component.

To get the MDS Address and MDS Port values for a live device, the best approach is to confirm these with your BES Administrator. Please note that the MDS Port value refers to the incoming push port assigned to your BES.


To get the Device PIN of a device/simulator, you can look this value up within your Device Options or by connecting your live device to, and launching, BlackBerry Desktop Manager.


Alternatively, for a device simulator, you can check within the [model].bat file used to launch the simulator for the Device PIN that has been assigned.


Example: 9810.bat

@echo off 
fledge.exe /app=Jvm.dll /handheld=9810 /session=9810 /app-param=JvmAlxConfigFile:9810.xml /data-port=0x4d44 /data-port=0x4d4e /pin=0x2100000A /app-param=DisableRegistration /app-param=NoTutorial


The Device Port should be set to match the listening port defined within the client-side component. By default, this value is set to 233.


Pushing Data to the Client-Side Component

Before any data can be received by the target device/simulator, the client-side componenet must be installed and running on your target.


The Push Content section allows you to edit various data fields which will be combined into a JSON String that is ultimately pushed to the target. For convenience, a Randomize button has been included to populate the fields for testing purposes. Add Contact will append the existing information to the current JSON String.


The JSON String is an editable field for customization. This also allows the user to save a copy of the String for future use, as well as paste an existing String into the field if they already have existing data to push. The JSON String can be Reset to a blank value.


Once you are ready, Send Push will initiate the data push to the target.


The Push Status section will provide information regarding your push.



  • The pushID (randomly generated, positive integer) and time that the push is initiated.
  • The full Push URL for your MDS-CS and target.
  • The HTTP Response from the MDS-CS server behind the Push URL.
  • Any additional messages returned by the MDS-CS or Exceptions thrown while closing our connection.

Generally, additional messages are only returned by the MDS-CS if an error occurs and will provide a more descriptive response to accompany the HTTP Response. Exceptions are documented for trouble-shooting purposes.


Client-Side Component



ECL Webworks Homescreen


Populated Data


Detailed Profile Information


Activity Log


Building the Client-Side Component

The sample source provided can be packaged into a BlackBerry application using the latest WebWorks Packager. For a detailed guide on packaging a WebWorks application, please refer to the WebWorks Documentation.


Once complete, you should have the necessary distributables (COD, ALX, JAD, etc.) files generated for deployment to a device simulator or live device.


Installing the Client-Side Component

To install your application on a live device, there are a number of options available including:

  • JavaLoader (requires COD file and USB connection to PC.)
  • Desktop Manager (requires COD, ALX files and USB connection to PC.)
  • Over-The-Air (requires COD, JAD files and wireless connection to hosting server.)

For additional approaches and specific details, please refer to the application deployment guide.


If you are distributing to a device simulator, you can also launch the simulator first, and then load the COD file directly through the simulator menu.



Launching the Client-Side Component

The client-side component is designed to auto-start and run in the background while the device is turned on. Therefore, as long as the application is installed and your device is turned on, you should be able to receive incoming data pushes. By default, incoming data is expected on port 233.


If a data push is received while the client-side component is in the foreground, the contact list will automatically re-populate with the new data.


When the application closes, it is currently designed to request the background instead of fully exiting. If the application is in the background when a data push is received, the application icon will update with a red splat to notify the user.


Activity Log

The Activity Log is intended for debugging/informational purposes with most recent items being listed at the top of the log.


Every time one of the JavaScript functions inside actions.js are triggered, they will announce themselves within the Activity Log. The subscribe and unsubscribe methods will also announce success/failure.


Throughout actions.js, each function wraps its content within a try/catch block; any Exceptions that are encountered will also be documented within the Activity Log.


Special Notes

  • NetBeans® IDE was leveraged to quickly construct a graphical user interface.
  • For enhanced application functionality as well as CSS styles, JQuery™ Mobile is leveraged.
  • Application Deep Linking was also used to enhance functionality and invoke various native applications for specific contact details.
  • While this sample application implements a BES Push Listener, similar steps can be taken to implement a BIS Push Listener.


Additional Resources


Users Online
Currently online: 10 members 826 guests
Please welcome our newest community members: