Trigger Tutorial

Application Trigger messages are SMS messages that target a specific port number on a mobile phone. These messages can be used to execute applications or perform actions within applications, without explicit user input. This article focuses on one of the main uses of this message, the ability to interact with the J2ME Push Registry in order to load or execute code within a Java MIDlet

Take a look at our Application Trigger API documentation for more information on how to send Application Trigger messages
Take a look Application Trigger Example Project to see an simple example of Application Trigger Messages in action.
View our application trigger for Windows Mobile page to get started on using this functionality with the Windows Mobile platform.

Push Registry

The Push Registry is essentially a lookup table within the Java Application Managment System (AMS) on a mobile device. A MIDlet supporting this functionality can add an entry to this registry either at install time or during the application runtime. This entry includes the name of the MIDlet as well as an assigned port number. When the MIDlet is not active, the Push Registry handles any push events that occur by activating the appropriate MIDlet to handle them. The Push Registry knows which MIDlet to activate as each MIDlet has to be registered on a different port. If the application is already active then the MIDlet is left to handle the event. The easiest way to register a port for a MIDlet is to do it statically by defining all the attributes in the JAD. This tutorial demonstrates how to register a MIDlet on the Push Registry statically.

There are severals ways to interact with the Push Registry, including triggers based on timers and incoming Bluetooth connections This article focuses on the use of SMS messages as the trigger mechanism. The following diagrams illustrates how the Push Registry fits in with the lifecycle of a MIDlet:

MIDlet activation and lifecycle

Resources to help you get started

The Wireless Toolkit (WTK)

The Wireless toolkit provides a good place to start when being introduced to the idea of Application Trigger messages. It allows an easy process to specify the static properties to register your MIDlet. To use the WTK it is necessary to download and install it, this also downloads a number of example applications that are useful to run.

http://java.sun.com/products/sjwtoolkit/

Netbeans IDE

Netbeans comes with a mobility pack add on, this can also be used to develop MIDlets using the Application Trigger mechanism. Netbeans is useful when developing the MIDlet as its offers a drag and drop interface to create the MIDlet interface . Developing this way does then limit the amount of code writing that can be done. It is also possible to write all the code yourself using Netbeans if you don't use the visual drag and drop process.

http://www.netbeans.org/

Eclipse IDE

Eclipse also offers a J2ME development add on called EclipseME. To use EclipseME you need to download Eclipse IDE and an emulator such as the Wireless Toolkit. Once these are installed follow these instructions on how to install EclipseME.

http://eclipseme.org/docs/installEclipseME.html

Definitions

Java Application Management System (AMS) The application management system is in control of each stage of the applications life-cycle, defined as installation, activation, execution and removal. The Push Registry is the section of the application management system that keeps track of all the MIDlets registered on their specific ports.
JAD File The JAD file describes a MIDlet, the description includes the name of the MIDlet and the location and size of the JAR file. The file may also contain other attributes defined by the Mobile Information Device Profile (MIDP) or by the developer. Attributes beginning with MIDlet- or MicroEdition- are reserved for use by the Application Management System.
JAR File Java ARchive file is a file that contains the class, image, and sound files for a Java application.
Install time Refers to the installation of the application. This is the setting up of the application on the device.
MIDlet A MIDlet is a MIDP application. A MIDlet is a managed application, it is managed by a special-purpose application-management software built into a device, often a cell phone or a two-way interactive pager. External management of the application makes sense in this context because it may be interrupted at any point by outside events.
Port Number This is the number used to define which port the MIDlet is registered with the Push Registry.
Run Time Refers to the actual execution of an application. <At run time> means while the applicaiton is running.
MIDP Mobile Information Device Profile. The Mobile Information Device Profile provides a basic J2ME application runtime environment targeted at mobile devices such as mobile phones.

References

For more information on Application Trigger messages have a look at the following links:

Application Trigger Tutorial

The first step to creating an Application Trigger is to set up the MIDlet so it will be registered successfully with the Push Registry

To create a MIDlet that uses the Push Registry you will need to download the most up to date version Java 2 Platform, Standard Edition (J2SE) and the Java Wireless Toolkit or Netbeans along with the mobility pack.

Wireless Toolkit Tutorial

The first step is to define the attributes for the Push Registry:

Start by creating a new project using the Wireless Toolkit.
Click settings, this will present you with a new window with a menu on the left hand side.
Under API section select the Target Platform as JTWI.
Select the User Defined section. This allows you to define the properties of your application that can later be used in your development. This allows you to define your SMS port number within the properties of the application rather than having to hard code it, and then retreive the SMS port using the method below. This means to change the port you only have to change it in one place, allowing easy maintenance.

This code shows how the SMS port can be retrieved from the applications properties.
```
public SMSReceive() {
    smsPort = getAppProperty("SMS-Port");
    //...
}
```
Within the MIDlet section it is necessary to define the details about the MIDlet you are creating i.e. the Name, any Icon you want for it, and where the class is found. If you are not defining any packages then the class is just the name of your file. When you created the new project these details where filled in so edit them as necessary.
In the Push Registry section you need to define all the MIDlet attributes. Click the add button to add a new entry. In the connection box you need to define the connection type and the port your want registered for the MIDlet. This should be the same as the port you defined in the User defined section. For example if you want the MIDlet to be activated by an SMS message on port 6666 enter sms://:6666 as the connection URL. The class is just the name of the application you want to be triggered by an SMS message and any packages you have defined it in. The allowed sender box is used to define who is allowed to trigger the application, to allow SMS messages from anyone just enter * in the box. To restrict who can trigger you application via an SMS message specify a URL in the allowed sender box and then messages just from this URL will be able to trigger the application.
It is now necessary to set the permissions for the MIDlet. Select the permissions by selecting the permissions icon and add the following using the tree structure:
```
javax/microedition/io/Connector/sms
javax/wireless/messaging/sms/receive
javax/microedition/io/PushRegistry
```
Once your application is created and transfered to a mobile device it will be registered on port 6666.
Now the Push Registry details are set up it is time to create your application. This Application Trigger function offers its self to a number of exciting applications.

Netbeans Tutorial

The first step is to define the attributes for the Push Registry:

Start by creating a new project using Netbeans- Select file, New Project, Mobility, Mobile Application.
Click settings, this will present you with a new window with a menu on the left hand side.
Under the Platform section select the Target Platform as CLDC/MIDP.
Select the Application Descriptor section. This section allows you to define the properties of your application that can later be used in your development. For example you can define your SMS port to be used in this section and then within your code request the port number. This code shows how the SMS port can be retrieved from the applications properties.
```
public SMSReceive() {
    smsPort = getAppProperty("SMS-Port");
//...
}
```
Within the MIDlets section it is necessary to define the details about the MIDlet you are creating i.e. the Name, any Icon you want for it, and where the class is found. If you are not defining any packages then the class is just the name of your file. When you created the new project these details where filled in so edit them as necessary.
In the Push Registry section you need to define all the MIDlet attributes. Click the add button to add a new entry. In the connection box you need to define the connection type and the port your want registered for the MIDlet. This should be the same as the port you defined in the User defined section. For example if you want the MIDlet to be activated by an SMS message on port 6666 enter sms://:6666 as the connection URL. The class is just the name of the application you want to be triggered by an SMS message and any packages you have defined it in. The allowed sender box is used to define who is allowed to trigger the application, to allow SMS messages from anyone just enter * in the box. To restrict who can trigger you application via an SMS message specify a URL in the allowed sender box and then messages just from this URL will be able to trigger the application.
It is now necessary to set the permissions for the MIDlet. Select the API permissions tab then add the following permissions by clicking the add button and then entering the following.
```
javax.microedition.io.Connector.sms
javax.wireless.messaging.sms.receive
javax.microedition.io.PushRegistry
```
After further development it may be necessary to add more permissions, these defined permissions just allow the application trigger mechanism to work.
Once your application is created and transfered to a mobile device it will be registered on port 6666.
Now the Push Registry details are set up it is time to create your application. This Application Trigger function offers its self to a number of exciting applications.

Creating the MIDlet

A MIDlet activated by an Application Trigger message will have to handle incoming messages so you will need to import the javax.wireless.messaging library. Any application to be triggered by an SMS message will need to implement the MessageListener interface and perform an action when this receives a message.

public class SMSReceive extends MIDlet 
    implements CommandListener, Runnable, MessageListener {
    //......
}

Below I have listed all the methods I feel are important with the handling of the SMS messages and their content. It is important to have a method that runs when a message is received. This method below creates and starts a new thread to run the application or it could be edited to perform an action if the application is already running when the message is received..

public void notifyIncomingMessage(MessageConnection conn) {
    if (thread == null) {
        done = false;
        thread = new Thread(this);
        thread.start();
    }
}

As you are creating a MIDlet it is necessary to create the startApp method that runs when you choose to run the application.

This will need to perform similar actions to the above method except it will need to create the message connection.The smsPort is obtained from the MIDlets properties as shown in the above section about registering the MIDlet.

public void startApp() {
    String smsConnection = "sms://:" + smsPort;
    if (smsconn == null) {
        try {
            smsconn = (MessageConnection) Connector.open(smsConnection);
            smsconn.setMessageListener(this);
        } catch (IOException ioe) {
            ioe.printStackTrace();
        }
    }
    //... 
}

Once a message has been received by an application it is useful to be able to retrieve the contents of the message. This can be done simply using the method below..

public String receiveMessage(){
    try{
        senderAddress = msg.getAddress();
        myString = ((TextMessage)msg).getPayloadText();
        return myString;
    } catch(Exception e) {System.out.println("nothing received");}
    return null;
}

To view the complete source code for an Application Trigger MIDlet refer to http://www.javaworld.com/javaworld/jw-04-2006/jw-0417-push.html?page=2#resources