6 Working With Devices

The Oracle Java ME SDK emulator simulates a CLDC or CDC device on your desktop computer. The emulator does not represent a specific device, but it provides correct implementations of its supported APIs.

The Oracle Java ME SDK provides default device skins. A skin is a thin layer on top of the emulator implementation that defines the appearance, screen characteristics, and input controls. To make your own skin, see Section 6.11, "Using the Custom Device Skin Creator".

6.1 Emulating Devices

The SDK runs applications on an emulated device or a real device. Before you can run an application from the SDK, the Device Manager, which manages both emulated and real devices, must be running. When the Oracle Java ME SDK runs, the Device Manager automatically launches and starts detecting devices. The default devices shipped with the SDK are automatically found and displayed in the Device Selector window (Tools > Java ME > Device Selector).

6.1.1 The Device Manager on Windows

The SDK uses the device manager to detect devices and displays the available devices in the Device Selector window (Tools > Java ME > Device Selector). The Device Manager is a service and you can see it running in your Windows system tray. In the task manager, the process is labeled device-manager.exe.

You can right-click on the icon and select Exit to stop the service.

Description of devmgrmenudef.gif follows

Description of the illustration devmgrmenudef.gif

To restart the device manager, double-click installdir\bin\device-manager.exe. You can also start it from the command line as described in Section 14.1, "Run the Device Manager".

Choosing Manage Device Addresses opens the Device Address Manager. Enter an IP address and select Add to add a device. Select an address and click Remove if you have an address you no longer want to detect. The device will no longer be displayed in the Device Selector.

6.1.2 Starting an Emulator

Typically an emulator is launched when a Java ME SDK project is run from the NetBeans IDE or the command line. The default emulator is determined by the Java ME platform selected for the project, as described in Section 2.2.1, "Java ME Platforms".

You can open an emulator without running an application from the IDE. From the Windows Start menu, select Programs > Java(TM) ME Platform SDK 3.2 and choose the desired emulator. You can also click the emulator shortcuts installed on your Windows desktop.

Description of the illustration emu-start.gif

To run an application from the emulator, select Application > Run MIDlet Suite (or IMlet Suite). Provide the path to the application and any other information, and click OK.

6.1.3 CLDC Application Management Software Home

The CLDC AMS home screen features three utilities:

Install Application. This utility opens a form in which you can specify a URL (or a file path) for a JAD file to install.
Manage Certificate Authorities. This feature displays the certificates authorities for the device. In this interface the white box indicates the certificate is checked (active). You can uncheck certificates that are not needed.
Output Console. The output console displays system output statements from a running application. The application must write to the Java standard output console using, for example: System.out.println("text");

Start the Output Console, then start your application. Use F7, Switch running MIDlet, to switch between the application and the Output Console.

The Output Console is an application that consumes resources. See Section 6.5, "Changing the Maximum Number of Concurrent Applications"

Description of the illustration emu-output-console.gif

See Section 6.9, "Emulator Features" and Section 6.10, "Emulator Menus".

6.2 Adding a Real Device

The device selector can detect a device that has a compatible runtime. Typically this device has network capabilities and is connected to the computer running Java ME SDK.

To detect a physical device, click CTRL-D, or click the device icon at the top of the Device Selector window.
Type an IP address and click Next. Click Finish.

You can also enter an IP address in the Device Manager, as described in Section 6.1.1, "The Device Manager on Windows".
The physical device is listed in the appropriate platform tree. By default the device has "ExternalPhone" appended to the name.

For example, if an IMP-NG device is detected it is placed in the IMP-NG node and given the name IMPNGExternalPhone1.

6.3 Viewing Device Properties

The Device Selector window lists all available devices grouped by platform. If this window is not visible, select Tools > Java ME > Device Selector.

If no Java ME platform is registered in NetBeans, the Device Selector displays a node labeled No Device Found. If you see this message at startup, it typically means device discovery is incomplete and you must wait a few seconds.

Each sub node represents a device skin. Two instances are provided for some CLDC devices, for example, JavaMEPhone1 and JavaMEPhone2. Instances of the same device have the same capabilities but unique names and phone numbers, making it easy for you to test communication between devices of the same type. To make your own device, see Section 6.11, "Using the Custom Device Skin Creator".

For Device names, see Section 8.4, "Oracle Java ME SDK Directories". The properties for each device skin are stored in XML files in your user work directory. See Table 8-1.

6.3.1 Platform Properties

To view platform properties from the device selector, click on the platform node (for example, CLDC or CDC). The Properties window is, by default, docked in the upper right portion of the user interface. If the Properties window is not visible, select Windows > Properties.

To view the platform properties in a separate window, right-click on the platform node and select Properties. The information in the docked properties window and the separate window is the same.

6.3.2 Device Information

In the Device Selector window, double-click a device node. The Device Information tab opens in the central Main window. It displays a picture of the device and displays details, supported hardware capabilities, keyboard support, supported media formats, and the supported runtimes.

6.3.3 Device Properties

In the Device Selector window, click a device node (such as JavaMEPhone1) to display the device properties. The Properties window is, by default, docked in the upper right portion of the user interface. If the Properties window is not visible, select Windows > Properties.

6.4 Setting Device Properties

In the Device Selector Window, right-click on a device and select Properties. Any properties shown in gray font cannot be changed. You can adjust the device properties shown in black. Only CLDC options can be adjusted. The CDC options cannot be changed.

6.4.1 General

This section lists general properties that can be changed.

Phone Number 1. You can set the phone number to any appropriate sequence, considering country codes, area codes, and so forth. If you reset this value, the setting applies to future instances. The number is a base value for the selected device.

Heapsize. The heap is the memory allocated on a device to store your applications's objects. The Heapsize property is the maximum heap size for the emulator. You can choose a new maximum size from the dropdown menu.

Security Domain. Select a security setting from the dropdown menu. See Section 13.2.1, "Specify the Security Domain for an Emulator". Applies to CLDC platforms.

JAM storage size in KB. The amount of space available for applications installed over the air.

Locale. Type in the locale as defined in the MIDP 2.0 specification: http://jcp.org/en/jsr/detail?id=118

Remove MIDlet Suite in execution mode. If this option is enabled, record stores and other resources created by the MIDlet are removed when you exit the MIDlet (assuming the MIDlet was started in execution mode).

6.4.2 Monitor

If enabled (checked), the Check boxes for Trace GC (garbage collection), Trace Class Loading, Trace Exceptions, and Trace Method Calls activate tracing for the device the next time the emulator is launched. The trace output is displayed at runtime in the user interface Output window. Trace Method Calls returns many messages, and emulator performance can be affected. See Chapter 11, "Monitoring Memory".

6.4.3 SATSA

See Section 21.1, "Card Slots in the Emulator".

6.4.4 Location Provider #1 and #2

These properties determine the selection of a location provider. Two providers are offered so that your application can test matching the location provider criteria.

If you select a property a short explanation is shown in the description area just below the Properties table. For more information on these values, see the Location API at http://jcp.org/en/jsr/detail?id=179.

6.4.5 Bluetooth and OBEX

Bluetooth. See Section 18.1, "Setting OBEX and Bluetooth Properties".

6.5 Changing the Maximum Number of Concurrent Applications

By default the CLDC runtime allows a maximum of five applications to run simultaneously. If you exceed the limit, you see the message, "No more concurrent applications allowed."

This number includes active applications, the Application Management Software (AMS), and any active on-device tooling agent (such as the profiler). You can close some applications, or increase the limit as follows:

In the Oracle Java ME SDK installation, locate the following file:

installdir\runtimes\cldc-hi\bin\jwc_properties.ini
Locate the property MAX_ISOLATES. The value can be increased up to 15. However, you should be conservative as many applications running concurrently can affect performance.

6.6 Opening a Serial Port

In application code, you can use Connector.open("comm:COM1") to open a port on the device. On Windows, you can open a serial port such as COM1 or COM2.

6.7 Running a Project from the Device Selector

The SDK determines which open projects are suitable for a device. Right-click on the device and select a project from the context menu.

You can also launch the emulator to run a project from the command line, as explained in Section 14.3, "Emulator Command Line Options".

6.8 Running Projects Simultaneously on a Single Device

CLDC-based devices are capable of running multiple virtual machines. You can test this behavior in the emulator. Be sure the output window is visible in the SDK (select Window > Output > Output). To test this feature, follow these steps:

Open the sample projects Games and AudioDemo.
In the device selector, choose a CLDC device and run Games. When the emulator launches run AudioDemo on the same device.

As each MIDlet loads, the AMS automatically installs it.
In AudioDemo, launch the Audio Player, and play the JavaOne theme.

Select AudioPlayer, then from the soft menu, select 1, Launch. Select JavaOne Theme and press the Play soft button.
In the emulator, choose Application > AMS Home, or press F4.

Select Games. From the soft menu, select 1, Open. The music continues to play while you are able to simultaneously launch and play games.
Select Application > AMS Home, or press F4. Highlight AudioSamples, and from the soft menu, select 2, Bring to foreground. Press the Pause soft key. The music stops playing.
Select Application > AMS Home, or press F4. Highlight AudioSamples and from the soft menu, select 1, Open. Select Bouncing Ball from the list and press the Launch soft button. Select MIDI background and press the Play soft button.
Select Application > AMS Home, or press F4. Select Application > Switch Running MIDlet. Select Audio Player and press the Switch to soft button. You can press the Play soft button to resume the Audio Player.

6.9 Emulator Features

Figure 6-1, "Emulator Features" shows common emulator features available on emulators for the CLDC platform.

Device Name. Shown in the upper window frame. See Table 8-1, "Device Names".

Transmission Indicator. On the upper left of the emulator image, this blue light turns on when a transmission is occurring. Typically you see it when an application is installed over-the-air, or when a message is being sent or received. For example, when you receive a message from the WMA console.

Menus. See Section 6.10, "Emulator Menus".

Device ID. See Table 8-1, "Device Names".

Exit Button. Pushing the button on the upper right of the emulator image has the same effect as selecting Application > Exit.

Emulator Status Bar. Information about the current system state is shown in the status bar at the bottom of the emulator window.

Figure 6-1 Emulator Features

Description of "Figure 6-1 Emulator Features"

6.10 Emulator Menus

The emulator for the CLDC platform has Application, Device, Edit, View, and Help menus.

The emulator for the CDC platform has Application, View, and Help menus. The View and Help menus are the same on CDC and CLDC platforms. For CDC, the Device menu is not populated, and Application menu contains only the Exit option.

6.10.1 Application

The Application menu is fully populated for the CLDC platform. The Application options are as follows:

Option	Accelerator	Description
Run MIDlet suite		Emulator interface for launching MIDlets.
AMS Home	F4	Exit the current application and return to the Application Management Software home.
Stop	F10	Stops the currently running MIDlet.
Change Locale		This option only works with localized MIDlets. Enter a locale identifier. The format is similar to Java SE 6, as follows: 2-letter-lang-code separator 2-letter-country-code For example, en-US, cs-CZ, zh-CN, ja-JP. The separator can be a dash or an underscore.
Resume	F6	Resume a suspended application.
Suspend	F5	Pause a running application. Do not use this option if you are runing the memory monitor.
Switch Running MIDlet	F7	When you have multiple MIDlets running, toggle between them. You see a list of running MIDlets and you can chose the one you want to switch to. See Section 6.8, "Running Projects Simultaneously on a Single Device".
Exit	Exit button on emulator upper right	Close the emulator process and stop the build process (or processes).

6.10.2 Device

This menu is available on CLDC platforms only.

6.10.2.1 Messages

Choose Device > Messages to see what is written in the message area. This is the emulator's Inbox. The Inbox displays WMA messages that are addressed to the device, not an application on the device. Messages are sent to this interface in the following cases:

an MMS message is sent without an AppID in the address
an SMS message is sent without a port in the address (or the port number is 0)
an SMS text message is sent with a port in the address, but there is not a Java ME application listening on the specified port

To test sending messages to the inbox use the WMA Console in Netbeans, or from the command line, use wma-tool.exe to send SMS messages. Note, wma-tool.exe requires an AppID for MMS, so wma-tool can not be used to send an MMS.

6.10.2.2 Landmark Stores

Choose Device > Landmark Stores to open the Landmark Store utility. In this interface you can view and edit a landmark store installed as part of an application. You can also create a new landmark store, define landmarks, define landmark categories, and assign landmarks to categories.

6.10.2.3 Orientation

Use this feature to test your application's ability to display in portrait and landscape formats. The default is 0 degrees. Change the orientation to 90, 180, or 270 degrees. You can also rotate 90 degrees clockwise (F8) or counterclockwise (F9) from the current position.

6.10.2.4 External Events Generator

The External Events Generator provides a way to interact with an application by injecting events. The interaction may be through a user interface, or through a script file. The following menu options each have a tab on the External Events Generator. The use of the External Events Generator is addressed in the discussion for each JSR.

Contactless Communication. See Section 29.1, "Using ContactlessDemo".
File Connection. Section 17.1, "FileConnection API".
Location. Section 22.1, "Setting the Emulator's Location at Runtime".
Sensors. Section 28.2, "Using a Mobile Sensor Project", Section 28.3, "Creating a Sensor Script File".

6.10.3 Edit

The Edit menu provides basic editing utilities for the CLDC platform.

Option	Accelerator	Description
Copy	CTRL-C	Copy selected material to the paste buffer.
Cut	CTRL-X	Move selected material to the paste buffer.
Paste	CTRL-V	Insert the contents of the paste buffer.

6.10.4 View

The View menu is available for both CLDC and CDC platforms. The only View option available is Always On Top.

Option	Description
Always On Top	Keeps the emulator in the foreground. This is especially useful when you are running multiple emulator instances and you want to see them all and send messages between devices.

6.10.5 Help

The Help menu displays an abbreviated helpset specifically for the emulator window.

6.11 Using the Custom Device Skin Creator

With the Custom Device Skin Creator you can create your own skins. The appearance of the custom skins is generic, but the functionality can be tailored to your own specifications.

6.11.1 Creating a New Custom Device Skin

Follow these steps to create a new custom device skin.

Select Tools > Java ME > Custom Device Skin Creator.

The custom device tree displays Java ME platforms and custom devices, if any.
Select a platform and click the New... button.
Change the default configuration to match your specifications, and click OK.

Your skin is added to the custom device tree and eventually appears in the Device Selector. Your custom skin can be used to run projects from the IDE or from the command line.

The custom device tree affects what appears in the Device Selector. For example, if you don't want a custom skin to appear in the device selector, you must remove it from the custom device tree.

The skin definition is saved in installdir\toolkit-lib\devices.

6.11.2 Managing Custom Skins

Custom skins should always be managed using the Custom Device Skin Creator. Using the tool ensures that your skin will be properly detected and integrated with the Oracle Java ME SDK.

Edit. Select a device to change, and click Edit.
Clone. Select a device to copy, and click Clone. To prevent confusion, be sure to provide a unique name.
Export. Select a device to save, and click Export.

When a custom device is created it is saved in installdir\toolkit-lib\devices, therefore you could lose your device if you reinstall.

An exported device is stored in a .zip file and saved in the user's My Documents directory (typically userhome\My Documents).
Import. Select a node in the custom device tree and click Import. Choose a .zip file created with the Export command.
Remove. Select a device to delete and click Remove. This action completely deletes the skin.