Nokia 3510i User manual

Nokia 3510i MIDP SDK
User’s Guide
February, 2003

Nokia 3510i MIDP SDK User’s Guide
Copyright © Nokia 2002-2003. All rights reserved.
This document is for use with the Nokia 3510i MIDP SDK. Reproduction, transfer,
distribution or storage of part or all of the contents in this document in any form without the
prior written permission of Nokia is prohibited.
Nokia, Nokia 3510i, and the Nokia Connecting People logo are trademarks or registered
trademarks of Nokia Corporation. Other product and company names mentioned herein may
be trademarks or trade names of their respective owners.
Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun
Microsystems, Inc., in the United States and other countries.
Nokia operates a policy of on-going development. Nokia reserves the right to make changes
and improvements to any of the products described in this document without prior notice.
UNDER NO CIRCUMSTANCES SHALL NOKIA BE RESPONSIBLE FOR ANY LOSS OF
DATA OR INCOME OR ANY SPECIAL, INCIDENTAL, CONSEQUENTIAL OR
INDIRECT DAMAGES HOWSOEVER CAUSED.
THE CONTENTS OF THIS DOCUMENT ARE PROVIDED "AS IS". EXCEPT AS
REQUIRED BY APPLICABLE LAW, NO WARRANTIES OF ANY KIND, EITHER
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE, ARE MADE IN RELATION TO THE ACCURACY, RELIABILITY OR
CONTENTS OF THIS DOCUMENT. NOKIA RESERVES THE RIGHT TO REVISE THIS
DOCUMENT OR WITHDRAW IT AT ANY TIME WITHOUT PRIOR NOTICE.
The availability of particular phone products may vary by region. Please check with the Nokia
dealer nearest to you.
Visit Forum Nokia (http://www.forum.nokia.com), the site designed for developers using
technologies supported by Nokia.

1
Nokia 3510i MIDP SDK User’s Guide
Table of Contents
Nokia 3510i MIDP SDK
User’s Guide
Preface
Document Overview ............................................................................................... 3
Audience ................................................................................................................ 3
Typographical Conventions .................................................................................... 3
Other Product Documents ...................................................................................... 3
Related Forum Nokia Documents .......................................................................... 4
Forum Nokia Software ............................................................................................ 4
Introduction to Nokia 3510i MIDP SDK
What is the Nokia 3510i MIDP SDK? ..................................................................... 5
Using the SDK as a Standalone Product ............................................................... 6
Using the Nokia 3510i MIDP SDK Within an IDE ................................................... 6
Overview of MIDlet Development Using the SDK .................................................. 6
Methods for Running MIDlets................................................................................ 6
Running MIDlets Immediately ............................................................................... 7
Running MIDlets Through MIDlet Provisioning ..................................................... 8
Provisioning Using Local Files........................................................................... 8
Provisioning Using the Network......................................................................... 8
Provisioning Process ......................................................................................... 9
Technical Specifications for the Nokia 3510i Handset ........................................... 9
Screen Attributes, Colors, Soft Keys................................................................... 10
Available Memory................................................................................................ 10
Java APIs Supported .......................................................................................... 10
Character Set Support ........................................................................................ 10
Configuring Nokia 3510i MIDP SDK With IDEs
Configuring JBuilder to Recognize Nokia 3510i MIDP SDK ................................. 11
Configuring Nokia 3510i MIDP SDK for A JBuilder Project................................. 12
Configuring JBuilder to the SDK With J2ME Wireless Toolkit............................. 14
Configuring the SDK With NDS for J2ME 1.0 Through JBuilder......................... 15
Configuring the SDK With NDS for J2ME 1.1 Through JBuilder......................... 18
Configuring Nokia 3510i MIDP SDK with Sun One Studio ................................... 20
Using Nokia 3510i MIDP SDK With JBuilder ........................................................ 22
Creating a MIDlet and Running It on Nokia 3510i MIDP SDK ............................ 22
Running a MIDlet and Displaying Trace Information........................................... 23
Understanding Nokia 3510i MIDP SDK Life Cycle.............................................. 23
Using Nokia 3510i MIDP SDK
Menu Commands ................................................................................................. 25
File Menu ............................................................................................................ 25
Tools Menu ......................................................................................................... 26
Help Menu........................................................................................................... 28

Nokia 3510i MIDP SDK User’s Guide
Phone Menus ...................................................................................................... 29
Running the SDK Through a Command Line Interface ........................................ 29
Command Line Syntax........................................................................................ 29
About Options ..................................................................................................... 30
Options for Starting the SDK............................................................................... 30
Options for Managing SDK Instances ................................................................. 32
About Parameters ............................................................................................... 33
Working With a CLI Shell .................................................................................... 33
Keyboard Shortcuts .............................................................................................. 34
QWERTY Text Input ............................................................................................. 35

Nokia 3510i MIDP SDK User’s Guide
3
Preface
Document Overview
This manual describes how to use the Nokia 3510i MIDP SDK. The Nokia 3510i MIDP SDK is a
phone simulation software that simulates those features of a Nokia 3510i mobile handset that are
related to the running of Java applications (MIDlets).
Audience
The Nokia 3510i MIDP SDK is designed to accommodate the needs of MIDlet developers
wishing to test their MIDlet on a simulation of the Nokia 3510i phone handset.
Typographical Conventions
The following typographical conventions are used in this guide:
Other Product Documents
These documents are included when you install the product and are located in the same directory
as the SDK executable. You can also download the documents from www.forum.nokia.com.
•Nokia 3510i MIDP SDK, Installation Guide
•Nokia 3510i MIDP SDK, Release Notes
Notation Explanation
Courier
•Text that you enter (as opposed to system prompts and responses)
•File paths
•Commands
•Program code
Italic •Names of books and documents
•New terminology
Bold Names of Windows menus, commands, buttons, and icons
URL link Active link to an external URL.

4Preface
Nokia 3510i MIDP SDK User’s Guide
Related Forum Nokia Documents
The following documents, in addition to many others, are created and maintained by Forum
Nokia. They are freely available at http://www.forum.nokia.com/.
•How to Write a Mobile Java Program and Run it in a Nokia Phone
•Nokia Developer’s Suite for the Java 2 Platform, Micro Edition: User’s Guide and
Installation Guide
•Settings for OTA Download of MIDlets
•Characteristics of Nokia Java-Enabled Phones
•A Brief Introduction to MIDP Programming
Forum Nokia Software
•Nokia Developer’s Suite for the Java 2 Platform, Micro Edition
•MIDP Example Applications

Nokia 3510i MIDP SDK User’s Guide
5
Introduction to Nokia 3510i MIDP SDK
This chapter describes how to use the SDK as a standalone product and within an IDE, an
overview of MIDlet development within an IDE, and the technical specification of the 3510i
handset that correlates to the SDK.
What is the Nokia 3510i MIDP SDK?
Nokia 3510i MIDP SDK is a simulation of a real Nokia 3510i phone handset and is based on a
close copy of the actual phone software. The SDK consists of a menu bar, a phone image whose
keys map to functions in the phone software identical to the functions available in the actual
phone handset, and a Command Line Interface (CLI) through which the SDK can be started.
The SDK can be used by itself as a standalone to run Java mobile applications (MIDlets) or can be
used with supported Integrated Development Environments (IDEs).
This figure shows the Nokia 3510i MIDP SDK GUI:
Display (x,y pixels)
End call
Start call
Up and Down keys
for menus in display
Left soft key:
Activation key for
menu on left (in this
example, Menu)
Right soft key: Activation
key for menu on right (in
this example, Names)
Instance number

6 Introduction to Nokia 3510i MIDP SDK
Nokia 3510i MIDP SDK User’s Guide
Using the SDK as a Standalone Product
Before you launch the SDK, make sure your .jad and .jar files are located in the same
directory.
Launch the SDK standalone in either of these ways:
•From the Windows GUI, using standard Windows commands such as Start>Programs.
Once the SDK has started, you can run a MIDlet by using the SDK’s File>Open command
and then navigating to the location of the
.jad file for the MIDlet you want to run.
•From the Windows Command Prompt. Enter the full path to the SDK executable file. For
example, the following command launches the SDK and runs the BlockGame MIDlet:
c:\\<install-directory>\bin\3510i.exe c:\midlet\BlockGame.jad
Using the Nokia 3510i MIDP SDK Within an IDE
You’ll need to configure your IDE to recognize the SDK as a supported device before you can
launch the SDK from within the IDE interface. The method used for launching the SDK varies
on the IDE. This document does not describe integration with all IDEs, but the next chapter,
"Configuring Nokia 3510i MIDP SDK With IDEs", provides useful information about
configuring some IDEs to use the SDK.
Overview of MIDlet Development Using the SDK
This document assumes that end-users, the target audience for the MIDlet application
developer, will use their 3510i handsets in the following ways:
•To run applications and play games that are already loaded on their 3510i handset.
•To browse to Internet sites from which they may download games and other applications.
(The term MIDlet provisioning, also called Over the Air (OTA) Provisioning,is used to
describe the process by which you make a MIDlet accessible for downloading over the
network.)
Methods for Running MIDlets
You, the MIDlet developer, will want to test your MIDlet directly on the SDK from within
your chosen IDE (by choosing a Run button or some such equivalent command within the
IDE application). This you would do as part of the edit/compile/run phase of the development
process. This immediate running or direct invocation of a MIDlet is supported by the SDK. So,
you can edit program code, compile it, and then display it on the SDK.
Once you are satisfied that your MIDlet works as desired, you may wish to test how the end-
user would experience the downloading of your MIDlet if you planned to make it available via
MIDlet provisioning. the SDK enables you to do this in two ways:
•You can emulate provisioning using files on your local drive by starting the SDK from the
command line while specifying the
-provisioning option. For this, no WAP gateway is
required.

Overview of MIDlet Development Using the SDK 7
Nokia 3510i MIDP SDK User’s Guide
•If you have access to a WAP gateway or to a server simulator, you might post your MIDlet
on an Internet server and then use the SDK’s browser to navigate to it.
The following sections describe some differences between the immediate running of a MIDlet
versus the MIDlet provisioning of a MIDlet.
Running MIDlets Immediately
The procedures for configuring the SDK to run MIDlets standalone or from within your
chosen IDE are given in the chapter Installation and Configuration With IDEs. After proper
configuration, you can load and run your MIDlet as part of the normal edit/compile/run
development process.
The SDK provides the run immediately feature to facilitate the MIDlet development and
testing process. To accomplish this, small sacrifices are made in fidelity to the way in which
Nokia 3510i handset runs MIDlets. The MIDlet provisioning method of running MIDlets more
closely resembles the way in which MIDlets run in the Nokia 3510i handset.
When running a MIDlet immediately, in contrast to running a MIDlet through MIDlet
provisioning, note these differences:
•In immediate running, the .
jad /. jar validation process is skipped. This process involves
the checking for consistency between .
jad , . jar , and .jar manifest files with respect to
various attributes, including
MIDlet-jar-size . This validation process is enforced when a
MIDlet is loaded using MIDlet provisioning.
•In immediate running, the MIDlet is not installed in the SDK’s Game or Application
folders. In MIDlet provisioning, the MIDlet is installed in the appropriate folder.
•In immediate running, only one MIDlet at a time may be loaded and run. In MIDlet
provisioning, several MIDlets may be installed at once.
•In immediate running, the maximum size of a
jad or jar file that can be loaded is 300 KB;
larger sizes are discarded with warning messages. In MIDlet provisioning, as with the
Nokia 3510i handset itself, the maximum sizes are:
jad file, 5 KB, and jar file, 63.7 KB.
•In immediate running, record stores (a collection of records which persist across multiple
invocations of the MIDlet) are stored persistently on the hard drive. Thus, even after
closing the SDK, record stores associated with previously run MIDlets will be available
once again after the MIDlet is run immediately on a subsequent invocation of the SDK.
In MIDlet provisioning, record stores are not persistent, not stored on the hard drive, and
are never available again after the SDK closes. This behavior is necessary to enforce a
closer parallel between the behavior of the SDK in MIDlet provisioning and the behavior
of the 3510i Nokia handset: that is, installed MIDlets are removed between invocations of
the SDK and so therefore must their associated records be removed.
In sum, for the MIDlet developer, the running MIDlet immediately method provides a faster,
less strict environment in which to test MIDlets in the early developmental stages. In contrast,
the MIDlet provisioning method is more constraining but truer to the Nokia 3510i handset
running environment.

8 Introduction to Nokia 3510i MIDP SDK
Nokia 3510i MIDP SDK User’s Guide
Running MIDlets Through MIDlet Provisioning
MIDlet provisioning, or Over-the-Air (OTA) Provisioning, is a mechanism for making a
MIDlet on an Internet server available for downloading to a mobile phone.
Provisioning Using Local Files
True MIDlet provisioning requires an Internet connection through a WAP gateway to a URL
target that is a
jad file. However, you can simulate this provisioning process by starting the
SDK from the command line without a WAP gateway connection and with a MIDlet residing
on a local drive, as described below.
For MIDlet provisioning, network connections must always occur through a WAP gateway
both in the SDK and in the 3510i mobile handset. (For this reason, MIDlet provisioning is
available only for WAP-enabled mobile phones.)
If you have a WAP gateway, you can a make a WAP connection to a WAP gateway or server
simulator in order to load a MIDlet. (Nokia Mobile Internet Toolkit (NMIT) includes a WAP
server simulator; NMIT is freely available for downloading from Forum Nokia.)
You can test MIDlet provisioning using the SDK, as follows:
1Configure the SDK to use a WAP gateway (Tools>Settings>WAP networking).
2Using the SDK’s browser, navigate to the URL of the site hosting the MIDlet and request it
be downloaded. The Internet server sends a
jad file to the mobile phone.
Provisioning Using the Network
For MIDlet provisioning, network connections must always occur through a WAP gateway
both in the SDK and in the 3510i mobile handset. (For this reason, MIDlet provisioning is
available only for WAP-enabled mobile phones.) Therefore, to provision a MIDlet using the
network, do the following:
1Configure the SDK to use a WAP gateway.
1From the command line, enter a command similar to the
following:
3510i.exe -provisioning blockgame.jad
The SDK starts and displays the information about the MIDlet
which is contained in the
jad file.
2Press the button labeled Dnload to download the jar file.
The SDK downloads the
jar file, reports that it has been saved
to the Games folder, and then queries whether you wish to
open the MIDlet now.
Choosing Ye s causes the SDK to load and run the MIDlet;
choosing No does not. In either case, the MIDlet is available in
either the Applications or Games folder until the SDK is
closed; installed MIDlets are not persistent between instances
of the SDK.

Technical Specifications for the Nokia 3510i Handset 9
Nokia 3510i MIDP SDK User’s Guide
2Using the SDK’s browser, navigate to the URL of the site hosting the MIDlet and request it
be downloaded. The Internet server sends a
jad file to the mobile phone.
You must configure a WAP connection to a WAP gateway or to a server simulator in order to
load a MIDlet. (Nokia Mobile Internet Toolkit (NMIT) includes a WAP server simulator and is
freely available for downloading from Forum Nokia.
To configure a WAP connection, you must either (1) start the SDK using the
- wap gateway
option to specify a WAP gateway address or (2) specify the address on the WAP networking
tab page (Tools>Settings>WAP networking).
Provisioning Process
After configuring the WAP connection to the SDK, you may provision the MIDlet in an
identical manner to that used on the 3510i mobile handset. The following steps describe the
provisioning process:
1Using the mobile handset browser, the user navigates to the URL of the site hosting the
MIDlet and requests it be downloaded. The Internet server sends a
jad file to the mobile
phone. The following is an example of the contents of such a
jad file:
MIDlet-Name: BlockGame
MIDlet-Vendor: Forum Nokia
MIDlet-Version: 1.0
MIDlet-Jar-Size: 25978
MIDlet-Jar-URL: http://domain/directory/BlockGame.jar
Nokia-MIDlet-Category: Game
MIDlet-1: MIDletName, MIDletIcon, MIDletMainClassName
2The Java Application Manager (JAM) running on the mobile handset determines whether
the MIDlet can be run on the handset, and if so, requests that the Internet server send the
jar file.
3JAM next displays a message on the handset requesting permission to install the MIDlet.
4When the user chooses to install the MIDlet, the JAM in the handset then installs it to the
Applications or Games folder. Note that the MIDlet is installed to the Games folder only
if the
jad file specifies the string Nokia-MIDlet-Category: Games , as our example
Blockgame.jad file does; otherwise, all MIDlets are installed to the Applications folder.
JAM may optionally forward a notification to the Internet server that the MIDlet has been
downloaded (usually done for billing or customer care purposes.
See the document titled Settings for OTA Download of MIDlets at Forum Nokia for additional
details regarding MIDlet provisioning.
Technical Specifications for the Nokia 3510i Handset
Most of the information provided in this section was excerpted from the document titled
Characteristics of Nokia Java-Enabled Phones, available at Forum Nokia. Refer to this
document for a complete list of the technical specifications for the Nokia 3510i handset.

10 Introduction to Nokia 3510i MIDP SDK
Nokia 3510i MIDP SDK User’s Guide
Screen Attributes, Colors, Soft Keys
•Java canvas full screen layout: 96x65 pixels
•Java MIDP canvas layout: 96x54 pixels
(Left and right soft key zones occupy 11 vertical pixels.)
•Colors: 4096
•Image formats: PNG
Available Memory
Java APIs Supported
•CLDC 1.0
•MIDP 1.0
•Nokia UI API
Character Set Support
•ISO-8859-1
•UTF-8
•ISO-10646-UCS-2
Character encodings supported are fixed and cannot be changed.
•Heap memory size Can be set from 0 to ~1 MB in the SDK; default value is ~200
KB (same as the Nokia 3510i handset)
•OTA download limit ~64 KB

Nokia 3510i MIDP SDK User’s Guide
11
Configuring Nokia 3510i MIDP SDK With IDEs
This chapter describes how to configure the SDK so you can use it with your IDE.
You’ll need to configure your IDE to recognize the SDK as a supported device before you can
launch the SDK from within the IDE interface. The method used for launching the SDK varies on
the IDE, and it is beyond the scope of this document to describe integration with all IDEs.
Configuring JBuilder to Recognize Nokia 3510i MIDP SDK
Before you begin to configure JBuilder to recognize the SDK, make sure you have installed
JBuilder, MobileSet, and the SDK as described in Nokia 3510i MIDP SDK Installation Guide.
To configure JBuilder to recognize the SDK:
1In JBuilder, choose Tools>Configure JDKs. A dialog such as the following is displayed:

12 Configuring Nokia 3510i MIDP SDK With IDEs
Nokia 3510i MIDP SDK User’s Guide
2Click New to display the New JDK Wizard shown below.
Enter the following information:
•In the first text-entry field, set the JDK home path to the SDK’s installation directory.
Use the adjacent button at the right to navigate to this directory.
•In the Name for this JDK field, enter a name by which you wish JBuilder to refer to
the SDK. This name is a matter of your personal preference.
•Click OK.
3After clicking OK, you will now see in the Configure JDK dialog (below) that the SDK
has been added to JBuilder’s JDK list. Note that you can also specify which JDK is used by
the SDK by entering the desired JDK version in the Emulator JDK text box.
Configuring Nokia 3510i MIDP SDK for A JBuilder Project
After configuring JBuilder to recognize the SDK as an installed JDK, as described in the
previous section, you must instruct JBuilder to use the SDK as the target JDK for the particular
project you are working on. Use the following procedure to do this:

Configuring JBuilder to Recognize Nokia 3510i MIDP SDK 13
Nokia 3510i MIDP SDK User’s Guide
1In JBuilder, choose the project and display its project properties (for example, by right-
clicking the project name). The project properties dialog is displayed as shown below.
On the Paths tab of the Properties dialog, in the JDK field, select the SDK from the list of
installed JDKs, using the navigation button to the right.
2On the Run tab of the Properties dialog (shown below), click New or Edit.

14 Configuring Nokia 3510i MIDP SDK With IDEs
Nokia 3510i MIDP SDK User’s Guide
3In Runtime Properties (shown below), configure the runtime parameters to be used when
your MIDlet starts on the SDK:.
•Ensure that the SDK is selected in the Emulator Device drop-down list.
•Enter a runtime parameters in the Emulator parameters text-entry box. See the
section titled "About Parameters" for a description of all available the SDK command
parameters.
4In Runtime Properties, do one of the following:
•Click Main class and then click the adjacent button to display the Choose Main class
to run dialog box. In this dialog box, navigate to the location of the files of your main
class. Click OK.
•Click JAD file and then click the adjacent button to display the Choose JAD file to
run dialog box. In this dialog box, navigate to the location of the JAD file for your
MIDlet. Click OK.
5In JBuilder, click Run project (or press F9) to run the project. You will see the MIDlet
execute in the SDK.
Configuring JBuilder to the SDK With J2ME Wireless Toolkit
J2ME Wireless Toolkit Version (J2MEWTK) is automatically installed when you install
MobileSet. Some MIDlet developers may wish to configure the SDK with J2MEWTK in order
to have the SDK appear in J2MEWTK’s list of supplied emulators.
The easiest way to configure the SDK for this purpose is to install the SDK in the following
directory:
<JBuilder-install-directory>\J2mewtk\wtklib\devices

Configuring JBuilder to Recognize Nokia 3510i MIDP SDK 15
Nokia 3510i MIDP SDK User’s Guide
If you have already installed the SDK but did not install it in the above directory, you can copy
the entire the SDK directory structure to this directory.
To make the SDK the active device emulator within J2MEWTK:
1Choose Tools>Configure JDKs. Select the J2ME Wireless Toolkit 1.04_01 JDK in the left
panel. Click the Micro tab in the right panel, as shown below:
2The SDK should appear as an option in the Target Device drop-down list, as shown below:
3Select the SDK from the drop-down list to make it the active emulator
Configuring the SDK With NDS for J2ME 1.0 Through JBuilder
To configure the SDK With NDS for J2ME 1.0 Through JBuilder:
1When you install NDS v1.0 for J2ME, choose the Integrated with Borland Jbuilder
option at the beginning of the installation program.

16 Configuring Nokia 3510i MIDP SDK With IDEs
Nokia 3510i MIDP SDK User’s Guide
2Still within the NDS installation program, enter the directory into which you want NDS to
be installed. As shown below, it is recommended to specify JBuilder’s root directory:
3After completing the NDS installation, start JBuilder. In JBuilder’s Tools menu, you should
now see a new Nokia Developer’s Suite for J2ME menu item, as shown below:

Configuring JBuilder to Recognize Nokia 3510i MIDP SDK 17
Nokia 3510i MIDP SDK User’s Guide
4In JBuilder, choose Tools>Nokia Developer’s Suite for J2ME>Configure Emulators.
The following dialog is displayed:
5Click New in the dialog above, and then in the Select emulator’s configuration file dialog
box (shown below), navigate to the SDK’s configuration file (Nokia 3510i MIDP
SDK.xml), which is an
.xml file in the root directory of the SDK. Then click Select.
6Returning to JBuilder’s Configure Emulators dialog (shown in step 4), you now see that
the SDK is displayed in the Emulator list. Be sure to check the Launch check box at the
top right of the dialog window.
If you already have a project file with a
jad and jar file, then to run the MIDlet, select the
.jad file in the JBuilder Project Explorer and then in JBuilder choose
Tools>Nokia Developer’s Suite for J2ME>Start Emulators. The
jad file runs on the
SDK.
If you do not have a project file, you can use NDS to create one by selecting
Tools>NDS>Create Application Package. (See the NDS User’s Guide for more details.)
After configuring the SDK for use with JBuilder and NDS for J2ME as described above, the
general usage procedure is as follows:
1In JBuilder, create a new project or open an existing project, and then compile the Java
files.

18 Configuring Nokia 3510i MIDP SDK With IDEs
Nokia 3510i MIDP SDK User’s Guide
2In JBuilder, choose
Tools>Nokia Developer’s Suite for J2ME>Create Application Package. The NDS
Create Application Package dialog is displayed. Enter the necessary information (see the
NDS for J2ME User’s Guide) and click Finish. You now have a
jad and jar file.
3Select the
jad file, and then choose Tools>Start Emulators. The MIDlet is loaded in the
selected simulator.
Configuring the SDK With NDS for J2ME 1.1 Through JBuilder
To configure the SDK With NDS for J2ME 1.1 Through JBuilder:
1When you install NDS 1.1 for J2ME, choose the Integrated with Borland Jbuilder option
at the beginning of the installation program.
2Still within the NDS installation program, enter the directory into which you want NDS to
be installed. As shown below, it is recommended to specify JBuilder’s root directory: