MIDlet lifecycle

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 Series 40 devices, startApp cannot be called multiple times by default. On Nokia Asha software platform devices the startApp method is called when the MIDlet is resumed (for example, after a call).

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 on Series 40 devices.

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()
{
}

The hideNotify and showNotify methods are called when a Canvas application is forced to the background by an incoming call and when it is set to the foreground respectively. These methods can be used to pause network transactions, media playback, location retrieval or UI/drawing operations while the application remains in the background. On Nokia Asha software platform devices however, the pauseApp is properly called when the MIDlet is forced to the background, so pausing these operations can be implemented within pauseApp.

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

• By the AMS

• By removing the memory card

• By an unchecked exception (for example, an uncaught IOException), an external to the application error (for example, an OutOfMemoryException), or a runtime exception caused by a logical programming error.

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 to true, 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. The destroyApp() method will not be called in this case, but all necessary cleanup operations and release of resources need to be performed as they would have, if the destroyApp() had been called.