FileDocCategorySizeDatePackage
MIDletSuiteUtils.javaAPI DocphoneME MR2 API (J2ME)19080Wed May 02 18:00:06 BST 2007com.sun.midp.main

MIDletSuiteUtils

public class MIDletSuiteUtils extends Object
The class designed to provide utils for starting MIDlet suites, and scheduling their start using VM cycling mechanism.

Fields Summary
static int
lastMidletSuiteToRun
The unique ID of the last MIDlet suite to run.
static String
lastMidletToRun
The class name of the last MIDlet to run.
static String
arg0ForLastMidlet
If not null, this will be available to the last MIDlet to run as application property arg-0.
static String
arg1ForLastMidlet
If not null, this will be available to the last MIDlet to run as application property arg-1.
static int
nextMidletSuiteToRun
The unique ID of the next MIDlet suite to run.
static String
nextMidletToRun
The class of the next MIDlet to run.
static String
arg0ForNextMidlet
If not null, this will be available to the MIDlet to run as application property arg-0.
static String
arg1ForNextMidlet
If not null, this will be available to the MIDlet to run as application property arg-1.
static String
arg2ForNextMidlet
If not null, this will be available to the MIDlet to run as application property arg-2.
static int
memoryReserved
The minimum amount of memory guaranteed to be available to the VM at any time; < 0 if not used.
static int
memoryTotal
The total amount of memory that the VM can reserve; < 0 if not used.
static int
priority
Priority to set after restarting the VM; <= 0 if not used.
static String
profileName
Name of the profile to set after restarting the VM; null if not used.
Constructors Summary
Methods Summary
static voiddisplayException(com.sun.midp.lcdui.DisplayEventHandler handler, java.lang.String exceptionMsg)
Display an exception to the user.

param
handler display event handler to draw displays
param
exceptionMsg exception message


        SystemAlert alert = new SystemAlert(
            handler, "Exception", exceptionMsg, null, AlertType.ERROR);
        alert.run();
        alert.waitForUser();
public static booleanexecute(int id, java.lang.String midlet, java.lang.String displayName)
Starts a MIDlet in a new Isolate or queues the execution of the named Application suite to run. The current application suite should terminate itself normally to make resources available to the new application suite. Only one package and set of MIDlets can be queued in this manner. If multiple calls to execute are made, the package and MIDlets specified during the last invocation will be executed when the current application is terminated.

param
id ID of an installed suite
param
midlet class name of MIDlet to invoke
param
displayName name to display to the user
return
true if the MIDlet suite MUST first exit before the MIDlet is run
exception
SecurityException if the caller does not have permission to manage midlets

        return executeWithArgs(
            id, midlet, displayName, null, null, null);
public static booleanexecute(com.sun.midp.security.SecurityToken securityToken, int suiteId, java.lang.String midlet, java.lang.String displayName)
Starts a MIDlet in a new Isolate or queues the execution of the named Application suite to run. The current application suite should terminate itself normally to make resources available to the new application suite. Only one package and set of MIDlets can be queued in this manner. If multiple calls to execute are made, the package and MIDlets specified during the last invocation will be executed when the current application is terminated.

param
securityToken security token of the calling class application manager
param
suiteId ID of an installed suite
param
midlet class name of MIDlet to invoke
param
displayName name to display to the user
return
true if the MIDlet suite MUST first exit before the MIDlet is run
exception
SecurityException if the caller does not have permission to manage midlets


        return executeWithArgs(
            securityToken, suiteId, midlet,
            displayName, null, null, null);
public static booleanexecuteWithArgs(int suiteId, java.lang.String midlet, java.lang.String displayName, java.lang.String arg0, java.lang.String arg1, java.lang.String arg2)
Starts a MIDlet in a new Isolate or queues the execution of the named Application suite to run. The current application suite should terminate itself normally to make resources available to the new application suite. Only one package and set of MIDlets can be queued in this manner. If multiple calls to execute are made, the package and MIDlets specified during the last invocation will be executed when the current application is terminated.

param
suiteId ID of an installed suite
param
midlet class name of MIDlet to invoke
param
displayName name to display to the user
param
arg0 if not null, this parameter will be available to the MIDlet as application property arg-0
param
arg1 if not null, this parameter will be available to the MIDlet as application property arg-1
param
arg2 if not null, this parameter will be available to the MIDlet as application property arg-2
return
true if the MIDlet suite MUST first exit before the MIDlet is run
exception
SecurityException if the caller does not have permission to manage midlets


        return executeWithArgs(
            null, suiteId, midlet, displayName, arg0, arg1, arg2);
public static booleanexecuteWithArgs(com.sun.midp.security.SecurityToken securityToken, int suiteId, java.lang.String midlet, java.lang.String displayName, java.lang.String arg0, java.lang.String arg1, java.lang.String arg2)
Starts a MIDlet in a new Isolate or queues the execution of the named Application suite to run. The current application suite should terminate itself normally to make resources available to the new application suite. Only one package and set of MIDlets can be queued in this manner. If multiple calls to execute are made, the package and MIDlets specified during the last invocation will be executed when the current application is terminated.

param
securityToken security token of the calling class
param
suiteId ID of an installed suite
param
midlet class name of MIDlet to invoke
param
displayName name to display to the user
param
arg0 if not null, this parameter will be available to the MIDlet as application property arg-0
param
arg1 if not null, this parameter will be available to the MIDlet as application property arg-1
param
arg2 if not null, this parameter will be available to the MIDlet as application property arg-2
return
true if the MIDlet suite MUST first exit before the MIDlet is run
exception
SecurityException if the caller does not have permission to manage midlets


        return executeWithArgs(
            securityToken, 0, suiteId, midlet,
            displayName, arg0, arg1, arg2);
public static booleanexecuteWithArgs(com.sun.midp.security.SecurityToken securityToken, int externalAppId, int suiteId, java.lang.String midlet, java.lang.String displayName, java.lang.String arg0, java.lang.String arg1, java.lang.String arg2)
Starts a MIDlet in a new Isolate or queues the execution of the named Application suite to run. The current application suite should terminate itself normally to make resources available to the new application suite. Only one package and set of MIDlets can be queued in this manner. If multiple calls to execute are made, the package and MIDlets specified during the last invocation will be executed when the current application is terminated.

param
securityToken security token of the calling class
param
externalAppId ID of MIDlet to invoke, given by an external application manager
param
suiteId ID of an installed suite
param
midlet class name of MIDlet to invoke
param
displayName name to display to the user
param
arg0 if not null, this parameter will be available to the MIDlet as application property arg-0
param
arg1 if not null, this parameter will be available to the MIDlet as application property arg-1
param
arg2 if not null, this parameter will be available to the MIDlet as application property arg-2
return
true if the MIDlet suite MUST first exit before the MIDlet is run
exception
SecurityException if the caller does not have permission to manage midlets


        return executeWithArgs(
            securityToken, externalAppId, suiteId, midlet, displayName,
            arg0, arg1, arg2, -1, -1, -1, null);
public static booleanexecuteWithArgs(com.sun.midp.security.SecurityToken securityToken, int externalAppId, int suiteId, java.lang.String midlet, java.lang.String displayName, java.lang.String arg0, java.lang.String arg1, java.lang.String arg2, int memoryReserved, int memoryTotal, int priority, java.lang.String profileName)
Starts a MIDlet in a new Isolate or queues the execution of the named Application suite to run. The current application suite should terminate itself normally to make resources available to the new application suite. Only one package and set of MIDlets can be queued in this manner. If multiple calls to execute are made, the package and MIDlets specified during the last invocation will be executed when the current application is terminated.

param
securityToken security token of the calling class
param
externalAppId ID of MIDlet to invoke, given by an external application manager
param
suiteId ID of an installed suite
param
midlet class name of MIDlet to invoke
param
displayName name to display to the user
param
arg0 if not null, this parameter will be available to the MIDlet as application property arg-0
param
arg1 if not null, this parameter will be available to the MIDlet as application property arg-1
param
arg2 if not null, this parameter will be available to the MIDlet as application property arg-2
param
memoryReserved the minimum amount of memory guaranteed to be available to the isolate at any time; < 0 if not used
param
memoryTotal the total amount of memory that the isolate can reserve; < 0 if not used
param
priority priority to set for the new isolate; <= 0 if not used
param
profileName name of the profile to set for the new isolate; null if not used
return
true if the MIDlet suite MUST first exit before the MIDlet is run
exception
SecurityException if the caller does not have permission to manage midlets


        MIDletSuiteStorage midletSuiteStorage;

        // Note: getMIDletSuiteStorage performs an AMS permission check.
        if (securityToken != null) {
            midletSuiteStorage =
                MIDletSuiteStorage.getMIDletSuiteStorage(securityToken);
        } else {
            midletSuiteStorage = MIDletSuiteStorage.getMIDletSuiteStorage();
        }

        return AmsUtil.executeWithArgs(
            midletSuiteStorage, externalAppId, suiteId,
            midlet, displayName, arg0, arg1, arg2,
            memoryReserved, memoryTotal, priority, profileName);
public static native intgetAmsIsolateId()
Get the Isolate ID of the AMS Isolate.

return
Isolate ID of AMS Isolate

public static native intgetIsolateId()
Get the current Isolate ID.
return
ID of this Isolate.
public static intgetNextMIDletSuiteToRun()
Gets the unique storage name of the next MIDlet suite to run.
return
storage name of a MIDlet suite
        return nextMidletSuiteToRun;
    
public static java.lang.StringgetNextMIDletToRun()
Gets the name of the next MIDlet to run.
return
storage name of a MIDlet
        return nextMidletToRun;
    
static voidinitAmsResources()
The method is designed to init AMS task resources. The resources
can be shared between all working isolates, so it is important to
init them before other isolate tasks will require the resources.

The tasks other than AMS shouldn't call this method, it's guarded
by run-time exception.

IMPL_NOTE: The method is temporarily loacated here, since we need
to introduce new abstraction for AMS task logic and separate it
from the MIDlet suite loading and execution logic. Now the method
is needed to MIDletSuiteLoader & NativeAppManagerPeer classes
which represent an AMS task for Java AMS and Native AMS cases
correspondingly.
        // Check whether caller task is an AMS task
        if (!isAmsIsolate()) {
            throw new RuntimeException(
                "Resources initialization should be done from the AMS task");
        }

        // The static initializer of the Display class will forward on
        // the Chameleon skin resources loading if Chameleon is being used.
        // It is important to load Chameleon resources from the AMS isolate
        // before other isolates will need them.
        try {
            Class.forName("javax.microedition.lcdui.Display");
        } catch (Throwable ex) {
            throw new RuntimeException(
                "Display initialization has failed");
        }
    
public static native booleanisAmsIsolate()
Check whether current Isolate is an AMS Isolate
return
true if the current Isolate is an AMS Isolate,
false otherwise.
static native voidregisterAmsIsolateId()
Register the Isolate ID of the AMS Isolate by making a native
method call that will call JVM_CurrentIsolateId and set
it in the proper native variable.
public static voidsetLastSuiteToRun(int id, java.lang.String midlet, java.lang.String arg0, java.lang.String arg1)
Queues the last suite to run when there is not a next Suite
to run. This value will be persistent until it is used.
Not used in MVM mode.
param
id ID of an installed suite
param
midlet class name of MIDlet to invoke
exception
SecurityException if the caller does not have permission
to manage midlets

        MIDletSuite midletSuite =
            MIDletStateHandler.getMidletStateHandler().getMIDletSuite();

        // if a MIDlet suite is not scheduled, assume the JAM is calling.
        if (midletSuite != null) {
            midletSuite.checkIfPermissionAllowed(Permissions.AMS);
        }

        lastMidletSuiteToRun = id;
        lastMidletToRun = midlet;
        arg0ForLastMidlet = arg0;
        arg1ForLastMidlet = arg1;
    
static native voidvmBeginStartUp(int midletIsolateId)
Send hint to VM about begin of a MIDlet startup phase within specified
isolate to allow the VM to fine tune its internal parameters to achieve
optimal perfomance
param
midletIsolateId ID of the started MIDlet isolate
public static voidvmBeginStartUp(com.sun.midp.security.SecurityToken token, int midletIsolateId)
Secure method to send VM hint about begin of a MIDlet startup phase
within specified isolate
param
token security token with the AMS permission allowed
param
midletIsolateId ID of the started MIDlet isolate
        token.checkIfPermissionAllowed(Permissions.AMS);
        vmBeginStartUp(midletIsolateId);
    
static native voidvmEndStartUp(int midletIsolateId)
Send hint to VM about end of a MIDlet startup phase within specified
isolate to allow the VM to restore its internal parameters changed on
startup time for better performance
param
midletIsolateId ID of the started MIDlet isolate
public static voidvmEndStartUp(com.sun.midp.security.SecurityToken token, int midletIsolateId)
Secure method to send VM hint about end of a MIDlet startup phase
within specified isolate
param
token security token with the AMS permission allowed
param
midletIsolateId ID of the started MIDlet isolate
        token.checkIfPermissionAllowed(Permissions.AMS);
        vmEndStartUp(midletIsolateId);