Skip Headers
NetBeans Developing Applications with NetBeans IDE
Release 7.4
E40142-08
Go to Documentation Home
Home		 Go to Book List
Book List		 Go to Table of Contents
Contents		 Go to Feedback page
Contact Us
Go to previous page
Previous		 Go to next page
Next
PDF · Mobi · ePub

21 Developing Java ME Applications

This chapter describes how to create, test, debug, and deploy Java ME applications using NetBeans IDE.

This chapter contains the following sections:

21.1 About Developing Java ME Applications

The Java ME project development support for NetBeans enables you to create applications for mobile devices with the following features:

21.1.1 About Java ME MIDP and CLDC Applications

A JavaTM 2, Micro Edition platform (Java METM Platform), Mobile Information Device Profile (MIDP) application is an application targeted for mobile devices such as mobile phones, PDAs, and two-way pagers. Such applications conform to both the Connected, Limited Device Configuration (CLDC) and MIDP.

A MIDP application, or "MIDlet Suite," typically consists of:

  • A Java Application Descriptor file. This file contains a predefined set of attributes (denoted by names that begin with MIDlet-) that allows Application Management Software to identify, retrieve, and install the MIDlets.

  • A Java Archive file that contains:

    • Java classes for each MIDlet in the suite.

    • Java classes shared between MIDlets.

    • Resource files used by the MIDlets (for example, image files).

    • A manifest file describing the JAR contents and specifying attributes used by the AMS to identify and install the MIDlet suite.

In the IDE, MIDlet Suites are managed as mobility projects. Mobility projects are executed through an emulator platform, which simulates the execution of the application on a specific mobile device. Using project configurations and preprocessor code blocks, you can define conditions for multiple devices in a single set of code, enabling you test and produce MIDlet suites for each device.

NetBeans also supports CDC development.

21.1.2 About Java ME CDC Applications

A Java 2, Micro Edition platform (Java ME Platform), Connected Device Configuration (CDC) application is an application targeted for mobile devices such as high end mobile phones, Blu-ray consoles and embedded systems. Such applications conform to the Connected Device Configuration with a set of profiles that include the Personal Basis Profile, Personal Profile and AGUI.

A CDC application typically consists of:

  • A Java Archive (JAR) file. This file contains:

    • Java class with a main method, applet, or one or more Xlets.

    • Java classes.

    • Resource files used by the Application (for example, image files).

    • A manifest file describing the JAR contents.

  • A deployment file.

    For Nokia S80 phones, a JAR file with special attributes is included in the manifest.

In the IDE, CDC applications are managed as Java ME projects. Java ME projects are executed through an emulator platform, which simulates the execution of the application on a specific mobile device.

You can use the NetBeans GUI Builder's drag and drop, GUI environment to design your application. The IDE also supports unit testing.

21.2 Understanding Java Platform Manager

The Java Platform Manager is a tool for registering different versions of the Java Development Kit (JDK) and other Java tools that your programs depend on. The dialog box lists all of your registered JDKs and SDKs in the left pane. It also lists the JDK that the IDE is running on as the Default Platform.

You can open the dialog box by choosing Tools > Java Platforms.

Using the Java Platform Manager, you can:

Note:

Though NetBeans supports Java Micro Edition (ME) Connected Device Configuration (CDC) development, the IDE does not have a CDC platform included in the installer that allows you to create applications for CDC devices using the Personal, Foundation, or AGUI Profiles. For more information, see NetBeans CDC Emulator Platform Setup Guide at https://netbeans.org/kb/docs/javame/cdcemulator-setup.html.

21.3 Creating Java ME Projects

A project is a group of source files and the settings with which you build, run, and debug those source files. In the IDE, all Java development has to take place within a project. Within a MIDP project, you can create multiple project configurations that customize your MIDlet for different types of mobile devices.

When a project is created, the IDE:

CDC applications are called xlets. The xlet application programming model is very similar to the applet application programming model. Xlets are loaded into an xlet manager and controlled through a life cycle interface. This is similar to how an applet is loaded and run inside a browser. The main difference is that the xlet application programming model does not have implicit API requirements like java.applet, which allows it to be used in a greater variety of product scenarios.

The MIDP project structure is similar to that of standard NetBeans projects. There are differences, however, in the build and dist folders to accommodate the MIDP build process.

Logical View

The logical view of the project, shown in the Projects window, provides a hierarchy of sources and resources which reflects the type of project and its contents.

By right-clicking on the project node, you can choose the following Mobility-specific menu items:

The Source Packages node encapsulates all the Java packages of the project. Right-clicking on the Source Package node and choosing New lets you add new file templates to your application.

The Resources node encapsulates all resources and libraries of the active configuration. The IDE notifies you through a note on the node if the active configuration inherits resources and libraries from DefaultConfiguration.

Right-clicking the Resources node enables you to add Project, JARs, folders, and libraries as resources for your application. You can not add or remove inherited resources.

Right-clicking on the Project Configurations node opens the Add Configuration wizard, which enables you to create new configurations for your project.

Files View

When a project is created, the following folders are created under build (shown in the Files window):

21.3.1 How to Create a MIDP Project Configuration Template

Project configuration templates enables you to create new configurations based on the saved settings of other useful configurations.

For example, if you have a series of mobile devices that are similar except for the size of their screen displays, you could create a project configuration for one device, then use a project template to create an additional configuration for each device in the series.

To create a project configuration template:

  1. Right-click on a project in the Projects view and choose Properties.

  2. Click Manage Configurations.

  3. In the Project Configuration Manager, select a configuration and click Save as Template.

  4. In the Save Project as Configuration Template dialog, enter a name for the template.

  5. Click Save.

To add a new configuration using a template:

  1. Right-click on a project in the Projects view and choose Properties.

  2. Choose Add Configuration from the Project Configuration dropdown menu.

  3. Select a template from the Use Configuration template drop--down list.

  4. Optionally, modify the name of the configuration in the New Configuration Name field.

  5. Click OK.

21.3.2 How to Create a Java ME Application from a Template

The IDE manages applications in projects. To create a new application, you must first create and configure a new project. Use the New Project wizard or the project properties to create multiple configurations that enable you to simultaneously build and deploy your application to a range of platforms and devices.

With project templates, the IDE controls all aspects of how your application is built, run, and debugged. You set a project's source directory, classpath, emulator platform, and other project settings when creating the project and in the Project Properties dialog box.

The NetBeans comes with the following Java ME project templates:

  • Mobile Application. A new MIDP in a standard IDE project.

  • Embedded Application. A new MIDP or IMP/IMP-NG application in a standard IDE project.

  • Mobile Class Library. An empty Java ME class library with no main class.

  • Mobile Project with Existing MIDP Sources. A Java ME MIDP project created from an existing source folder.

  • Import Wireless Toolkit Project. A Java ME MIDP project that imports a project created previously in the Sun Java Wireless Toolkit.

  • CDC Application. Creates a new CDC application in a standard IDE project.

  • CDC Class Library. Creates a new CDC library in a standard IDE project. A CDC library does not contain a main class.

  • Import CDC Pack 5.5 Project. Imports an existing NetBeans Mobility Pack 5.5 for CDC project into a current NetBeans IDE project.

  • Import CDC Toolkit Project. Imports an existing Sun Java Toolkit for CDC project into current NetBeans IDE.

To create a new project:

  1. Choose File > New Project.

  2. Select the right template for your project.

  3. Specify the name of the project and where to create it. The IDE creates the project folder in the specified location. Click Next.

  4. Specify the emulator platform for the project. The emulator platform determines the execution environment for your project.

  5. Click Finish to complete the wizard.

21.3.2.1 Creating Mobile Application

You open the New Mobile Project wizard by choosing File > New Project and selecting the Mobile Application project template from the Java ME category. You use this wizard to create a new project for a Java ME/MIDP application.

The IDE creates a project folder based on the name of the new project, as shown in the Project Folder field. The project files are stored in this folder.

If you want the new project to be your main project, choose Run > Set Main Project from the main menu after you create the project.

21.3.2.2 Creating Mobile Class Library

You open the New Mobile Class Library wizard by choosing File > New Project and selecting the Mobile Class Library project template from the Java ME category.

The IDE creates a new Java ME class library in a standard IDE project. A Java ME library does not contain a MIDlet. This project uses an IDE-generated Ant build script and special tasks to preprocess, build, obfuscate, preverify, run, debug, and deploy your library in the Java ME environment.

You can use this template to create a library within an existing project.

21.3.2.3 Creating Mobile Project with Existing MIDP Sources

You open the New Mobile Project with Existing MIDP Sources wizard by choosing File > New Project and selecting the Mobile Project with Existing MIDP Sources project template from the Java ME category.

The IDE imports an existing MIDP application from existing sources and an optional application descriptor into a standard IDE project.

21.3.2.4 Creating CDC Application

You open the New CDC Application wizard by choosing File > New Project and selecting the CDC Application project template from the Java ME category.

The IDE creates a new CDC application in a standard IDE project. You can also generate a main class in the project.

21.3.2.5 Creating CDC Class Library

You open the New CDC Class Library wizard by choosing File > New Project and selecting the CDC Class Library project template from the Java ME category.

The IDE creates a new CDC project with no main (executable) class.

21.3.2.6 Creating Embedded Application

You open the New Embedded Application wizard by choosing File > New Project and selecting the Embedded Application project template from the Java ME category.

The IDE creates a new IMP-NG application in a standard IDE project. You can also generate a IMlet in the project.

21.3.2.7 Importing CDC Pack 5.5 Project

You open the New Import CDC Pack 5.5 Project wizard by choosing File > New Project and selecting the Import CDC Pack 5.5 Project project template from the Java ME category.

The IDE imports a NetBeans 5.5 CDC Pack project into a regular Java ME project.

21.3.2.8 Importing CDC Toolkit Project

You open the New CDC Toolkit Project wizard by choosing File > New Project and selecting the CDC Toolkit Project project template from the Java ME category.

The IDE imports a NetBeans 5.5 CDC Toolkit project into a regular Java ME project.

21.3.2.9 Importing Wireless Toolkit Project

You open the New Import Wireless Toolkit Project wizard by choosing File > New Project and selecting the Import Wireless Toolkit Project project template from the Java ME category.

The IDE imports an existing MIDP application from Sun Java Wireless Toolkit into a standard IDE project.

21.3.3 How to Add a MIDlet to a Project Configuration

To add a MIDlet to a Project Configuration:

  1. Open the MIDlets properties page by choosing File > <active project name> Properties.

  2. In the Project Properties dialog, select Application Descriptor > MIDlets.

    Note:

    If you are setting the MIDlet properties for a project configuration other than the default configuration, you must uncheck the Use Values from "DefaultConfiguration" checkbox at the top of the page.

  3. Click the Add button. This opens the Add MIDlet dialog. The dialog lists the MIDlets available in the project.

  4. Use the Add MIDlet dialog to enter a name, then select a MIDlet class from the dropdown menu. You can also choose an icon for the MIDlet from the MIDlet icon dropdown menu.

  5. Click OK to close the dialog. The MIDlet is listed in the table.

21.3.4 How to Add Push Registry Entries

The push registry allows MIDlets to be launched in response to an incoming network connection. When a MIDlet registers for push notifications, the device software is instructed to listen for incoming network connections and launch the MIDlet, if appropriate.

A MIDlet can register for push connections at runtime using static methods in javax.microedition.io.pushregistry, which would require the user to run the MIDlet manually when the device is turned on.

A more common approach is to register at installation using properties contained in the application descriptor (JAD) file. This approach allows the AMS to ensure that the MIDlet can be registered, and to cause the installation to fail if there are registration conflicts (for example, if another MIDlet is already registered for the same socket connection).

Each key designation is unique and of the form MIDlet-Push-<n>, where <n> begins at 1 and is incrementally increased with each registration. A MIDlet suite can have multiple push registrations.

Note:

Push registry configuration is only available for projects whose profile version is set to MDP 2.0.

To add Push Registry Entries:

  1. Choose File > <active project name> properties. This opens the Project Properties dialog.

  2. Select Push Registry from the left pane.

  3. In the Push Registry properties page, click Add to add a new MIDlet, and provide the following information in the Add Push Registry Entries dialog:

    • Class Name. The MIDlet's class name.

    • Sender IP. A valid sender that can launch the associated MIDlet. If the value is the wildcard (*), connections from any source are accepted. If datagram or socket connections are used, the value of Allowed Sender can be a numeric IP address.

    • Connection String. A connection string that identifies the connection protocol and port number.

A push registration key is automatically generated and shown as an attribute in the MIDlet suite's Java Application Descriptor (JAD) file. To view the JAD file, choose the Application Descriptor Property settings from the left pane.

Note:

To make use of the Push Registry, you must also have permission to access the Push Registry API, javax.microedition.io.PushRegistry. API permissions are handled in the API Permissions page of the Project Properties.

Each key designation is unique and of the form MIDlet-Push-<n>, where <n> begins at 1 and is incrementally increased with each registration. A MIDlet suite can have multiple push registrations.

For more information about using the push registry, see http://www.oracle.com/technetwork/systems/index-156665.html.

21.3.5 Adding API Permissions

If your MIDlet suite needs to access certain protected APIs (for example, network connections), the MIDP 2.0 security architecture requires that the connection grant permission for access. Required permissions are listed in the Java Application Descriptor (JAD) file with the attribute MIDlet-Permissions.

You can also define optional permissions to limit access to sensitive data or functionality with the attribute MIDlet-Permissions-Opt.

During MIDlet suite installation, the MIDP compares the permissions requested with the permissions in the destination protection domain. If the required permissions can not be granted, the application will not be installed.

During execution, if a required permission is denied, an exception is returned. If an optional permission is denied, the application might continue to function, although its functionality would be limited.

You can set the permission requests from the API Permissions page of the Project Properties.

Note:

API Permissions are only available for projects whose profile version is set to MDP 2.0.

To Add API Permissions:

  1. Choose File > <active project name> properties. This opens the Project Properties dialog.

  2. Select API Permissions from the left pane.

  3. Click the Add Button.

  4. Choose an API from the dropdown list or enter an API name in the combo box. Permissions have the same naming structure as a Java class. For instance, javax.microedition.io.Connector.http is the permission for the HTTP protocol.

  5. Click OK.

  6. In the API Permissions table, check the Required box if you want installation to fail in the event that permission cannot be granted.

For more information about API Permissions, see Security for MIDP Applications in the MIDP 2.0 (JSR-118) specification, available at http://jcp.org/aboutJava/communityprocess/final/jsr118/index.html.

21.4 Importing Java ME Projects

There are four project templates you can use to import a Java ME MIDP project:

Note:

Each MIDP project supports only a single source root. If the project you are importing has multiple source roots, you need to create one project for each source root and then create dependencies between the projects.

To import a Sun Java Wireless Toolkit project:

  1. Choose File > New Project.

  2. Under Categories, select Java ME. Under Projects, select Import Wireless Toolkit Project and click Next.

  3. In the Specify WTK Toolkit project page, browse to select the project you want to import. Click Next.

  4. In the Project Name and Location page, choose a home and a location for the new project. Click Next.

  5. Use the Platform Selection page to set the emulator platform that the IDE will use to compile and run the project. Click Finish.

  6. To test the Project, right-click the project node in the projects tab, and choose Run Project.

To import a Java ME project from existing MIDP sources:

  1. Choose File > New Project.

  2. Under Categories, select Java ME. Under Projects, select Mobile Project with Existing MIDP Sources and click Next.

  3. Use the Specify Sources page to locate the source directory for the source code and .jad file you want to import. Click Next.

  4. Use the Project Name and Location page to define a new name and location for your NetBeans project. Click Next.

  5. Use the Platform Selection page to select the platform emulator that will be used to emulate device performance when the project is executed. Click Finish.

The NetBeans Java ME preprocessor is almost fully compatible with the Antenna preprocessor, so you can import Antenna projects and preserve the preprocessing code from the original project.

To Import an Antenna Project:

  1. Create a new project:

    1. Choose File > New Project.

    2. Under Categories, select Java ME. Under Projects, select Mobile Project with Existing MIDP Sources and click Next.

    3. Use the Specify MIDP Sources page to locate the source directory for the source code and (optionally) the .jad file you want to import.

    4. Click Next. Use the Project Name and Location page to define a new name and location for your NetBeans project. Click Finish.

  2. Create project configurations for each of the symbols (mobile devices) listed in your original project. For example, for the following line of code in the build.xml file: <wtkpreprocess srcdir="src" destdir="src_colorphone" symbols="colorphone,JSR185,JSR172," verbose="true"/> you would create a configuration for the symbol (mobile device) "colorphone":

    1. In the Projects view, right click on the project node and choose Properties from the context menu.

    2. Click the Manage Configurations button. This opens the Project Configuration Manager.

    3. Click the Add button. This opens the Add Project Configuration dialog.

    4. Add the name of a symbol (mobile device) listed in the build.xml file, in this case "colorphone". Be sure to match the symbol names precisely. Click OK to create the configuration.

    5. Repeat as necessary.

  3. Add abilities to each configuration.

    1. In the Properties window, under Categories, click the Abilities node.

    2. Uncheck the Use Values from "DefaultConfiguration" check box.

    3. Click the Add button and add abilities for each configuration so that they correspond to the non-device symbols listed in your build.xml file. For example, if you are in the colorphone configuration and the build.xml file has the code <wtkpreprocess srcdir="src" destdir="src_colorphone" symbols="colorphone,JSR185,JSR172," verbose="true"/> you would add abilities for JSR185 and JSR172.

    4. Delete excess abilities that have nothing to do with the antenna sources just imported.

Note:

The #include directive is not supported by the Java ME preprocessor. Instead, the preprocessor inserts "hints" that identify the files that need to be inserted into the source code. For example, the Antenna code //#include ConverterMIDlet.java is identified in the source code editor as shown below:

Include statement

You can now build and run your applications in the IDE.

To import a project created in Mobility Pack for CDC 5.5:

  1. Choose File > New Project.

  2. Under Categories, select Java ME. Under Projects, select Import CDC Pack 5.5 Project and click Next.

  3. In the Specify CDC Pack 5.5 project page, browse to select the project you want to import. Click Next.

  4. In the Project Name and Location page, choose a home and a location for the new project. Click Finish.

  5. To test the Project, right-click the project node in the projects tab, and choose Run Project.

To import a project created with the Sun Java Toolkit for CDC:

  1. Choose File > New Project.

  2. Under Categories, select Java ME. Under Projects, select Import CDC Toolkit Project and click Next.

  3. In the Specify CDC Toolkit project page, browse to select the project you want to import. Click Next.

  4. In the Project Name and Location page, choose a home and a location for the new project. Click Next.

  5. Use the Platform Selection page to set the emulator platform that the IDE will use to compile and run the project. Click Finish.

  6. To test the Project, right-click the project node in the projects tab, and choose Run Project.

21.5 Customizing MIDlet Properties

You can add, edit, or delete the attributes of a MIDlet suite for the active project configuration, and determine the order in which MIDlets are shown in a MIDlet suite.

To add a MIDlet to a suite:

  1. Open the MIDlets properties page by choosing File > <active project name> Properties.

  2. In the Project Properties dialog, select MIDlets.

  3. Click the Add button. This opens the Add MIDlet dialog. The dialog lists the MIDlets available in the project.

  4. Use the Add MIDlet dialog to enter a name, then select a MIDlet class from the dropdown menu. You can also choose an icon for the MIDlet from the MIDlet icon dropdown menu.

  5. Click OK to close the dialog. The MIDlet is listed in the table.

Note:

Any class added to the project that extends MIDlet (directly or indirectly) will be automatically be added to the Application Descriptor.

To edit a MIDlet in the suite:

  1. Open the MIDlets properties page by choosing File > <active project name> Properties.

  2. Under Categories, select Java ME. Under Projects, select Import CDC Toolkit Project and click Next.

  3. Select a midlet and click the Edit button. This opens the Edit MIDlet dialog.

  4. Use the Edit MIDlet dialog to Edit the name, MIDlet class, and MIDlet icon.

To change the order in which a MIDlet is shown:

Select an attribute and click the Move Up or Move Down button.

21.5.1 How to Customize the Application Descriptor (JAD) Attributes

You can choose which attributes are included or excluded in your project configuration by choosing File > <active project name> properties. In the Project Properties dialog, select Attributes.

The Application Descriptor page enables you to add, edit, or remove the list of attributes that allow application management software to identify, retrieve, and install the MIDlets of a MIDlet suite.

To add, edit, or remove an attribute:

  1. Click the Add button. The Add Attributes dialog opens.

  2. Choose an attribute from the combo box. Then add a value for the attribute. Note that the list of available attributes is dependent upon the MIDP version supported by the project configuration, as set in the Platform properties. You can also add user-defined attributes by entering the attribute in the combo box.

Note:

To avoid errors in verification, make sure all required attributes have a defined value. Also, do not begin user-defined attribute keys with MIDlet- or MicroEdition-.

21.5.2 How to Customize MIDP Javadoc Settings

For each of your projects, you can produce a set of Javadoc HTML pages that describe the project's classes, inner classes, interfaces, constructors, methods, and fields. The Javadoc is constructed from the structure of your code and the Javadoc comments embedded in your code.

You open the Generating Javadoc properties page by choosing File > <active project name> Properties. In the Project Properties dialog, select Build > Generating Javadoc.

Note:

If you are setting the properties for a project configuration other than the default configuration (DefaultConfiguration), you must uncheck the Use Values from "DefaultConfiguration" checkbox at the top of the page to customize these options.

To set the javadoc generation properties:

  1. Choose File > <active project name> Properties.

  2. In the Project Properties dialog, select Build > Generating Javadoc.

For more information on generating Javadoc documentation, see http://docs.oracle.com/javase/1.4.2/docs/tooldocs/solaris/javadoc.html.

21.6 Building Java ME Applications

The development life cycle of applications for mobile devices that support the Java ME, CLDC, MIDP and CDC technologies includes building Java ME applications.

The IDE builds its project infrastructure directly on top of Apache Ant, the leading build tool for Java applications. The IDE stores all of the information about your project in an Ant script, a properties file, and a few XML configuration files. This means that you can build and run your projects outside of the IDE exactly the same as inside the IDE.

To build a Java ME project:

Choose Build > Build Project.

To create JAR files for multiple devices at once:

Right-click on the project and choose Batch Build.

To view and customize the build options for a project configuration:

  1. Choose File > <active project name> Properties.

  2. Expand the Build node in the left pane and choose one of the following:

    • Sources Filtering. Select the files to be included or excluded from the build.

    • Compiling. Customize javac options for generating debugging information, optimizing the compilation, and reporting the use of deprecated APIs. You can also set encoding and the level of debugging for the //#debug and //#mdebug preprocessor directives.

    • Libraries & Resources. Add or remove resources from the build.

    • Obfuscating. Set the obfuscation level for the application.

    • Creating JAR. Set the names of the JAR and JAD files for the build, and whether to compress the JAR file.

    • Signing. Sign MIDlets and add or remove security keystores.

    • Generating Javadoc. Manage the source code documentation for the application.

The active project configuration is listed in the dropdown menu at the top of the Project Properties dialog.

21.6.1 How to Customize Compilation Options

You can set the build options in a project configuration by choosing File > <active project name> properties. In the Project Properties dialog, select Build > Compiling.

Click in the associated check box to enable the following options:

  • Generate Debugging Info. If checked, the compiler generates line numbers and source files information. This is the -g option in javac. If unchecked, no debugging information is generated (-g:none).

  • Compile with Optimization. If checked, the compiled application is optimized for execution. This is the -O option in javac. Optimizing can slow down compilation, produce larger class files, and make the program difficult to debug.

  • Report Uses of Deprecated APIs. If checked, the compiler lists each use or override of a deprecated member or class. This is the -deprecated option in javac. If unchecked, the compiler shows only the names of source files that use or override deprecated members or classes.

You can also set the default encoding used by the preprocessor and compiler in the encoding field. The default value is the default encoding used by your JVM and IDE.

The Debug Block Level drop-down menu sets the debug level for the //#debug and //#mdebug preprocessor directives. If you enter a unique value for the level (for example, debug_graphics), the preprocessor allows only debug blocks that exactly match the debug block (for this example, //#debug debug_graphics). All other debug blocks are commented out.

If you choose a pre-defined level from the drop-down menu, the preprocessor comments out debug blocks on lower levels, as defined by the following hierarchy:

  • fatal (most exclusive)

  • error

  • warn

  • info

  • debug (most inclusive)

For example, if you choose warn, all info and debug blocks will be commented out.

Note:

If you are setting the properties for a project configuration other than the default configuration (DefaultConfiguration), you must uncheck the Use Values from "DefaultConfiguration" checkbox at the top of the page to customize these options.

21.6.2 How to Add Libraries and Resources to a MIDP Project

Adding a group of class files to a project's classpath tells the IDE which classes the project should have access to during compilation and execution. Use the Libraries & Resources properties page to add or remove additional libraries, projects, or JAR and ZIP files to a classpath for a project configuration.

Note:

If you are setting the properties for a project configuration other than the default configuration (DefaultConfiguration), you must uncheck the Use Values from "DefaultConfiguration" checkbox at the top of the page to customize these options.

You can add the following item types to your project:

  • Project. The JAR file produced by another project, as well as the associated source files and Javadoc documentation. Adding this item to a class path sets up a dependency between the current project and the selected JAR.

  • Library. A collection of JAR files or folders with compiled classes, which can optionally have associated source files and Javadoc documentation.

  • JAR file. A JAR file somewhere on your system. Adding a JAR file creates a library entry named by the JAR and containing the JAR.

  • Folder. The root of a package or directory containing files. Adding a folder does not create a library entry.

To add a project, file, folder or library to the project's classpath:

  1. Choose File > <active project name> properties. This opens the Project Properties dialog.

  2. Expand Build > Libraries & Resources in the left pane.

  3. Click on the appropriate button to open a file chooser for that item type. Clicking the Add Library button opens the Library Manager, where you can add or edit library classes.

Note:

If a project has multiple distribution JAR files, all of the JARs appear in the Project Jar Files window. You will need to select the correct version of the JAR file to include with the project configuration.

21.6.3 How to Customize MIDP Build Filter Settings

Filtering settings determine the files and packages that are included in a JAR file for a specific project configuration.

To set the Filtering options:

  1. Choose File > <active project name> properties.

  2. In the Project Properties dialog, expand Build > Filtering.

  3. Using the Filtering Properties dialog, you can set the following options:

    • Use Default Ant Excludes. If checked, files that are defined by Ant to be excluded by default (version control files and folders) are excluded from the JAR file.

    • Exclude Test and Test Packages. If checked, tests and test packages are excluded from the JAR file.

To include or exclude an item from the build:

All items are included by default. Expand the nodes and uncheck the boxes next to the files or packages you want to exclude.

Note:

If you are setting the properties for a project configuration other than the default configuration (DefaultConfiguration), you must uncheck the Use Values from "DefaultConfiguration" checkbox at the top of the page to customize these options.

21.6.4 How to Obfuscate a MIDlet Suite

Performance and security are primary concerns for any application. Because the Java language was designed to be compiled into a platform-independent bytecode format, much of the information contained in the source code remains in the bytecode, making it easy to decompile or reverse-engineer a Java application. This format can also contribute to larger file sizes, and with the limited resources of mobile devices, every byte saved in a MIDP application counts towards mobility and performance.

Obfuscators use a variety of methods to transform compiled code. Code obfuscation techniques include stripping object code of its symbol tables, or altering the names of variables and identifiers. Obfuscated programs are not only more difficult to decompile or reverse-engineer, they are also frequently smaller in size, improving performance and mobility as well as security.

You can add additional obfuscation parameters in the Additional Obfuscation Settings window. The default obfuscator included with the IDE is ProGuard.

You can find more details about command parameters for this obfuscator at http://proguard.sourceforge.net/.

Obfuscators make it more difficult for your application to be decompiled or re-engineered. Depending on the methods used, obfuscation can also reduce the size of the compiled MIDlet suite, reducing the size of the application and improving performance.

To obfuscate a MIDlet suite:

  1. Choose File > <active project name> Properties.

  2. In the Project Properties dialog, select Build > Obfuscating.

  3. Use the Obfuscation lever to set the level of obfuscation for the suite. The Level Description window describes the impact each level has on the MIDlet.

  4. You can add additional obfuscation parameters in the Additional Obfuscation Settings window.

Note:

If you are setting the properties for a project configuration other than the default configuration (DefaultConfiguration), you must uncheck the Use Values from "DefaultConfiguration" checkbox at the top of the page to customize these options.

21.6.5 How to Customize the JAR and JAD Files in a Build

You can modify the names of the JAR and JAD files, and specify whether the JAR file is compressed.

To modify the JAR and JAD files:

  1. Choose File > <active project name> Properties.

  2. In the Project Properties dialog, select Build > Creating JAR.

  3. The Creating JAR page lets you set the following options:

    • JAD File Name. Name of the JAD file created by the project sources. The file name must have a .jad extension.

    • JAR File Name. Name of the JAR file created by the project sources. The file name must have a .jar extension.

    • Compress JAR. If checked, the JAR file is compressed.

    Note:

    If you are setting the properties for a project configuration other than the default configuration (DefaultConfiguration), you must uncheck the Use Values from "DefaultConfiguration" checkbox at the top of the page to customize these options.

21.7 Working with Security and MIDlet Signing

Signing a MIDlet suite allows MIDP devices to verify the integrity and origins of your MIDlet suite. MIDP devices use signing information to check an application's source and validity before allowing it to access protected APIs. To sign a MIDlet suite, you create a key pair:

Each certificate has a designated security domain. Once your MIDlet suite has been verified, it can access any of the protected APIs permitted by its security domain.

Although the security domains available vary from device to device, the following security domains are supported by the IDE and the default emulator platform, the Sun Java Wireless Toolkit:

You can sign a MIDlet suite by:

You then have to export the certificate and set its security domain in each emulator.

Note:

MIDlet signing is only available for projects whose profile version is set to MDP 2.0. For information on setting the project profile version, see Section 21.10.4.2, "Customizing Platform Properties".

For more information about Java ME security features, see http://www.oracle.com/technetwork/systems/index-156466.html.

21.7.1 How to Set Security through MIDlet Signing

Signing a MIDlet suite allows MIDP devices to verify the integrity and origins of your MIDlet suite. To sign a MIDlet suite, you use the Signing Properties page to assign or create a key pair:

  • A private key that is used to create a digital signature, or certificate.

  • A public key that can be used by anyone to verify the authenticity of the signature.

You can then export the key pair to the emulator platform you are using for testing.

To sign a MIDlet suite:

  1. Choose File > <active project name> Properties. In the Project Properties dialog, select Build > Signing.

  2. Check the Sign Distribution checkbox to enable signing.

  3. Choose a keystore from the Keystore dropdown menu.

    Note:

    To create a new keystore or key pair, click the Open Security Manager button.

  4. Choose an alias from the Alias keystore dropdown menu. The menu lists the available aliases for the selected keystore.

  5. If necessary, click the unlock buttons to make the keystore and alias available for use.

  6. Click the Export Key into Java ME SDK/Platform/Emulator button to export a key into the emulator platform you intend to use to test the MIDlet.

21.7.2 How to Add or Creating a Keystore

Signing a MIDlet suite allows MIDP devices to verify the integrity and origins of your MIDlet suite. To sign a MIDlet suite, you assign or create a key pair.

  • A private key that is used to create a digital signature, or certificate.

  • A public key that can be used by anyone to verify the authenticity of the signature.

Key pairs are stored in keystore (.ks) files.

To create a new keystore:

  1. Choose File > <active project name> Properties. In the Project Properties dialog, select Build > Signing.

  2. Click the Open Keystores Manager button. This opens the Keystores Manager dialog.

  3. Click the Add Keystore button.

  4. Choose the Create a New Keystore radio button and enter the following information:

    • Keystore Name. A legal filename with the extension .ks

    • Keystore Folder. Folder in your system where the keystore file will be saved.

    • Password. The password that can be used to unlock the keystore.

  5. Click OK to close the dialog. The new keystore is displayed in the Keystores window of the Keystores Manager.

To add an existing keystore:

  1. Choose File > <active project name> Properties. In the Project Properties dialog, select Build > Signing.

  2. Click the Open Keystores Manager button. This opens the Keystores Manager dialog.

  3. Click the Add Keystore button. This opens the Add Keystore dialog.

  4. Choose the Add Existing Keystore radio button.

  5. Click the browse button to navigate to the location of the keystore file you want to add.

  6. Click OK to close the dialog. The new keystore is displayed in the Keystores window of the Keystores Manager.

For more information about key pairs and keystores, see http://docs.oracle.com/javase/1.4.2/docs/tooldocs/windows/keytool.html.

21.7.3 How to Create a New Key Pair

Signing a MIDlet suite allows MIDP devices to verify the integrity and origins of your MIDlet suite. To sign a MIDlet suite, you use the Signing Properties page to assign or create a key pair:

  • A private key that is used to create a digital signature, or certificate.

  • A public key that can be used by anyone to verify the authenticity of the signature.

You can then export the key pair to the emulator platform you are using for testing.

To create a new key pair:

  1. Choose File > <active project name> Properties. In the Project Properties dialog, select Build > Signing.

  2. Check the Sign Distribution checkbox to enable signing.

  3. Choose a keystore from the Keystore drop-down menu. The Security certificate details of the selected keystore:

    1. If no keystore is available, or you want to create a new keystore, click the Open Keystores Manager button. This opens the Keystores Manager dialog.

    2. Choose a keystore from the left window of the dialog, or click Add Keystore to create a new keystore. Then close the Keystores Manager.

  4. Choose an alias from the Alias keystore drop-down menu. The menu lists the available aliases for the selected keystore. You can create new aliases in the Keystores Manager dialog.

  5. If necessary, click the unlock buttons to make the keystore and alias available for use.

  6. Click the Export Key into Java ME SDK/Platform/Emulator button to export a key into the emulator platform you intend to use to test the MIDlet.

For more information about key pairs and keystores, see http://docs.oracle.com/javase/1.4.2/docs/tooldocs/windows/keytool.html.

21.7.4 How to Set the Security Domain

The Java ME platform uses security domains to restrict an application's access to protected APIs. Devices use signing information to check an application's source and validity before allowing it to access protected APIs.

Although the security domains available vary from device to device, the following security domains are supported by the IDE and the Sun Java Wireless Toolkit:

  • Trusted. A MIDlet suite with a JAR file that is both signed with a certificate chain that the device can verify and has not been tampered with.

  • Untrusted. A MIDlet suite for which the origin and the integrity of the JAR file cannot be trusted by the device (for example, unsigned MIDlet suites).

  • Minimum. A security domain where all permissions to protected APIs are denied, including access to push functionality and network protocols.

  • Maximum. The equivalent to Trusted.

You can set the security domain for a MIDlet suite:

  • For regular (local) execution.

  • To be exported to an emulator platform and for execution with OTA provisioning.

To set the security domain for regular execution:

  1. Choose File > <active project name> Properties.

  2. In the Project Properties dialog, select Running.

  3. In the Running properties page, Choose the Regular Execution radio button.

  4. Check the Specify the Security Domain checkbox and choose a security domain from the drop-down menu.

To set the security domain for export to an emulator platform or for execution with OTA provisioning:

  1. Choose File > <active project name> Properties.

  2. In the Project Properties dialog, select Build > Signing.

  3. Check the Sign Distribution checkbox.

  4. Select a keystore and alias (key pair).

  5. Click the Export Key into Java ME SDK/Platform/Emulator button.

  6. In the Export Key dialog:

    1. Select the emulator platform,

    2. Select the security domain,

    3. Click the Export button.

21.7.5 How to Export a Key to an Emulator Platform

To test a signed MIDlet in an emulator device, you must export the key and its corresponding certificate to the emulator platform.

To export a key:

  1. Choose File > <active project name> Properties.

  2. In the Project Properties dialog, select Build > Signing.

  3. Check the Sign Distribution checkbox.

  4. Select a Keystore and alias (a key pair).

  5. Click the Export Key into Java ME SDK/Platform/Emulator button.

  6. In the Export Key dialog:

    1. Select the emulator platform,

    2. Select the security domain,

    3. Click the Export button.

21.8 Adding Localization Support to a Java ME Project

Localization is the process of designing software so that it can be adapted (localized) to various languages and regions without engineering changes to the software. When you localize an application, you provide alternate language values for each element in your application, such as screen text, menus, and icons.

In the NetBeans IDE, you can use the New Localization Support Class wizard to create the files you need to localize an application:

After you create the key/value pairs for your application, you can then use the getMessage() method within your code to prove the proper value for the called key. The initialization method is called automatically when a call to the getMessage(java.lang.String) method is attempted for the first time.

For example, LocalizationSupport.getMessage("TEXT_HELLO").

Note:

To see an example of a localized project, choose File > New Project. Under Categories, expand the Samples node and choose Mobile. Under Projects, choose Localization Support Example.

Adding Localization support to your MIDlet is a four-step process:

  1. Create the java classes that initialize the localization support and message property files. The messaged property stores the localization keys and their values.

  2. Change the Internationalization String and Search formats.

  3. Add the localization keys and their values to the properties file.

  4. Add getMessage() methods to your MIDlet to identify elements to be localized.

To create the initial class and properties files:

  1. Select a Java ME MIDP project node (Java ME MIDP project node icon) and choose New > File/Folder.

  2. Under Categories, select MIDP. Under File Types, select Localization Support Class. Click Next.

  3. Enter the values required for the New Localization Support Class wizard. The wizard creates two files:

    • <Localization Supportfilename>.java. A Java class with the code that initializes localization.

    • <messages filename>.properties. A properties file where message keys and their localized values are stored.

To Change the String and Search formats:

  1. Choose Tools > Options from the Main Menu.

  2. Click the Advanced Options button.

  3. Choose the Internationalization node in the Options menu tree.

  4. In the properties window:

    • Change the value of the II8N String Format property to LocalizationSupport.getMessage("{key}")

    • Change the value of the II8N Search Format property to (getString|getBundle|getMessage)[:space:]*\([:space:]*{hardString}|//NOI18N

To add localization keys and their values:

  1. Navigate to the .properties file and double-click on its node. This opens the file in the Source Editor.

  2. Use the Source Editor to add your keys and their values into the properties file. For example, LAB_NextButton = Next.

To add code to initiate localization:

Enter the following string in your MIDlet wherever you want a key localized: LocalizationSupport.getMessage("Key");

For example, LocalizationSupport.getMessage("LAB_NextButton");

Note:

You can use the NetBeans Internationalization wizard to complete the key/value pairs. Choose Tools > Internationalization > Internationalization Wizard and modify the values according to directions.

After all the strings have been added to the messages.properties file, do the following to add values for each new locale:

  1. Right-click on the file node in the Projects view and choose Add Locale.

  2. Choose a locale you want to support from the Predefined Locales list box, or use the combo boxes at the top of the form to define a new locale.

  3. Expand the message.properties node in the Projects view, and double-click on the newly-added locale.

  4. Translate all properties into the appropriate language.

The mobile application will use the microedition.locale attribute to determine which version of the messages.properties file should be used.

21.9 Connecting MIDP Applications to Web Services

Web services extend the availability of server-based applications and services to remote clients.

Mobile client applications use the same Web services architecture as do larger Java SE applications:

The IDE enables you to create client MIDlets that can connect to Web services either through a direct "two-tier" architecture, or a "three-tier" architecture that connects to Web services through a middleware Web application.

The IDE provides two wizards for creating the connecting classes:

21.9.1 How to Create a Java ME Web Services (JSR-172) Client

With the Web Services Client wizard, you can create stub (client proxy) files that directly call a Web Service using the Simple Object Access Protocol. The code stubs use a Web Service Descriptor Language (WSDL) file and implement the JSR-172 Web Services Specification.

Note:

Before you begin, you must already have a WS-I compliant, WSDL file available on your system or at a location that can be reached through the HTTP protocol. You must also have a device or device emulator that supports the JSR-172 specification to successfully run and deploy the project.

To create the Web Services Client:

  1. Right-click on a project node and choose New > Mobile to Client Web Application.

  2. In the Web Application filed choose the location of the Web Project you want to use.

  3. Identify the .wsdl file location for the Web service to be added to the project.

    • If the WSDL service is on the Web:

      1. Choose Running Web Service and enter a URL for the .wsdl file and enter a local filename for the retrieved .wsdl file.

      2. If you are behind a firewall, click Proxy Settings to designate the appropriate HTTP host and port.

      3. Click Retrieve WSDL to get a local copy of the .wsdl file. The IDE downloads the .wsdl file.

    • If you have a .wsdl file on your system, select Existing WSDL File and enter a file name.

    The WSDL file is retrieved and the rest of the fields on the page are filled with default names derived from the WSDL file name.

    Note:

    The message "WSDL file is not WS-I compliant as required by the specification," indicates that the client cannot be generated with the selected WSDL file. To solve this problem, you can change the style of the WSDL file (see the website). Another option is to use the Mobile Client to Web Application Generator to create a "three-tier" Web services connection.

  4. Press Finish.

    The IDE creates an opened settings file and generates the client stubs.

Note:

In some situations, you might need to convert CLDC 1.1 types to CLDC 1.0 types, which means Float and Double types are converted to String variables. To make the conversion, select the “Convert floating point to String” checkbox on the Settings file and click the Generate Stubs button.

Note:

If you are behind a firewall, there is no public setting available for the HTTPS proxy within NetBeans. To work around this, run the IDE from the command line with the command -J-DhttpsProxy.host and -J-DhttpsProxy.port, or add the proxy settings into the /etc/netbeans.conf file.

Note:

The generated files should not be edited. Any changes made to the files are lost when you update them with the Settings file.

21.9.2 How to Update Java ME Web Services Client Files

You can use the Java ME Web Services Client wizard or the Mobile Client to Web Application Generator to create a MIDP client/server connection.

After you have created the client and connection files, you can not manually edit them. You can, however, regenerate them with different settings using the Settings file, which is displayed in the Editor after you generate the original application, or when you open the Settings file in the Editor window.

To open the Settings file:

In the Files or Projects window, expand the project and double-click on the appropriate node (.wsclient file).

The Web Services Settings File opens in the Editor window.

To make changes in the generated files:

You can change the selection of services the application uses, and edit any of the following fields:

  • Client Information. This information cannot be edited.

  • Client Options:

    • Generate stubs. Generates stub methods on the client for each exported service. Method names are incorporated in the class name. Using HelloService for example, the sayHello() method is exported. The generated stub method creates a method on the client called example_HelloService_sayHello(). If this option is not selected, only one method is generated on the client.

      When the option is selected, the server is called only after several grouped calls are made and the getGroupedResults() method on the client class is called. All the method calls are invoked in a single HTTP request and response. Methods are invoked in the order they were called. Results are returned in an enumeration object.

      If a server call causes an exception, the exception is thrown when getGroupedResults() is called. When an exception is thrown in a sequence of grouped calls, the calls following the exception are not processed.

    • Allow floating point. Activates support for float and double data types.

  • If you need to convert CLDC 1.1 types to CLDC 1.0 types, you will need to convert Float and Double types to String variables. To make the conversion, check the Allow floating point checkbox in the Settings panel. (This field might not be available in all instances.)

To regenerate the application:

Click the Generate Stubs button to regenerate the stub classes.

Note:

If you have deleted or updated the local WSDL file, you also need to refresh the WSDL file.

To refresh the WSDL file:

Click the Refresh WSDL button.

If you have changed the WSDL file, you will be asked to if you want to change your local WSDL file and update the stub files.

Note:

If you are using a proxy server, you must set the proxy by choosing Tools > Options in the Main Menu.

Note:

If you are regenerating a three-tier application (an application generated by the Mobile Client to Web Application Generator), you will need to build and re-deploy the application.

21.10 Working with Java ME Project Configurations

One of the most difficult aspects of developing applications for mobile devices is device fragmentation. The situation arises when vendor-specific, proprietary, or optional APIs are added to mobile devices to expand device functionality. Mobile devices often differ in a variety of attributes, such as screen size or color depth, and many support proprietary or optional APIs. These differences can require special code or project settings. To solve this problem, the IDE supports project configurations.

A project configuration enables you to define an execution environment for each device you want to run your application on. With project configurations and preprocessing, you can write a single application and create, customize, and deploy a separate distribution JAR for multiple devices.

You should create one configuration for each distribution JAR you plan to build for your project. For example, if you are planning to support three different screen sizes using two sets of vendor specific APIs, you should create six configurations.

Properties that are defined in a project configuration include:

21.10.1 How to Work with MIDP Project Configurations

The following steps outline the basic process of working with MIDP Project configurations:

  1. Create a project using the best template for your programming needs.

  2. Create Additional Configurations:

    In the Project Properties window, click the Manage Configurations button. Then choose Add.

    You can also add additional emulator platforms.

  3. Customize the Configuration.

    Right-click the project node and choose Properties. You can use the same settings as the default configuration, or you can add MIDlets, libraries, and other resource files, define push registry entries and API permissions, and create settings for obfuscation and security. All changes you make to the default configuration, other than to the Run options, propagate to all other configurations automatically. Any changes you make to a configuration other than the default configuration apply only to that non-default configuration.

  4. Add Preprocessor Code Blocks.

    You can right-click in the code and choose preprocessor blocks to add in blocks of code customized for a specific configuration.

  5. Run Configurations.

    1. Right-click the project node and chose Run.

    2. Activate a different configuration by selecting the project node and choosing Run > Set Project Configuration from the main menu. Then choose a different configuration and run the project again. You can also change the configuration of the selected project with the Configuration combo box in the main toolbar.

21.10.2 About Abilities

Abilities are identifiers that enable you to group similar project configurations and simplify the process of managing preprocessor code.

When you create an ability, you associate it with one or more project configurations that support a specific attribute or set of attributes. You can then associate the ability with one or more code blocks that support the attribute. If you later need to add or remove configurations, you won't have to go through all your code and associate the configuration with each code block. Instead, you need only to associate the configuration with an ability. The configuration is then automatically associated with any code block that is associated with the ability.

For example, you might write an application for six devices, three of which support a single screen size. You can create an ability named smallscreen, and associate it with the three project configurations. You can then associate the single ability with code blocks that support the specific screen size. If you decide later to support an additional device, you need only to associate the new project configuration with the smallscreen ability, and the ability will be associated with all the relevant code blocks.

Ability values can be integer numbers, strings or empty symbols used as booleans. Internally they are all treated as strings. When preprocessed, however, if it is determined that the value the variable holds is an integer, they are treated as integers and compared as such. Comparisons should not be done on different variable types. However, such comparisons do not break the build process. If different variable types are compared, the preprocessor issues a warning in the Editor and Output windows and evaluates the expressions, treating abilities on both sides of the operator as Strings.

21.10.3 How to Create an Ability and Associating Configurations

Abilities are identifiers that enable you to group similar project configurations and simplify the process of managing preprocessor code.

When you create an ability, you associate it with a project configuration. After you create the ability, you can then associate it with other configurations as well.

To create an ability and associate it with a project configuration:

  1. Right-click on a project in the Projects view and choose Properties.

  2. Choose the Abilities page from the Category menu tree.

    If necessary, uncheck the Use Values from "DefaultConfiguration" check box.

  3. Click the Add button. This opens the Add Ability dialog.

  4. In the Add Ability dialog, enter a name for the ability.

  5. Optionally, add a value for the new ability. Values can be integer numbers, strings or empty symbols used as booleans.

  6. Click OK to close the Add Ability dialog. The ability is now associated with the selected project configuration.

You can associate the ability with other configurations by choosing a different configuration from the Project Configuration menu and clicking the Add Ability button.

You can also add and associate abilities in the Navigator. Select one or more project configuration nodes in the Projects window and right-click on one or more abilities in the Navigator.

If you select more than one configuration, the Navigator shows the intersection of abilities assigned to the selected configurations. Abilities with different values are shown with the value "Multiple different values." Selected configurations must be part of the same project.

The context menu lists the following actions:

  • Add. Adds the selected ability or abilities to all of the selected configurations.

  • Remove. Removes the selected abilities from all of the selected configurations.

  • Copy. Copies the selected abilities to an internal buffer.

  • Paste. Pastes abilities from the buffer to the selected configurations.

21.10.4 How to Customize Java ME Project Configurations

A project configuration defines the execution environment for a Java ME MIDP application that emulates a specific mobile device. You can define multiple project configurations for an application, then customize the properties of each configuration to match the specific devices for which you are programming. This enables you to test and debug your application for each device. You can then use project configurations to deploy a separate distribution JAR for one or all of your configurations.

You customize project configurations using the Properties dialog. You can then group configurations as abilities, and embed preprocessor blocks within your code to take advantage of the specific functions of each configuration.

After a project containing multiple configurations is built, the build folder contains the build directory for DefaultConfiguration. Sub-directories in the dist folder contain the build and distribution files for each configuration in the project.

To open the Project Properties dialog, choose File > <active project name> properties.

21.10.4.1 Customizing Project Configurations

Properties that can be viewed or customized in a project configuration include:

  • emulator platform

  • specific emulator device

  • supported version of the Connected Limited Device Configuration (CLDC)

  • supported version of the Mobile Information Device Platform (MIDP)

  • supported optional packages and APIs

  • attributes listed in the JAD file

  • MIDlets included in the JAR

  • push registry entries

  • API permissions

  • build properties

  • libraries and resource files bundled in the project

  • file filtering

  • obfuscation level

  • JAD and JAR file names

  • security domains and signing

  • javadoc generation

  • deployment methods

21.10.4.2 Customizing Platform Properties

You can set the Platform properties of a project configuration by choosing File > "active project name" properties. In the Project Properties dialog, select Platform.

The Platform project properties dialog enables you to choose an emulator platform that simulates a mobile device to which the application will be deployed. The properties shown are specific to the active project configuration, shown in the Project Configuration dropdown menu at the top of the dialog.

To change the active emulator platform:

Choose an installed emulator from the Emulator Platform dropdown menu.

To add or remove an emulator platform:

Choose Tools > Java Platform Manager from the Main Toolbar, or click the Manage Emulators button in the Platform Properties dialog. This opens the Java Platform Manager, where you can add or remove the platform.

To set the version of CLDC or MIDP supported:

Choose the appropriate radio button for Device Configuration and Device Profile.

Note:

The configuration and profile versions supported depend upon the platform emulator and device selected.

To choose the optional packages and APIs supported by the emulator platform:

Check the appropriate check boxes in the Optional Packages pane of the Project Platform Properties dialog. The dialog lists all the packages provided by the selected emulator platform.

To utilize tools and utilities included with the emulator platform:

  1. Choose Tools > Java Platform Manager from the Main Toolbar, or click the Manage Emulators button in the Platform Properties dialog. This opens the Java Platform Manager.

  2. If available, choose the Tools and Extensions tab. The tab will list the tools and extensions provided by the emulator.

    Note:

    The default emulator, Sun Java Wireless Toolkit, supports various performance tuning and monitoring tools that can be accessed through the Tools and Utilities tab.

21.10.4.3 Customizing the Application Descriptor (JAD) Attributes

You can choose which attributes are included or excluded in your project configuration by choosing File > "active project name" properties. In the Project Properties dialog, select Attributes.

The Application Descriptor page enables you to add, edit, or remove the list of attributes that allow application management software to identify, retrieve, and install the MIDlets of a MIDlet suite.

To add, edit, or remove an attribute:

  1. Click the Add button. The Add Attributes dialog opens.

  2. Choose an attribute from the combo box. Then add a value for the attribute.

    Note that the list of available attributes is dependent upon the MIDP version supported by the project configuration, as set in the Platform properties. You can also add user-defined attributes by entering the attribute in the combo box.

    Note:

    To avoid errors in verification, make sure all required attributes have a defined value. Also, do not begin user-defined attribute keys with MIDlet- or MicroEdition-

21.10.4.4 Adding MIDlets to a Project Configuration

To add an existing MIDlet:

  1. Right-click on a project and choose Properties.

  2. Select Application Descriptor from the Categories window and select the MIDlet tab in the right pane.

  3. Click the Add button.

  4. Fill in the Add MIDlet dialog and click OK. The MIDlet is automatically added to the Application Descriptor (JAD) file.

To add a new MIDlet:

  1. Select a Project and Choose File >New File (Ctrl+N).

  2. Select MIDP under Categories, then select the desired file template under File Types.

  3. Enter the appropriate information in the MIDlet wizard.

  4. Click Finish.

    The MIDlet is automatically added to the JAD file.

21.10.4.5 Customizing Compilation Options

You can set the build options in a project configuration by choosing File > "active project name" properties. In the Project Properties dialog, select Build > Compiling.

For more information on compiler options, see: http://docs.oracle.com/javase/1.5.0/docs/tooldocs/solaris/javac.html

Click in the associated check box to enable the following options:

  • Generate Debugging Info. If checked, the compiler generates line numbers and source files information. This is the -g option in javac. If unchecked, no debugging information is generated (-g:none).

  • Compile with Optimization. If checked, the compiled application is optimized for execution. This is the -O option in javac. Optimizing can slow down compilation, produce larger class files, and make the program difficult to debug.

  • Report Uses of Deprecated APIs. If checked, the compiler lists each use or override of a deprecated member or class. This is the -deprecated option in javac. If unchecked, the compiler shows only the names of source files that use or override deprecated members or classes.

You can also set the default encoding used by the preprocessor and compiler in the encoding field. The default value is the default encoding used by your JVM and IDE.

The Debug Block Level drop-down menu sets the debug level for the //#debug and //#mdebug preprocessor directives. If you enter a unique value for the level (for example, debug_graphics), the preprocessor allows only debug blocks that exactly match the debug block (for this example, //#debug debug_graphics). All other debug blocks are commented out.

If you choose a pre-defined level from the drop-down menu, the preprocessor comments out debug blocks on lower levels, as defined by the following hierarchy:

  • fatal (most exclusive)

  • error

  • warn

  • info

  • debug (most inclusive)

For example, if you choose warn, all info and debug blocks will be commented out.

Note:

If you are setting the properties for a project configuration other than the default configuration (DefaultConfiguration), you must uncheck the Use Values from "DefaultConfiguration" checkbox at the top of the page to customize these options.

21.10.4.6 Adding Libraries and Resources to a MIDP Project

Adding a group of class files to a project's classpath tells the IDE which classes the project should have access to during compilation and execution. Use the Libraries & Resources properties page to add or remove additional libraries, projects, or JAR and ZIP files to a classpath for a project configuration.

Note:

If you are setting the properties for a project configuration other than the default configuration (DefaultConfiguration), you must uncheck the Use Values from "DefaultConfiguration" checkbox at the top of the page to customize these options.

You can add the following item types to your project:

  • Project. The JAR file produced by another project, as well as the associated source files and Javadoc documentation. Adding this item to a class path sets up a dependency between the current project and the selected JAR.

  • Library. A collection of JAR files or folders with compiled classes, which can optionally have associated source files and Javadoc documentation.

  • JAR file. A JAR file somewhere on your system. Adding a JAR file creates a library entry named by the JAR and containing the JAR.

  • Folder. The root of a package or directory containing files. Adding a folder does not create a library entry.

To add a project, file, folder or library to the project's classpath:

  1. Choose File > "active project name" properties.

    This opens the Project Properties dialog.

  2. Expand Build > Libraries & Resources in the left pane.

  3. Click on the appropriate button to open a file chooser for that item type.

    Clicking the Add Library button opens the Library Manager, where you can add or edit library classes.

Note:

If a project has multiple distribution JAR files, all of the JARs appear in the Project Jar Files window. You will need to select the correct version of the JAR file to include with the project configuration.

21.10.5 How to Work with Preprocessing

Preprocessing modifies the code in your source files before the code is parsed by the compiler. The preprocessor modifies the code according to preprocessor directives inserted as code blocks into the code. These code blocks are marked visually in the Source Editor and are included (or excluded) when you build the JAR for a specific project configuration or ability. You can use these code blocks to create, manage and track code that is specific to one or more project configurations or abilities.

For example, if you are writing an application targeted for several different devices, you can create a project configuration for each device, then create a preprocessor block with directives for each project configuration. You can then test the application for each device quickly by changing the active project configuration and running the application.

The If/Else code block shown in Figure 21-1 uses the directives #if, #else, and #endif to create a conditional timeout alarm. If the active configuration is DefaultGrayPhone, the ALERT_TIMEOUT is set for 2000. If the active configuration is set to any other project configuration, the ALERT_TIMEOUT is set to 3000. To test the application for either timeout, you can simply change the default configuration from DefaultGrayPhone to any other configuration.

Figure 21-1 If/Else Code Block

If/Else Code Block

21.10.5.1 Managing Preprocessor Blocks

Preprocessor code blocks enable you to manage preprocessor directives as you insert them into your code. These code blocks are marked visually in the Source Editor and are included (or excluded) when you build the JAR for a specific project configuration or ability. You can use these code blocks to create, manage and track code that is specific to one or more project configurations or abilities.

In the IDE, you can do the following:

  • Add preprocessor blocks.

  • Change a preprocessor block's association with configurations or abilities.

To add a preprocessor block to your source code:

  1. Select and a line or block of code and right-click on it Then choose from the following:

    • Create <nested> If/Else Block. Creates a conditional If/Else expression for the default configuration or you can use code completion to choose other configurations.

    • Add Elif Block Section. Creates a conditional #elif expression within an IF/Else block.

    • Create Debug Block. Determines if the line following the directive should be commented or uncommented based on the debug level set in the project properties.

  2. Use the Editor to enter code within the code blocks.

To change a preprocessor block's association:

  1. Click to the right of a preprocessor directive (signified by the characters //#).

  2. Type Ctrl-Space and choose a configuration or ability from the code completion drop-down menu.

21.10.5.2 Specifying Preprocessor Directives

Most preprocessing is controlled by preprocessor directives. Directives are specified within the source code by creating a commented line that starts with the //# character sequence, immediately followed by the directive. For example, //#ifdef.

Like the XML language, preprocessor directives must be well-formed. That is, they must have a beginning directive and an ending directive. For example, when a block is started with one of the //#if directives, it must be closed by an //#endif directive. Blocks can be nested, which means that inside an if/elif/else/endif block can be any number of additional if/elif/else/endif blocks.

Directives define actions and conditions. The preprocessor decides upon whether to comment or uncomment the block of code. Symbols in directive expressions can be either defined or not defined. Identifiers and variables, however, must always contain a value that can be used or compared during preprocessing. The preprocessor supports three types of variables: strings, integers, and booleans.

Variable names must start with characters/tokens which are same as start characters/tokens of valid Java identifiers but in addition, consequential characters can also be '.' '\' and '/'. You can compare different variable types using common comparison syntax (<=, <, >=, > and ==). You can also use boolean operations, such as &&, ||, ! and ^. You can also use <variable name>:defined or defined(<variable name>) functions to check for variable definitions. This is not necessary and should not be used when creating new code blocks but is built in for easy imports from J2ME Polish.

Figure 21-1 shows If/Else block with a nested elif directive.

Example 21-2 If/Else block with a nested elif directive

//#if mmedia
   //#if nokia
     //#if s60_ver=="1.0"
     import com.nokia.mmapi.v1
     //#elif s60_ver=="2.0"
     import com.nokia.mmapi.v2
    //#else
    import com.nokia.mmapi.def
   //#endif
  //#else
     import javax.microedition.mmapi
  //#endif
//#endif

Note:

The NetBeans IDE supports all directives of the Antenna preprocessor (http://antenna.sourceforge.net/), so you can migrate Antenna projects into the NetBeans IDE and retain your preprocessor code.

Directive Syntax

See Table 21-1 for a description of preprocessor directives.

Table 21-1 Preprocessor Directives

Directive Description

#ifdef [identifier]

The identifier represents a variable of any type (boolean, string, or integer) and checks whether or not the variable is defined. If true (the variable is defined), the code that follows is processed. Nested blocks are processed as well. If false (the variable is not defined), the code that follows is commented and nested blocks are not evaluated. The directive must be closed with #endif.

#ifndef [identifier]

Works in the same manner as ifdef, but returns "True" if the variable is not defined. The directive must be closed with #endif.

#elifdef [identifier]

Works as a standard else if statement, but automatically checks whether or not the identifier is defined. The directive can only complement inside blocks started by ifdef/ifndef.

#elifndef [identifier]

Works as a standard else if statement but automatically checks whether the identifier is not defined. The directive can only complement inside blocks started by ifdef/ifndef.

#if [expression]

Evaluates an expression passed to it and fires the appropriate action. The directive must be closed with endif.

#elif [expression]

Works as a standard else if statement and can complement only in blocks started by an if statement. The directive preprocesses the code that follows based on the result of the expression.

#else

Works as a standard else statement only preprocesses the code that follows when none of the previous conditions in the defining block were true. Complements inside any block started with the if/ifdef/ifndef directive.

#endif

This directive must be used to close any block started with if/ifdef/ifndef.

#condition [expression]

Must be on the first line in a file. This directive determines if the file should be included in the build based on the result of the expression.

#debug [level]

Determines if the line following the directive should be commented or uncommented based on the debug level set in Compiling page of the project properties. If the debug level is omitted and the debug level is not set to "Off" in the project properties, the preprocessor will automatically debug the line in question. Used for debugging purposes with expressions such as System.out.println, for example. This directive can be nested.

#mdebug [level]

Behaves the same as #debug, but instead comments or uncomments a whole block of lines following the line it is on until it reaches #enddebug. This directive is used for debugging purposes with expressions such as System.out.println, for example. This directive can be nested. If the mdebug block partially intersects an if/ifdef/ifndef block (for example, enddebug is outside a closed if block in which mdebug is called) the preprocessor will generate errors.

#enddebug

Must terminate #mdebug block.

#define [identifier] #define [identifier=value] #define [identifier value]

Adds temporary abilities or variables to the preprocessor memory. Can not be used in nested blocks. Global variables defined in the project configuration properties override these temporary variables.

#undefine [identifier]

Removes temporary abilities/variables from the memory. This declaration can also be used to remove global variables defined in the project configuration properties from the preprocessor memory, but will not remove the variables from the list of project or configuration variables.

21.10.5.3 Using Comparison Syntax in Preprocessor Directives

The preprocessor supports three types of variables:

  • strings

  • integers

  • boolean values

Most common comparisons (<=, <, >=, > and ==) are supported between the variables.

Boolean operations such as &&, ||, ! and ^ can also be performed on all symbol types.

Integers behave the same as strings when it comes to boolean operations. However, they are compared as true integers and can be used for such tasks as preprocessing code where various screen resolutions require different images that are optimized for different resolutions. For example, the directive //#if ScreenWidth>100 && ScreenHeight>120 can specify a code block which will import images only for devices whose screens are larger than 100x120.

If a variable is defined, then it is considered a boolean with the value, "true." If the variable is not defined anywhere as an ability or configuration. then it is considered a boolean with value "false."

Comparisons should not be done on different variable types. However, such comparisons do not break the build process. If different variable types are compared, the preprocessor issues a warning in the Editor and Output windows, and evaluates the expressions as follows:

  • Left and right sides of the comparison operation are of different types. Both sides are considered strings and compared lexically, with the exception of the @ operation where the "subset" relationship operation will still be performed (allowing you to check whether a certain integer is in a particular set).

  • One of the variables is not defined or is defined as a boolean symbol. The variable is considered an empty string "". If one of the variables is integer it is also converted to a string and a lexical comparison will take place.

Operators

There are three types of operators with different priorities:

  1. The "not" operator (!)

    This operator has the highest priority and can be used on variables and expressions with the syntax !<identifier> or !<expression>.

    For example, //#if !(ScreenWidth>100 && ScreenHeight>120) checks if the screen size is smaller than 100x120.

    Since the ! operator has the highest priority, expressions such as //#if !ScreenSize=="100x200" are illegal and yield syntax errors because a boolean result cannot be compared to a string.

  2. Comparison operators

    Comparison operators have the second highest priority and perform typical comparison operations. Because the operators can compare strings lexically and integers mathematically, cross-type comparisons are supported. However, they can be used only in expressions and should compare two variables, not symbols.

    There is also a special comparison operator which performs a "subset" relationship operation. This operator is denoted by the character @. Both left and right arguments should be strings which represent two sets of tokens delimited by specific delimiters. The operator first considers both left and right string arguments as sets and then determines if the set from the left argument is a subset of the set from the right argument. The valid word delimiters are <whitespace>,',' and ';'. The delimiters can be mixed arbitrarily within each argument, as shown in Example 21-3.

    Example 21-3 Delimiters mixed within arguments

    "gif" @ "gif86, jpeg, gifaboo" = false
"gif" @ "gif gif86 jpeg" = true
"1 2 4;7,8" @ "0,1,2,3,4,5,6,7,8,9" = true
"3 5 7 11 13" @ "0,1,2,3,4,5,6,7,8,9" = false

  3. Boolean operators

    Boolean operators have the lowest priority relative to the rest of the operators. They also have different priorities amongst each other, just as in the Java language. Boolean operators perform typical logical operations such as &&, || and ^ on boolean expression results, or check for variable definitions and then treat those as boolean expressions as well. Boolean operators are processed in the order:

    1. &&

    2. ^

    3. ||

21.11 Running MIDP Applications

When you run a MIDP application, the IDE compiles, preverifies and builds the application according to the settings of the current. As the MIDlet executes, the output is shown in the device emulator. You can run any individual project that contains an executable class.

To run a project:

Choose Run >Run Project (F6) or right-click any project in the Projects window and choose Run.

To run a project with a different emulator platform or device emulator:

  1. Right-click on a project and choose Run With.

  2. Choose an installed emulator platform and device emulator from the dropdown menus. The project uses the current distribution JAR and does not rebuild the project before running.

You can also choose to execute the MIDlet using Over-the-Air provisioning which is the process of deploying an application from a website on to a mobile device. If you choose Execute Through OTA in the MIDP Project Running Property sheet, the IDE simulates the OTA process so you can test and demonstrate the full provisioning process of the MIDlet suites from the server to a device. Additional information on OTA Application Provisioning is available at http://www.oracle.com/technetwork/systems/index-156355.html.

21.11.1 How to Customize MIDP Project Run Options

You can choose one of two different ways to execute a MIDP program:

  • Regular Execution. Runs the project on an emulator device. In this mode, you can also set a security domain for the application, to test its security.

  • Execute Through OTA. Runs the project using Over-The-Air provisioning, which simulates the process of deploying an application from a server to a mobile device.

To customize the run options:

  1. Choose File > <active project name> Properties. In the Project Properties dialog, select Running.

  2. Click a radio button to choose between the two run options.

The MIDP specification includes the Over The Air User Initiated Provisioning Specification, which describes how MIDlet suites can be transferred over-the-air (OTA) to a device.

21.11.2 How to Run a MIDlet Suite with OTA Provisioning

Running your MIDlet suite with Over-The-Air (OTA) provisioning emulates the process that takes place when a device downloads and installs your suite from a server. If your suite is signed, the emulator gives it access to protected APIs according to the security domain of the suite's certificate. Running a suite with OTA provisioning also lets you test any inbound connections from the server as defined in the suite's push registry.

To enable OTA provisioning for an emulator:

  1. Choose File > <active project name> Properties.

  2. In the Project Properties dialog, select Running.

  3. Choose the Execute Through OTA radio button.

    The IDE enables OTA provisioning for the emulator and runs the MIDlet suite with the specified preferences.

Note:

If you are setting the properties for a project configuration other than the default configuration (DefaultConfiguration), you must uncheck the Use Values from "DefaultConfiguration" checkbox at the top of the page to customize these options.

21.11.3 How to Run Headless Builds

Headless builds for mobility projects are handled under the same principles as standard MIDP projects. If the project has already been opened in the IDE on a target computer and no reference problems exist, then any Ant target can be invoked from within the project directory.

To invoke the Ant target:

Type ant jar run at the command line.

21.12 Testing Java ME Applications With JMUnit

The IDE provides built-in JMUnit support for unit testing CLDC and MIDP applications. JMUnit is an open source project, based on JUnit, that provides a framework for writing and executing tests on Java ME code.

For more information about JMUnit see http://sourceforge.net/projects/jmunit/.

Test Types in the IDE

You can use the IDE to create the following:

Note:

The IDE cannot create unit tests with JMunit for MIDlet classes or private methods.

JMUnit Test Structure

When generating tests with JMUnit the IDE creates empty test skeletons by default. Each test class has the name of the class it is testing appended by the word Test (for example, MyClassTest.java). Each standard project has a default test folder that is used to store your tests. This folder is displayed as the Test Packages node in the Projects window. You can add any number of test folders to your project. Test files must be located in a separate source tree than the source files they test.

Running JMunit Tests

You can generate and navigate to tests by selecting any class or package node in the Projects window and choosing from the Tools > JUnit menu.

When you generate your first test, a TestSuite MIDlet from the framework JAR gets added to the list of MIDlets. This MIDlet will be shown in the emulator windows Run list when you run the project.

All test classes are added to a property in the JAD manifest called JMunitTestClasses. When you generate your first test for the project, the JMunit framework JAR gets added to the project libraries for all project configurations. The framework JAR builds a list of tests to run from the JMUnittestClasses property. Remember that Java ME does not support the reflective API as JUnit does. Therefore the empty tests JMUnit creates must be modified to include assertions of expected results to give the Pass/Fail results relevance.

The following steps outline the basic process of working with JMUnit for CLDC and MIDP applications:

  1. Create Tests.

    • Generate tests for existing classes or packages as JUnit does for Java SE projects.

    • Create an empty test skeleton.

  2. Edit Tests.

    Add test logic and assertions of expected results to test skeletons.

  3. Run Tests.

    • Run the test file for a specific class.

    • Run tests for an entire project. Note that MIDlets and private methods cannot be tested using JMUnit.

  4. Debug Tests.

21.13 Deploying Java ME Applications

One of the most challenging aspects of developing Java ME applications is that MIDlets are created on one platform, such as Linux or Windows, but are deployed to MIDP and CDC devices running on completely different platforms. Deployment is the process of transferring the application you develop in the IDE to a mobile device or to a server for further testing or implementation.

The IDE supports several methods of deployment, including:

To Deploy a MIDlet Suite:

  1. Choose File > <active project name> Properties.

  2. In the Project Properties dialog, select the Deploying node from the Category tree.

    Note:

    If you are setting the properties for a other than the default configuration (DefaultConfiguration), you must uncheck the Use Values from "DefaultConfiguration" checkbox at the top of the page to customize these options.

  3. Choose a deployment method from the Select Deployment Method dropdown menu.

  4. Optionally, you can customize the URL for the JAR file by checking the Override JAR URL in JAD and entering a custom JAR file name.

  5. Enter the appropriate information in the dialog.

  6. Right-click on the project and choose Deploy Project.

21.13.1 How to Deploy Java ME Applications Remotely to the Device Anywhere Website

You can deploy your Java ME applications to the Device Anywhere website from within the IDE. Device Anywhere's servers host the most popular mobile devices on the market today and allow you to test and debug your Java ME applications on your target devices using their site. Please note that registration is required to use this service.

For more information about deploying to Device Anywhere see http://www.deviceanywhere.com/.

Using Device Anywhere to deploy to a MIDlet suite:

  1. Choose File > <active project name> Properties.

  2. In the Project Properties dialog, select the Deploying node from the Category tree.

  3. Choose Device Anywhere Remote Device Deployment from the Select Deployment Method dropdown menu.

  4. Choose a Deployment Instance from the drop-down list or click Manage Deployment, then Add Instance to create a custom instance for deployment.

  5. Click on the Retrieve Devices button to connect to the Device Anywhere website and view the list of mobile phones available for remote deployment.

21.13.2 How to Deploy a MIDlet Suite Using File Copy

You can set the properties of your project to automatically deploy your MIDlet suite. Using the Copy method moves the JAR and JAD files of a MIDlet suite to a specified location on a local system.

Note:

If you are setting the properties for a other than the default configuration (DefaultConfiguration), you must uncheck the Use Values from "DefaultConfiguration" checkbox at the top of the page to customize these options.

To deploy a MIDlet suite using Copy:

  1. Choose File > <active project name> Properties.

  2. In the Project Properties dialog, select the Deploying node from the Category tree.

  3. Choose Copy from the Select Deployment Method drop-down menu.

  4. Optionally, you can customize the URL for the JAR file by checking the Override JAR URL in JAD and entering a custom value.

  5. Enter the name of the target directory where the MIDlet suite is to be copied.

  6. Right-click on the project and choose Deploy Project.

Each time you compile the MIDlet suite, the application's JAR and JAD files are copied to the target directory.

21.13.3 How to Deploy a MIDlet Suite Using FTP

You can set the properties of your project to automatically deploy your MIDlet suite.

You can use the File Transfer Protocol (FTP) protocol method to move the JAR and JAD files of a MIDlet suite over the Internet.to a specified location on a remote server.

Note:

If you are setting the properties for a other than the default configuration (DefaultConfiguration), you must uncheck the Use Values from "DefaultConfiguration" checkbox at the top of the page to customize these options.

To deploy a MIDlet suite using the FTP protocol:

  1. Choose File > <active project name> Properties.

  2. In the Project Properties dialog, select the Deploying node from the Category tree.

  3. Choose FTP from the Select Deployment Method drop-down menu.

  4. Optionally, you can customize the URL for the JAR file by checking the Override JAR URL in JAD and entering a custom value.

  5. Enter the following information to specify the target location on the remote server:

    • Server. Name or IP address of the target server.

    • Target Directory. Location on the server where the MIDlet suite is to be sent.

    • Port. The FTP server's command port. Typically the server uses port 21.

    • Separator. Defines whether the file location names separators use a slash ("/" as in UNIX) or backslash ("\" as in Windows/DOS systems) to separate directory names.

    • To use passive FTP transfer protocol, check the Passive Mode Transfer check box.

    • Optionally, enter your user name and password. If you do not enter a name and password here, you will be asked to enter the name and password when the application is deployed.

    • Right-click on the project and choose Deploy Project.

21.13.4 How to Deploy a MIDlet Suite Using WebDAV

You can set the properties of your project to automatically deploy your MIDlet suite. You can use the WebDAV protocol method to move MIDlet suite files using the Web-based Distributed Authoring and Versioning (WebDAV) protocols, a set of extensions to the HTTP protocol which allows you to work in collaboration with others to edit and manage files on remote web servers.

Note:

If you are setting the properties for a project configuration other than the default configuration (DefaultConfiguration), you must uncheck the Use Values from "DefaultConfiguration" checkbox at the top of the page to customize these options.

To deploy a MIDlet suite using the WebDAV protocol:

  1. Choose File > <active project name> Properties.

  2. In the Project Properties dialog, select the Deploying node from the Category tree.

  3. Choose WebDAV from the Select Deployment Method drop-down menu.

  4. Optionally, you can customize the URL for the JAR file by checking the Override JAR URL in JAD and entering a custom value.

  5. Enter the following information to specify the target location on the remote server:

    • Server. Name or IP address of the target server.

    • Target Directory. Location on the server where the MIDlet suite is to be sent.

    • Port. The server's connection port.

  6. Optionally, enter your user name and password. If you do not enter a name and password here, you will be asked to enter the name and password when the application deploys.

  7. Right-click on the project and choose Deploy Project.

21.13.5 How to Deploy a MIDlet Suite to Nokia Mobile Devices

You can set the project properties to automatically deploy MIDlet suite to a Nokia Mobile device. This deployment method also enables you to run and debug the device deployed application from within the IDE.

Note:

You must have a Nokia (On-Device Debug) emulator registered with the IDE to use this option.

Note:

If you are setting the properties for a project configuration other than the default configuration (DefaultConfiguration), you must uncheck the Use Values from "DefaultConfiguration" checkbox at the top of the page to customize these options.

To deploy a MIDlet suite to a Nokia Phone:

  1. Choose File > <active project name> Properties.

  2. In the Project Properties dialog, select the Deploying node from the Category tree.

  3. Choose Nokia Terminal connected via PC Suite from the Select Deployment Method dropdown menu.

  4. Click Manage Deployment, then Add Instance to create a custom instance for deployment, or use the current setting as the default instance. Click OK.

  5. Right-click on the project and choose Deploy Project.

21.13.6 How to Deploy a MIDlet Suite Using SCP or SFTP

You can set the properties of your project to automatically deploy your MIDlet suite. You can use the Secure Client Protocol (SCP) or Secure File Transfer Protocol (SFTP) deployment methods to establish a secure connection and encrypt the data before passing the data between the client and server.

Note:

If you are setting the properties for a other than the default configuration (DefaultConfiguration), you must uncheck the Use Values from "DefaultConfiguration" checkbox at the top of the page.

To deploy a MIDlet suite using the SCP protocol:

  1. Choose File > <active project name> Properties.

  2. In the Project Properties dialog, select the Deploying node from the Category tree.

  3. Choose SCP from the Select Deployment Method drop-down menu.

  4. Optionally, you can customize the URL for the JAR file by checking the Override JAR URL in JAD and entering a custom value.

  5. Enter the following information to specify the target location on the remote server:

    • Server. Name or IP address of the target server.

    • Target Directory. Location on the server where the MIDlet suite is to be sent.

    • Port. The server's SCP connection port.

    • User Name. The name for the SCP login.

  6. Choose between using password and key authentication.

    • Use Password Authentication. Enter a password that is required when the MIDlet is deployed.

    • Use Key Authentication. Asks you to identify a key file and passphrase that is required when the MIDlet is deployed. You create and manage key files and their passwords in the MIDP Project Properties: Signing page.

    • Right-click on the project and choose Deploy Project.

21.13.7 How to Deploy a MIDlet Suite to Windows Mobile Devices

You can deploy your project to a Windows Mobile device using Sun's CLDC/MIDP Virtual Machine and ActiveSync. Before attempting to deploy the application, please make sure the following steps are completed:

  • Your MIDP Project ran successfully on the Java ME SDK or target device emulator.

  • The Windows Mobile device has the Sun CLDC/MIDP VM installed and running.

  • ActiveSync is installed and running with an active connection between the device and the computer.

To deploy a MIDlet suite to a Windows Mobile Device:

  1. Choose File > <active project name> Properties.

  2. In the Project Properties dialog, select the Deploying node from the Category tree.

  3. Choose Windows Mobile Deployment from the Select Deployment Method dropdown menu.

  4. Click Manage Deployment, then Add Instance to create a custom instance for deployment, or use the current setting as the default instance.

  5. Click the Browse button to navigate to where you want your MIDP application's JAD and JAR files copied to on the device. Click OK.

  6. Right-click on the project and choose Deploy Project.

21.13.8 How to Automatically Increment Java ME Application Version Attributes

The IDE has a built-in method that allows you to automatically increment the MIDlet-Version attribute in the JAR file each time you deploy the application. This is useful for mobile devices that check for updates of installed applications. Incrementing the value of the MIDlet-Version attribute enables such devices to automatically detect a new version when you deploy the application.

To automatically increment MIDlet-version with each deployment:

  1. Right-click on a project in Projects view and choose Properties.

  2. Choose Attributes from the Category menu tree.

  3. Select the MIDlet-Version field in the General Attributes table and click the Edit button.

  4. Enter ${deployment number} in the Value field.

  5. Click OK.

21.14 Using Java ME Emulator Platforms

An emulator platform simulates the execution of an application on one or more target devices. For example, the Java ME SDK enables you to run applications on several example devices, or "skins" included with the emulator. An emulator allows you to understand the user experience for an application on a particular device, and to test the portability of the application across different devices.

In the IDE, you specify the emulator platform as part of the overall project configuration. Many emulator platforms are packaged as software developer kits (SDKs) from manufacturers of mobile devices.

Some of the differences between emulators include their support for:

You can access the special tools and extensions of an emulator platform by choosing the Tools and Extensions tab in the Java Platform Manager.

Note that having an emulator does not completely free you from testing on your target devices. An emulator can only approximate a device's user interface, functionality, and performance. For example, an emulator might not simulate processing speed, so an application may run faster or slower on a target device than it does on an emulator.

21.14.1 How to Add MIDP Emulator Platforms

Adding an emulator platform to the IDE enables you to create project configuration and use that platform for compilation, execution and debugging within the IDE. Through the Java Platform Manager, you can add both custom and UEI-compliant emulator platforms.

Unified Emulator Interface (UEI) is a common set of standards specifying command-line access to emulator functionality. The UEI allows IDE manufacturers to write to a single interface and, with little or no effort, be able to support emulators from many different companies.

To add a UEI-compliant MIDP or CDC emulator platform:

  1. Choose Tools > Java Platforms.

  2. Click the Add Java Platform button.

  3. Choose Java ME CLDC Platform Emulator (or Java ME CDC Emulator Platform if this is the emulator type you wish to add).

    Click Next.

    The wizard searches your system and compiles a list of all available Java ME platforms. The wizard indicates which platforms:

    • have already been installed.

    • are available for installation. Indicated by a box with a check in it.

    • cannot be installed. Indicated in red. You might be able to install these platforms as custom (non-UEI) platforms.

    If the platform you want to install is not listed in the page, click on the Find More Java ME Platforms and navigate to the directory where the platform is installed.

  4. Put a check in the checkboxes of the platforms you want install.

    Click Next.

    The chosen platforms are installed.

To add a non-UEI-compliant emulator platform:

  1. Choose Tools > Java Platform Manager.

  2. Click the Add Platform button.

  3. Choose Custom Java Micro Edition Platform Emulator. Click Next.

  4. In the General Information page, specify the following information:

    • The directory where the platform is located.

    • Syntax for preverify, execution, and debugger commands

  5. In the Bootstrap Libraries page, add any additional libraries used by the emulator.

  6. In the Sources and Javadoc page, add any additional source files and Javadoc used by the emulator. Click Finish to add the emulator.

21.14.2 How to Add CDC Emulator Platforms

Adding CDC emulator platforms to the IDE enables you to compile, execute and debug CDC projects within the IDE. The Java ME SDK for Windows includes CDC profile support. To enable application development for additional CDC platforms you can download and install whichever of the following SDKs meets your needs.

CDC emulator platforms:

  • Nokia Series 80 Platform SDK for Symbian OS, for Java, Personal Profile

  • Microsoft Device Emulator

To add a CDC emulator platform:

  1. Choose Tools > Java Platforms.

  2. Click the Add Platform button.

  3. Choose Java ME CDC Platform Emulator. Click Next.

  4. Navigate to the directory where the CDC platform is installed. Click Next.

  5. The IDE will find the platform name automatically. You can edit the name if you prefer. Click Finish and the CDC platform is installed.

For complete CDC emulator platform installation instructions, see the NetBeans CDC Emulator Platform Setup Guide at https://netbeans.org/kb/docs/javame/cdcemulator-setup.html.

21.14.3 How to Customize Java ME Platform Properties

You can set the Platform properties of a project configuration by choosing File > <active project name> properties. In the Project Properties dialog, select Platform.

The Platform project properties dialog enables you to choose an emulator platform that simulates a mobile device to which the application will be deployed. The properties shown are specific to the active project configuration, shown in the Project Configuration dropdown menu at the top of the dialog.

To change the active emulator platform:

  • Choose an installed emulator from the Emulator Platform dropdown menu.

To add or remove an emulator platform:

  • Choose Tools > Java Platform Manager from the Main Toolbar, or click the Manage Emulators button in the Platform Properties dialog.

    This opens the Java Platform Manager, where you can add or remove the platform.

To set the version of CLDC or MIDP supported:

  • Choose the appropriate radio button for Device Configuration and Device Profile.

    Note:

    The configuration and profile versions supported depend upon the platform emulator and device selected.

To choose the optional packages and APIs supported by the emulator platform:

  • Check the appropriate check boxes in the Optional Packages pane of the Project Platform Properties dialog. The dialog lists all the packages provided by the selected emulator platform.

To utilize tools and utilities included with the emulator platform:

  1. Choose Tools > Java Platform Manager from the Main Toolbar, or click the Manage Emulators button in the Platform Properties dialog.

    This opens the Java Platform Manager.

  2. If available, choose the Tools and Extensions tab. The tab will list the tools and extensions provided by the emulator.

    The default emulator, Sun Java Wireless Toolkit, supports various performance tuning and monitoring tools that can be accessed through the Tools and Utilities tab.

21.14.4 How to Use the Java ME SDK

The Java Micro Edition SDK is a collection of tools and device emulators that support the development of Java applications that run on devices compliant with the Mobile Device Information Profile (MIDP), Connected Limited Device Configuration (CLDC) and Connected Device Configuration (CDC). These include a wide range of mobile phones, embedded systems, Blu-ray consoles and other devices.

The NetBeans IDE comes bundled with different versions of the SDK depending on which OS you are using:

  • Windows: Java ME SDK with CLDC/MIDP and CDC support.

  • Linux: Sun Java Wireless Toolkit with CLDC/MIDP support.

  • Mac OS: Java ME SDK with CLDC/MIDP support.

The Java ME SDK supports testing with several key features:

  • The Java ME SDK can simulate several devices including various standard mobile phone designs and touch screen devices. This helps you learn what type of experience users can expect and verify the portability of your application across different devices.

  • The Java ME SDK supports tracing and debugging with run-time logging of various events, such as garbage collection, class loading, method calls, and exceptions. You can also perform source-level debugging with an IDE while an application runs in the Java ME SDK.

  • The Java ME SDK enables you to collect information that you can examine to optimize the performance of your mobile applications. Performance tuning utilities include profiling methods and monitoring memory usage and network traffic. Also included is the ability to adjust the speed settings for graphic rendering and refreshing as well as VM speed emulation and network throughput.

To use the Java ME SDK utilities:

  1. Choose File > <active project name> properties.

  2. In the Properties page, choose Platform from the left pane.

  3. In the Platform page, click the Manage Emulators button. The Java Platform Manager opens.

  4. Select an installed Java ME SDK emulator from the menu in the left pane.

  5. Select Tools & Extensions tab from the right pane.

  6. Click the Open Preferences or Open Utilities buttons to open the platform tools.

  7. Click the Use SDK Extensions checkbox to use the Profiler and the Memory and Network monitors.

  8. Run the application.

For more information about the Java ME SDK, see http://www.oracle.com/technetwork/java/javame/javamobile/download/overview/index.html.

Go to previous page
Previous		 Go to next page
Next
Go to Documentation Home
Home		 Go to Book List
Book List		 Go to Table of Contents
Contents		 Go to Feedback page
Contact Us