4 About Java ME Embedded Applications

Java ME Embedded applications run on small devices, with either a simple or no display at all, with low power consumption, and with limited network connectivity. Target devices include wireless modules, smart meters, industrial controllers, home automation systems, and so on.

The chapter contains the following topics:

Structure of Java ME Embedded Application

Each Java ME Embedded application consists of an IMlet and other classes and resources as may be needed by the application. An IMlet is a class that extends the javax.microedition.midlet.MIDlet class and conforms to the Java ME Embedded Profile 8 (MEEP 8) specification. The methods of this class enable the application management software (AMS) on an embedded device to create, start, pause, and destroy an IMlet. Several IMlets can be packaged into a Java Archive (JAR) file along with a manifest file to form an IMlet suite. A Java Application Descriptor (JAD) file is used to describe the IMlet suite. Figure 4-1 shows the structure of a Java ME Embedded Application.

Figure 4-1 Structure of a Java ME Embedded Application

Description of "Figure 4-1 Structure of a Java ME Embedded Application"

For more information about the javax.microedition.midlet.MIDlet class, see the API documentation at

http://docs.oracle.com/javame/8.0/api/meep/api/javax/microedition/midlet/MIDlet.html

Note:

Although an IMlet is a type of MIDlet, in the context of the Java ME Embedded platform, both terms are used interchangeably. They both refer to an application that conforms to the MEEP 8 specification.

Procedures to Develop a Java ME Application

You can develop a Java ME Embedded application either with or without using an IDE.

The general procedure for developing a Java ME Embedded application includes the following steps:

Create an IMlet source code file that extends the javax.microedition.midlet.MIDlet class.
Compile the IMlet into a binary class file.
Create a manifest file.
Package the IMlet class and manifest into a JAR file.
Create a JAD file associated with the JAR.

The JAD file and the associated JAR file form an IMlet suite that can be deployed on an embedded device.

An Integrated Development Environment (IDE) automates most tasks involved in the development of applications. For instance, an IDE manages source code and resource files, parses code to highlight syntax errors, and configures the necessary settings to build, package, run, and debug an application. Source files and settings are combined by the IDE into a project.

Developing a Java ME Embedded application using an IDE includes the following steps:

Create a Java ME Embedded Application project.
Add one or more IMlet source files along with any other necessary resource files to the project.
Build the project.

The IDE automatically compiles the IMlet class and other necessary classes, creates the manifest file, packages it all into a JAR file, and creates a JAD file to complete the IMlet suite.

Oracle Java ME SDK provides plug-ins for NetBeans IDE and Eclipse IDE that enable you to use all features of the SDK from within the IDE.

Creating and running a sample Java ME Embedded application is a good way to learn the basics of Oracle Java ME SDK. You can create an application either with or without an Integrated Development Environment (IDE), run it on a real connected device or an emulated device.

Source Code for a Sample IMlet

The following example shows the source code for a sample IMlet. You can use this source code to create a sample Java ME Embedded application.

package imletdemo;
import javax.microedition.midlet.MIDlet;

public class IMletDemo extends MIDlet {

    public void startApp() {
        try {
            // Add startup operations here
        } catch (Exception ex) {
            ex.printStackTrace();
            return;
        }
        System.out.println("IMletDemo is started...");
        // Add application code here
    }

    public void destroyApp(boolean unconditional) {
       // Add operations to close all resources that have been opened
    }
}

Developing a Sample Java ME Embedded Application in NetBeans IDE

NetBeans IDE automates the process of building, packaging and running Java ME Embedded applications by providing a standard Java ME Embedded Application project. A Java ME Embedded Application project contains a fully functional template IMlet, and is configured in such a way that you only have to click one button to run it.

You can edit the provided IMlet source code, add other resource files to the project, and configure the project settings as needed. NetBeans IDE will ensure that all source files, resources, and settings are managed properly.

When you run a Java ME Embedded Application project, NetBeans IDE automatically builds, packages, and runs the application on the default emulated EmbeddedDevice1 or on another available device. You can choose to run it on another emulated device, or a real connected device.

Developing a sample Java ME Embedded application in NetBeans IDE using Oracle Java ME SDK involves the following procedures:

Creating the IMletDemo Project in NetBeans IDE

A project combines source files and settings that are necessary to build, run, and debug an application. Without an IDE, there are a lot more manual actions required to manage all project files and settings.

NetBeans IDE includes various project types that are preconfigured for developing Java SE, JavaFX, Java ME, and many other types of applications. To create a Java ME Embedded Application project in NetBeans IDE:

On the File menu, select New Project.
On the Choose Project step, select Java ME Embedded from the Categories list and Java ME Embedded Application from the Projects list. Click Next.
On the Name and Location step, enter IMletDemo in the Project Name field. Click Finish.

You should see the created IMletDemo project in the Projects tab of NetBeans IDE. The IMletDemo.java source file from the imletdemo package should be open in a separate tab.

If everything is correct, you should be able to build and run the IMletDemo project generated from the standard Java ME Embedded Application template in NetBeans IDE. However, the application will not do anything, because methods do not contain any code.

Copy the code shown in "Source Code for a Sample IMlet" into the IMletDemo.java file. This will make the application print IMletDemo is started... to the output console when you run the application.

Running the IMletDemo Project in NetBeans IDE

Oracle Java ME SDK 8.3 provides the Java ME Embedded 8.3 emulation environment that enables you to duplicate (or emulate) an embedded device and run the application without the actual device. By default, when you run a Java ME Embedded Application project in NetBeans IDE, it is started on the emulated device EmbeddedDevice1.

To run the IMletDemo project, do one of the following:

Select the IMletDemo project in the Projects tab and click the green right-arrow icon in the NetBeans IDE toolbar.
Select the IMletDemo project in the Projects tab and press F6 on the keyboard.
Select the IMletDemo project in the Projects tab, open the Run menu and select Run Project (IMletDemo).
Right-click the IMletDemo project name in the Projects tab and select Run.

If successful, the EmbeddedDevice1 emulator starts with the IMletDemo suite running. If you used the code from "Source Code for a Sample IMlet", you should see the following line in the Output tab of NetBeans IDE:

IMletDemo is started...

To open the Output tab in NetBeans IDE, select Output on the Window menu, or press Ctrl+4 on the keyboard.

You can run the IMletDemo project on a device other than the default emulated EmbeddedDevice1 (for example, another emulated device, or a real connected device). To run the IMletDemo project on a specific device:

Open the Device Selector tab in NetBeans IDE as follows:
- On the Tools menu, select Java ME, and then Device Selector.
On the Device Selector tab, right-click the device on which you want to run the IMletDemo project, select Run Project, and then IMletDemo.

Developing a Sample Java ME Embedded Application in Eclipse IDE

Eclipse IDE automates the process of building, packaging and running Java ME Embedded applications by providing standard Java ME Project and Java ME MIDlet templates. A Java ME project is configured in such a way that you only have to click one button to run it.

The standard MIDlet template can be used to create the IMlet source code. You can also add other resource files to the project, and configure the project settings as needed. Eclipse IDE will ensure that all source files, resources, and settings are managed properly.

When you run a Java ME project, Eclipse IDE automatically builds, packages, and runs the application on the default emulated EmbeddedDevice1 or on another available device. You can choose to run it on another emulated device, or a real connected device.

Developing a sample Java ME Embedded application in Eclipse IDE using Oracle Java ME SDK involves the following procedures:

Creating the IMletDemo Project in Eclipse IDE

To create a Java ME project in Eclipse IDE:

Ensure that the Java ME perspective is active as follows:
1. Open the Window menu, select Perspective, select Open Perspective, and then Other.
2. In the Open Perspective window, select Java ME and click OK.
On the File menu, select New and then Java ME Project.
In the New Java ME Project dialog, enter IMletDemo in the Project name field. Click Finish.

You should see the created IMletDemo project in the Package Explorer tab of Eclipse IDE.
Right-click the IMletDemo project in the Package Explorer tab, select New and then Java ME MIDlet.
In the New Java ME MIDlet dialog, enter imletdemo in the Package field and IMletDemo in the Name field. Click Finish.

You should see the created IMletDemo.java source file open in a separate tab in Eclipse IDE. The source file should be located in the imletdemo package under src in the IMletDemo project in the Package Explorer tab of Eclipse IDE.

If everything is correct, you should be able to build and run the IMletDemo project in Eclipse IDE. However, the application will not do anything, because methods do not contain any code.

Running the IMletDemo Project in Eclipse IDE

Oracle Java ME SDK 8.3 provides the Java ME Embedded 8.3 emulation environment that enables you to duplicate (or emulate) an embedded device and run the application without the actual device. By default, when you run a Java ME project in Eclipse IDE, it is started on the emulated device EmbeddedDevice1.

To run the IMletDemo project, do one of the following:

Select the IMletDemo project in the Projects tab and press Ctrl+F11 on the keyboard.
Select the IMletDemo project in the Projects tab, open the Run menu and select Run.
Right-click the IMletDemo project name in the Projects tab and select Run As, then Emulated Java ME JAD.

If successful, the EmbeddedDevice1 emulator starts with the IMletDemo suite running. If you used the code from "Source Code for a Sample IMlet", you should see the following line in the Console tab of Eclipse IDE:

IMletDemo is started...

To open the Console tab in Eclipse IDE, open the Window menu and select Show View, then Console, or press Alt+Shift+Q and then C on the keyboard.

Open the Device Selector tab in Eclipse IDE as follows:
- On the Window menu, select Show View, and then Device Selector.
On the Device Selector tab, right-click the device on which you want to run the IMletDemo project, select Run Project, and then IMletDemo.

Developing a Sample Java ME Embedded Application Without an IDE

An IDE automates most tasks involved in the development of applications to increase speed and efficiency. However, understanding how to develop a Java ME Embedded application without an IDE can help you realize what those tasks are, how and why they are performed.

To develop a sample Java ME Embedded application without an IDE:

Create a sample IMlet source code file that extends the javax.microedition.midlet.MIDlet class using any text editor.

See Creating the IMletDemo Source Code File.
Build the sample application by compiling the sample IMlet source code file using the javac command-line tool.

See Building the IMletDemo Class File From the Command Line.
Package the sample application by creating a Java Archive (JAR) file with the compiled sample IMlet class file and manifest file using the jar command-line tool, and a Java Application Descriptor (JAD) file with the description of the JAR file using any text editor.

See Packaging the IMletDemo Application From the Command Line.
Run the sample application by starting the Java ME Embedded Emulator using the emulator command-line tool with the -Xdescriptor command that specifies the JAD file.

See Running the IMletDemo Application From the Command Line.

Creating the IMletDemo Source Code File

An IMlet is a class that extends the javax.microedition.midlet.MIDlet class and conforms to the Java ME Embedded Profile 8 (MEEP 8) specification. You can use any text editor to create the IMlet source code file.

To create a sample IMlet source code file:

Create an empty text file using any text editor.
Copy the code shown in "Source Code for a Sample IMlet" into this file.
Save the file as IMletDemo.java.

Building the IMletDemo Class File From the Command Line

Building an application involves compiling source code files into bytecode class files. This is done using the standard Java SE Development Kit javac compiler.

Use the -bootclasspath option to specify the location of the CLDC and MEEP 8 APIs that are necessary to compile an IMlet. You can also use the -d option to specify where to place the compiled class files.

For example, if the IMletDemo.java source file is located in the C:\meApp\src directory, the Oracle Java ME SDK installation directory is set to the JAVAME_SDK_HOME environment variable, Java SE Development Kit installation directory is set to the JAVA_HOME environment variable, and you would like to place the compiled class files to the C:\meApp\classes directory, then on the Windows Command Prompt, change to the C:\meApp directory, and run the following command:

C:\meApp>%JAVA_HOME%\javac -bootclasspath %JAVAME_SDK_HOME%\lib\cldc_1.8.jar;%JAVAME_SDK_HOME%\lib\meep_8.0.jar -d classes src\IMletDemo.java

As a result of this command, the following class file should be created: C:\meApp\classes\imletdemo\IMletDemo.class

For more information about the javac compiler, see the corresponding section of the JDK Tools Reference at

http://docs.oracle.com/javase/8/docs/technotes/tools/windows/javac.html

Packaging the IMletDemo Application From the Command Line

Java ME Embedded applications are deployed as IMlet suites. An IMlet suite contains at least one IMlet class file, any number of additional resource files, and a manifest file packaged in a Java Archive (JAR). It also includes a separate Java Application Descriptor (JAD) file to describe the IMlet suite.

To package the sample IMletDemo application:

Create a manifest file as follows:
1. Create an empty text file using any text editor.
2. Copy the following text into the file:
```
MIDlet-Name: IMletDemo
MIDlet-Version: 1.0
MIDlet-Vendor: Company Inc.
MIDlet-1: IMletDemo,,imletdemo.IMletDemo
MicroEdition-Configuration: CLDC-1.8
MicroEdition-Profile: MEEP-8.0
```
  These are the required attributes for any IMlet suite JAR manifest file as specified by the MEEP 8 specification.
3. Save the file as manifest.mf.
Create a JAR file that contains the manifest and the IMletDemo.class file using the standard Java SE Development Kit jar tool. Use the c option to create a new JAR, the f option to specify the name of the JAR, and the m option to specify the name of the manifest file to include.

For example, if the IMletDemo.class file is located in the C:\meApp\classes\imletdemo directory, the manifest.mf file is located in the C:\meApp directory, Java SE Development Kit installation directory is set to the JAVA_HOME environment variable, and you want to create the IMletDemo.jar file in the C:\meApp\dist directory, then on the Windows Command Prompt, change to the C:\meApp directory, and run the following command:
```
C:\meApp>%JAVA_HOME%\jar cfm dist\IMletDemo.jar manifest.mf -C classes .
```
As a result of this command, the following JAR file should be created: C:\meApp\dist\IMletDemo.jar

For more information about the jar tool, see the corresponding section of the JDK Tools Reference at

http://docs.oracle.com/javase/8/docs/technotes/tools/windows/jar.html
Create a JAD file as follows:
1. Create an empty text file using any text editor.
2. Copy the following text into the file:
```
MIDlet-Name: IMletDemo
MIDlet-Version: 1.0
MIDlet-Vendor: Company Inc.
MIDlet-1: IMletDemo,,imletdemo.IMletDemo
MIDlet-Jar-Size: 933
MIDlet-Jar-URL: IMletDemo.jar
```
  These are the required attributes for any IMlet suite JAD file as specified by the MEEP 8 specification.
  
  Note:
  
  You must set the MIDlet-Jar-Size attribute value to the size of the JAR file in bytes.
3. Save the file as IMletDemo.jad to the C:\meApp\dist directory.

Running the IMletDemo Application From the Command Line

The Java ME Embedded Emulator executable (emulator) is located under bin in the Oracle Java ME SDK installation directory JAVAME_SDK_HOME.

You should use the -Xdescriptor command to specify the location of the JAD file associated with the Java ME Embedded application (IMlet suite) that you want to run. By default, the application starts on the EmbeddedDevice1 emulator, unless you use the -Xdevice option that enables you to specify the name of the emulated device on which you want to run the application.

For example, if you want to run the IMletDemo application packaged in the IMletDemo.jar file with the IMletDemo.jad file in the C:\meApp\dist directory, then on the Windows Command Prompt, change to the bin directory in the Oracle Java ME SDK installation directory (JAVAME_SDK_HOME), and run the following command:

JAVAME_SDK_HOME>bin>emulator -Xdescriptor:C:\meApp\dist\IMletDemo.jad

If successful, the EmbeddedDevice1 emulator starts with the IMletDemo suite running.