Oracle® Java ME Embedded Application Management System API Guide Release 3.4 E35109-03 |
|
Previous |
Next |
This chapter introduces the basic data interfaces used throughout the AMS APIs.
All apps, libraries, and links maintain a basic set of identification and state information that acts as a descriptor. This descriptor is represented by an implementation of the SuiteInfo
interface.
Suites can be one of four types, as shown in Table 2-1:
Table 2-1 AMS Suite Types
Suite Type | Description |
---|---|
|
The suite contains one or more MIDlets with an entry point that can be executed by the AMS. |
|
The suite is a library that can be used by one or more applications. |
|
The suite is a link, which references another application that has yet to be downloaded. |
|
The suite is invalid and cannot be found or executed. |
In addition, suites contain five binary flags that describe their state, as shown in Table 2-2:
Table 2-2 AMS Suite States
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 hidden, and should not be visible to the user. |
|
The suite should not be removed. |
|
The suite should not be updated. |
The suite state flags are not enforced by the AMS APIs. In other words, even though the STATE_REMOVE_DENIED
or STATE_UPDATE_DENIED
flags may be set to true, the AMS APIs do not prevent a removal or update if the appropriate method is invoked. It is up to the UI that implements the AMS APIs to enforce this behavior.
Programmers can use the getState()
method to obtain the state information for the suites, then use the logical AND operator (&) to test if a given state is true. For example, to test if a suite is disabled:
if ((appSuite.getState() & SuiteInfo.STATE_DISABLED) != 0) { // The app is disabled }
The SuiteInfo
interface contains the following methods to access basic information about a suite. Many methods throw a SuiteNotFoundException
if the AMS can no longer locate the suite described by the SuiteInfo
:
java.lang.String[] getAvailableProperties() throws SuiteNotFoundException
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 getDownloadUrl()
This method returns the URL that the JAD or JAR was downloaded from.
byte[] getIcon()
This method returns the icon representing the suite as a byte array. The AMS does not perform any decoding of the image, as this is the job of the AMS UI, so the image format is undefined.
java.lang.String getName()
java.lang.String getProperty(java.lang.String name) throws SuiteNotFoundException
This method returns the value of the property with the given name.
SuiteSettings getSettings() throws SuiteNotFoundException
This method returns the settings of the suite encapsulated in a SuiteSettings
class. See "SuiteSetting Interface" for more details on suite settings.
int getState() throws SuiteNotFoundException
This method returns the current state of the suite as a combination of flags: STATE_DISABLED
, STATE_HIDDEN
, STATE_AVAILABLE
, STATE_REMOVE_DENIED
, or STATE_UPDATE_DENIED
. See Table 2-2 for more information.
int getSuiteType() throws SuiteNotFoundException
This method returns the suite type as one of the predefined constants shown in Table 2-1.
java.lang.String getVendor()
void remove() throws SuiteLockedException, SuiteNotFoundException, SecurityException
This method is used to remove the suite from the AMS. The method throws a SuiteLockedException
if the suite is currently locked by the AMS. A suite is locked if the STATE_REMOVE_DENIED
boolean is set to true.
void remove(boolean ignoreRemoveLock) throws SuiteLockedException, SuiteNotFoundException, SecurityException
This method is used to remove the suite from the AMS, ignoring the STATE_REMOVE_DENIED lock if the boolean parameter is set to true.
boolean setState(int state, boolean value) throws SuiteLockedException, SuiteNotFoundException, ConcurrentModificationException
This method modifies the state of the suite, as per the constants shown in Table 2-2. The method returns the previous value of the state. If the suite is locked, the method throws a SuiteLockedException
. A suite is locked if the STATE_REMOVE_DENIED
boolean is set to true.
Alternatively, if two threads attempt to modify the state of the suite at the same time, the method can throw a ConcurrentModificationException
.
The AppSuite
interface extends the SuiteInfo
interface, and is used to describe executable apps that are installed in the Oracle Java ME Embedded.
Apps can be one of three types: regular apps, system apps, or preinstalled apps, as shown in Table 2-3:
Table 2-3 Application Suite Types
Type | Description |
---|---|
|
The application suite is preinstalled. |
|
A normal application suite. |
|
A system application suite. |
To determine the type that this suite belongs to, use the getType()
method, int getType()
throws SuiteNotFoundException
. This method returns the type of the suite as one of the predefined constants shown in Table 2-3. If the suite can no longer locate information about the app referenced by this descriptor, this method throws a SuiteNotFoundException
.
The programmer can also obtain more detailed information about the suite with the following methods:
java.lang.String getDefaultApp() throws SuiteNotFoundException
This method returns the name of the default MIDlet from the suite. If the suite can no longer locate information about the app referenced by this descriptor, this method throws a SuiteNotFoundException
.
int getType() throws SuiteNotFoundException
This method returns the type of the suite. If the suite cannot be found, this method throws a SuiteNotFoundException
.
java.util.Enumeration getDependencies()
This method returns the dynamic components that this MIDlet suite depends on as an Enumeration
of LibSuite
object instances. Library suites are only installed when an application that has a dependency on them specifies them using this method.
boolean isTrusted()
This method returns a boolean indicating whether the AMS considers this application trusted via its signature and certificate authorities.
String getSecurityDomain() throws SuiteNotFoundException
This method returns the security domain that the suite is bound to.
In addition, you can use the AMS to start the app as a running task with either of the following methods:
TaskInfo startTask(java.lang.String className)
This method starts the application as a task from this suite, returning information about the executing task in a TaskInfo
class. TaskInfo
is covered in more detail in "TaskManager Interface".
TaskInfo debugTask(java.lang.String className)
This method starts the application as a task from this suite in debug mode, returning information about the executing task in a TaskInfo
class. TaskInfo
is covered in more detail in"TaskManager Interface".
The LibSuite
interface is used to provide descriptive information about a library suite that has been installed on the system. A library suite can have one of two types: regular and system, as shown in Table 2-4. Library suites can only be installed on a system if there is an application that has a dependency on them. See AppSuite.getDependencies()
for more information.
Table 2-4 Library Suite Types
Type | Description |
---|---|
|
A regular application library. |
|
A system library. |
To determine the type that this suite belongs to, use the getType()
method, int
getType()
. This method returns the type of the suite as one of the predefined constants shown in Table 2-4 above.
The SuiteSetting
interface provides the data for a single suite setting. Each setting has an optional title to be displayed to user, an optional description, and number of choices. For example, the following represents a possible suite setting:
Title: Check for New Mail Description: How often should the application check for new mail? Choices: -Every 5 Minutes -Every 10 Minutes -Every 30 Minutes -Every Hour -Only When Requested
The following methods are provided by the SuiteSetting
interface:
int getIdx()
This method returns the integer index of the setting in the suite settings group. See below for more information on the SuiteSettingsGroup
interface.
java.lang.String getTitle()
java.lang.String getDescription()
int getChoicesCount()
This method returns an integer indicating the number of choices for this setting.
int getSelectedChoice()
This method returns the index of the currently selected choice.
void setSelectedChoice(int newSelection) throws java.lang.IndexOutOfBoundsException
This method sets the current choice. This method throws a java.lang.IndexOutOfBoundsException
if the selection index is not valid
java.lang.String getChoiceTitle(int idx)
This method returns the title of choice with specified index.
SuiteSettingsGroup
is an interface for a logical group of settings. Each group has an optional title, an optional description, and contains several individual settings defined using the SuiteSetting
interface in "SuiteSetting Interface". Each SuiteSettingsGroup
can be part of a larger SuiteSettings
object, defined in "SuiteSettings Interfaces".
int getIdx()
This method returns the index of this settings group in a SuiteSettings object, defined in "SuiteSettings Interfaces".
java.lang.String getTitle()
java.lang.String getDescription()
int getSettingsCount()
This method returns the number of individual settings in the group.
SuiteSetting getSetting(int idx)
The SuiteSettings
interface provides access to several SuiteSettingsGroup
objects. Do not confuse the SuiteSettings
(note the plural) object with the SuiteSetting
object defined in "SuiteSetting Interface".
The SuiteSettings
interface provides the ability to save the settings to persistent storage using the save()
method. Before doing so, however, the programmer must call the checkForError()
method to ensure that no settings, especially those from other MIDlet suites, contain a mutually exclusive combination with settings in this object.
int getGroupsCount()
This method returns the number of suite settings groups contained in this object.
SuiteSettingsGroup getGroup(int idx)
This method return the suite settings group with specified index.
java.lang.String checkForError()
This method checks if any settings contain a mutually exclusive combination of setting values, including those from other MIDlet suites. If so, the method returns an error message; otherwise, it returns null
. Only the first error is reported. Settings containing mutually exclusive combinations cannot be saved using the save()
method of this interface.
java.lang.String checkForWarning()
This method checks if a given settings contain a potentially dangerous combination of setting values. If so, the method returns a warning message; otherwise the method returns null
.
void save() throws java.lang.IllegalArgumentException
This method saves the suite settings. Before saving the settings, the programmer must check if these are valid using the checkForError()
method. Settings are not be saved if there are errors. Settings should also be checked for warnings. If there are warnings, those must be shown to the user as per the MIDP 2.0 specification. This method throws a java.lang.IllegalArgumentException
if the settings contain errors.