Implementing MIDlet lifecycle requirements

To make your MIDlet conform to the lifecycle requirements, it must follow the conditions described in this section. To better demonstrate these requirements, their use in the Hello World MIDlet is presented as an example.

Every MIDlet must define three methods:

  • startApp

    The startApp method is called when the MIDlet is started. After startApp has completed, the MIDlet is in Active state and the Application Management Software allows it to hold resources. If a runtime exception occurs during the startApp call, the MIDlet is destroyed immediately.

    On Nokia devices, startApp cannot be called multiple times by default. However, from S60 3rd Edition FP2 onwards, a custom JAD attribute Nokia-MIDlet-Background-Event can be used to activate this feature. Use this attribute to design your MIDlet so that multiple calls can be made without errors.

    In the Hello World example, startApp checks whether any elements have been set as the current screen (Display) and creates an instance of the HelloScreen class if the screen has not been set. The HelloScreen instance is then set as the current screen:

    public void startApp()
{
    Displayable current = Display.getDisplay(this).getCurrent();
    if(current == null)
    {
        HelloScreen helloScreen = new HelloScreen(this, "Hello, world!");
        Display.getDisplay(this).setCurrent(helloScreen);
    }
}

  • pauseApp

    By default, the pauseApp method is never called, but it can be enabled with the Nokia-proprietary JAD attributes Nokia-MIDlet-Background-Event and Nokia-MIDlet-Flip-Close. Even if pauseApp is not called, it still needs to be included in the MIDlet.

    In the Hello World example, pauseApp is left empty:

    public void pauseApp()
{
}

    For an example of using pauseApp, see Enabling pauseApp() method calls in Java ME on Forum Nokia.

  • destroyApp

    The destroyApp method signals the MIDlet to terminate and places it in Destroyed state. During termination, all the MIDlet's resources are released and objects deleted. The MIDlet has five seconds to handle the destroyApp call, after which the AMS closes the application itself.

    The MIDlet can be closed in one of the following ways:

    • By pressing the End key

      Note: The Nokia-specific JAD attribute Nokia-MIDlet-No-Exit can be used to disable the MIDlet from exiting after pressing the End key.

    • By the AMS

    • By removing the memory card

    • By an out-of-memory situation

    The destroyApp method provides an unconditional parameter. If the parameter is set to false, the MIDlet is allowed to refuse its termination by throwing a MIDletStateChangeException. If the parameter is set totrue, the AMS terminates the MIDlet irrespective of what state the MIDlet is in.

    The Hello World example implements the MIDlet exit in two parts:

    1. First, the destroyApp method is initialized:

      public void destroyApp(boolean unconditional)
{
}

    2. The destroyApp method is then be called from the MIDlet. A common way to do this is to map the exit function to a softkey, as the Hello World example does in its HelloScreen class:

      private final HelloWorldMIDlet midlet;
private final Command exitCommand; // Exit command for closing the MIDlet in the device UI.

public HelloScreen(HelloWorldMIDlet midlet, String string)
{
    super("");
    StringItem helloText = new StringItem("", string);
    super.append(helloText);
    this.midlet = midlet;
    exitCommand = new Command("Exit", Command.EXIT, 1);
    addCommand(exitCommand);
    setCommandListener(this);
}

public void commandAction(Command command, Displayable displayable)
{
    if (command == exitCommand)
    {
        midlet.notifyDestroyed();
    }
}

      The notifyDestroyed method used in the example notifies the AMS that the MIDlet has entered Destroyed state. All the resources held by the MIDlet are reclaimed.

© Nokia 2010.