4 Creating and Editing Projects

A project is a group of files comprising a single application. Files include source files, resource files, XML configuration files, automatically generated Apache Ant build files, and a properties file.

When a project is created, the SDK performs these tasks:

Creates a source tree you can examine in the Section 4.3, "Working With Projects" or Section 4.4, "View Project Files".
Sets the emulator platform for the project.
Sets the project run and compile-time classpaths.
Creates a build script that contains actions for running, compiling, debugging, and building Javadoc. The build process is controlled by project properties, as described in Section 5.4, "Building a Project". See also Section 13.4, "Build a Project from the Command Line".

Java ME SDK and NetBeans create their project infrastructure directly on top of Apache Ant. Java ME SDK projects can be opened and edited in NetBeans, and vice-versa. With the Ant infrastructure in place, you can build and run your projects within the SDK or from the command line.

The SDK provides two views of the project:

The Projects window provides a logical view of the project.
The Files window displays a physical view of the project.

Project settings are controlled in the project Properties window. Typically, you right-click on an item or subitem in a tree (a project, a file, or a device) and select Properties.

4.1 Project Types

The CLDC/MIDP platform implements the Mobile Information Device Profile and Connected Limited Device Configuration (JSRs 118 and 139).

The CDC platform is implemented to support Advanced Graphics and User Interface Optional Package for the J2ME Platform, Personal Basis Profile 1.1, and the Connected Device Configuration (JSRs 209, 217 and 218). The AGUI API combines the PBP API and a subset of Java Platform, Standard Edition (Java SE) Swing capabilities.

4.1.1 CLDC Projects

A MIDP application (a MIDlet), is deployed as a MIDlet suite. A MIDlet suite is distributed as a Java archive (JAR) file and a Java Application Descriptor (JAD) file.

The JAR file includes the Java classes for each MIDlet in the suite, Java classes shared between MIDlets, resource files, and other supporting files. The JAR file also includes a manifest describing the JAR contents and specifying attributes the application management software (AMS) uses to identify and install the MIDlet suite.

The JAD file contains attributes that allow the AMS to identify, retrieve, and install the MIDlets in a project. The SDK automatically creates JAD and JAR files when you build the project.

To create a new project, see the NetBeans help topic "New MIDP Project Wizard."

4.1.2 CDC Projects

Java ME SDK version 3.0.5 supports CDC projects running as standalone applications. This means the CDC project structure and behavior are much the same as that of CLDC projects.

Note:

An Xlet cannot be run standalone. It depends upon an application manager to manage its life cycle (its state) and system services. Xlets are not supported in this release.

A standalone CDC project requires a main application class that includes a method named main() that handles class loading, object creation, and method execution. The application interacts directly with the Java runtime environment to manage its own life cycle and system resource needs. When the main() method exits, the standalone application terminates.

4.2 The Project Wizard

The project provides a basic infrastructure for development. You provide source files, resource files, and project settings as needed. The SDK provides a wizard for creating new projects quickly and easily using an application template. Most project properties can be edited later by changing the project properties. For more on project properties, see Chapter 5, "Viewing and Editing Project Properties".

4.2.1 Project Template Page

This is the first page in the New Project wizard.

For MIDP the project options are as follows:

MIDP Application. Create a new MIDP application in a CLDC/MIDP project.
Import Wireless Toolkit Project. Create a project by importing a Sun Java Wireless Toolkit project from an existing toolkit installation.

See Section 4.2.8, "Create a CLDC Project".

For CDC the project options are as follows:

CDC Application. Create a new CDC application in a CDC project.
Import CDC Toolkit Project. Create a project by importing a CDC Toolkit project from an existing toolkit installation.

See Section 4.2.9, "Create a CDC Project".

4.2.2 Name and Location Page

Use this form to enter project information. This form is the second page in the New Project wizard. The name and location cannot be changed, but you can view a project's name and location.

Project Name. Enter a project name. If you are importing an existing project this field is pre-populated with the old filename prefixed.

Project Location. The default location is:

C:\Documents and Settings\user\My Documents\NetBeansProjects

Project Folder. The Project Folder value is extrapolated from Project Name and Project Location.

Set as Main Project. Check this box to make the project the Main Project when it is first opened. The Main project is automatically the focus of all actions initiated from the user interface (for example, the actions on the Run menu, which provide the same functionality as clicking icons on the main tool bar).

Create Hello MIDlet. This check box is only visible for a new MIDP project. It inserts sample MIDlet code as a template for your development. You can compile and run the MIDlet immediately.

Create Main Class. This check box is only visible for a new CDC project. Enter the fully qualified name of the main class without the .java extension. For example: com.me.MyClass.

See Section 4.2.9, "Create a CDC Project".

4.2.3 Choose Project (CDC)

You can view this page in the New Project wizard. The CDC project options are as follows:

CDC Application. Create a new CDC application in a CLDC project.

Import CDC Toolkit Project. Create a project by importing a CDC Toolkit project from an existing toolkit installation.

See Section 4.2.6, "CDC Toolkit Project Location". See Section 4.2.9, "Create a CDC Project".

4.2.4 Platform Selection (CDC)

You can view this form in the New Project wizard, or, in the Projects view, right-click a project, select Properties, and select Platform.

These settings help you test how your project runs on devices with different capabilities. Your choice of device limits your choice of Device Configuration and Device Profile.

Emulator Platform. By default you will see two CDC platforms - the 3.0 version installed with the Mobility pack and the 3.0.5 version installed with the Java ME SDK plugin. For the Java ME SDK plugin, choose the 3.0.5 version.

Device. Select a device. Only devices appropriate for the platform appear in the Device drop-down menu. The device selection determines the remaining options.

Device Profile. PBP-1.1 is the only option.

See Section 4.2.9, "Create a CDC Project".

4.2.5 WTK MIDP Project Location

To see this form, start the New Project wizard and select Import Wireless Toolkit Project.

WTK Location. Browse to select the location of your Sun Java Wireless Toolkit installation. Choose the installation directory.

Detected Applications. When the WTK Location is selected the Detected Applications window displays the available projects. Highlight a project, and click Next.

See Section 4.5.1, "Import a Legacy MIDP Project".

4.2.6 CDC Toolkit Project Location

To see this form, start the New Project wizard and select Import CDC Toolkit Project.

Project Location. Browse to select the location of your legacy CDC Toolkit project.

See Section 4.5.2, "Import a Legacy CDC Project".

4.2.7 Platform Selection Page (CLDC/MIDP)

You can view this form in the New Project wizard, or in the Projects view. Right-click a project, select Properties, and select Platform.

These settings help you test how your project runs on devices with different capabilities. Your choice of device limits your choice of Device Configuration, Device Profile, and Optional Packages (if applicable).

Emulator Platform. By default you will see two CLDC platforms - the 3.0 version installed with the Mobility pack and the 3.0.5 version installed with the Java ME SDK plugin. For the Java ME SDK plugin, choose the 3.0.5 version.

Device. Select a device. Only devices appropriate for the platform appear in the Device drop-down menu. The device selection determines the remaining options.

Device Configuration. Select a CLDC version.

Device Profile. Select a MIDP version. The available selections are determined by the Device Configuration.

Optional Packages. This pane is visible when you are viewing an existing project. You can check or uncheck optional packages to approximate device capabilities.

See Section 4.2.8, "Create a CLDC Project".

4.2.8 Create a CLDC Project

Select File > New Project.

The New Project wizard opens. Java ME SDK is the only category.
Follow the prompts in the New Project wizard, consulting Help if necessary.
To run the new project, follow the steps in Section 3.1, "Running a Project", except select your new project instead of a sample project.
Be sure to exit or close the application when you are finished.

Once the emulator is launched, it runs as an independent process. Pressing the red stop button in the SDK user interface or closing the SDK does not stop the application running in the emulator.

Applications usually provide a way to terminate. For example, most of the samples offer an Exit soft key, or an option in the soft menu. You can close the application and leave the emulator running (so you do not have to wait for the emulator to open the next time you run the project).

If you want to close the emulator and stop the project build process, select Application > Exit.

4.2.9 Create a CDC Project

The SDK provides a wizard for creating new projects quickly and easily. Most project properties can be edited later on. CDC core, FP, and PBP APIs are automatically included in every CDC project.

Select File > New Project.

The New Project wizard opens.
Follow the prompts in the New Project wizard, consulting help if necessary. See Section 4.2.4, "Platform Selection (CDC)", and Section 4.2.6, "CDC Toolkit Project Location".
The Name and Location page has the following fields:

Project Location. Browse to the project location. See the default locations in the table "File Locations".

Project Name. The name you supply is the default name for the Main class, if you use one.

Project Folder. This value is extrapolated from the Name and Location entries.

Set as Main Project. Check this box to set this project as main. Toolbar actions, such as Build and Run, operate on the main project. The main project is displayed in bold font in the project tree.

Create Main Class. If you want to create a sample Main class in the project, check the box and supply a project name. If the box is not checked, the project will not have a Main class.
Select platform.

Select the platform, a device, and the profile. Click Finish.

If an AGUI device is selected, the AGUI API is added to the project.

To run the new project follow the steps in Section 3.1, "Running a Project", except you can select your new project instead of a sample project.

When you are finished viewing the application, go to the emulator's Application menu and select Exit to close the emulator and stop the execution of the project's build script.

The SDK provides a wizard for creating new projects quickly and easily. Most project properties can be edited later on. CDC core, FP, and PBP APIs are automatically included in every CDC project.

Note:

Once the emulator is launched, it runs as an independent process. Pressing the red stop button in the Output window terminates the build script, but it does not close the emulator. Likewise, closing the SDK does not affect the emulator. In the emulator, select Application > Exit to ensure that both the emulator and the project build process close.

To modify the project, right-click on the project node and select Properties. For more information on project properties, see Chapter 5, "Viewing and Editing Project Properties".

4.3 Working With Projects

The logical view of the project, shown in the Projects window, provides a hierarchy of sources and resources. Right-click on the project node to see actions related to the project.

New. Opens a form to build a new object for the current project. The new object is placed in the project's file structure by default, but you can control the file name and location. The possible objects are dependent on the currently selected project. For example, if the project is CLDC, the options are MIDlet, Java class, Java package, or Java interface. Selecting New > Other allows you to add different types of files to the project. For a sample procedure, see Section 19.1, "Generating Stub Files from WSDL Descriptors".

Build. Builds a distribution Java archive (JAR) file. The build process is controlled by project properties, as described in Section 5.4, "Building a Project".

Clean & Build. Cleans, then builds a distribution JAR file.

Clean. Cleans the build files.

Generate Javadoc. See the online help topic Generating Javadoc Documentation.

Deploy. See the online help topic "Deploying Java ME Applications".

Batch Build..., Batch Clean & Build..., Batch Clean..., Batch Deploy... See the online help topic "About Java ME MIDP Projects".

Run. Runs the project with the default device, as specified on the Platform property page. See Section 5.2, "Platform Selection".

Run With... Run the selected project with a device you choose. This option can override the default device specified in the project properties.

Debug. See the online help topic "Debugging Tasks: Quick Reference".

Profile. Attach the profiler to the selected project. See Chapter 9, "Profiling Applications".

Set as Main Project. Make the current project the new main project. Toolbar actions, such as clicking the green Run button, act upon the main project by default.

Unset as Main Project. This option is visible if the selected project is already the main project.

Open Required Projects. Open any projects that the current project is dependent upon.

Close. Close the current project. Be sure that any processes are stopped, as closing a project might not stop the emulator.

The Source Packages node encapsulates all the Java packages in the project. Right-click on the Source Packages node and choose New to add a new MIDlet to your application.

The Resources node encapsulates all resources and libraries of the active configuration. Right-click the Resources node to add Projects, JARs, folders, and libraries as resources for your application. You cannot add or remove inherited resources.

4.4 View Project Files

The Files window displays a physical view of all project files. Right-click to view project properties or choose an action related to the project.

build. The output directory for the compiled classes listed below. This directory also contains manifest.mf, the manifest file that will be added to the JAR file.

compiled. Contains all compiled classes.
obfuscated. Holds the obfuscated versions of the class files.
preprocessed. Holds the source files after they are preprocessed. The files will differ from the original source files if you are using project configurations.
preverified. Holds the preverified versions of the class files. These files are packaged into your project's distribution JAR.
preverifysrc. Versions of the source files before they are preverified.

dist. The output directory of packaged build outputs (JAR files and JAD files). The dist directory also contains generated Javadoc documentation.

lib. Contains libraries you have added to the project. See Section 5.4.3, "Adding Libraries and Resources".

nbproject. The directory that contains the project Ant script and other metadata.This directory contains the following files:

build-impl.xml. The SDK-generated Ant script. Do not edit build-impl.xml directly. Always override its targets in build.xml.
private/private.properties. Properties that are defined for you alone. If you are sharing the project, any properties you define in this file are not checked in with other project metadata and are only applied to your SDK installation.
project.properties. Ant properties used to configure the Ant script. This file is automatically updated when you configure the project's properties. Manual editing is possible, but it is not recommended.
project.xml and genfiles.properties. Generated metadata files. It is possible to edit project.xml manually, but it is not recommended. Do not edit genfiles.properties.

res. Resource files you have added to the project. See Section 5.4.3, "Adding Libraries and Resources".

src. The project source files.

build.xml. The build script. This build script only contains an import statement that imports targets from nbproject/build-impl.xml. Use the build.xml to override targets from build-impl.xml or to create new targets.

4.5 Create a New MIDlet

To create a new MIDlet from the Files view, right-click a project and select New > MIDlet. With this form you can specify the name of the MIDlet and its location within the selected project.

MIDlet Name. The name of the new MIDP class.

MIDlet Class Name. The name that users see when the application runs on a device.

MIDlet Icon. The path to an icon associated with the MIDlet. Users see the icon when the application runs on a device.

Project. Displays the name of the project.

Package. Specifies the location of the MIDlet class. You can select an existing package from the drop down menu, or type in the name of a new package. The new package is created along with the class.

Created File. Displays the name and location of the MIDlet.

When the new MIDlet is created the SDK automatically adds it to the project's Application Descriptor File.

4.5.1 Import a Legacy MIDP Project

If you created a project using the Sun Java Wireless Toolkit for CLDC on Windows or Linux you can import your MIDlets into Java ME SDK projects. You can also use this procedure to create a project based upon a legacy sample project.

Select File > New Project.
In the Projects area, select Import Wireless Toolkit project. Click Next.
Specify the WTK project location.

Use browse to open the directory containing the legacy project.
Select a project and click Next.
Supply the Project Name, Location, and Folder for the new project.

Note that the default name, project name and folder name are based on the name of the project you are importing. Click Next.
Select the Platform type, the default device, and the configuration and profile, if applicable. Click Finish.

Your new project opens in the Projects window.
If the legacy project used signing, you must configure the signing properties as described in Section 12.4, "Managing Keystores and Key Pairs".

4.5.2 Import a Legacy CDC Project

If you created a project using the CDC Toolkit, you can import your applications into Java ME SDK projects. You can also use import to create a project based upon a sample project.

Note:

Standalone projects created in the CDC Toolkit can be imported. Xlets cannot be imported.

The CDC platform name for the Java ME SDK version 3.0.5 does not match the legacy platform name in the CDC Toolkit 1.0 and the CDC Mobility Pack. Consequently, you get a reference error when you import a legacy CDC project.

Note:

To avoid the reference error, create a platform with the legacy name, as described in Section 2.2.3, "Create a Platform for Legacy CDC Projects". You only need to do this once.

Select File > New Project.
In the Projects area select Import CDC Toolkit Project. Click Next.
Browse to select the project location.

The wizard detects any applications in the legacy installation and displays their locations on disk. Select a project and click Next.
Supply the Project Name, Location, and Folder for the new project. Note, the default name project name and folder name are based on the name of the project you are importing. Click Finish.

The imported project opens in the Projects window.

See also: Section 2.2.3, "Create a Platform for Legacy CDC Projects", Section 4.4, "View Project Files".

4.6 Add Files to a Project

For all projects, right-click to use the context menu to add files to a project. Using this method places files in the proper location in project source or resources.

To add a MIDlet, Java class, Java package, Java interface or Other files, right-click the project name or the Source Packages node, choose New, and select the file type.

To add files by format (Project, JAR, Folder, Library) right-click the Resources node and select a format. See Section 5.4.3, "Adding Libraries and Resources".

4.7 Search Project Files

To search a project's files, right-click on the project and select Find...

The Find in Files utility supports searching a project's file contents or file names. The search input fields supports simple text matching and regular expressions.

Containing Text. The string you are looking for. If File Name Patterns is empty, all files are searched.

File Name Patterns. The files you are searching in. If the Containing Text field is empty you get a listing of files that match the pattern.

The options Whole Words, Match Case, and Regular Expression further restrict the search. Regular Expression Constructs are fully explained in:

http://download.oracle.com/javase/6/docs/api/java/util/regex/Pattern.html#sum