Sun GlassFish Mobility Platform 1.1 Developer's Guide for Client Applications

Developing Client Applications for the BlackBerry Using NetBeans IDE

This guide cannot describe how to develop client applications for every possible device using every possible development tool. This section, however, describes how to develop a client application for one of the most commonly used devices, the BlackBerry, using one of the most commonly used development tools, NetBeans IDE. It contains the following sections:

Prerequisites

Before you can develop a client application for the Blackberry using NetBeans IDE, you must install the following software on a Microsoft Windows system:

The Java Development Kit (JDK), version 5 or 6. Set your JAVA_HOME and PATH environment variables to point to your installation of JDK 5 or JDK 6.
NetBeans IDE 6.5

Go to http://www.netbeans.org/, then download and install NetBeans IDE 6.5. BlackBerry client application development has been thoroughly tested only with this version of NetBeans IDE.

On the NetBeans download page, select Java as the bundle to download. This bundle includes Java SE, Web and Java EE, and Java ME. When you install NetBeans IDE, click Customize to install only some of the components. Deselect all of the listed runtimes, since you are using the Sun GlassFish Mobility Platform version of Sun GlassFish Enterprise Server.
BlackBerry Java Development Environment (BlackBerry JDE) v4.2.1

Go to http://na.blackberry.com/eng/developers/javaappdev/javadevenv.jsp, then download and install BlackBerry JDE v4.2.1. This is the only version that is compatible with current versions of NetBeans IDE. BlackBerry JDE runs only on Windows systems.
BlackBerry Email and MDS Services Simulator Package v4.1.4

Go to http://na.blackberry.com/eng/developers/browserdev/devtoolsdownloads.jsp, then download and install the BlackBerry Email and MDS Services Simulator Package v4.1.4.

Note –

You must have a BlackBerry Developer Community account in order to download the BlackBerry software. If you do not have an account, follow the instructions on the website to obtain one.

To Configure BlackBerry JDE v4.2.1

Click Start->All Programs->Research In Motion->BlackBerry JDE 4.2.1->JDE.

Click Edit->Preferences.

Click the Simulator tab and perform these steps:
1. Select the 8800-JDE Profile from the pull-down menu.
2. Select the Launch simulator checkbox.
3. Select the Launch Mobile Data Service (MDS) with Simulator checkbox.

Click the MDS Simulator Tab. Make sure that the MDS Simulator directory location is pointing to the v4.1.4 MDS directory you installed. For example:
```
C:\Program Files\Research In Motion\BlackBerry Email and MDS Services Simulators 4.1.4\MDS
```

Click OK.

You can leave the JDE running, because you may need it later on.

To Configure NetBeans IDE for BlackBerry Application Development

Start a text editor and copy the following text into an empty file.

Note –

If you installed BlackBerry JDE in a non-default location (for example, not on the C:\ drive), edit the contents of the home property setting for the platform element.

Make sure that the contents of the preverifycmd property setting for the platform element all appear on one line of the file. The contents are broken up here for readability only.

<?xml version='1.0'?>
<!DOCTYPE platform PUBLIC '-//NetBeans//DTD J2ME PlatformDefinition 1.0//EN' 
          'http://www.netbeans.org/dtds/j2me-platformdefinition-1_0.dtd'>
<platform name="BlackBerry_JDE_421" 
          home="C:\Program Files\Research In Motion\BlackBerry JDE 4.2.1" 
          type="CUSTOM" 
          displayname="BlackBerry JDE 421" 
          srcpath="" 
          docpath="${platform.home}/docs/api," 
          preverifycmd="&quot;{platformhome}{/}bin{/}preverify&quot; 
                        {classpath|-classpath &quot;{classpath}&quot;} 
                        -d &quot;{destdir}&quot; &quot;{srcdir}&quot;" 
          runcmd="cmd /C &quot;cd /D {platformhome}{/}simulator&amp;{device}&quot;" 
          debugcmd="cmd /C &quot;cd /D {platformhome}{/}bin&amp;jdwp&quot;">
    <device name="8800" description="8800">
        <optional name="JSR75" version="1.0" 
                  displayname="File Connection and PIM Optional Packages" 
                  classpath="${platform.home}/lib/net_rim_api.jar" 
                  dependencies="" default="true"/>
        <optional name="MMAPI" version="1.0" 
                  displayname="Mobile Media API" 
                  classpath="${platform.home}/lib/net_rim_api.jar" 
                  dependencies="" default="true"/>
        <configuration name="CLDC" version="1.1" 
                       displayname="Connected Limited Device Configuration" 
                       classpath="${platform.home}/lib/net_rim_api.jar" 
                       dependencies="" default="true"/>
        <optional name="OBEX" version="1.0" 
                  displayname="Object Exchange APIs" 
                  classpath="${platform.home}/lib/net_rim_api.jar" 
                  dependencies="" default="true"/>
        <optional name="JSR82" version="1.0" 
                  displayname="Java APIs for Bluetooth Wireless Technology" 
                  classpath="${platform.home}/lib/net_rim_api.jar" 
                  dependencies="" default="true"/>
        <optional name="WMA" version="1.1" 
                  displayname="Wireless Messaging API" 
                  classpath="${platform.home}/lib/net_rim_api.jar" 
                  dependencies="" default="true"/>
        <optional name="JSR179" version="1.0" 
                  displayname="Location Based APIs" 
                  classpath="${platform.home}/lib/net_rim_api.jar" 
                  dependencies="" default="true"/>
        <optional name="JSR177" version="1.0" 
                  displayname="Security and Trust Services APIs" 
                  classpath="${platform.home}/lib/net_rim_api.jar" 
                  dependencies="" default="true"/>
        <profile name="MIDP" version="2.0" 
                 displayname="Mobile Information Device Profile" 
                 classpath="${platform.home}/lib/net_rim_api.jar" 
                 dependencies="" default="true"/>
    </device>
</platform>

Save the file, giving it the name BlackBerry_JDE_421.xml.

Copy the file to the following location in your home directory under C:\Documents and Settings:
```
.netbeans\6.5\config\Services\Platforms\org-netbeans-api-java-Platform
```

If NetBeans IDE is running, stop it.

You will be prompted to start (or restart) NetBeans IDE in the next task, To Import the SecureMusicDB Sources into NetBeans IDE as a BlackBerry Project.

Next Steps

After you start NetBeans IDE, The Blackberry JDE will appear in the list of platforms when you choose Java Platforms from the Tools menu.

To Import the SecureMusicDB Sources into NetBeans IDE as a BlackBerry Project

To build and run a SecureMusicDB project for the BlackBerry from sources in NetBeans IDE, follow these steps.

To obtain the Sun GlassFish Mobility Platform client library bundle, go to the following URL: http://www.sun.com/software/products/mep/get.jsp.

Click Download, provide the requested information, then click Log In and Continue.

Download the sgmp-client-1_1_01-fcs-b02.zip bundle.

Unzip the bundle in a location of your choosing (for example, under C:\).

Unzip the source files for the SecureMusicDB project.
1. Navigate to the directory C:\sgmp-client-1_1_01-fcs-b02\samples\secure-musicdb\src\mcbo.
2. Extract the files from the securemusicdb-sources.jar file to the C:\sgmp-client-1_1_01-fcs-b02\samples\secure-musicdb\src\mcbo directory.
  
  You could use WinZip or the jar xvf command, for example, to extract the files.
3. Remove the META-INF directory and its contents (the file MANIFEST.MF).

Start NetBeans IDE.

The first time you start NetBeans IDE, you are prompted to install some updates. Install them.

In NetBeans IDE, follow these steps to create a Java ME Project and import the secure-musicdb sources.
1. From the File menu, select New Project.
  
  The Choose Project screen appears.
2. Click Java ME, then click Mobile Project with Existing MIDP Sources.
3. Click Next.
  
  The Specify MIDP Sources Screen appears.
4. In the Sources Location field, specify the location of the secure-musicdb sources you extracted. For example, if you unzipped the bundle to the C:\ directory, specify the following:
```
C:\sgmp-client-1_1_01-fcs-b02\samples\secure-musicdb\src\mcbo
```
  Leave the JAD/Manifest Location field empty.
5. Click Next.
  
  The Name and Location Screen appears.
6. Type a name for the Project or keep the default name.
7. Click Next.
  
  The Default Platform Selection Screen appears.
8. Set the Emulator Platform to “BlackBerry JDE 421” and verify that the Device is 8800.
9. Click Finish.
  
  The project appears in the Projects pane.

To specify the MIDlet and icon to be used, follow these steps.
1. Right-click the project and select Properties.
2. Click the Application Descriptor node.
3. Click the MIDlets tab.
4. If the SecureJdbcMIDlet appears, click Edit. If it does not, click Add.
  
  In the Add MIDlet dialog, the MIDlet name and class, SecureJdbcMIDlet and sample.SecureJdbcMIDlet, are already filled in.
5. For the MIDlet Icon, select /Clear_Note_32.png from the menu (it is the only choice). If no menu appears, type the value in the field.
6. Click OK, then click OK in the properties dialog.

To add the files mep_client_api.jar and jerseyme_api.jar to the supported Libraries & Resources, follow these steps.
1. Right-click the project and select Properties.
2. Click Libraries & Resources under Build.
3. Click Add Jar/Zip.
4. Browse to the lib\BlackBerry directory to add mep_client_api.jar.
  
  For example, if you unzipped the bundle to the C:\ directory, the file name would be C:\sgmp-client-1_1_01-fcs-b02\lib\BlackBerry\mep_client_api.jar.
5. From the same location, add jerseyme_api.jar.
6. Click OK.
7. Click the Files tab (next to the Projects tab) and open the project.properties file under the nbproject directory.
8. Edit the file.reference.mep_client_api.jar property to contain the fully qualified path name of the mep_client_api.jar file.
  
  For a BlackBerry project, the pathname must be absolute, not relative.
  
  For example, if you unzipped the bundle to the C:\ directory, edit the property definition to look like this:
```
file.reference.mep_client_api.jar=C:/sgmp-client-1_1_01-fcs-b02/lib/BlackBerry/mep_client_api.jar
```
  Use forward slashes (/) instead of the usual Windows file separator.
9. Edit the file.reference.jerseyme_api.jar property to contain the fully qualified path name of the jerseyme_api.jar file.
  
  For example, if you unzipped the bundle to the C:\ directory, edit the property definition to look like this:
```
file.reference.jerseyme_api.jar=C:/sgmp-client-1_1_01-fcs-b02/lib/BlackBerry/jerseyme_api.jar
```
10. Edit the file.reference.src-mcbo property to contain the fully qualified path name of the project sources.
  
  For example, if you unzipped the bundle to the C:\ directory, edit the property definition to look like this:
```
file.reference.src-mcbo=C:/sgmp-client-1_1_01-fcs-b02/samples/secure-musicdb/src/mcbo
```

Click the Files tab and open the project's build.xml file.

Add the following code fragment immediately before the </project> tag at the end of the file:

    <target name="do-preprocess">
        <fail unless="libs.ant-contrib.classpath">
     Classpath to Ant Contrib library (libs.ant-contrib.classpath property) is not set.
        </fail>
        <taskdef resource="net/sf/antcontrib/antlib.xml">
            <classpath>
                <pathelement path="${libs.ant-contrib.classpath}"/>
            </classpath>
        </taskdef>
        <available file="${platform.home}/bin/rapc.exe" property="do.rapc"/>
        <if>
            <isset property="do.rapc"/>
            <then>
                <property name="jpda.port" value="8000"/>
                <path id="antlib.classpath">
                    <fileset dir="${user.dir}/mobility8/modules/ext/" 
                             includes="ant-contrib-1.0b3.jar"/>
                </path>
                <mkdir dir="${dist.dir}"/>
                <path id="src-files">
                    <fileset dir="${src.dir}" includes="**/*.*"/>
                </path>
                <property name="srcs" value="${toString:src-files}"/>
                <for list="${srcs}" param="file" delimiter=";" trim="true">
                    <sequential>
                        <echo message="@{file}${line.separator}" 
                              file="${src.dir}/${name}_build.files" append="true"/>
                    </sequential>
                </for>
                <touch file="${dist.dir}/${dist.jar}"/>
                <nb-overrideproperty name="buildsystem.baton" 
                                     value="${preprocessed.dir}"/>
            </then>
            <else>
                <nb-overrideproperty name="buildsystem.baton" value="${src.dir}"/>
                <antcall target="${name}-impl.do-preprocess"/>
            </else>
        </if>
    </target>
    <target name="do-compile">
        <if>
            <isset property="do.rapc"/>
            <then>
                <antcall target="create-jad"/>
                <antcall target="update-jad"/>
                <copy file="${dist.dir}/${dist.jad}" toDir="${src.dir}"/>
                <exec dir="${src.dir}" 
                      executable="${platform.home}/bin/rapc.exe" failonerror="true">
                    <arg value="-quiet"/>
                    <arg value="import=${platform.bootclasspath};${libs.classpath}"/>
                    <arg value="codename=${name}"/>
                    <arg value="-midlet"/>
                    <arg value="jad=${dist.jad}"/>
                    <arg value="@${name}_build.files"/>
                </exec>
                <delete file="${basedir}/${src.dir}/${name}_build.files"/>
                <copy file="${name}.alx" todir="${dist.dir}"/>
                <nb-overrideproperty name="buildsystem.baton" 
                                     value="${build.classes.dir}"/>
            </then>
            <else>
                <nb-overrideproperty name="buildsystem.baton" 
                                     value="${preprocessed.dir}"/>
                <antcall target="${name}-impl.do-compile"/>
            </else>
        </if>
    </target>
    <target name="pre-obfuscate">
        <nb-overrideproperty name="buildsystem.baton" value="${build.classes.dir}"/>
    </target>
    <target name="post-jar" if="do.rapc">
        <move todir="${dist.dir}">
            <fileset dir="${src.dir}">
                <include name="**/${name}*.*"/>
            </fileset>
        </move>
        <copy todir="${platform.home}/simulator" verbose="true">
            <fileset dir="${dist.dir}">
                <include name="**/${name}*.*"/>
            </fileset>
        </copy>
    </target>
    <target name="post-clean">
        <delete failonerror="false" includeemptydirs="true">
            <fileset dir="${platform.home}/simulator">
                <include name="**/${name}*.*"/>
            </fileset>
            <fileset dir="${dist.dir}">
                <include name="**/*.*"/>
            </fileset>
            <fileset dir="${src.dir}">
                <include name="**/${name}*.*"/>
            </fileset>
        </delete>
    </target>

Create an .alx file for this project.

Click the Files tab.

Right-click your project and select New->Other.

In the Choose File Type screen, click Other, then click Empty File.

Click Next.

In the Name and Location screen, give the file the same name as your project, with the extension .alx.

For example, if bb-secure-musicdb is the project name, name the file bb-secure-musicdb.alx.

Click Finish.

The empty file opens.

Copy and paste the following text into the file, replacing myProject with your project name, and including any vendor and copyright information needed for your application.

<loader version="1.0">
    <application id="myProject">
        <name>
            myProject
        </name>
        <description/>
        <version>
            1.0
        </version>
        <vendor>
        </vendor>
        <copyright>
        </copyright>
        <fileset Java="1.3">
            <directory/>
            <files>
                myProject.cod
            </files>
        </fileset>
        <application id="mep_client_api">
            <name/>
            <description/>
            <version>
                1.0
            </version>
            <vendor>
                Sun Microsystems Inc.
            </vendor>
            <copyright>
                Copyright (c) 2009 Sun Microsystems Inc.
            </copyright>
            <fileset Java="1.3">
                <directory/>
                <files>
                    mep_client_api.cod
                </files>
                <files>
                    jerseyme_api.cod
                </files>
            </fileset>
        </application>
    </application>
</loader>

Save and close the file.

Copy the files mep_client_api.cod and jerseyme_api.cod from the directory C:\sgmp-client-1_1_01-fcs-b02\lib\BlackBerry to the simulator directory of the BlackBerry JDE (for example, C:\Program Files\Research In Motion\BlackBerry JDE 4.2.1\simulator).

Click the Projects tab, then right-click your secure-musicdb project and select Clean & Build.

If a message that begins error while reading original manifest appears, you can ignore it.

Right-click your secure-musicdb project and select Run.

The BlackBerry Device Simulator appears.

Note –
When you select Run, NetBeans IDE automatically loads the application on the Simulator using the .jad and .jar files (not the .cod file). If you want to load the application from the .cod file created, use the File->Load Java Program option in the Simulator.

Launch the SecureJdbcMIDlet application and perform a Sync.

The icon for the application is a musical note.

Note –
The MDS must be running for the client to perform syncs. If you started the JDE, MDS should get launched automatically. Otherwise, start MDS manually as follows: From the Windows Start menu, choose All Programs->Research in Motion->BlackBerry Email and MDS Services Simulators 4.1.4->MDS.

Next Steps

To remove the application from the Simulator, delete the .jad, .jar, and .cod files from the Simulator directory within the JDE and execute the three erase options in the JDE under File->Erase Simulator File.

To Create a New BlackBerry Project to Use the MCBO API

To create a new NetBeans IDE project that uses the MCBO API, follow these steps.

In NetBeans IDE, choose New Project from the File menu.

Choose Project Screen.

Click Java ME->MIDP Application.

Click Next.

In the Name and Location screen:
1. Type a name for the project or keep the default name.
2. Select Set as Main Project.
3. Select Create Hello MIDlet.
4. Click Next.

In the Default Platform Selection Screen:
1. Specify BlackBerryJDE421 as the Emulator Platform.
2. Specify 8800 as the Device.
3. Click Finish.

Add the mep_client_api.jar and jerseyme_api.jar files to your Libraries & Resources for this project in order to call and have access to the MCBO API.
1. If you have not done so before, go to http://www.sun.com/software/products/mep/get.jsp and download the sgmp-client-1_1_01-fcs-b02.zip bundle.
2. Unzip the sgmp-client-1_1_01-fcs-b02.zip bundle (for example, under C:\).
3. In NetBeans IDE, right-click the project and select Properties.
4. Click Libraries & Resources.
5. Click Add Jar/Zip.
6. Browse to the location of the unzipped bundle above the lib directory to add mep_client_api.jar.
  
  For example, if you unzipped the bundle to the C:\ directory, the file name would be C:\sgmp-client-1_1_01-fcs-b02\lib\BlackBerry\mep_client_api.jar.
7. From the same location, add jerseyme_api.jar.
8. Click OK.
9. Click the Files Tab (next to the Projects tab) and open the project.properties file under the nbproject directory.
10. Edit the file.reference.mep_client_api.jar property to contain the fully qualified path name of the mep_client_api.jar file.
  
  For a BlackBerry project, the pathname must be absolute, not relative.
  
  For example, if you unzipped the bundle to the C:\ directory, edit the property setting to look like this:
```
file.reference.mep_client_api.jar=C:/sgmp-client-1_1_01-fcs-b02/lib/BlackBerry/mep_client_api.jar
```
  Use forward slashes (/) instead of the usual Windows file separator.
11. Edit the file.reference.jerseyme_api.jar property to contain the fully qualified path name of the jerseyme_api.jar file.
  
  For example, if you unzipped the bundle to the C:\ directory, edit the property setting to look like this:
```
file.reference.jerseyme_api.jar=C:/sgmp-client-1_1_01-fcs-b02/lib/BlackBerry/jerseyme_api.jar
```
12. Click the Files Tab and open the project's build.xml file. Immediately before the </project>tag at the end of the file, add the same code fragment you added in Step 11 of To Import the SecureMusicDB Sources into NetBeans IDE as a BlackBerry Project.

Create an .alx file for this project:
1. Click the Files tab.
2. Right-click your project and select New->Other.
3. In the Choose File Type screen, click Other, then click Empty File.
4. Click Next.
5. Give the file the same name as your project name, with the .alx extension.
6. Click Finish.
7. Copy and paste into the file the content from Step g under Step 12 of To Import the SecureMusicDB Sources into NetBeans IDE as a BlackBerry Project, replacing myProject with your project name.
8. Save and close the file.

Copy the files mep_client_api.cod and jerseyme_api.cod from the directory C:\sgmp-client-1_1_01-fcs-b02\lib\BlackBerry to the simulator directory of the BlackBerry JDE (for example, C:\Program Files\Research In Motion\BlackBerry JDE 4.2.1\simulator).

Click the Projects tab, then right-click your project and select Clean & Build.

Right-click your project and select Run.

The BlackBerry Device Simulator appears.

Note –
When you select Run, NetBeans IDE automatically loads the application on the Simulator using the .jad and .jar files (not the .cod file). To load the application from the .cod file created, use the Load Java Program option in the Simulator.

Launch the MIDlet application.

Next Steps

At this point, you have a boilerplate application that says Hello World. You can now add code to implement and call the MCBO API classes and methods, and you can edit the MIDlet code to provide a user interface and to perform synchronizations.