2 Application and Library Suites

The SuiteInfo Interface

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:

In addition, suites contain five binary flags that describe their state, as shown in Table 2-2:

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()

  This method returns the name for given suite.

• 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()

  This method retrieves the vendor name for given suite

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

AppSuite Interface

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:

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

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

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.

SuiteSetting Interface

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()

  This method returns the title of the setting.

• java.lang.String getDescription()

  This method returns the description of the setting.

• 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 Interface

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()

  This method returns the settings group title.

• java.lang.String getDescription()

  This method returns the settings group description.

• int getSettingsCount()

  This method returns the number of individual settings in the group.

• SuiteSetting getSetting(int idx)

  This method returns the SuiteSetting with specified index.

SuiteSettings Interfaces

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.