GETTING STARTED WITH JAVA ON THE NOKIA 9200 SERIES COMMUNICATORS Version 1.0 5 March 2002
GETTING STARTED WITH JAVA ON THE NOKIA 9200 SERIES COMMUNICATORS Version 1.0
Table of Contents
INTRODUCTION ...... 4
1. JAVA CAPABILITIES OF NOKIA 9200 SERIES COMMUNICATORS...... 4
2. GETTING STARTED...... 5
2.1. NOKIA 9200 SERIES COMMUNICATORS SDK FOR SYMBIAN OS...... 5 2.2. PC RUNNING MICROSOFT WINDOWS...... 6 2.3. JDK 1.1.8 ...... 6 2.4. GSM PHONE WITH INFRARED MODEM...... 6 3. USING AN IDE ...... 6
4. DEVELOPING A SIMPLE APPLICATION ...... 7
4.1. RUNNING THE APPLICATION ON THE EMULATOR...... 7 4.2. PORTING THE APPLICATION TO THE NOKIA 9200 SERIES COMMUNICATOR ...... 7 5. SKILLS TO LEARN ...... 8
5.1. EMULATOR’S VIRTUAL PATH SYSTEM AND CLASSPATH CONVENTIONS...... 8 5.2. EXECUTABLES TO LAUNCH THE EMULATOR...... 8 5.3. CUSTOM API FOR CBA BUTTONS...... 9 5.4. JAVAPHONE API ...... 12 5.5. PACKAGING APPLICATIONS FOR GENERAL RELEASE...... 13 6. HINTS AND TIPS...... 14
7. DEVELOPING FOR PHONES OTHER THAN THE NOKIA 9200 SERIES COMMUNICATORS ...... 18
8. GETTING HELP...... 18
8.1. FORUM NOKIA...... 18 8.2. SYMBIAN DEVELOPER NETWORK ...... 18 9. OTHER AVAILABLE LITERATURE ...... 18
9.1. FORUM NOKIA...... 18 9.2. SYMBIAN DEVELOPER NETWORK ...... 19 9.3. WIRELESS JAVA FOR SYMBIAN DEVICES...... 19
Copyright © 2002. Nokia Mobile phones. All rights reserved. 2
GETTING STARTED WITH JAVA ON THE NOKIA 9200 SERIES COMMUNICATORS Version 1.0
Disclaimer: Nokia Corporation disclaims all liability, including liability for infringement of any proprietary rights, relating to the implementation of information presented in this document. Nokia Corporation does not warrant or represent that such use will not infringe such rights.
Nokia Corporation retains the right to make changes to this specification at any time without notice.
License: A license is hereby granted to download and print a copy of this specification for personal use only. No other license to any other intellectual property rights is granted herein.
Copyright © 2002. Nokia Mobile phones. All rights reserved. 3
GETTING STARTED WITH JAVA ON THE NOKIA 9200 SERIES COMMUNICATORS Version 1.0
Symbian developer paper
Getting Started with Java on the Nokia 9200 Series Communicator
Authors: Martin de Jode, Developer Consultant Colin Turfus, Manager, Symbian Developer Network
Revision: 1.0, March 2002
INTRODUCTION
The following pages offer an introduction to creating Java applications for Nokia 9200 Series Communicators, including the Nokia 9210 Communicator in Europe and (soon) the Nokia 9290 Communicator in the Americas. These devices are based on the Symbian OS, an open, robust operating system designed specifically for use in data-enabled mobile devices.
With full native Java support, there is no need to learn a new language to develop applications for Symbian OS – Java developers are immediately productive, thanks to their existing skills and experience. Java is expected to become the preferred language for developing third-party applications and services on Symbian OS. It provides a powerful programming environment, and key Symbian OS technologies, such as telephony, contacts management, calendaring, datagram messaging, and IR comms are exposed through the JavaPhone APIs. Furthermore, Java applications can have the look and feel of Symbian OS devices.
This paper assumes that the reader has no prior specific knowledge of Symbian OS, but it does presume familiarity with Java and the Nokia 9200 Series Communicators SDK for Symbian OS (Java edition). The SDK, which can be requested on the Forum Nokia developer web site (http://www.forum.nokia.com/), is essential for developing, testing, and debugging Java applications. It provides documentation, tools and sample code to assist developers, along with a Microsoft Windows hosted emulator of the Nokia 9200 Series Communicators.
Below you will find a brief overview of the main components that work to make an application suitable for use on the Nokia 9200 Series Communicators. We will outline in detail the code for a basic example application and the key concepts. Minimal treatment is given to the Symbian OS tool chain or the development environment used to create applications, as more comprehensive system documentation is provided with the SDK.
1. JAVA CAPABILITIES OF NOKIA 9200 SERIES COMMUNICATORS
The Java functionality available in Nokia 9200 Series Communicators is similar to, and indeed exceeds in a number of areas, that which is typically available in a desktop environment. Furthermore, it rivals the capabilities available to native C++ application developers, while the support available for Java Native Interface programming reduces this gap still further.
The Java environment on Nokia 9200 Series Communicators devices is based on the PersonalJava Application Environment, implementing Sun’s version 1.1.1 specification based on its 3.0.1 reference implementation and legacy code from Symbian’s Version 5 Java Runtime. PersonalJava (or pJava) is similar to Standard Java as embodied in JDK 1.1 (see http://java.sun.com/products/personaljava/index.html). The main difference is that Copyright © 2002. Nokia Mobile phones. All rights reserved. 4
GETTING STARTED WITH JAVA ON THE NOKIA 9200 SERIES COMMUNICATORS Version 1.0
certain functional components – packages, classes or methods – that are obligatory in Standard Java, are optional inPersonalJava, reducing the minimum ROM budget for handheld devices like PDAs and mobile phones. Symbian’s PersonalJava implementation also adds some functionality, such as timers. However, Symbian has opted for a fairly complete PersonalJava API set, implementing virtually all optional components including RMI and JDBC support.
Over and above the standard Java functionality, Symbian OS also provides an implementation of the JavaPhone 1.0 API that gives Java programs access to a selection of invaluable native services on the device. These include the following:
Java Telephony API – Allows Java programs to: • Create and terminate calls • Listen for and answer incoming calls • Detect changes in call state Calendar and address book API – Allows Java programs to: • Read, write, and modify contact details, calendar items and to-do items • Work transparently with data in native Symbian format • Search across all entries in calendar or address book P2P wireless datagram API – Allows Java programs to: • Exchange datagrams with other devices via UDP or SMS • Keep a specified port open for incoming datagrams javax.comm – Allows Java programs to: • Discover and configure available ports (serial and infrared) • Send and receive data • Listen for events on monitored ports
Forum Nokia is also making available a beta release of the J2ME Mobile Information Device Profile (MIDP) runtime environment for Nokia 9200 Series Communicators. This can be downloaded for free at www.forum.nokia.com. Check the Forum Nokia web site for further news.
2. GETTING STARTED
2.1. Nokia 9200 Series Communicators SDK for Symbian OS
The Nokia 9200 Series SDK for Symbian OS (Java edition) can be ordered from the Forum Nokia web site at www.forum.nokia.com. You will need to install this on your PC in order to develop Java applications for the Nokia 9200 Series Communicator. The Nokia 9200 Series Communicators SDK for Symbian OS installation provides the following: • Emulator • PersonalJava Application Environment • Classes.zip archive providing the necessary Java classes customized for the Nokia 9200 Series • JavaPhone.jar archive • Useful utilities • Tools required to package an application • JRE 1.2.2. (required by the tools) • Full documentation
Copyright © 2002. Nokia Mobile phones. All rights reserved. 5
GETTING STARTED WITH JAVA ON THE NOKIA 9200 SERIES COMMUNICATORS Version 1.0
2.2. PC Running Microsoft Windows
The emulator is designed to run on a PC with Windows NT4.0 or Windows 98. Although it should run successfully on other Windows platforms such as Windows ME and Windows 2000, these configurations have not been fully tested. The Java installation will require approximately 200 MB of free hard disk space.
2.3. JDK 1.1.8
To compile your Java source code, you will need to install a copy of Sun’s Java Development Kit (JDK). The recommended version is the JDK 1.1.8, since the PersonalJava Application Environment implemented on the Nokia 9200 Series is close to a full implementation of the JDK 1.1.8 specification. The JDK 1.1.8 for Microsoft Windows is available for download from Sun’s web site at
http://java.sun.com/products/jdk/1.1/download-jdk-windows.html
It is possible to use one of Sun’s Java 2 SDKs (v1.2.2 or v1.3), but see the notes in Section 6 below.
2.4. GSM Phone with Infrared Modem
An optional requirement is a GSM phone with infrared modem for testing the telephony and communication features offered in the JavaPhone API. This modem can communicate with the emulator via a Jet Eye infrared pod, which plugs into the serial port of the PC. Some infrared-enabled phones (such as the Ericsson R320) have a serial link, which plugs directly into the serial port, avoiding the need for an infrared pod.
If you want to use the PC’s serial port to drive the infrared link to a mobile phone, make sure nothing else is using the port (such as the Symbian OS connectivity software). Using the infrared port emulation may require modifications to a file called irda_wins.esk. This can be found in
[tinytp] filename= irda.prt index= 2 irPod= jeteye7401 irBaud= 115200 irPhysicalComPort= 1 irSupportedBaudRates= 319 irPhysicalComPort refers to the com port as seen by the emulator. Set this value to 0 if you have plugged your infrared pod into COM1 on your PC, to 1 if you have plugged it into COM2.
3. USING AN IDE
The previous procedure provides all the tools necessary to develop and deploy Java applications on Symbian OS. In particular, if you are happy working with a command prompt, JDK 1.1.8 is the only compilation tool you will need. Indeed, all the example projects have been written in such a way that once you have installed the items mentioned above, you should be able to compile, deploy, and run the examples with preconfigured batch files launched from a command prompt or a Windows Explorer file browser.
If you prefer to work with an IDE and have a favorite that you are already using for PC-based Java development, chances are you will be able to make use of it alongside your Symbian SDK for Java. In order for this to work well, the IDE should support pluggable virtual machines so that you can launch your applications in a Symbian Copyright © 2002. Nokia Mobile phones. All rights reserved. 6
GETTING STARTED WITH JAVA ON THE NOKIA 9200 SERIES COMMUNICATORS Version 1.0
OS environment emulating a Nokia 9200 Series Communicator and have access to the custom UI and JavaPhone functionality.
It should be noted that Metrowerks and Symbian are creating CodeWarrior for the Symbian OS product line. The first of these integrated IDEs will target PersonalJava development on the Nokia 9200 Series Communicators, while later products will support both C++ and Java development.
Another partnership, between Borland and Nokia, has produced Java development tools for the Nokia 9200 Series Communicators. There are now two development toolkits available at the Forum Nokia web site. Nokia Developer's Suites for the Java™ 2 Platform, Micro Edition; and PersonalJava™ Application Environment (PJAE) tools, in conjunction with Borland JBuilder and Sun Forte™ for Java™, create a complete environment for application development.
4. DEVELOPING A SIMPLE APPLICATION
The installation of the Nokia 9200 Series Communicator SDK for Symbian OS provides full documentation. However, a quick reference for developing a basic “Hello World” application can be found by navigating the following path from your PC’s Start button:
Start | Symbian 6.0 SDKs | Nokia Java | SDK Documentation | Quick Start
4.1. Running the Application on the Emulator
The Quick Start guide provides full instructions for building and deploying a simple “Hello World” application. A screen shot of the application running on the Nokia 9210 emulator is shown below:
The Quick Start tutorial also includes an introduction to the AIFBuilder tool on the SDK, which enables Java applications to be launched from the emulator or target hardware in the same manner as a native application.
4.2. Porting the Application to the Nokia 9200 Series Communicator
Assuming the “Hello” application ran successfully on the emulator, you can now transfer it to the target hardware. To do this, you must have installed the Connectivity software that is on the CD accompanying the Nokia 9200 Series Communicator. Next, ensure that the device is connected to your PC using the serial cable and that the connection is active. Then, using PC Suite for the Nokia 9210 Communicator, simply copy the files contained in the
GETTING STARTED WITH JAVA ON THE NOKIA 9200 SERIES COMMUNICATORS Version 1.0
be read successfully by the Java runtime, and your Java application will fail to run. To avoid this situation, drag the file with a right mouse click and select the "Copy here" option (not "Copy here and convert") when prompted. The application can then be launched from the Extras screen view shown above in the same way as the application was launched in the emulator.
5. SKILLS TO LEARN
You will need to become familiar with a number of areas before you get into any serious Java development with the SDK. To use Symbian OS Java effectively, note the following concepts.
5.1. Emulator’s Virtual Path System and Classpath Conventions
When working with the Nokia 9200 Series Communicator emulator running on a host PC, you need to be aware of the two concepts of classpath: the compilation and execution classpaths. Although you should be familiar with compilation classpath see the note in Section 6 about classes.zip. Unlike the JDK compiler, the emulator uses its own virtual file system, wherein the folder
When running Java on the emulator, any arguments that are passed to the Java runtime (including the classpath specification) must be in terms of the emulator’s virtual drive identities. The default classpath of the emulator is (in search order)
1. the current directory 2. ?:\classes\ for classes shared between more than one application 3. ?:\ext\* for shared .jar files 4. ?:\lib\classes.zip where “?” indicates that all mapped drives are to be searched, in reverse alphabetical order. Although the “- classpath” specifier switch is defined, you should normally use the “-cp” classpath modifier switch, since - classpath overrides the default classpath of the Java runtime. For instance, in the Quick Start guide, the location of the “Hello” classes is passed to the Java runtime using the following switch to modify the classpath
-cp j:\Hello argument. This causes the folder
5.2. Executables to Launch the Emulator
There are two batch files that can be used to launch the emulator with the associated Java Runtime. The file pjava_g.bat launches the debug version of the emulator, which you would use if you were debugging Java or native code. The file pjava.bat launches the release version of the emulator. These batch files pass their arguments to, and invoke,
GETTING STARTED WITH JAVA ON THE NOKIA 9200 SERIES COMMUNICATORS Version 1.0
Similarly, the file epoc.bat launches the debug emulator without also instantiating a Java runtime. Typing “epoc.bat -rel” launches the release emulator. A Java application can then be launched via its .app file from the Extras view.
5.3. Custom API for CBA buttons
As Nokia 9200 Series Communicators do not by default have a pointer, user interaction is via the keyboard or the Command Button Array (CBA). To ensure a satisfying user experience, developers will have to familiarize themselves with the API used to program the CBA. Let’s look at the code for a simple “Hello World” application that uses the CBA correctly, and also introduce some of the issues involved. The code for the main Frame class is shown below: import java.awt.*; import com.symbian.epoc.awt.*; public class HelloWorldDemo extends Frame implements CBAListener { private EikCommandButtonGroup cbg = new EikCommandButtonGroup();
public HelloWorldDemo(String title) { super(title); add(cbg); show(); setBounds(CKONToolkit.getAvailableScreenRect()); setFrameCBA(); }
/** Sets up the Command Button Area */ public void setFrameCBA() { cbg.addCBAListener(this); cbg.setEnabled(EikCommandButtonGroup.BUTTON1, true); cbg.setText(EikCommandButtonGroup.BUTTON1, "Say Hello"); cbg.setEnabled(EikCommandButtonGroup.BUTTON4, true); cbg.setText(EikCommandButtonGroup.BUTTON4, "Quit"); }
public void cbaActionPerformed(CBAEvent ae) { /* Show SayHello Dialog */ if (ae.getID() == EikCommandButtonGroup.BUTTON1) { //remove listener from this Frame cbg.removeCBAListener(this); //pass reference to CBA SayHelloDialog mydialog = new SayHelloDialog(this, cbg); }
/* Quit application */ else if (ae.getID() == EikCommandButtonGroup.BUTTON4) { System.exit(0); } Copyright © 2002. Nokia Mobile phones. All rights reserved. 9
GETTING STARTED WITH JAVA ON THE NOKIA 9200 SERIES COMMUNICATORS Version 1.0
}
public static void main(String[] args) { try { Thread.sleep(25000); } catch(InterruptedException ie) { }
new HelloWorldDemo("My Frame");
} }
We will go through the code pointing out features specific to the Nokia 9200 Series Communicators user interface. The appropriate classes controlling the CBA and other specific features of the device are contained in the com.symbian.epoc.awt package, so this needs to be imported. The CBA responds to CBActionEvents, hence the Frame implements a CBAListener interface, which extends the EventListener interface.
The line
private EikCommandButtonGroup cbg = new EikCommandButtonGroup(); creates a new CBA. It is important to note that each application can only support one instance of EikCommandButtonGroup.
The line
setBounds(CKONToolkit.getAvailableScreenRect());
uses a static method of the CKONToolKit class to find out how much screen real-estate is available to the Frame.
The setFrameCBA(…) method is used to set up the required buttons of the CBA for this Frame, as well as to add the current CBAListener (which is this Frame) to the CBA.
The cbaActionPerformed(…) method of the CBAListener interface must be implemented, and in this case it responds to presses to the first and fourth buttons of the CBA, generating a new SayHelloDialog or exiting the application, respectively. Carefully note the code required to produce the SayHelloDialog:
if (ae.getID() == EikCommandButtonGroup.BUTTON1) { cbg.removeCBAListener(this); //remove listener from this Frame SayHelloDialog mydialog = new SayHelloDialog(this, cbg); }
The first line removes the current CBAListener from the CBA, since the current listener is the this frame, which is about to be put in the background behind a new dialog that will become the new listener. The new dialog takes a reference to the EikCommandButtonGroup as an argument to its constructor. Since each application can only support one instance of EikCommandButtonGroup, it is necessary to pass this to the new dialog.
We will now look at the source code for the dialog: Copyright © 2002. Nokia Mobile phones. All rights reserved. 10
GETTING STARTED WITH JAVA ON THE NOKIA 9200 SERIES COMMUNICATORS Version 1.0
import java.awt.*; import com.symbian.epoc.awt.*; public class SayHelloDialog extends Dialog implements CBAListener { private HelloWorldDemo parent; private EikCommandButtonGroup cbg; private TextField text = new TextField("Hello from the Nokia 9210 Communicator");
public SayHelloDialog (HelloWorldDemo _parent, EikCommandButtonGroup _cbg) { super(_parent,"Hello Folks", false); parent = _parent; cbg = _cbg; add(text); Rectangle r = CKONToolkit.getAvailableScreenRect(); int y = r.y; int x = r.x; int width = (int)(3*r.width/4); int height = r.height/2; setBounds( x + width/8, y + height/4, width, height ); show(); setDialogCBA();
}
public void setDialogCBA() { cbg.addCBAListener(this);//add listener to Dialog cbg.setEnabled(EikCommandButtonGroup.BUTTON1, false); cbg.setText(EikCommandButtonGroup.BUTTON1, ""); cbg.setEnabled(EikCommandButtonGroup.BUTTON4, true); cbg.setText(EikCommandButtonGroup.BUTTON4, "Close"); }
public void cbaActionPerformed(CBAEvent ae) { if (ae.getID() == EikCommandButtonGroup.BUTTON4) { cbg.removeCBAListener(this); dispose(); parent.setFrameCBA(); } } }
The structure of this class is similar to that of the Frame class with regard to handling the CBA. The constructor receives a reference to the CBA from the previous view. The setDialogCBA method uses this reference to set up the CBA for the current view and, of course, makes the dialog (which implements the CBAListener interface) the current listener.
Again, pay special attention to the contents of the cbaActionPerformed(…) method. This responds to the fourth button of the CBA by disposing of the dialog. First it removes the current listener, then after disposing of the
Copyright © 2002. Nokia Mobile phones. All rights reserved. 11
GETTING STARTED WITH JAVA ON THE NOKIA 9200 SERIES COMMUNICATORS Version 1.0
dialog it resets the CBA of the parent Frame (including restoring it as the current listener) since this is now the active view.
To make it easier to program the CBA for multiple views, the SDK installation includes the CBAHandler utility. This class provides a wrapper around EikCommandButtonGroup and, among other things, ensures that the appropriate CBAListener is active for a given view. This avoids the need to explicitly add and remove listeners upon changing views. CBAHandler and other utility classes supplied with the SDK are discussed in Section 6: Hints and Tips. Further information on programming for the Crystal reference design is contained in the Symbian Press book, Wireless Java for Symbian Devices.
Two screen shots of this “Hello World” application running on the emulator are shown below. The first screen shot depicts the main frame of the application, showing the two activated CBA buttons.
The second screen shot shows the dialog displayed as a result of selecting the “Say Hello” CBA button.
Note how the CBA has been reset for the dialog view.
5.4. JavaPhone API
JavaPhone is a Sun API that is designed to give Java full access to the telephony features of a mobile phone. The Symbian OS Java offering is the reference implementation of this API. JavaPhone comprises a number of extension packages from Sun and, as with other extension packages from Sun, the intention is that the required functionality is provided by the host operating system. The following packages are provided in the current Symbian OS implementation:
Copyright © 2002. Nokia Mobile phones. All rights reserved. 12
GETTING STARTED WITH JAVA ON THE NOKIA 9200 SERIES COMMUNICATORS Version 1.0
javax.net.datagram javax.pim.addressbook javax.pim.calendar javax.pim.database javax.pim.userprofile javax.power.monitor javax.telephony javax.telephony.mobile javax.telephony.capabilities javax.comm
Packages included in the JavaPhone API but not included in the current implementation are listed below:
javax.ce.install javax.power.management javax.telephony.callcontrol javax.telephony.phone javax.net.ssl
A full description of the features offered by the JavaPhone API is beyond the scope of this paper, and the reader is referred to the Sun’s JavaPhone API specification at
http://java.sun.com/products/javaphone/ or the various technical papers and tutorials available on the Symbian Developer Network web site at
http://www.symbiandevnet.com/techlib/techlib.html or to the Symbian Press book, Wireless Java for Symbian Devices.
5.5. Packaging Applications for General Release
Finished applications ready for general release should be packaged into a .sis file using the Symbian Installation System. This provides a simple and consistent user interface for installing applications, data, or configuration information to Symbian OS phones. End users install components packaged in installation (.sis) files either from a PC, by using the installer, or from a Symbian OS phone, using the Add/remove Control Panel applet.
The first stage in generating a .sis file is to create a package file (a text file ending with the file extension .pkg). A minimal package file for a token “HelloWorld” Java application would look something like this:
#{"Minimal application"},(0x01000000),1,0,0 ; files to be installed "HelloWorld.app"-"!:\system\apps\HelloWorld\HelloWorld.app" "HelloWorld.txt"-"!:\system\apps\HelloWorld\HelloWorld.txt" "HelloWorld.jar"-"!:\system\apps\HelloWorld\HelloWorld.jar"
The package header defines the application’s name "Minimal application"; UID (0x01000000); major and minor build numbers (1, 0); and the build number (0). The second line, preceded by a semi-colon, is a comment. The final three lines specify the location of the files, which should be put in the installation file, and their destination on the target machine. The UID uniquely identifies this application (or, equivalently, its associated .sis file). For testing purposes, you can use any UID you like, the first hex digit of which is a “0”. If you want to redistribute Copyright © 2002. Nokia Mobile phones. All rights reserved. 13
GETTING STARTED WITH JAVA ON THE NOKIA 9200 SERIES COMMUNICATORS Version 1.0
your code, you should have your own unique number issued by making an email request to [email protected].
To create the installation file HelloWorld.sis, place the HelloWorld.pkg file in a directory along with files to be packaged, and then launch a command prompt from that directory and type
makesis HelloWorld.pkg .
HelloWorld.sis can then be transferred to the target machine and installed as an application by clicking on it in the File Manager and following the instructions. After installation, the application may be run by selecting the HelloWorld icon from the Extras view.
The installation system provides many options, including creating digitally signed .sis files. For full details refer to the SDK documentation at
Developer Library | Java Developer’s Guide for Crystal | Deploying and Running Applets and Applications | Application Installation Guide
6. HINTS AND TIPS
♦ Applications launched directly from a command prompt with pjava_g.exe or pjava.exe will often be put in the background behind the Desk view presented on launching the emulator. This problem can be overcome by adding the following line:
Thread.sleep(25000);
to the main(…) method of the HelloWorldDemo described in Section 5.3. If this line is omitted (as was the case for the source code of the Quick Start guide that is included in the SDK documentation), the application view will usually be put in the background behind the Desk view presented on launching the emulator. In practice, you are advised to write the main() method of your application to test for a flag, which can be passed in as an argument when the application is launched from a command prompt.
♦ In your application, be careful only to include classes that are supported by the PersonalJava Application Environment. Also, remember to compile your source code against Symbian’s classes.zip (at
♦ It is a limitation of the emulator that when a Java application running on the emulator is closed down, the emulator is also closed down. This is to ensure that all threads associated with the application are terminated.
♦ It is only possible to run one Java application at a time on the emulator. On the Symbian OS emulator, multiple Java virtual machines cannot run simultaneously (of course multiple Java applications can be run on actual phones). When a Java application starts up, it loads pjavai.dll (or pjavai_g.dll), and starts up the Java virtual machine. Because the emulator runs as a single process, a second Java application will find it is running in the same process as the first, so it cannot load another instance of that DLL. Instead, it will attempt to share the global variables associated with the existing DLL instance. Unlike native applications, the Java DLLs are not designed to be re-entrant in this manner, so this operation will fail. Currently, there is no way to work around this situation. There is, however, no problem with separate instances of the emulator, both running Java applications, because the two emulators run as separate processes.
Copyright © 2002. Nokia Mobile phones. All rights reserved. 14
GETTING STARTED WITH JAVA ON THE NOKIA 9200 SERIES COMMUNICATORS Version 1.0
On a target Symbian OS phone, which supports multiple processes, more than one instance of the Java virtual machine can be loaded simultaneously from a single instance of javai.dll in ROM or RAM. The only restriction is the amount of RAM available.
♦ One common source of confusion for Java developers new to Symbian OS arises between the two methods of launching a Java application, namely, from the command prompt via pjava.bat (or pjava_g.bat) or from the emulator Extras view. After developing a Java application in the erj directory, then packaging it using the AIFBuilder and installing it into the system\apps\ directory, the user may choose to launch the application from the command prompt using pjava.bat. The emulator fires up, but the Java application appears not to start, since it has been put in the background. If the user proceeds to select the application icon in a mistaken attempt to launch the application, the application will display a “Could not create the Java virtual machine” message. This happens because an instance of the JVM is already running the application (in the background), and selecting the application icon tries to start a second instance of the JVM. The emulator, as previously discussed, cannot support this, hence the error message. You can avoid this problem if the application is launched from the Extras, moved to the background, then “re-launched,” since the system is smart enough to recognize that the application you want is already running and only needs to be moved to the foreground.
♦ Programming for the Nokia 9200 Series Communicators user interface requires a little getting used to. To assist developers in working with the CBA, two useful utility classes are provided with the SDK. CFrame (which extends Frame) can be used instead of Frame in your applications to provide the correct look and feel, including a CBA. The CBAHandler class can be used for the correct handling of the reference to the EIKCommandButtonGroup, and in particular takes care of passing it between different views. These two classes are located in the
archive, which should be appended to the classpath if they are used in your code. It is possible to download from Forum Nokia a qawt.sis file, which installs this jar file into \system\java\ext\ on the target phone, ensuring its contents will automatically be included on the system classpath. You can then embed this .sis file into your own .sis file as a shareable system component by including the following line in the associated .pkg file
@"CAwt.sis",(0x101F4449)
This allows conditional installation of the utility classes only when they are needed. Note the associated UID, which must be specified correctly.
♦ The keyboard-driven user interaction paradigm of Nokia 9200 Series Communicators can affect the way a developer programs interaction with certain components, such as Lists. Consider the following code, which can be used to navigate a list using a pointer:
... public class ListDialog extends Dialog implements ItemListener { ... private List drinkList;
public ListDialog(Frame parent){ super(parent); drinkList = new List(6); drinkList.add("Vodka"); Copyright © 2002. Nokia Mobile phones. All rights reserved. 15
GETTING STARTED WITH JAVA ON THE NOKIA 9200 SERIES COMMUNICATORS Version 1.0
drinkList.add("Gin"); ... drinkList.addItemListener(this); add(drinkList); ... }
public void itemStateChanged(ItemEvent ie){ String drink = drinkList.getSelectedItem(); //do something with selected drink ... } ... }
This represents the standard way to choose an item from a list on a mouse-driven desktop system. Although the code also works satisfactorily on the emulator, which has access to the PC’s mouse, it proves unsatisfactory on the real hardware since, to navigate the list, it is necessary to use the four-way keypad (assuming the virtual cursor has not been enabled). However, the instant the keypad is pressed, an ItemEvent is generated and the itemStateChanged(…) method triggered, with the selected item being the next one in the list, though it may not be the one desired. Therefore it is not possible to directly select the desired item. The recommended way to choose an item from a list when developing for the Nokia 9200 Series Communicators is to use the CBA to select the item as follows:
... public class ListDialog extends Dialog implements CBAListener { ... private List drinkList; private EikCommandButtonGroup cbg;
public ListDialog(Frame parent, EikCommandButtonGroup cbg){ super(parent); this.cbg = cbg; drinkList = new List(6); drinkList.add("Vodka"); drinkList.add("Gin"); ... add(drinkList); ... cbg.addCBAListener(this); cbg.setEnabled(EikCommandButtonGroup.BUTTON1, true); cbg.setText(EikCommandButtonGroup.BUTTON1, "Select"); ... }
public void cbaActionPerformed(CBAEvent ae){ String drink = drinkList.getSelectedItem(); //do something with selected drink ... } ... }
Copyright © 2002. Nokia Mobile phones. All rights reserved. 16
GETTING STARTED WITH JAVA ON THE NOKIA 9200 SERIES COMMUNICATORS Version 1.0
In this example, the first button of the CBA is enabled for selection of the item and a CBAListener (rather than an ItemListener) is added to the Dialog. The List can now be navigated correctly using the four-way keypad. When the required item is highlighted, the user presses the “Select” button of the CBA. This selection triggers the cbaActionPerformed(…) method, and the correct item is selected via the getSelectedItem() method of the List class.
♦ There are problems accessing the infrared and RS232 serial ports from the JavaPhone javax.comm API. By design, the RS232 port on Nokia 9200 Series Communicators is configured to listen permanently for a remote link to a PC, so as to allow the Nokia Connect software to work seamlessly. In other words, don’t try to use the RS232 port on Nokia 9200 Series Communicators.
In the case of the infrared port, the problem stems from a defect in the javax.comm JavaPhone package that shipped with the Nokia 9210 Communicator and corresponding SDK, whereby the wrong name for the infrared port (“IrComm” rather than the correct “IRCOM1”) was hard-coded into the com.symbian.javax.comm.EpocCommDriver class in JavaPhone.jar. The solution is to patch this class with an updated version available from the Symbian OS Knowledge Base at
http://www3.symbiandevnet.com/faq.nsf
Open FAQ-0733 and unzip the \classes\ folder in the attached zip into the \erj\ folder on the SDK and/or \System\Java\ folder on the Nokia 9210 Communicator. You should then be able to initialize the infrared port successfully from the SerialChat application.
♦ To test the JTAPI or SMS datagram API of the JavaPhone API on the emulator requires an infrared-enabled GSM phone connected via an infrared Jet Eye pod to the PC’s serial port. If the phone is absent, your application will throw exceptions.
♦ In the Symbian OS implementation of the JavaPhone 1.0 specification, not all the JTAPI methods have been implemented, although the respective package is one of the supported packages. Invoking unsupported methods will result in a MethodNotSupportedException. The JTAPI command set is further limited under emulation by what the emulator’s device driver and GSM phone allow. More details are available in a technical paper on the Symbian Developer Network web site at
http://www.symbiandevnet.com/techlib/techcomms/techpapers/javatpaps.html
♦ The AIFBuilder tool (among others) requires a JRE 1.2.2 to be installed. The JRE 1.2.2 is supplied on the SDK and, if not detected by the SDK installer, must be installed. Note that this is required in addition to the installation of the JDK 1.1.8, which is needed to compile PersonalJava applications.
♦ For Java applications launched from the Extras view, System.out and System.err messages are not visible. This is true for both the emulator and the real hardware. To see this output, use the Redirector application. An emulator version comes pre-installed with the SDK. A version that can be installed onto a Nokia 9200 Series Communicator is included with the SDK at
When this is activated by launching from Extras, System.out and System.err text is channeled to it and can be subsequently viewed by moving the Redirect application to the foreground. Alternatively, you can configure Redirect to send output to permanent storage by specifying a target file name.
Copyright © 2002. Nokia Mobile phones. All rights reserved. 17
GETTING STARTED WITH JAVA ON THE NOKIA 9200 SERIES COMMUNICATORS Version 1.0
7. DEVELOPING FOR PHONES OTHER THAN THE NOKIA 9200 SERIES COMMUNICATORS
One of the main motivations behind the creation of Symbian was to enable a cross-platform development environment for products by multiple vendors. After you have gained familiarity with developing and deploying pJava/JavaPhone applications for the Nokia 9200 Series Communicators using the associated Symbian OS SDK, you should be able to do the same on future Symbian OS SDKs customized for other phones. In addition, future Symbian OS SDKs for Java will include the MIDP environment; so much of your experience in deploying and testing pJava applications under Symbian OS emulation will apply directly to MIDlet development.
For pJava applications targeting Nokia 9200 Series Communicators, you will of course want to do some device- specific customization of the UI, e.g., making use of the CBA preferential to a more pointer-oriented model.
8. GETTING HELP
8.1. Forum Nokia
Forum Nokia is Nokia’s Web site for developers using its technologies, and is found at:
http://www.forum.nokia.com/
Forum.Nokia.com contains a wealth of information about the Symbian OS for the Nokia 9200 Series Communicators. To gain full access to these resources, you must register, for which there is no charge. In addition, there are free discussion forums devoted to Symbian OS development and Java development on Nokia phones.
8.2. Symbian Developer Network
The Symbian Developer Network is Symbian’s developer service organization. It provides developers using Symbian OS with support and information to help them produce well-written and stable applications for Symbian OS devices. The Symbian Developer Network provides free public discussion forums at
http://www.symbiandevnet.com/support/discussion/forums.html and professional support forums for subscribing members at
http://www.symbiandevnet.com/support/promembs/supfor.html
Both public and professional Java forums are provided, the latter is manned by Symbian staff.
9. OTHER AVAILABLE LITERATURE
9.1. Forum Nokia
The Forum Nokia developer support Web site offers numerous technical papers devoted to Symbian OS about the Nokia 9200 Series Communicators. Included are papers addressing both Java and general configuration issues. These can be found on the Forum Nokia web site under the Technologies | Java and Symbian Platform | Documents heading.
Copyright © 2002. Nokia Mobile phones. All rights reserved. 18
GETTING STARTED WITH JAVA ON THE NOKIA 9200 SERIES COMMUNICATORS Version 1.0
9.2. Symbian Developer Network
The Symbian developer network web site contains a comprehensive technical library that can be found at
http://www.symbiandevnet.com/techlib/techlib.html
This section contains a full set of technical papers, including titles devoted to Java on the Symbian OS and JavaPhone, as well as tutorials, hints, and tips.
9.3. Wireless Java for Symbian Devices
The first title from the newly formed Symbian Press, Wireless Java for Symbian Devices, is a comprehensive textbook devoted to all aspects of programming Java on Symbian OS published by John Wiley and Sons, Ltd. The book includes chapters devoted to “Java on Crystal,” the reference design on which the Nokia 9200 Series user interface is based, and the JavaPhone API.
Symbian licenses, develops, and supports Symbian OS, the platform for next-generation data-enabled mobile phones. Symbian is headquartered in London, with offices worldwide. For more information see the Symbian web site, http://www.symbian.com/.
Trademarks and copyright ‘Symbian’, ‘Symbian OS’, and other associated Symbian marks are all trademarks of Symbian Ltd. Symbian acknowledges the trademark rights of all third parties referred to in this material. © Copyright Symbian Ltd 2001. All rights reserved. No part of this material may be reproduced without the express written permission of Symbian Ltd.
Disclaimer Symbian Ltd makes no warranty or guarantee about the suitability or accuracy of the information contained in this document. The information contained in this document is for general information purposes only and should not be used or relied upon for any other purpose whatsoever.
Copyright © 2002. Nokia Mobile phones. All rights reserved. 19