4 Software Management

This chapter introduces the Software Management (SWM) APIs of the Java ME Embedded Profile (MEEP) version 8. These APIs provided extended software management features for Oracle Java ME Embedded applications, as given in the javax.microedition.swm package. There are five interfaces and six classes in this package that can be used by applications to enhance software management. In addition, there are a number of enumerations that are present in the package; these are documented near the classes and methods that use them throughout this chapter.

4.1 SuiteInstallListener Interface

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.

Table 4-1 SuiteInstallState

Name	Description
`DONE`	Installation has completed
`DOWNLOADING_BODY`	Install stage: downloading application body.
`DOWNLOADING_DATA`	Install stage: downloading additional application data.
`DOWNLOADING_DESCRIPTOR`	Install stage: downloading application descriptor.
`STORING`	Install stage: storing application.
`VERIFYING`	Install stage: verifying downloaded content.

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

4.2 SuiteListener Interface

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.

4.3 SuiteManager Interface

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.

4.4 TaskListener Interface

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.

4.5 TaskManager Interface

The SuiteInstaller interface is a sub-interface that consists of only two methods: one that starts the installation and one that cancels the installation.

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.

4.6 ManagerFactory Class

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.

4.7 The Suite Class

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:

Table 4-2 SuiteType Enumeration

Suite Type	Description
`ST_APPLICATION`	The suite contains one or more MIDlets with an entry point that can be executed.
`ST_LIBRARY`	The suite is a library that can be used by one or more applications.
`ST_SYSTEM`	The suite is a system-level application.
`ST_INVALID`	The suite is invalid and cannot be found or executed.

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

Table 4-3 SuiteStageFlag Enumeration

State	Description
`AVAILABLE`	The suite is available for use.
`ENABLED`	The suite is enabled. When a suite is disabled, any attempt to run application or use a library from this suite should fail.
`SYSTEM`	The suite is a system-level suite.
`PREINSTALLED`	The suite is hidden, and should not be visible to the user.
`REMOVE_DENIED`	The suite should not be removed.
`UPDATE_DENIED`	The suite should not be updated.

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.

4.8 SuiteInstaller Class

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.

4.9 SuiteInstaller Class

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

4.10 SWMPermission Class

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.

4.11 Task Class

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.

4.12 InstallerErrorCode

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

Table 4-4 Installer Error Codes

Constant	Error Code	Description
`ALAA_ALIAS_NOT_FOUND`	78	Application Level Access Authorization: The alias definition is missing.
`ALAA_ALIAS_WRONG`	80	Application Level Access Authorization: The alias definition is wrong.
`ALAA_MULTIPLE_ALIAS`	79	Application Level Access Authorization: An alias has multiple entries that match.
`ALAA_TYPE_WRONG`	77	Application Level Access Authorization: The `MIDlet-Access-Auth-Type` has missing parameters.
`ALREADY_INSTALLED`	39	The JAD matches a version of a suite already installed.
`APP_INTEGRITY_FAILURE_DEPENDENCY_CONFLICT`	69	Application Integrity Failure: two or more dependencies exist on the component with the same name and vendor, but have different versions or hashs.
`APP_INTEGRITY_FAILURE_DEPENDENCY_MISMATCH`	70	Application Integrity Failure: there is a component name or vendor mismatch between the component JAD and IMlet or component JAD that depends on it.
`APP_INTEGRITY_FAILURE_HASH_MISMATCH`	68	Application Integrity Failure: hash mismatch.
`ATTRIBUTE_MISMATCH`	50	A attribute in both the JAD and JAR manifest does not match.
`AUTHORIZATION_FAILURE`	49	Application authorization failure, possibly indicating that the application was not digitally signed.
`CA_DISABLED`	60	Indicates that the trusted certificate authority (CA) for this suite has been disabled for software authorization.
`CANCELED`	101	Canceled by user.
`CANNOT_AUTH`	35	The server does not support basic authentication.
`CIRCULAR_COMPONENT_DEPENDENCY`	64	Circular dynamic component dependency.
`COMPONENT_DEPS_LIMIT_EXCEEDED`	65	Dynamic component dependencies limit exceeded.
`COMPONENT_NAMESPACE_COLLISION`	72	The namespace used by a component is the same as another.
`CONTENT_HANDLER_CONFLICT`	55	The installation of a content handler would conflict with an already installed handler.
`CORRUPT_DEPENDENCY_HASH`	71	A dependency has a corrupt hash code.
`CORRUPT_JAR`	36	An entry could not be read from the JAR.
`CORRUPT_PROVIDER_CERT`	5	The content provider certificate cannot be decoded.
`CORRUPT_SIGNATURE`	8	The JAR signature cannot be decoded.
`DEVICE_INCOMPATIBLE`	40	The device does not support either the configuration or profile in the JAD.
`DUPLICATED_KEY`	88	Duplicated JAD/manifest key attribute
`EXPIRED_CA_KEY`	12	The certificate authority's public key has expired.
`EXPIRED_PROVIDER_CERT`	11	The content provider certificate has expired.
`INCORRECT_FONT_LOADING`	82	A font that is contained with the JAR cannot be loaded.
`INSUFFICIENT_STORAGE`	30	Not enough storage for this suite to be installed.
`INVALID_CONTENT_HANDLER`	54	The `MicroEdition-Handler-`<n> JAD attribute has invalid values.
`INVALID_JAD_TYPE`	37	The server did not have a resource with the correct type or the JAD downloaded has the wrong media type.
`INVALID_JAD_URL`	43	The JAD URL is invalid.
`INVALID_JAR_TYPE`	38	The server did not have a resource with the correct type or the JAR downloaded has the wrong media type.
`INVALID_JAR_URL`	44	The JAR URL is invalid.
`INVALID_KEY`	28	A key for an attribute is not formatted correctly.
`INVALID_NATIVE_LIBRARY`	85	A native library contained within the JAR cannot be loaded.
`INVALID_PACKAGING`	87	A dependency cannot be satisfied.
`INVALID_PAYMENT_INFO`	58	Indicates that the payment information provided with the IMlet suite is incomplete or incorrect.
`INVALID_PROVIDER_CERT`	7	The signature of the content provider certificate is invalid.
`INVALID_RMS_DATA_TYPE`	76	The server did not have a resource with the correct type or the JAD downloaded has the wrong media type.
`INVALID_RMS_DATA_URL`	73	The RMS data file URL is invalid.
`INVALID_SERVICE_EXPORT`	86	A LIBlet that exports a service with a LIBlet Services attribute does not contain the matching service provider configuration information.
`INVALID_SIGNATURE`	9	The signature of the JAR is invalid.
`INVALID_VALUE`	29	A value for an attribute is not formatted correctly.
`INVALID_VERSION`	16	The format of the version is invalid.
`IO_ERROR`	102	A low-level hardware error has occurred.
`JAD_MOVED`	34	The JAD URL for an installed suite is different than the original JAD URL.
`JAD_NOT_FOUND`	2	The JAD was not found.
`JAD_SERVER_NOT_FOUND`	1	The server for the JAD was not found.
`JAR_CLASSES_VERIFICATION_FAILED`	56	Not all classes within JAR package can be successfully verified with class verifier.
`JAR_IS_LOCKED`	100	Component or MIDlet or IMlet suite is locked by the system.
`JAR_NOT_FOUND`	20	The JAR was not found at the URL given in the JAD.
`JAR_SERVER_NOT_FOUND`	19	The server for the JAR was not found at the URL given in the JAD.
`JAR_SIZE_MISMATCH`	31	The JAR downloaded was not the same size as given in the JAD.
`MISSING_CONFIGURATION`	41	The configuration is missing from the manifest.
`MISSING_DEPENDENCY_HASH`	67	A dependency hash code is missing.
`MISSING_DEPENDENCY_JAD_URL`	66	A dependency JAD URL is missing.
`MISSING_JAR_SIZE`	21	The JAR size is missing.
`MISSING_JAR_URL`	18	The URL for the JAR is missing.
`MISSING_PROFILE`	42	The profile is missing from the manifest.
`MISSING_PROVIDER_CERT`	4	The content provider certificate is missing.
`MISSING_SUITE_NAME`	13	The name of MIDlet or IMlet suite is missing.
`MISSING_VENDOR`	14	The vendor is missing.
`MISSING_VERSION`	15	The version is missing.
`NEW_VERSION`	32	This suite is newer that the one currently installed.
`NO_ERROR`	0	No error.
`NOT_YET_VALID_PROVIDER_CERT`	89	A certificate is not yet valid.
`NOT_YET_VALID_CA_KEY`	90	A CA's public key is not yet valid.
`OLD_VERSION`	17	This suite is older that the one currently installed.
`OTHER_ERROR`	103	Other errors.
`PROXY_AUTH`	51	Indicates that the user must first authenticate with the proxy.
`PUSH_CLASS_FAILURE`	48	The class in a push attribute is not in `MIDlet-`<n> attribute.
`PUSH_DUP_FAILURE`	45	The connection in a push entry is already taken.
`PUSH_FORMAT_FAILURE`	46	The format of a push attribute has an invalid format.
`PUSH_PROTO_FAILURE`	47	The connection in a push attribute is not supported.
`REVOKED_CERT`	62	The certificate has been revoked.
`RMS_DATA_DECRYPT_PASSWORD`	83	Indicates that a password is required to decrypt RMS data.
`RMS_DATA_ENCRYPT_PASSWORD`	84	Indicates that a password is required to encrypt RMS data.
`RMS_DATA_NOT_FOUND`	75	The RMS data file was not found at the specified URL.
`RMS_DATA_SERVER_NOT_FOUND`	74	The server for the RMS data file was not found at the specified URL.
`RMS_INITIALIZATION_FAILURE`	81	Failure to import RMS data.
`SUITE_NAME_MISMATCH`	25	The MIDlet or IMlet suite name does not match the one in the JAR manifest.
`TOO_MANY_PROPS`	53	Indicates that either the JAD or manifest has too many properties to fit into memory.
`TRUSTED_OVERWRITE_FAILURE`	52	Indicates that the user tried to overwrite a trusted suite with an untrusted suite during an update.
`UNAUTHORIZED`	33	Web server authentication failed or is required.
`UNKNOWN_CA`	6	The certificate authority (CA) that issued the content provider certificate is unknown.
`UNKNOWN_CERT_STATUS`	63	The certificate is unknown to OCSP server.
`UNSUPPORTED_CERT`	10	The content provider certificate has an unsupported version.
`UNSUPPORTED_CHAR_ENCODING`	61	Indicates that the character encoding specified in the MIME type is not supported.
`UNSUPPORTED_PAYMENT_INFO`	57	Indicates that the payment information provided with the MIDlet or IMlet suite is incompatible with the current implementation.
`UNTRUSTED_PAYMENT_SUITE`	59	Indicates that the MIDlet or IMlet suite has payment provisioning information but it is not trusted.
`VENDOR_MISMATCH`	27	The vendor does not match the one in the JAR manifest.
`VERSION_MISMATCH`	26	The version does not match the one in the JAR manifest.