3 Platforms

This chapter describes the Oracle Java ME SDK technology platforms, also called stacks. They are: "CLDC with MIDP," "IMP-NG," and "CDC," as discussed in "Emulation Platforms."

A project runs on a particular emulation platform. The Device Manager determines whether a device is appropriate for your project based on the platform, the APIs your application uses, and a set of device properties. If you run an application and an appropriate emulator or device is currently running, the SDK automatically installs and runs your application in the current device so that you do not have to launch the emulator repeatedly.

3.1 Emulation Platforms

An emulator simulates the execution of an application on one or more target devices. An emulation platform enables you to understand the user experience for an application and test basic portability. For example, a platform enables you to run applications on several sample devices with different features, such as screen size, keyboard, runtime profile and other characteristics.

Oracle Java ME SDK provides the following emulation platforms:

Connected Limited Device Configuration (CLDC) with Mobile Information Device Profile (MIDP)
CLDC with MIDP, Information Module Profile - Next Generation (IMP-NG) subset
Connected Device Configuration (CDC) with Advanced Graphics and User Interface (AGUI)
CDC with Personal Basis Profile (PBP)

All platforms include predefined devices with different screen sizes, runtime profiles, and input methods.

See "CLDC with MIDP," "IMP-NG," and "CDC."

3.1.1 CLDC with MIDP

CLDC/MIDP applications conform to the following specifications:

Connected Limited Device Configuration 1.1

http://jcp.org/en/jsr/detail?id=139
Mobile Information Device Profile 2.1

http://download.oracle.com/otndocs/jcp/midp-2.1-mrel-oth-JSpec
All the JSRs listed in "JCP APIs"

CLDC/MIDP applications are targeted for devices that typically have the following capabilities:

A 16-bit or 32-bit processor with a clock speed of 16MHz or higher
At least 160 KB of non-volatile memory allocated for the CLDC libraries and virtual machine
At least 192 KB of total memory available for the Java platform
Low power consumption, often operating on battery power
Connectivity to some kind of network, often with a wireless, intermittent connection and limited bandwidth

Typical devices might be cellular phones, pagers, low-end personal organizers, and machine-to-machine equipment. In addition, CLDC can also be deployed in home appliances, TV set-top boxes, and point-of-sale terminals.

The SDK provides two default emulators to support CLDC:

ClamshellJavaMEPhone1

A flip phone with a primary display and a secondary display.
JavaMEPhone1 and JavaMEPhone2

A flat touch screen device.

These devices support CLDC 1.1, MIDP 2.1, and optional packages for JSRs 75, 82, 135, 172, 177, 179, 184, 205, 211, 226, 234, 239, 256, 257, and 280.

See Chapter 4, "Using Sample Projects" Chapter 5, "Creating and Editing Projects," and Chapter 7, "Working With Devices."

3.1.2 IMP-NG

JSR 228 describes the Information Module Profile - Next Generation, referred to as IMP-NG. This JSR extends and enhances JSR 195: Information Module Profile.

The IMP-NG implementation depends upon CLDC 1.1. It is a strict subset of MIDP 2.1 that excludes MIDP 2.1 graphical display capabilities, resulting in a smaller footprint appropriate for Information Modules (IMs). Potential devices for CLDC with IMP-NG might be modems, home electronics devices, or industrial metering devices.

An IMP-NG application is an IMlet, and multiple IMlets in a single JAR file form an IMlet suite. When creating an IMlet project you follow the same process as that you use to create a Java ME Mobile Application project and select an IMP-NG device. The device selection determines the supported JSRs.

The IMP-NG stack supports the following JCP APIs: JSRs 75, 120, 172, 177, 179, 257, and 280. In addition, Oracle provides APIs to support IMP-NG development, as described in "Oracle APIs."

The Oracle Java ME SDK implementation provides IMP-NG emulation, on-device tooling connectivity to external devices, and Attention (AT) Command support. The SDK emulator supports IMP-NG with IMPNGDevice1 and IMPNGDevice2 skins and provides simple interfaces for Inter-Integrated Circuit (I²C), Serial Peripheral Interface (SPI), General Purpose Input/Output (GPIO), and Memory-mapped I/O (MMIO) buses. The emulator's external event generator provides a way for you to inject calls to emulate AT Commands, alter basic pin and port information for GPIO, and memory block values.

See "Running IMP-NG Sample Projects."

3.1.3 CDC

A CDC (http://jcp.org/en/jsr/detail?id=218) application is an application targeted for network-connected consumer and embedded devices, including high-end mobile phones, smart communicators, high-end PDAs, and set-top boxes.

Devices that support CDC typically include a 32-bit microprocessor or controller and make about 2 MB of RAM and 2.5 MB of ROM available to the Java application environment.

CDC is based upon the open source project phoneME Advanced, found at http://java.net/projects/phoneme. A CDC application conforms to the Connected Device Configuration with a set of profiles that include Personal Basis Profile, Foundation Profile, and AGUI:

CDC 1.1 with PBP 1.1 (http://jcp.org/en/jsr/detail?id=217)
Foundation Profile 1.1 (http://jcp.org/aboutJava/communityprocess/final/jsr219/index.html)
AGUI 1.0 (http://www.jcp.org/en/jsr/detail?id=209)

The SDK provides three default emulators to support CDC:

Default CdcPbpPhone1

CDC 1.1, PBP 1.1, Foundation Profile (FP) 1.1
VgaAGUIPhone1

CDC 1.1, PBP 1.1, FP 1.1 and AGUI 1.0
VgaCdcPhone1

CDC 1.1, PBP 1.1, FP 1.1

See "Project Types" and "Viewing Device Properties" for more information on project types and device properties.

3.2 Managing Java Platforms

To view the Java Platform Manager, click the Tools menu and select Java Platforms. Alternatively, right-click a project, select Properties from the context menu, select the Platform category, and select the Manage Emulators button to open the Java Platform Manager.

The Java Platform Manager is a tool for managing different versions of the Java Development Kit (JDK) and customizing Java platforms that your applications depend on. You can add source files and Javadoc documents to the existing platforms.

The Oracle Java ME SDK pre-registers CDC, J2ME, and Java SE (the JDK serves as the default platform) for version 3.4. These platforms have similar options:

Devices. (J2ME) View all the CLDC and IMP-NG devices that the Device Manager has discovered. Click Refresh to reconfigure the platform and refresh the list.
Classes. (CDC) View the platform's classpaths. A class's location in the list determines its place in the classpath. For the CDC platform, you can add a JAR or folder containing additional classes. You can also use the Move Up and Move Down buttons to change the class position.
Sources. (CDC, J2ME, and Java SE) Add JAR files or source files to the Sources tab to register source code.
Javadoc. (CDC, J2ME, and Java SE) Add Javadoc documentation to support any new classes or source files you have added.
Tools and Extensions. (For J2ME, only as Devices) See "Java ME Platforms" for more information.

3.2.1 Java ME Platforms

In the Oracle Java ME SDK the platforms are embedded Java runtimes specifically for resource-constrained devices. Because the NetBeans Mobility pack is installed for Java ME, you see the legacy 3.2 platforms coexisting with version 3.4 platforms and devices. Each platform has its own set of devices and optional packages.

Note:

If you cannot see the 3.4 devices in the Device Selector, select Tools > Java ME > Active Device Manager and select Java(TM) ME Platform SDK 3.4.

Applications that worked in previous platform versions might not run on the current version, and vice versa. Follow these steps to set a project's platform options.

Right-click on a project and select Properties from the context menu.
Select the Platform category. Be sure that the Emulator Platform is set to version 3.4.
The device configuration should be automatically selected, but the Device Profile might not be explicitly selected. Be sure to select a profile.
Optional. Check any optional packages that are required to support the current project. (If this is an IMP-NG project you also see the Oracle APIs listed as optional packages. See "Oracle APIs").

Click OK.
Rebuild the project and run.

3.2.2 Create a Platform for Legacy CDC Projects

The Oracle Java ME SDK version 3.4 platform name for CDC does not match the name in the legacy CDC toolkit and the CDC Mobility Pack. The legacy name is "Sun Java Toolkit 1.0 for Connected Device Configuration" while the SDK name is "CDC Oracle Java(TM) Platform Micro Edition SDK 3.4." To ensure a successful import, you can create a new platform and give it the legacy name.

The following procedure enables you to import legacy CDC projects without Reference errors (see "Resolving Reference Problems").

Click the Tools menu and select Java Platforms. Select "CDC Oracle Java(TM) Platform Micro Edition SDK 3.4." and in the Classes tab, note the libraries required for the platform.
Click Add Platform... .
Select Java ME CDC Platform Emulator and click Next.
On the Choose Platform page, select the SDK installation directory. Click Next.
On the Platform Name page, type "Sun Java Toolkit 1.0 for Connected Device Configuration" in the Name field. In the Sources tab, click Add and select the following libraries from the SDK installation directory: agui_1.0.jar, cdc_1.1.jar, fp_1.1.jar, pbp_1.1.jar, and secop_1.0.jar.

Click Finish and Close.

See "Import a Legacy CDC Project" and "Resolving Reference Problems."