Java Development
Development of an EPOC application in Java commences with the standard Java development path, creating the appropriate class files and packaging them into JARS. Once this has been done the application can be tested by running it in the emulator. In the case of the sample application this is done with the following command run at the DOS prompt (in this case the SDK is installed on the E drive):
E:>cd \epoc32\release\wins\rel
E:\epoc32\release\wins\rel>java -- -cd c:\system\apps\epocjava -cp epocjava.jar com.symbian.epoc.epocjava.EpocJava
|
In the JVM execution command -- separates parameters for the emulator (you can for example control the emulator screen size) which are placed before the -- and parameters for the JVM. The parameters passed to the JVM are -cd which sets the current folder to the application folder, -cp which adds the JAR to the classpath and finally the package method to be run.
Two things are worth noting here:
if the application produces output to the Console this will be seen in the DOS window
when the application is exited the emulator also closes.
Obviously running the application from the DOS prompt is somewhat laborious. The main reason that an application would be run in this way is to use the standard Java debug tool java_g. It is a lot more convenient, when not debugging, to run the application from the Extras bar.
Run from the Extras Bar
There are two steps to build the information necessary allow a Java application to be run from the Extras bar, creating an Application file and providing the command line parameters in a text file.
EPOC Application File
The application or app file defines the unique identification for the application and allows it to be detected so it is added to the Extras bar. The app file is built with the appbuild utility. appbuild is supplied with two parameters, the application name and its UID.
The following command was used to build the app file for the sample application:
E:\epoc32\wins\c\system\apps\epocjava>appbuild EpocJava 01010101
APPBUILD tool
Copyright (c) 1997-1999 Symbian Ltd.
building .app file
ok
Directory already exists
1 file(s) copied
|
Command Line File
The second element required to allow a Java application to be run from the Extras bar is the Command Line file. This is simply a text file containing the command line, in the case of the example program it is:
-cp EpocJava.jar com.symbian.epoc.epocjava.EpocJava
|
You will recognise part of this command line from the one used in running the application from the DOS prompt. The -cd parameter is not supplied however, this is because the default folder is set when an application is launched from the Extras bar to the folder in which the application resides. The command line file should be created in the applications folder.
With the app and txt file present the application will now appear on (and can be started from) the Extras bar, however it only has a ? icon so:
If the application should produce output to the console a console is created in the emulator and output is placed there. When the application exits, and console output is present, rather than shutting the emulator when the Java application closes it waits until the console has been examined and closed. This can give the impression that the application has not stopped.
Also once the app file and command file have been created the application could be run on an EPOC device. If this is done be aware of the fact that no console exists as a default on an EPOC device. To provide a way to view console output create a file (of any type) called console in the \system\java\ folder on any drive.
Give Your Application an Image
At this stage you have your application running as the user will run it on an EPOC device. The next stage is to provide an appropriate application icon and multi-lingual caption.
Program Icon
Applications delivered to an EPOC device use a program icon to identify the application on the Extras bar and any files created by that application. Ideally three icons should be supplied, being bitmaps of 24x24, 32x32 and 48x48 pixels (however a single icon can be supplied which is scaled by EPOC). These three icons are used in the various zoom levels available in the system view.
EPOC system screen showing file icons at maximum zoom
The first stage in creating the icon file is to develop the bit maps. Each icon requires two bit map files, one containing the icon and the second a mask that indicates which bits are set or cleared by the icon. The following 6 bit maps were developed to provide the example application with an icon:
EPOC uses its own image file, the mbm or multiple bit map file to store these icons. Once the icon bitmaps have been created they can be converted to a mbm file using the bmconv tool. The command used to create the icon file for the sample application is:
E:\epoc32\wins\c\system\apps\epocjava>bmconv epocjava.mbm 24i.bmp 24m.bmp 32i.bmp 32m.bmp 48i.bmp 48m.bmp
BMCONV version 51.
Compiling...
Multiple bitmap store type: File store
Epoc file: epocjava.mbm
Bitmap file 1 : 24i.bmp
Bitmap file 2 : 24m.bmp
Bitmap file 3 : 32i.bmp
Bitmap file 4 : 32m.bmp
Bitmap file 5 : 48i.bmp
Bitmap file 6 : 48m.bmp
Success.
|
Application Information File
For Java applications the Application Information File or aif allows for the applications icon and captions associated with various languages to be defined (the aif file serves a wider role for c++ applications). The aif builder utility, aiftool uses a resource file (which is a text file with the extension rss) to define the content of the aif file. The following is the resource file used to create the aif file for the example Java application discussed later:
#include <aiftool.rh>
RESOURCE AIF_DATA
{
app_uid = 0x01010101;
caption_list =
{
CAPTION { code = ElangEnglish; caption = "Java Example"; },
CAPTION { code = ElangFrench; caption = "Java Example"; }
CAPTION { code = ElangGerman; caption = "Java Beispiel"; }
CAPTION { code = ElangItalian; caption = "Java Esempio"; }
};
num_icons = 3;
embeddability = KappNotEmbeddable;
}
|
The resource file and icon file can now be compiled to create the aif file. It should be noted that the aiftool can currently only include header files if the file being compiled is no deeper that two folders from the drive root. Therefore before creating the aif file the icon file needs to be copied to the same folder and once the aif file has been compiled it will need to be copied to the applications folder. The Epocjava aif file is created as follows (note that the rss extension is omitted from the resource file name):
E:\aiffiles\epocjava>aiftool EpocJava EpocJava.mbm
AIF tool
Copyright (C) Symbian 1998
Compiling resource file
1 file(s) copied
Copying mbm
1 file(s) copied
Running AIF writer
Reading resource file...
Adding icons
Reading icons
Adding captions
Adding capability
Adding data types
Saving
1 file(s) copied
|
The application will now run with the ? icon replaced with the application icon and use the appropriate caption thus:
The author notes that the version of the Java SDK supplied with the Wrox press book appeared not to include the \epoc32\gcc folder which contains commands used by aiftool. This was rectified by copying this folder from the C++ SDK to the drive containing the Java SDK and updating the path to include ?:\epoc32\gcc\bin.
Application Installation Package
The application Installation package file (the sis file) is the final step in the development process. Using a command file processed by the makesis utility a single file containing all the elements of the application, Java code, supporting sound and image files, app, aif and command files, is built to provide the user with a single simple mechanism for installing an application.
The sis file allows for a high level of control over the install (creation of directories, copying of files, display of licence and other details) and de-install process. The sis file in this example has been kept quite straightforward, it displays a Yes/No dialog and then installs the application. The following command file was used:
; comment line
; Basic Application definition, name, UID, major, minor and variant release numbers
#{"Epoc Java Example"},(0x01010101),1,0,0
; Language Independent Files
; Text file displayed with Yes No dialog
"epocjavainstall.txt"-"!:\system\apps\epocjava\epocjavainstall.txt",FT,TS
; Application files
"epocjava.jar"-"!:\system\apps\epocjava\epocjava.jar"
"epocjava.txt"-"!:\system\apps\epocjava\epocjava.txt"
"epocjava.app"-"!:\system\apps\epocjava\epocjava.app"
"epocjava.aif"-"!:\system\apps\epocjava\epocjava.aif"
|
The installation file also supports the following features which we are not using here:
definition of languages supported
language dependant files
definition of files to be deleted when removing the application which were not in the install list, e.g. file created by running the application
dialog box with a 'Continue' button or with 'Yes/No', where 'No' skips the next file to be installed
executable files to be run on install, removal or both
requisite components
other sis files
The sis file is then built with the following command:
E:\epoc32\wins\c\system\apps\epocjava>makesis epocjava.pkg
Psion Software PLC 1997
Version 1.0
MakeSIS, a utility for creating Software Installation files
Generating epocjava.SIS from epocjava.pkg
|
You now have an installation package that can be distributed. When a user receives the sis file they can load it using the EPOC Connect software from a PC or by copying the file to their device and use the "Add/Remove" option from the Control Panel.
Next: The Future
