Glossary Confused by computer jargon? Look it up!

Shameless plug Now available!

Articles - Ten-minute guide to setting up a WAP site - Talk like your boss: new developments in managerese - More...

Development -  File handling in the Linux kernel -  Java development for the Sony-Ericsson P800 - SunONE Application Server 7 FAQ - More...

Linux -  Using Linux with the Treo 600 - Linux on the Tecra M1 - Some notes on openzaurus - More...

Download - Java stuff - Linux stuff - More... (Please read the download policy)

Home automation - The X10 system - Linux TW723 driver - More...

The K-Zone - K-Zone computing - K-Zone law - K-Zone education and science - K-Zone motorcycles - K-Zone DIY - K-Zone railways - K-Zone martial arts - About the author - K-Zone home page

Computing	J2ME FAQ	Perl for Java programmers	Web Service tutorial
CLASSPATH	EJBs on jBoss	CMP with jBoss	Bean managed persistence	C++ tutorial
Simple Java	JDK setup	Howto-appletviewer	Howto-dosprompt	EJB lifecycles
EJB transactions	Inside the J2EE RI	S1AS7 FAQ	iAS 6.0 FAQ	iAS JMQ

This article outlines the process of developing Java applications for the Sony-Ericsson P800 PDA phone, and discusses the trade-offs between the PersonalJava and MIDP environments. It also gives some suggestions how to do PersonalJava development for the P800 under Linux, without using any Symbian-specific tools.

P800 Java programming overview

	MIDP/CLDC	PersonalJava
Industry support	Most Java-enabled mobile devices support MIDP1.0, and it is available as an add-on for many others. There are MIDP implementations for Windows CE devices, for example. Much of the development of MIDP was done on the Palm PDA range. MIDP2.0 is a significant improvement of MIDP1.0, but there is very little industry support for MIDP2.0 at the time of writing.	PJ is only supported by high-end, expensive devices, like `smart' phones and PDAs. Top-of-the-range Ericsson and Nokia phones support it, as does the Sharp Zaurus. Don't expect PJ support on a budget mobile phone
JDK/JVM version	Loosely based on JDK1.3, but with some striking limitations (see below).	Loosely based on JDK1.1.6
User interface model	MIDP has its own user interface model, designed for very small displays. MIDP2.0 offers some substantial improvements over version 1.0, such as offering some control over the layout of data entry elements (rather than none at all)	PJ applications typically use the AWT user interface model. AWT is a very limited interface, but vastly superior to MIDP. Top-end PDAs generally offer richer user interfaces than AWT can support, and these may be made available as extensions to the PJ environment. Use of these extensions, of course, reduces portability, and makes it more difficult to debug applications
JVM restrictions	Strict sandboxing (no file access, for example); no floating point maths support; no finalization on garbage collection; persistent storage only available in MIDP-specific `record stores'; no native calls. MIDP devices are expected to have unimpressive CPU power, so the specification calls for part of the JVM's bytecode verification process to be carried out before execution, rather than in the JVM. As a result, standard Java compilers cannot produce MIDP code without additional software	Apart from supporting a rather elderly JDK version, PJ is a full JVM. In general, PJ apps can read and write the local filesystem, make native calls, load classes from outside the application, and make and receive network calls (hardware permitting). There is generally proper floating-point maths support.
Packaging and deployment	Universal, non-proprietary code deployment format based on JAR and JAD (see below) files (complicated, but well documented); well-established over-the-air (OTA) deployment provisions	No standard packaging or deployment; vendors implement their own methods of installing and configuring PJ applications; no generally accepted OTA deployment protocols
Development options	Use standard Java compiler with CLDC `preverifier'. Some integrated toolsets are available. Test on a MIDP emulator or real hardware device	Use standard Java compiler, test on a MIDP emulator or real hardware device, or - with some caveats - on a desktop workstation

The P800 SDK and emulator

• A Symbian mobile phone emulator, with customizations for the P800
• Packaging tools to turn your Java JAR files into the `SIS' files that end users will need to install your applications
• Documentation of the Ericsson/Symbian extensions to the PJ runtime environment
• Details of how the PJ and MIDP specifications are implemented on the P800 (e.g., which font sizes are available, and how the screen is laid out)

PersonalJava on the P800

• The P800 does not have the same range of fonts as a workstation JVM. Not all fonts are available in all sizes. The P800 font selector does not alway behave intuitively. For example, if you ask for a 100-point monospaced font, which the device does not provide, you might instead get a 12-point monospaced font rather than a 100-point proportional font. Arguably, the 100-point proportional font is closer to what the program requires - it wouldn't have asked for a 100-point font if a 12-point font would do - but the device has to make the best selection it can, and it favours matching typeface over matching size
• The P800 JVM fails silently if asked to load a class that it thinks is for a too-recent JVM version. It doesn't give any useful error message. The P800 emulator gives a NoClassDefFoundException. This is confusing when it is perfectly clear that the class file is available and in the right place. The simplest way to avoid problems like this is to compile and test with JDK1.1.6. However, this is annoying if you already have a Java development installation based on, say, JDK1.4.1. In this case, you can run a more modern version of javac with the argument -target 1.1 which produces the right type of bytecode. To avoid using classes that don't exist in JDK1.1.6, use the -bootclasspath to override the compiler's location to search for standard API classes. You can get a suitable classes.zip for the P800 from the Sony-Ericsson web site, or `beam' it off the P800 itself (it's in c:\system\java\lib).
• PJ applications can read and write files. The P800 has a Windows-like filesystem, where memory devices are represented as drive letters. So the internal non-volatile RAM is drive c:, and the memory stick, if installed, is drive d:. Typically drives c: and d: have the same structure. Of particular importance are the directories c:\system\apps and d:\system\apps: applications are installed here. Typically each application will have a subdirectory under apps, and this will become the application's current directory when it is invoked from the application launcher.
• A Java application based on a Frame will fill the whole display (at least, that part of it that isn't reserved for system icons). The P800 JVM silently ignores instructions to resize the main frame. By the same token, if one Frame creates another, the second completely obscures the first. Thus there needs to be some form of back-navigation on each Frame. On the other hand, if a Frame creates a Dialog, the Frame remains visible behind it. Unlike a workstation JVM, the P800 JVM does not allow users full control over windows placement, and the developer needs to take this into account.
• The UIQ design guidelines stipulate that applications must not have any user-accessible `close' or `exit' functionality. Moreover, if the system closes an application, the application should write its state to disk, and then restore it when reopened. In other words, the user should be shielded from the `open-load-save-close' logic of a desktop operating system. When the system closes a Java application, it sends a WINDOW_CLOSING event to the top frame. If you are used to developing for desktop systems, you will probably be handling this event anyway, because the JVM will send it when the main window is closed. So, in theory, a P800 application should be the same as a desktop AWT application, but with no `close' or `exit'. In practice, many applications for the P800 do have `exit' functionality, even some endorsed by Sony-Ericsson (like the MobiPocket eBook reader).

PersonalJava using the SDK and emulator

• Create Java sources and build using JDK1.1.6 or similar, linking against the classes.zip supplied with the Symbian SDK.
• Package into a JAR file
• Test on the Symbian emulator, by putting the JAR file onto the emulator's classpath, and running the java_g utility with the name of a class as the command-line argument. The emulator's classpath configuration is described in the JDK documentation. Basically, it is taken from an environment variable _epoc_drive_j. This is usually set to the emulator's Java directory, under which are directories lib, and ext. In short, any JAR file put into ext is added to the classpath. You can also modify the classpath on the emulator command line, but this is reasonably well documented so I won't go into it here. What is important is that the emulator does not honour the system CLASSPATH environment variable. In short, on my system I would put my application JAR into the directory \Symbian\UIQ_70\epoc32\java\ext\; the following commands would then launch it in the emulator: set EPOCROOT=\Symbian\UIQ_70\ set _epoc_drive_j=%EPOCROOT%\epoc32\java PATH=%PATH%;%EPOCROOT%\epoc32\tools pjava_g [my_main_class] It is a well-documented flaw (feature?) that a Java application launched this way runs in the background and, as it doesn't have an icon in the launcher (yet), there is no standard way to foreground it. The emulator provides a `task manager' feature that doesn't exist in the real P800, and you can use this to bring the application to the foreground.
• Create some files that the Symbian OS uses to identify an executable application. In particular you will need (i) an `AIF' file, which contains the name of the application and its icon, (ii) an `APP' file, which contains the application's unique numeric ID (which you are supposed to apply for, from Symbian), and (iii) a TXT file, which contains the command line arguments for the Symbian JVM. The TXT file is straightforward. If I intend to install my JAR into the directory \system\Apps\MyApp on the P800, and it is called MyJAR.jar, then I would create MyApp.txt like this:

  -cp MyJAR.jar [my_main_class]
  

  The `-cp' argument specifies the JAR file and, as it is in the application's working directory (by definition) I don't need a full pathname.
         This is where the simplicity ends, however. The AIF and APP files are proprietary, and their formats don't seem to be documented anywhere. On the Windows platform, you can use the tool AIFbuilder to construct them; this tool has an easy-to-use graphical interface. You could also construct an `AIFB' file (the format of which is documented) and use aifbuilder -generate to turn it into the appropriate AIF and APP files. On any platform other than Windows, you could be in trouble. I understand that the GNUPoc project describes a way to run these tools under WINE on Linux, but this requires some fairly extensive patching of the SDK itself. Happily, there is a way to run Java on a real P800 without these files, as I will explain below.

  With the AIF, APP, and TXT files, you can install the application on a real P800 by copying them into their own directory under system/Apps. The application should then show up in the launcher, and be runnable. If you've done your work properly up until now, the application should behave much as it did in the emulator.

• When you're happy with how the application behaves when run on the P800, you can create a SIS file for distribution to end users. The SIS file contains the AIF, APP, and TXT files described above, the JAR file with the executable code, and some information about where to install them on the target device. Unlike the MIDP packaging rules (see below), the SIS file is not platform-agnostic. That is, it contains information about exactly which files are to be installed and which directories created on the user's P800. You therefore have to be careful that your SIS file won't lead to some catastrophic error on the target device (such as overwriting a system file). If you've decided to install everything into its own directory, and the directory name is reasonable distinguished (not `test'), you'll probably be OK. The standard utility for creating a SIS file is called makesis and, like the other command-line utilities, only runs under Windows. However, Sony-Ericsson has released the source code for makesis, and there are Linux ports available (see below for where to get one and how to use it).
• Having got a SIS file, you can install it to the device in the usual way. Typically a user will double-click the SIS file in Windows Explorer, which will begin the download process. Alternatively, the user can copy it to the Documents directory in the P800, and then use the launcher on the P800 to install it.

• Create an AIFB file using the AIFBuilder utility
• Create an icon in the proprietary MBM format, either by converting it from another image format, or using the editor in AIFBuilder
• Generate the AIF, APP, and TXT files from the AIFB and MBM files using the AIFBuilder utility
• Create a PKG file for the makesis utility (the format is described in the Symbian documentation)
• Create a SIS file from the AIF, APP, TXT, and PKG files
• Distribute the SIS file to users

PersonalJava development on Linux without Symbian tools

• The current directory is the directory containing the class file
• The classpath includes the current directory (so other classes in that directory are also loadable)
• Execution starts in the main() method of the selected class

The problem with the approach to development and testing described above is that it doesn't produce a distributable application, nor provide a way to run the application from the launcher. So while it may work for developers, it's not very useful for end users. A more subtle problem is that if you run a Java application from the file manager, you only get the JVM's defaults. You can't, for example, run the JVM with a larger initial heap or stack (which is essential for running large or memory-hungry applications). Happily, with a bit of hacking you can produce a distributable application in .SIS format, which behaves exactly like the applications produces by the Symbian SDK, and all without using Windows.
       To do this, you'll need the following things:

• A Linux implementation of Sun Java JKD1.1.6 or earlier
• The bootstrap class library classes.zip from the Symbian Web site or from the P800 itself (or use the version that comes with the old JDK)
• The GCC C compiler to compile the following two tools
• The Linux version of the makesis utility, from the GNUpoc Web site.
• My hacked version of Rudolf König's genaif program. Grab genaif.c and compile it. This program has been hacked to produce APP files, and to generate AIF files with the correct magic numbers in place for PersonalJava and Symbian 7. I have only the haziest notion of how this program works - I simply hacked it around until it produced the same output as the Windows aifbuilder
• At least one icon in EPOC MBM format. I don't know a way to produce these under Linux - but there are plenty of MBM files around. If you don't have an icon, the only consequence is that the application will get a default icon in the launcher - it will still work
• All your favourite development tools
• If you want to use Ant for development under JDK1.1.6, you have two avenues to explore. Either run it under a modern JDK, and configure your build script to produce Java1 output (and modify bootstrap classpath etc), or run Ant under JDK1.1.6. The latter approach will automatically give you the right kind of class files, but you may have to go for an earlier version of Ant. The latest versions won't run under JDK1.1.6. I have had most success with the latter approach, running Ant under JDK1.1.6

genaif 0xNNNNNNNN < [config_file] > [appname.aif]

genaif 0x00000000 0x10001734 0xNNNNNNNN > [appname.app] 

-cp myapp.jar [main_class_name]

echo -n "-cp myapp.jar [main_class_name]" > myapp.txt

&EN
#{"myapp"}, (0xNNNNNNNN), 1,0,0
"myapp.aif"-"!:\system\apps\myapp\myapp.aif"
"myapp.app"-"!:\system\apps\myapp\myapp.app"
"myapp.txt"-"!:\system\apps\myapp\myapp.txt"
"myapp.jar"-"!:\system\apps\myapp\myapp.jar"
(0x101F617B), 2, 0, 0, {"UIQ20ProductID"}