×

MIDlet lifecycle

The MIDlet lifecycle defines the execution states of a MIDlet, as well as valid state transitions. The lifecycle can be considered to start when the MIDlet is installed on a device and it ends when the MIDlet is uninstalled. From a developer's point of view, all the important aspects of the lifecycle functions are concentrated on the time when the MIDlet is in different stages, such as start, active or close. When a MIDlet suite is installed on a device, its classes, resource files, arguments, and persistent storage are kept on the device and ready for use. The MIDlets are managed and made available through the device Application Management Software (AMS).

Implementing MIDlet lifecycle requirements

To make your MIDlet conform to the lifecycle requirements, it must follow the conditions described below. 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 Asha software platform and Series 40 devices, startApp cannot be called multiple times by default.

    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 Nokia Asha software platform and 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.

  • 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.

Interplay with Application Management Software

The user interface, like any other resource in the MIDP API, works within the context of the Application Management Software (AMS). When designing an application, the AMS behaves as follows:

  • The Display class represents the display manager of the AMS.

  • To obtain a Display object, getDisplay() method is callable starting from MIDlet’s constructor until destroyApp() has returned.

  • Display class has the methods setCurrent() and getCurrent() for setting the current Displayable and retrieving the current Displayable.

  • The Display object remains the same until destroyApp() is called.

  • The Displayable object set by setCurrent() is not changed by the AMS.

  • On Series 40, setCurrent(null) does nothing as the platform does not support Java application multitasking for normal MIDlets.

User may force MIDlet to exit by pressing the Call Termination key or long pressing the back key or swiping the screen on Nokia Asha software platform devices.


Last updated 9 October 2013

Back to top

Was this page helpful?

Your feedback about this content is important. Let us know what you think.

 

Thank you!

We appreciate your feedback.

×