Oracle® Java ME Embedded Application Management System API Guide Release 3.4 E35109-03 |
|
Previous |
Next |
This chapter introduces the "headless" Application Management System (AMS) APIs that are used to interface with the Oracle Java ME Embedded device. The AMS APIs contain management functionality, including application and library installation and storage, certificate maintenance, and task management. The AMS is typically accessed through a command-line interface, or via a remote protocol and a remote tool with a user interface.
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.
WARNING: The command-line interface (CLI) feature in this Oracle Java ME Embedded software release is provided only as a concept for your reference. It uses insecure connections with no encryption, authentication, or authorization. |
Table 1-1 Ports Used by the Embedded Board
Port | Description |
---|---|
65000 |
Logging / Java VM System Output |
65002 |
Command-line interface |
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.
Table 1-2 AMS CLI Commands
Syntax | Description |
---|---|
|
List all installed IMlet suites and their statuses or show the detail of a single suite |
|
Install an IMlet using the specified JAR or JAD file, specified as a URL. An optional username and password can be supplied for login information as well. |
|
Update the installed IMlet |
|
Remove an installed IMlet |
|
Execute the specified IMlet or the default if none is specified. An optional debug parameter can be specified to run the IMlet in debug mode. |
|
Stop the specified IMlet or the default if none is specified |
|
Suspend (pause) the specified IMlet or the default if none is specified |
|
Resume the specified IMlet or the default if none is specified |
|
Display the setup menu of the IMlet |
|
Show information about the installed IMlet |
|
Display the IMlet log or watchdog log if recorded by the watchdog handler in the platform |
|
Retrieve the logger list for the IMlet or all the tasks if one is not specified |
|
Retrieve logger info for the specified IMlet and logger or all the loggers if is one is not specified |
|
Set the logger level for specified IMlet or all loggers if one is not specified |
|
List the available commands or detailed usages for a single command |
|
Enable hidden system menu commands. Currently, the password is |
|
Terminates the current session. |
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.
Table 1-3 Additional System Commands Available in the AMS CLI
Syntax | Description |
---|---|
|
Sets a property identified by |
|
Returns a property identified by |
|
Explicitly sets the on-device debugging (ODD) property to on or off. If no parameters are passed, returns the current ODD value. |
|
Perform either a shutdown of the board, or a reboot if the |
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
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.