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 |
---|---|
|
Installation has completed |
|
Install stage: downloading application body. |
|
Install stage: downloading additional application data. |
|
Install stage: downloading application descriptor. |
|
Install stage: storing application. |
|
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 ofSuiteState
, 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 currentSuiteManager
. -
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)
-
SuiteInstaller getSuiteInstaller(java.lang.String locationUrl, boolean ignoreUpdateLock)
-
java.util.List<Suite> getSuites(SuiteType type)
This method requests a list of installed suites of specified type.
-
void removeSuite(Suite suite, boolean ignoreRemoveLock)
-
void removeSuiteListener(SuiteListener theListener)
4.4 TaskListener Interface
The TaskListener
interface is an interface used to receive updates about a task that is currently running.
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
-
Task getCurrentTask() throws SecurityException
-
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)
-
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 givenSuite
. 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 withTaskStatus.STARTING
on success orTaskStatus.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.IllegalStateExceptionThis 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.
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 |
---|---|
|
The suite contains one or more MIDlets with an entry point that can be executed. |
|
The suite is a library that can be used by one or more applications. |
|
The suite is a system-level application. |
|
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 |
---|---|
|
The suite is available for use. |
|
The suite is enabled. When a suite is disabled, any attempt to run application or use a library from this suite should fail. |
|
The suite is a system-level suite. |
|
The suite is hidden, and should not be visible to the user. |
|
The suite should not be removed. |
|
The suite should not be updated. |
The following are method present in the Suite
class.
-
java.lang.String getName()
-
java.lang.String getVendor()
-
java.lang.String getVersion()
-
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
andSuiteStateFlag.AVAILABLE
are always set totrue
, whileSuiteStateFlag.REMOVE_DENIED
andSuiteStateFlag.UPDATE_DENIED
are set tofalse
. These states can be changed by calling this method. TheSuiteStateFlag.SYSTEM
andSuiteStateFlag.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 requestjavax.microedition.swm.SWMPermission("client", "manageSuite")
orjavax.microedition.swm.SWMPermission ("crossClient", "manageSuite")
permission. SeeSWMPermission
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 aSYSTEM_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 ofSuiteManagementTracker
; the caller can observe the progress of the installation via theSuiteInstallListener
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 thestart()
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 ofSuiteManagementTracker
will be created for every call to this method and assigned to theSuite
to be installed as soon as the installation has been completed successfully. In case of an update of an existingSuite
, theSuiteManagementTracker
instance is assigned to the existingSuite
object from the beginning.If the initiating application does not have the rightSWMPermission
, the installation will fail withInstallErrorCodes.UNAUTHORIZED_INSTALL
. -
void cancel()
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.
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()
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()
-
public int getHeapUse()
-
public TaskStatus getStatus()
-
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 |
---|---|---|
|
78 |
Application Level Access Authorization: The alias definition is missing. |
|
80 |
Application Level Access Authorization: The alias definition is wrong. |
|
79 |
Application Level Access Authorization: An alias has multiple entries that match. |
|
77 |
Application Level Access Authorization: The |
|
39 |
The JAD matches a version of a suite already installed. |
|
69 |
Application Integrity Failure: two or more dependencies exist on the component with the same name and vendor, but have different versions or hashs. |
|
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. |
|
68 |
Application Integrity Failure: hash mismatch. |
|
50 |
A attribute in both the JAD and JAR manifest does not match. |
|
49 |
Application authorization failure, possibly indicating that the application was not digitally signed. |
|
60 |
Indicates that the trusted certificate authority (CA) for this suite has been disabled for software authorization. |
|
101 |
Canceled by user. |
|
35 |
The server does not support basic authentication. |
|
64 |
Circular dynamic component dependency. |
|
65 |
Dynamic component dependencies limit exceeded. |
|
72 |
The namespace used by a component is the same as another. |
|
55 |
The installation of a content handler would conflict with an already installed handler. |
|
71 |
A dependency has a corrupt hash code. |
|
36 |
An entry could not be read from the JAR. |
|
5 |
The content provider certificate cannot be decoded. |
|
8 |
The JAR signature cannot be decoded. |
|
40 |
The device does not support either the configuration or profile in the JAD. |
|
88 |
Duplicated JAD/manifest key attribute |
|
12 |
The certificate authority's public key has expired. |
|
11 |
The content provider certificate has expired. |
|
82 |
A font that is contained with the JAR cannot be loaded. |
|
30 |
Not enough storage for this suite to be installed. |
|
54 |
The |
|
37 |
The server did not have a resource with the correct type or the JAD downloaded has the wrong media type. |
|
43 |
The JAD URL is invalid. |
|
38 |
The server did not have a resource with the correct type or the JAR downloaded has the wrong media type. |
|
44 |
The JAR URL is invalid. |
|
28 |
A key for an attribute is not formatted correctly. |
|
85 |
A native library contained within the JAR cannot be loaded. |
|
87 |
A dependency cannot be satisfied. |
|
58 |
Indicates that the payment information provided with the IMlet suite is incomplete or incorrect. |
|
7 |
The signature of the content provider certificate is invalid. |
|
76 |
The server did not have a resource with the correct type or the JAD downloaded has the wrong media type. |
|
73 |
The RMS data file URL is invalid. |
|
86 |
A LIBlet that exports a service with a LIBlet Services attribute does not contain the matching service provider configuration information. |
|
9 |
The signature of the JAR is invalid. |
|
29 |
A value for an attribute is not formatted correctly. |
|
16 |
The format of the version is invalid. |
|
102 |
A low-level hardware error has occurred. |
|
34 |
The JAD URL for an installed suite is different than the original JAD URL. |
|
2 |
The JAD was not found. |
|
1 |
The server for the JAD was not found. |
|
56 |
Not all classes within JAR package can be successfully verified with class verifier. |
|
100 |
Component or MIDlet or IMlet suite is locked by the system. |
|
20 |
The JAR was not found at the URL given in the JAD. |
|
19 |
The server for the JAR was not found at the URL given in the JAD. |
|
31 |
The JAR downloaded was not the same size as given in the JAD. |
|
41 |
The configuration is missing from the manifest. |
|
67 |
A dependency hash code is missing. |
|
66 |
A dependency JAD URL is missing. |
|
21 |
The JAR size is missing. |
|
18 |
The URL for the JAR is missing. |
|
42 |
The profile is missing from the manifest. |
|
4 |
The content provider certificate is missing. |
|
13 |
The name of MIDlet or IMlet suite is missing. |
|
14 |
The vendor is missing. |
|
15 |
The version is missing. |
|
32 |
This suite is newer that the one currently installed. |
|
0 |
No error. |
|
89 |
A certificate is not yet valid. |
|
90 |
A CA's public key is not yet valid. |
|
17 |
This suite is older that the one currently installed. |
|
103 |
Other errors. |
|
51 |
Indicates that the user must first authenticate with the proxy. |
|
48 |
The class in a push attribute is not in |
|
45 |
The connection in a push entry is already taken. |
|
46 |
The format of a push attribute has an invalid format. |
|
47 |
The connection in a push attribute is not supported. |
|
62 |
The certificate has been revoked. |
|
83 |
Indicates that a password is required to decrypt RMS data. |
|
84 |
Indicates that a password is required to encrypt RMS data. |
|
75 |
The RMS data file was not found at the specified URL. |
|
74 |
The server for the RMS data file was not found at the specified URL. |
|
81 |
Failure to import RMS data. |
|
25 |
The MIDlet or IMlet suite name does not match the one in the JAR manifest. |
|
53 |
Indicates that either the JAD or manifest has too many properties to fit into memory. |
|
52 |
Indicates that the user tried to overwrite a trusted suite with an untrusted suite during an update. |
|
33 |
Web server authentication failed or is required. |
|
6 |
The certificate authority (CA) that issued the content provider certificate is unknown. |
|
63 |
The certificate is unknown to OCSP server. |
|
10 |
The content provider certificate has an unsupported version. |
|
61 |
Indicates that the character encoding specified in the MIME type is not supported. |
|
57 |
Indicates that the payment information provided with the MIDlet or IMlet suite is incompatible with the current implementation. |
|
59 |
Indicates that the MIDlet or IMlet suite has payment provisioning information but it is not trusted. |
|
27 |
The vendor does not match the one in the JAR manifest. |
|
26 |
The version does not match the one in the JAR manifest. |