Implementing MIDlet lifecycle requirements

To make your MIDlet compatible with the lifecycle requirements, it must follow the conditions described in this section. To better demonstrate these requirements, their usage in the HelloWorldPlus S60 MIDlet is presented as an example.

Every MIDlet must have three methods:

• startApp

  startApp method is called when the MIDlet is started. After startApp, the MIDlet is in Active state and the AMS allows it to hold resources. If a runtime exception occurs during startApp, the MIDlet will be destroyed immediately.

  In Nokia devices, startApp can not be called multiple times by default. However, from S60 3rd Edition FP 2 onwards, a custom JAD-attribute Nokia-MIDlet-Background-Event can be used to activate this feature, Therefore, developers should design the MIDlet so that multiple calls can be accomplished without errors.

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

      private TextScreen textScreen;
  
      public void startApp() {
          if (display == null) {
              // First time we've been called.
              display = Display.getDisplay(this);
              textScreen = new TextScreen(this, "Hello World!");
          }
          display.setCurrent(textScreen);
      }

• pauseApp

  By default, pauseApp() isn't called but it can be set to be called with 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 S60 or Series 40 MIDP implementations.

  In HelloWorldPlus example, pauseApp() is left empty.

      public void pauseApp() {
      }
  

• destroyApp

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

  A MIDlet can be closed in several different scenarios

  • an End key press

  • by AMS

  • memory card removal

  • out-of-memory situation

  The destroyApp method provides an unconditional parameter; if it 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.

  HelloWorldPlus implements the MIDlet exit in two parts. First, the destroyApp method is initialized and another method to handle the application exit (by calling destroyApp) is created:

      public void destroyApp(boolean unconditional) {
      }
  
      public void exitRequested(){
          destroyApp(false);
          notifyDestroyed();
      }
  

  The destroyApp method can then be called from the MIDlet. A common way to do this is to map the exit function to a softkey, as the HelloWorldPlus MIDlet does in the TextScreen class.

  	private static final Command CMD_EXIT = new Command("Exit", Command.EXIT, 1);
  
      TextScreen(HelloWorldPlusMIDlet midlet, String message) {
          super("Hello World Plus MIDlet");
          this.midlet = midlet;
  
          addCommand(CMD_EXIT);
          setCommandListener(this);
      }
  
  	public void commandAction(Command cmd, Displayable source) {
          if (cmd == CMD_EXIT) {
              midlet.exitRequested();
      }

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