javax.microedition.midlet
Class MIDlet

java.lang.Object
  javax.microedition.midlet.MIDlet

public abstract class MIDlet
extends java.lang.Object

A MIDlet is a Mobile Information Device Profile application. The application must extend this class to allow the application management software to control the MIDlet and to be able to retrieve properties from the application descriptor and notify and request state changes. The methods of this class allow the application management software to create, start, and destroy a MIDlet. A MIDlet is a set of classes designed to be run and controlled by the application management software via this interface. The states allow the application management software to manage the activities of a MIDlet. It can select which MIDlet is active at a given time by starting and destroying them individually. The application management software maintains the state of the MIDlet and invokes methods on the MIDlet to notify the MIDlet of change states. The MIDlet implements these methods to update its internal activities and resource usage as directed by the application management software. The MIDlet can initiate some state changes itself and notifies the application management software of those state changes by invoking the appropriate methods.

Note: Some of the methods on this class signal state changes. The state change is not considered complete until the state change method has returned. It is intended that these methods return quickly.

Since:

MIDP 1.0

Constructor Summary

protected

MIDlet() Protected constructor for subclasses.

Method Summary

int	checkPermission(java.lang.String permission) Deprecated. The permissions model in this specification does not use named permissions.
protected abstract void	destroyApp(boolean unconditional) Signals the MIDlet to terminate and enter the Destroyed state.
java.lang.String	getAppProperty(java.lang.String key) Provides a MIDlet with a mechanism to retrieve named properties from the application management software.
static java.lang.String[]	getAppProperty(java.lang.String name, java.lang.String vendor, java.lang.String attributeName, java.lang.String attributeDelimiter) Provides a mechanism to retrieve and at the same time parse application property values from the application descriptor and the manifest of the MIDlet or bound LIBlets.
MIDletIdentity	getMIDletIdentity() Gets a MIDletIdentity instance associated with this MIDlet, which can be used to obtain a MIDlet's name, vendor, version, domain, and authorization state.
long	getSplashScreenTime() Gets the length of time that the application's splash screen has been shown to the user.
boolean	isSelectedScreenSaver() Checks if the MIDlet is the currently selected screen saver.
void	notifyDestroyed() Used by an MIDlet to notify the application management software that it has entered into the Destroyed state.
void	notifyPaused() Deprecated. The Paused state is deprecated; the application does not need to inform the implementation that it is quiescent.
protected void	pauseApp() Deprecated. Previously calls to pauseApp did not provide reliable information about system state changes. To be informed of changes in resources available to the application, use the listeners in the respective APIs. For example, to be notified that the application is not in the foreground, register a DisplayListener. The EventManager can be used to listen for system state changes.
boolean	platformRequest(java.lang.String URL) Requests that the device handle (for example, display or install) the indicated URL.
void	resumeRequest() Deprecated. MIDlets will not be paused and do not need to be resumed.
protected abstract void	startApp() Signals the MIDlet that it has entered the Active state.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MIDlet

protected MIDlet()

Protected constructor for subclasses. The application management software is responsible for creating MIDlets and creation of MIDlets is restricted. MIDlets should not attempt to create other MIDlets.

Throws:

java.lang.SecurityException - unless the application management software is creating the MIDlet.

Since:

MIDP 2.0

Method Detail

startApp

protected abstract void startApp()
                          throws MIDletStateChangeException

Signals the MIDlet that it has entered the Active state. In the Active state the MIDlet may hold resources. The method will only be called when the MIDlet is in the Paused state.

The use of MIDletStateChangeException to delay starting a MIDlet is deprecated. If MIDletStateChangeException exception is thrown it MUST be handled as a RuntimeException below.

If a Runtime exception occurs during startApp the MIDlet will be destroyed immediately. Its destroyApp will be called allowing the MIDlet to cleanup.

Throws:

MIDletStateChangeException - is thrown if the MIDlet cannot start now but might be able to start at a later time.

Since:

MIDP 1.0

pauseApp

protected void pauseApp()

Deprecated. Previously calls to pauseApp did not provide reliable information about system state changes. To be informed of changes in resources available to the application, use the listeners in the respective APIs. For example, to be notified that the application is not in the foreground, register a DisplayListener. The EventManager can be used to listen for system state changes.

Pausing of MIDlets is deprecated. The application management software MUST NOT call the pauseApp method. The MIDlet is not required to implement the pauseApp method. Classes in a MIDlet suite may call the pauseApp method but the state of the MIDlet MUST NOT be changed.

Since:

MIDP 1.0

destroyApp

protected abstract void destroyApp(boolean unconditional)
                            throws MIDletStateChangeException

Signals the MIDlet to terminate and enter the Destroyed state. In the destroyed state the MIDlet must release all resources and save any persistent state. This method may be called from the Paused or Active states.

MIDlets should perform any operations required before being terminated, such as releasing resources or saving preferences or state.

The use of MIDletStateChangeException to delay destruction of a MIDlet is deprecated. The destroyApp method MUST always be called with true to force termination. The MIDlet is put in the Destroyed state regardless of how this method terminates.

If a Runtime exception occurs during destroyApp then the exception is ignored and the MIDlet is put into the Destroyed state.

When an uncaught exception occurs in a thread, the thread MUST be stopped in accordance with the Java Language Specification MIDletStateChangeException - is thrown if the MIDlet wishes to continue to execute (not enter the Destroyed state). This exception is ignored and the MIDlet is destroyed.

Since:

MIDP 1.0

notifyDestroyed

public final void notifyDestroyed()

Used by an MIDlet to notify the application management software that it has entered into the Destroyed state. The application management software will not call the MIDlet's destroyApp method, and all resources held by the MIDlet will be considered eligible for reclamation. The MIDlet must have performed the same operations (clean up, releasing of resources etc.) it would have if the MIDlet.destroyApp() had been called.

Since:

MIDP 1.0

notifyPaused

public final void notifyPaused()

Deprecated. The Paused state is deprecated; the application does not need to inform the implementation that it is quiescent.

Pausing of MIDlets is deprecated. For backward compatibility and to avoid problems with existing MIDlets, calling notifyPaused in the Active state MUST cause startApp to be called immediately. The MIDlet is expecting a call to startApp to restore it to the Active state.

Invoking this method MUST NOT have any effect if the MIDlet is not in the Active state. A misbehaving MIDlet that continuously calls notifyPaused may be destroyed.

Since:

MIDP 1.0

getAppProperty

public final java.lang.String getAppProperty(java.lang.String key)

Provides a MIDlet with a mechanism to retrieve named properties from the application management software. The properties are retrieved from the combination of the application descriptor and the manifest. Refer to the MIDlet Suite Installation for the handling of attributes that appear in both application descriptor and manifest.

Parameters:

key - the name of the property

Returns:

A string with the value of the property. null is returned if no value is available for the key.

Throws:

java.lang.NullPointerException - is thrown if key is null.

Since:

MIDP 1.0

getAppProperty

public static final java.lang.String[] getAppProperty(java.lang.String name,
                                                      java.lang.String vendor,
                                                      java.lang.String attributeName,
                                                      java.lang.String attributeDelimiter)

Provides a mechanism to retrieve and at the same time parse application property values from the application descriptor and the manifest of the MIDlet or bound LIBlets. This method retrieves property value for a specific LIBlet or MIDlet, so the same property name is allowed to be used by multiple LIBlets without ambiguity in the same binding.

Parameters:

name - name of the LIBlet or MIDlet to retrieve named property information from. If both name and vendor are null , this retrieves information from the MIDlet JAD/Manifest

vendor - the vendor of the LIBlet or MIDlet

attributeName - the name of the property to retrieve

attributeDelimiter - The characters in this parameter are the delimiters for separating the retrieved property value into tokens. Delimiter characters themselves will not be treated as tokens. If this is null , the value is not tokenized.

Returns:

An array of string with the value of the property tokenized. null is returned if no value is available for the attributeName

Throws:

java.lang.NullPointerException - is thrown if attributeName is null.

Since:

MIDP 3.0

resumeRequest

public final void resumeRequest()

Deprecated. MIDlets will not be paused and do not need to be resumed.

Pausing of MIDlets is deprecated. Invoking this method MUST have no effect. The application management software maintains the MIDlet in the Active state.

Since:

MIDP 1.0

platformRequest

public final boolean platformRequest(java.lang.String URL)
                              throws javax.microedition.io.ConnectionNotFoundException

Requests that the device handle (for example, display or install) the indicated URL.

If the platform has the appropriate capabilities and resources available, it SHOULD bring the appropriate application to the foreground and let the user interact with the content, while keeping the MIDlet suite running in the background. If the platform does not have appropriate capabilities or resources available, it MAY wait to handle the URL request until after the MIDlet suite exits. In this case, when the requesting MIDlet suite exits, the platform MUST then bring the appropriate application (if one exists) to the foreground to let the user interact with the content.

This is a non-blocking method. In addition, this method does NOT queue multiple requests. On platforms where the MIDlet suite must exit before the request is handled, the platform MUST handle only the last request made. On platforms where the MIDlet suite and the request can be handled concurrently, each request that the MIDlet suite makes MUST be passed to the platform software for handling in a timely fashion.

If the URL specified refers to a MIDlet suite (either an Application Descriptor or a JAR), the application handling the request MUST interpret it as a request to install the named package. In this case, the platform's normal MIDlet suite installation process SHOULD be used, and the user MUST be allowed to control the process (including cancelling the download and/or installation). If the MIDlet suite being installed is an update of the currently running MIDlet suite, the platform MUST first stop the currently running MIDlet suite before performing the update. On some platforms, the currently running MIDlet suite MAY need to be stopped before any installations can occur.

If the URL specified is of the form tel:<number>, as specified in [RFC2806], then the platform MUST interpret this as a request to initiate a voice call. The request MUST be passed to the "phone" application to handle if one is present in the platform. The "phone" application, if present, MUST be able to set up local and global phone calls and also perform DTMF post dialing. Not all elements of [RFC2806] need be implemented, especially the area-specifier or any other requirement on the terminal to know its context. The isdn-subaddress, service-provider and future-extension may also be ignored. Pauses during dialing are not relevant in some telephony services.

Devices MAY choose to support additional URL schemes beyond the requirements listed above.

Many of the ways this method will be used could have a financial impact to the user (e.g. transferring data through a wireless network, or initiating a voice call). The component of the platform that handles the request is responsible for protecting the user from unexpected financial impacts. For example, some platforms may launch the appropriate application and populate the URL or phone number fields, but not take the action until the user explicitly clicks the load or dial buttons.

Parameters:

URL - The URL for the platform to load. An empty string (not null) cancels any pending requests.

Returns:

true if the MIDlet suite MUST first exit before the content can be fetched.

Throws:

javax.microedition.io.ConnectionNotFoundException - if the platform cannot handle the URL requested.

Since:

MIDP 2.0

checkPermission

public final int checkPermission(java.lang.String permission)

Deprecated. The permissions model in this specification does not use named permissions.

The Named Permissions of MIDP 2.x have been deprecated. For MIDP 3.0 applications, calling checkPermission throws an exception. For MIDP 2.x applications, the implementation must implement checkPermission.

Gets the status of the specified legacy named permission. If no API on the device defines the specific permission requested then it must be reported as denied. If the status of the permission is not known because it might require a user interaction then it should be reported as unknown.

Parameters:

permission - to check if denied, allowed, or unknown.

Returns:

0 if the permission is denied; 1 if the permission is allowed; -1 if the status is unknown

Throws:

java.lang.IllegalStateException - if the MIDlet suite is a MIDP 3.0 MIDlet suite.

Since:

MIDP 2.0

getSplashScreenTime

public final long getSplashScreenTime()

Gets the length of time that the application's splash screen has been shown to the user.

An application may specify a splash screen in its manifest (see Packaging and the MIDlet package description for more details regarding splash screens).

If the splash screen is still visible, this method returns the elapsed time since when it was first shown. Implementations are required to provide a time value that is accurate to within +/-100 milliseconds, as measured by viewing the physical display of the device. A value of -1 is returned if the splash screen has been hidden or if a valid splash screen image is not specified in the MIDlet's manifest.

Returns:

the length of time (in milliseconds) that the currently visible splash screen has been shown, or -1 if no splash screen is currently visible

Since:

MIDP 3.0

getMIDletIdentity

public final MIDletIdentity getMIDletIdentity()

Gets a MIDletIdentity instance associated with this MIDlet, which can be used to obtain a MIDlet's name, vendor, version, domain, and authorization state.

Returns:

a MIDletIdentity instance representing the identity of the MIDlet

Since:

MIDP 3.0

isSelectedScreenSaver

public final boolean isSelectedScreenSaver()

Checks if the MIDlet is the currently selected screen saver. If the MIDlet is not a screen saver MIDlet, this method MUST return false.Since the SCREENSAVER_MODE_ACTIVATED system event is sent to all screen saver MIDlets, a MIDlet can use this method to determine if it is the selected screen saver.

Returns:

true if the MIDlet is the selected screen saver, false otherwise.

Since:

MIDP 3.0