1 AMS Introduction

Connecting to the Headless AMS CLI

With the Java ME Embedded distribution running, start a terminal emulator (such as PuTTY) and create a raw socket connection to the device address shown on the board. The default ports that are used are shown in Table 1-1.

Once you have a successful connection to the AMS CLI, you can use it to install Java embedded programs with the AMS commands shown in Table 1-2. Note that the AMS syntax may change in future releases; entering help [command] is the best way to obtain the latest CLI syntax.

When the sysmenu command is entered with the on option, additional system menu commands are available with the AMS CLI, as shown in Table 1-3.

Installed IMlets can be in one of three states: stopped, suspended, or running. Here is a typical example of using the AMS to install, list, run, and remove an application.

oracle>> ams-install file:///helloworld.jad
<<ams-install,start install,file:///helloworld.jad
<<ams-install,install status: stage 0, 5%
<<ams-install,install status: stage 3, 100%
<<ams-install,install status: stage 4, 100%
<<ams-install,OK,Install success

oracle>> ams-list
<<ams-list,0.helloworld|Oracle,STOPPED
<<ams-list,1.netdemo|Oracle,STOPPED
<<ams-list,2.rs232demo|Oracle,RUNNING
<<ams-list,OK,3 suites are installed
 
oracle>> ams-remove 0
<<ams-remove,OK,helloworld removed
 
oracle>> ams-list
<<ams-list,1.netdemo|Oracle,STOPPED
<<ams-list,2.rs232demo|Oracle,RUNNING
<<ams-list,OK,2 suites are installed
 
oracle>> ams-run 1
<<ams-run,OK,started
 
oracle>> ams-list
<<ams-list,1.netdemo|Oracle,RUNNING
<<ams-list,2.rs232demo|Oracle,RUNNING
<<ams-list,OK,2 suites are installed

AmsFactory Class

Certain Java ME Embedded applications may interface with the low-level API classes for the AMS. The entry point for all AMS functionality is provided by the AmsFactory class. The AmsFactory must not be instantiated. Instead, the AmsFactory class provides seven static methods which return objects that provide AMS operations, including application and library installation and storage, certificate maintenance, and task management.

The seven static methods are:

• static AMSRequestManager getAMSRequestManager() throws SecurityException, UnsupportedServiceException

  This static method returns the AMSRequestManager, which is responsible for handling special user requests, such as pressing a "Home" button or switching to another running application. This method can throw a SecurityException if the user does not have the required permission (for example, if the calling MIDlet is untrusted or unsigned as an AMS UI MIDlet), or an UnsupportedServiceException if the service is not implemented.

• static AppInstaller getAppInstaller() throws SecurityException

  This static method returns the AppInstaller, which is responsible for downloading and installing applications and subordinate libraries. This method can throw a SecurityException if the user does not have the required permissions.

• static CertificateInfoManager getCertificateInfoManager() throws SecurityException

  This static method returns the CertificateInfoManager, which manages the certificates installed on the system. Certificates are used to authenticate apps that are downloaded to the system. This method can throw a SecurityException if the user does not have the required permissions.

• static LinkInstaller getLinkInstaller() throws SecurityException, UnsupportedServiceException

  This static method returns the LinkInstaller, which is responsible for downloading and installing links to applications. This method can throw a SecurityException if the user does not have the required permissions, or an UnsupportedServiceException if the service is not supported.

• static LocaleChangeNotifier getLocaleChangeNotifier() throws SecurityException

  This static method returns a LocaleChangeNotifier, which alerts applications when a change in locale occurs. This method can throw a SecurityException if the user does not have the required permissions.

• static SuiteStoreManager getStoreManager() throws SecurityException

  This static method returns the SuiteStoreManager, which is responsible for providing a data store for installed suites. This object does not provide access to any purchasing mechanism, but instead assists in storing and managing applications on the local device. This method can throw a SecurityException if the user does not have the required permissions.

• static TaskManager getTaskManager() throws SecurityException, UnsupportedServiceException

  This static method returns the TaskManager, which is responsible for organizing, identifying, and starting applications. This method can throw a SecurityException if the user does not have the required permissions, or an UnsupportedServiceException if the service is not supported.

The seven static methods of the AmsFactory class provide a complete view of the AMS itself. The AMS consists of two installers:

• App Installer

• Link Installer

In this context, an app is synonymous with an application: a MIDlet that is running in the Oracle Java ME Embedded. A link is a reference to an application or library that is yet to be downloaded. Apps, libraries, and links are the three unique entities that are installed and managed in the AMS.

In addition, two managers assist with installing and monitoring application suites:

• Suite Store Manager

• Task Manager

The AMS also contains the AMS Request Manager, which notifies the UI of requests such as pressing a "Home" button or switching between applications. In addition, the Certificate Info Manager is responsible for managing certificates. Finally, the AMS contains a notification mechanism, the Locale Change Notifier, that alerts interested listeners if the current locale changes.

The AmsFactory is the only class in the AMS APIs. The rest of the objects that are presented to the programmer are implementations of interfaces defined throughout the remainder of this document. The use of encapsulated classes is a common software design pattern that decouples the AMS implementation from the means of accessing it, allowing further development and improvement of the AMS without the risk of breaking the API.