4 Software Management

SuiteInstallListener is a sub-interface that provides progress data for an installer that is downloading an app or a link.

The interface consists of two methods, both of which are called at certain times during installation. One is the installationDone() method, which provides only a single code, the definitions of which can be found in the InstallerErrorCode interface. The other is the updateStatus() method, which identifies the current task as one of the SuiteInstallStage constants that are shown in Table 4-1, and provides an integer percentage of completeness.

Here are the two method defined in the SuiteInstallListener interface:

• void installationDone(int errorCode)

  This method is called by the installer to report that the installation has completed. The resulting integer code is contained in the InstallerErrorCode class. See "InstallerErrorCode" for more information about installation error codes.

• void updateStatus(SuiteManagementTracker tracker, SuiteInstallStage status, int percent)

  This method is called by the installer to inform the listener of the current status of the install. The stage is given by an integer constant as shown in Table 4-1. The percent is an integer between 0 and 100.

SuiteListener is an interface that provides a notification that the current state of a suite has changed.

There is only one method defined in the SuiteListener interface:

• void notifySuiteStateChanged(SuiteManagementTracker tracker, SuiteState newState)

  This method is called to notify a listener that the current state of a suite has changed. A reference to the current SuiteManagementTracker is included, as well as an instance of SuiteState, which indicates the new state.

The SuiteManager interface consists of only seven methods that add or remove suites, add or remove suite listeners, retrieve a list of the currently installed suites, or retrieve the current SuiteInstaller.

• void addSuiteListener(SuiteListener theListener)

  This method adds a SuiteListener object to the current SuiteManager.

• Suite getSuite(java.lang.String vendor, java.lang.String name)

  This method returns an instance of the currently installed Suite.

• SuiteInstaller getSuiteInstaller(byte[] instData, int offset, int length, boolean ignoreUpdateLock)

  This method returns the current SuiteInstaller.

• SuiteInstaller getSuiteInstaller(java.lang.String locationUrl, boolean ignoreUpdateLock)

  This method returns the current SuiteInstaller

• java.util.List<Suite> getSuites(SuiteType type)

  This method requests a list of installed suites of specified type.

• void removeSuite(Suite suite, boolean ignoreRemoveLock)

  This method removes a Suite.

• void removeSuiteListener(SuiteListener theListener)

  This method removes a SuiteListener.

The TaskListener interface is an interface used to receive updates about a task that is currently running.

• void notifyStatusUpdate(Task task, TaskStatus newStatus)

  This method is called when the current task has a new status update to report. The method passes a reference to the Task in question, as well as a TaskStatus object reporting the new status.

The TaskManager interface is an interface used to manage the tasks.

• void addTaskListener(TaskListener) throws SecurityException

  This method adds a TaskListener.

• Task getCurrentTask() throws SecurityException

  This method returns the current task that is running.

• java.util.List<Task> getTaskList(boolean includeSystem)

  This method obtains a list of Task objects. If system tasks are to be included, that can be specified with the boolean parameter.

• void removeTaskListener(TaskListener listener)

  This method removes a TaskListener.

• boolean setForegroundTask(Task task) throws java.lang.IllegalArgumentException

  This method assigns the specified task to be the currently running foreground task. A task is said to be in the foreground if the LUI API or another UI API is supported and the task is visible on the display, or if the Key API is supported and input device events will be delivered to it. If none of those packages is supported by the implementation, a call to this method has no effect.

• boolean setPriority(Task task, TaskPriority priority) throws java.lang.IllegalArgumentException

  Changes the priority for the given task. The method returns true if the change was successful, or false otherwise.

• Task startTask(Suite suite, String className) throws java.lang.IllegalArgumentException, java.lang.IllegalStateException

  Starts a Task from the given class name in the given Suite. This method throws an exception if suite is a library and can therefore not be started. Calling this method schedules a new application execution. The new task is created with TaskStatus.STARTING on success or TaskStatus.START_FAILED on failure.

  More than one call to this method can be performed with the same arguments. In this case subsequent calls lead to attempts to re-start the task. In case of unsuccessful attempt to re-start the task, an appropriate exception is thrown or the corresponding state TaskStatus.START_FAILED is set to the returned task object.

• boolean stopTask(Task task) throws java.lang.IllegalArgumentException, java.lang.IllegalStateException

  This method cancels an installation that is in progress. It returns true if the cancellation was successful, or false otherwise.

The ManagerFactory class is a global factory that is used to obtain a SuiteManager or a TaskManager implementation.

• static SuiteManager getSuiteManager()

  This method returns an implementation of a SuiteManager.

• static TaskManager getTaskManager()

  This method returns an implementation of a TaskManager.

All IMlet suites maintain a basic set of identification and state information that acts as a descriptor. This descriptor is represented by the Suite class.

Suites can be one of four types, presented in the SuiteType enumeration, and shown in Table 4-2:

In addition, suites contain binary flags that describe their state, presented in the SuiteStateFlag enumeration, and shown in Table 4-3:

The following are method present in the Suite class.

• java.lang.String getName()

  This method returns the name for the given suite.

• java.lang.String getVendor()

  This method returns the vendor for the given suite.

• java.lang.String getVersion()

  This method returns the version of the given suite.

• java.lang.String getDownloadUrl()

  This method returns the URL that the JAD or JAR was downloaded from.

• java.util.Iteration<String> getAttributes()

  This method returns a String array that provides the names of the available properties. The properties returned are those from the JAD file and the manifest combined into a single array.

• java.lang.String getAttributeValue(String name)

  This method retrieves the value for the respective attribute name.

• SuiteType getSuiteType()

  This method returns the suite type. See Table 4-2 for more information.

• public boolean isSuiteState(SuiteStateFlag state)

  This method checks the current state boolean to see if it is true.

• public void setSuiteStateFlag(SuiteStateFlag state, boolean value) throws java.lang.IllegalArgumentException, java.lang.IllegalStateException, java.lang.SecurityException

  This method sets the specified flag to the specified value. If a Suite has been created, SuiteStateFlag.ENABLED and SuiteStateFlag.AVAILABLE are always set to true, while SuiteStateFlag.REMOVE_DENIED and SuiteStateFlag.UPDATE_DENIED are set to false. These states can be changed by calling this method. The SuiteStateFlag.SYSTEM and SuiteStateFlag.PREINSTALLED flags are only set for system suites or pre-installed suites, respectively, and cannot be unset or set by this method. To be able to set suite flags, caller application should request javax.microedition.swm.SWMPermission("client", "manageSuite") or javax.microedition.swm.SWMPermission ("crossClient", "manageSuite") permission. See SWMPermission for more details.

• public java.util.Iterator<java.lang.String> getMIDlets()

  This method returns a list of the applications (application class names) in this suite. The first application in the enumeration is the default application as specified in the MIDlet-1 field of the descriptor.

• public java.util.Iterator<Suite> getDependencies()

  This method returns a list of the shared libraries this Suite depends on

• public boolean isTrusted()

  Checks if this Suite is trusted or not. The return value is always true if it is a SYSTEM_SUITE.

• public boolean isInstalled()

  Checks if this Suite is still installed or has been removed.

The ManagerFactory class is a global factory that is used to obtain a SuiteManager or a TaskManager implementation.

• void addInstallationListener(SuiteInstallListener listener)

  This method adds a SuiteInstallListener to this suite installer

• void removeInstallationListener(SuiteInstallationListener listener)

  This method removes a SuiteInstallListener to this suite installer.

• SuiteManagementTracker start()

  This method starts installation of the suite. The installation can be the first installation of this suite, or a re-installation (update) of a suite that had been installed before. A SuiteInstallListener must be added in order to handle callback requests.This method returns an instance of SuiteManagementTracker; the caller can observe the progress of the installation via the SuiteInstallListener added. Please note that the method may not return quickly. Depending on the provisioning mechanism used in the implementation of MEEP 8, it may be necessary to download the entire JAR data first in order to inspect the manifest of the application suite in order to find out whether this is a new installation or an update of an existing application suite. Depending on the network connection, this may take some time.In case the previous attempt to install this suite (initiated by a previous call of the start() method) has not been finished at the time the new call takes place, the call is queued and the new attempt to install (in case the first one failed) or the re-installation (in case the first call was successful), respectively, starts as soon as the first installation attempt or installation has been finished.A new instance of SuiteManagementTracker will be created for every call to this method and assigned to the Suite to be installed as soon as the installation has been completed successfully. In case of an update of an existing Suite, the SuiteManagementTracker instance is assigned to the existing Suite object from the beginning.If the initiating application does not have the right SWMPermission, the installation will fail with InstallErrorCodes.UNAUTHORIZED_INSTALL.

• void cancel()

  Begins installation of the suite.

An instance of this class is generated as soon as an installation or update of a Suite is started using SuiteInstaller.start(). Invoking that method creates a new tracker instance. Whether two trackers refer to the same Suite can be found out by calling getSuite() for both and compare the returned Suite instances. The tracker instance created for a management operation is passed to any call of SuiteListener.notifySuiteStateChanged() in order to inform about the progress of this operation.

For the installation of a new Suite, as long as the installation hasn't been successfully completed, an instance of SuiteManagementTracker is not assigned to any Suite instance yet, as it does not exit yet. In these cases, a call to getSuite() returns null. In case of an update, the tracker is assigned to the existing Suite from the beginning, though.

This class has one method.

• Suite getSuite()

  This method returns the Suite that this tracker is assigned to, if the installation has completed successfully

The SWMPermission provides permission handling for SWM API permissions. An SWMPermission object contains a scope and actions. The scope is the scope of the permission. Valid scopes are "client" stands for permission to perform the listed actions only for applications assigned to the same Client. "crossClient" stands for permission to perform the listed actions also for applications assigned to other Clients. Usually this is a permission reserved for the Root Client. Granting this permissions to other Clients should be figured out well in order to avoid security breaches.The actions to be granted are passed to the constructor in a non-empty string, containing a list of comma-separated keywords. Trailing and leading white spaces as well as those between the keywords and commas in the list are not allowed and lead to an IllegalArgumentException. The possible values can be seen in this table in the Security Policy Provider chapter of the spec. The actions string is converted to lowercase before processing.

This class has one constructor and several methods.

• SWMPermission(java.lang.String scope, java.lang.String actions)

  This method creates a new SWMPermission object with the specified name and actions.

• public boolean implies(java.security.Permission p)

  This method checks if the specified permission is "implied" by this object.

• String getActions()

  This method returns the permitted actions of this Permission as a comma separated list in alphabetical order.

• java.security.PermissionCollection newPermissionCollection()

  This method creates a new SWMPermissionCollection.

The Task class is, in effect, a simple task descriptor. A Task is the abstraction of the execution of an application (see javax.microedition.midlet.MIDlet). Tasks are started using the TaskManager.startTask() method, where the arguments specify the application suite and the class within the suite being the starting point of the application. Starting a new task attempts to execute corresponding application. A task has a status, as described in the TaskStatus enumeration, that describes corresponding application lifecycle state. A task has a priority with possible values as described in TaskPriority. Depending on whether the implementation supports multiple VMs, several tasks can run in parallel.There are special tasks called system tasks. Those tasks cannot be started or stopped via this API, but are started by the system. The isSystemTask() method can be used to find out whether a task is a considered a system task.

The Task class contains the following methods.

• String getName()

  This is a convenience method for returning the name of the task. The returned string is the name of the application running in this task.

• TaskPriority getPriority()

  This method returns the priority of given task.

• public int getHeapUse()

  This method returns the heap use of given task.

• public TaskStatus getStatus()

  This method returns the task's status.

• public Suite getSuite()

  This method returns the suite information this task executed from.

• public boolean isSystemTask()

  This method returns a boolean indicating whether a task is a system task.

The InstallerErrorCode provides several constants used by the installation routines. These constants are shown in Table 4-4.