Skip Headers
Oracle® Java ME Embedded Application Management System API Guide
Release 3.4
  Go To Table Of Contents
Go To Index


1 AMS Introduction

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.

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.


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


Logging / Java VM System Output


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

ams-list [INDEX or NAME|VENDOR]

List all installed IMlet suites and their statuses or show the detail of a single suite

ams-install <URL> [username:password]

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.

ams-update <INDEX or NAME|VENDOR>

Update the installed IMlet

ams-remove <INDEX or NAME|VENDOR>

Remove an installed IMlet

ams-run <INDEX or NAME|VENDOR> [IMLET_ID] [-debug]

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

ams-suspend <INDEX or NAME|VENDOR> [IMLET_ID]

Suspend (pause) the specified IMlet or the default if none is specified

ams-resume <INDEX or NAME|VENDOR> [IMLET_ID]

Resume the specified IMlet or the default if none is specified

ams-setup <INDEX or NAME|VENDOR>

Display the setup menu of the IMlet

ams-info <INDEX or NAME|VENDOR>

Show information about the installed IMlet

ams-log <command> [param1, param2, ..., paramN]

ams-log wdog

Display the IMlet log or watchdog log if recorded by the watchdog handler in the platform

ams-logger-list [INDEX or NAME|VENDOR]

Retrieve the logger list for the IMlet or all the tasks if one is not specified

ams-logger-info <INDEX or NAME|VENDOR> [LOGGER_NAME]

Retrieve logger info for the specified IMlet and logger or all the loggers if is one is not specified

ams-logger-level-set <INDEX or NAME|VENDOR> [LOGGER_NAME] <LOGGER_LEVEL>

Set the logger level for specified IMlet or all loggers if one is not specified

help [command name]

List the available commands or detailed usages for a single command

sysmenu <on PASSWORD|off>

Enable hidden system menu commands. Currently, the password is 12345.


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

setprop <KEY> <VALUE>

Sets a property identified by <KEY> with the value <VALUE>

getprop <KEY>

Returns a property identified by <KEY>

odd [on|off]

Explicitly sets the on-device debugging (ODD) property to on or off. If no parameters are passed, returns the current ODD value.

shutdown [-r]

Perform either a shutdown of the board, or a reboot if the -r parameter has been passed. Note that the watchdog property should be set to true for some platforms (see appropriate reference documentation) to successfully reboot the board.

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,OK,3 suites are installed
oracle>> ams-remove 0
<<ams-remove,OK,helloworld removed
oracle>> ams-list
<<ams-list,OK,2 suites are installed
oracle>> ams-run 1
oracle>> ams-list
<<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:

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

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:

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.