File	Doc	Category	Size	Date	Package
MIDletPeer.java	API Doc	phoneME MR2 API (J2ME)	16908	Wed May 02 18:00:06 BST 2007	com.sun.midp.midlet

MIDletPeer

• java.lang.Object

Fields Summary
public static final int	PAUSED State of the MIDlet is Paused; it should be quiescent
public static final int	ACTIVE State of the MIDlet is Active
static final int	ACTIVE_PENDING State of the MIDlet when resumed by the display manager
static final int	PAUSE_PENDING State of the MIDlet when paused by the display manager
static final int	DESTROY_PENDING State of the MIDlet with destroy pending
public static final int	DESTROYED State of the MIDlet is Destroyed
private static MIDletStateHandler	midletStateHandler The controller of MIDlets.
private static MIDletStateListener	midletStateListener The call when a MIDlet's state changes.
private static PlatformRequest	platformRequest Handles platform requests.
private static MIDletTunnel	tunnel The MIDletTunnel implementation from javax.microedition.midlet
private int	state The applications current state.
protected javax.microedition.midlet.MIDlet	midlet The MIDlet for which this is the state.

Constructors Summary
MIDletPeer() Creates a MIDlet's peer which is registered the MIDletStateHandler. Shall be called only from MIDletStateHandler. The peer MIDlet field is set later when the MIDlet's constructor calls newMidletState. state = ACTIVE_PENDING; // So it will be made active soon

Methods Summary
public int	checkPermission(java.lang.String permission) Get the status of the specified 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. param permission to check if denied, allowed, or unknown. return 0 if the permission is denied; 1 if the permission is allowed; -1 if the status is unknown return getMIDletSuite().checkPermission(permission);
void	destroyApp(boolean unconditional) Forwards destoryApp to the MIDlet. param unconditional the flag to pass to destroy exception MIDletStateChangeException is thrown if the MIDlet wishes to continue to execute (Not enter the Destroyed state). This exception is ignored if unconditional is equal to true. tunnel.callDestroyApp(midlet, unconditional);
public javax.microedition.midlet.MIDlet	getMIDlet() Get the MIDlet for which this holds the state. return the MIDlet; will not be null. return midlet;
static com.sun.midp.midlet.MIDletPeer	getMIDletPeer(javax.microedition.midlet.MIDlet m) Returns the MIDletPeer object corresponding to the given midlet instance. param m the midlet instance return MIDletPeer instance associate with m return tunnel.getMIDletPeer(m);
public final MIDletSuite	getMIDletSuite() Provides a MIDlet with a mechanism to retrieve MIDletSuite for this MIDlet. return MIDletSuite for this MIDlet return midletStateHandler.getMIDletSuite();
int	getState() Get the state. return current state of the MIDlet. synchronized (midletStateHandler) { return state; }
public void	handleMIDletActivateEvent() Activate a MIDlet. MIDletEventConsumer I/F method. setState(MIDletPeer.ACTIVE_PENDING);
public void	handleMIDletDestroyEvent() Destroy a MIDlet. MIDletEventConsumer I/F method. setState(MIDletPeer.DESTROY_PENDING);
public void	handleMIDletPauseEvent() Pause a MIDlet. MIDletEventConsumer I/F method. setState(MIDletPeer.PAUSE_PENDING);
static void	initClass(MIDletStateHandler theMIDletStateHandler, MIDletStateListener theMIDletStateListener, PlatformRequest thePlatformRequestHandler) Initialize the MIDletPeer class. Should only be called by the MIDletPeerList (MIDletStateHandler). param theMIDletStateHandler the midlet state handler param theMIDletStateListener the midlet state listener param thePlatformRequestHandler the platform request handler midletStateHandler = theMIDletStateHandler; midletStateListener = theMIDletStateListener; platformRequest = thePlatformRequestHandler;
public final void	notifyDestroyed() Used by a 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. synchronized (midletStateHandler) { state = DESTROYED; midletStateHandler.notify(); }
public final void	notifyPaused() Used by a MIDlet to notify the application management software that it has entered into the PAUSED state. Invoking this method will have no effect if the MIDlet is destroyed, or if it has not yet been started. It may be invoked by the MIDlet when it is in the ACTIVE state. If a MIDlet calls notifyPaused(), in the future its startApp() method may be called make it active again, or its destroyApp() method may be called to request it to destroy itself. int oldState; synchronized (midletStateHandler) { oldState = state; /* * do not notify the midletStateHandler, * since there is nothing to do */ setStateWithoutNotify(PAUSED); } // do work after releasing the lock if (oldState == ACTIVE) { midletStateListener.midletPausedItself(getMIDletSuite(), getMIDlet().getClass().getName()); }
void	pauseApp() Forwards pauseApp to the MIDlet. tunnel.callPauseApp(midlet);
public final boolean	platformRequest(java.lang.String URL) Requests that the device handle (e.g. 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 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 file), the request is interpreted 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. 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). Therefore the platform MUST ask the user to explicitly acknowledge each request before the action is taken. Implementation freedoms are possible so that a pleasant user experience is retained. For example, some platforms may put up a dialog for each request asking the user for permission, while other 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. return true if the MIDlet suite MUST first exit before the content can be fetched. param URL The URL for the platform to load. exception ConnectionNotFoundException if the platform cannot handle the URL requested. return platformRequest.dispatch(URL);
public final void	resumeRequest() Used by a MIDlet to notify the application management software that it is interested in entering the ACTIVE state. Calls to this method can be used by the application management software to determine which applications to move to the ACTIVE state. When the application management software decides to activate this application it will call the startApp method. The application is generally in the PAUSED state when this is called. Even in the paused state the application may handle asynchronous events such as timers or callbacks. midletStateListener.resumeRequest(getMIDletSuite(), getMIDlet().getClass().getName());
public static void	setMIDletTunnel(com.sun.midp.security.SecurityToken token, MIDletTunnel t) Sets up the reference to the MIDletTunnel implementation. This must be called exactly once during system initialization. param token security token for authorizing the caller param t the MIDletTunnel implementation token.checkIfPermissionAllowed(Permissions.MIDP); tunnel = t;
void	setState(int newState) Change the state and notify. Check to make sure the new state makes sense. Changes to the status are protected by the midletStateHandler. Any change to the state notifies the midletStateHandler. param newState new state of the MIDlet synchronized (midletStateHandler) { setStateWithoutNotify(newState); midletStateHandler.notify(); }
void	setStateWithoutNotify(int newState) Change the state without notifying the MIDletStateHandler. Check to make sure the new state makes sense. To be called only by the MIDletStateHandler or MIDletState while holding the lock on midletStateHandler. param newState new state of the MIDlet switch (state) { case DESTROYED: // can't set any thing else return; case DESTROY_PENDING: if (newState != DESTROYED) { // can only set DESTROYED return; } break; case PAUSED: if (newState == PAUSE_PENDING) { // already paused by app return; } break; case PAUSE_PENDING: if (newState == ACTIVE_PENDING) { /* * pausedApp has not been called so the state * can be set to active to cancel the pending pauseApp. */ state = ACTIVE; return; } break; case ACTIVE: if (newState == ACTIVE_PENDING) { // already active return; } break; case ACTIVE_PENDING: if (newState == PAUSE_PENDING) { /* * startApp has not been called so the state * can be set to paused to cancel the pending startApp. */ state = PAUSED; return; } break; } state = newState;
void	startApp() Forwards startApp to the MIDlet. exception MIDletStateChangeException is thrown if the MIDlet cannot start now but might be able to start at a later time. tunnel.callStartApp(midlet);