Configurations

Java2PDA

Description

This configuration runs on PDA's with a Java 2 SE environment.

Supported devices

X-Smiles should be able to run on Compaq iPAQ handhelds with SavaJe XE operating system installed. See the SavaJe web-site for up to date information on applicable hardware and installation instructions for that product.

The installation instructions in this document have been tested out with iPAQ 3630 running SavaJe XE 1.0, ensuring that they work with the minimal configuration of 32MB memory and 16MB flash. A Compaq Serial AutoSync cable or Serial Cradle is generally required to install SavaJe XE.

X-Smiles functionality

The goal has been to preserve as much X-Smiles functionality as possible. With a fully compliant J2SE implementation all X-Smiles features should be attainable, so the SavaJe build does not exclude any specific parts of X-Smiles functionality. However, as the Compaq iPAQ is a fairly powerful platform, there are several different installations and use-cases possible. This document tries to give a basic overview for a typical installation to build on, but almost everything can be done in more than one way.

Because Java Media Framework (JMF) is very performance-dependent, and the high-performance codecs for it platform-dependent, full media support in SMIL is not available with SavaJe XE currently. Any pure-Java JMF implementation can be dropped in to provide basic media support, within the limitations of the used implementation. This will also increase the installation size significantly, and so isn't included in the detailed sample configuration.

A build-target of "jar-ipaq" for ant has been provided for convenience. To trim down the distribution package, skin packs, virtual prototype and desktop browser user-interface elements are left out of the package by this target. It is recommended to turn off virtual prototypes and skin support in config for this reason, altough they work on SavaJE XE. The generated jar-file is also left uncompressed for optimal use on iPAQ's compressed flash filesystem, and a sample manifest-file for iPAQ is included. It is possible this build-target will do more in future.

Preparing the files

Choosing modules

Depending on the specific needs, different .jar files may be included, up to and including the whole X-Smiles distribution, storage-space allowing. See the latest installation instructions for details on the purpose of each included library file. The minimum needed for parsing XML content are xerces.jar, xalan.jar, xml-apis.jar, w3c.jar and sax.jar - with these, display of basic SMIL presentations and Xforms elements is possible.

The default manifest file for iPAQ builds, at src/ipaq.mf, contains classpath with aforementioned modules and fop.jar, needed for XSL-FOP rendering, svg.jar and ss_css2.jar needed for SVG rendering support, js.jar for JavaScript support and Tidy.jar for XHTML tidying.

Building X-Smiles

To build the xsmiles.jar for use on SavaJe XE, first make sure src/ipaq.mf has classes you intend to use included. Note that SavaJe XE will complain loudly about backslash characters escaping the newlines in manifest file, or missing files listed in their classpaths. Once this is done, refer to the platform-specific build-instructions for invoking ant, with the build-target jar-ipaq. This will build and package X-Smiles browser core classes into bin/xsmiles.jar, leaving the package uncompressed for use on a compressed filesystem.

Preparing library modules

For optimizing storage and performance on SavaJe XE platform, which utilizes a compressed CramFS filesystem, it is recommended to re-package any external .jar files stored on the device. This can be done for example with the equivalent of 'mkdir tmp; cd tmp; jar -xf ../file.jar; jar -c0f ../file.jar *; cd ..; rm -rf tmp' repeated for each .jar file. This isn't absolutely neccessary, but will save space and computing resources by avoiding double-compression - the -0 (zero) toggle for creating the jar-file is the important part here. In addition it will get rid of SavaJe XE's complaints due to strict parsing of manifest files.

Constructing jar-file index

Since handhelds will always have performance somewhat behind desktop machines, it is useful to take every little performance-enchancing trick into use for them. The jar-file index is one little known such trick. Once you've built the xsmiles.jar with the final classpath and placed the library modules into the relative paths specified in it, you can index your jar-files for faster class lookup with jar -i xsmiles.jar.

Unfortunately, the latest Xalan package employs the Services API, which appears not fully supported by the Sun jar tool, and Xalan doesn't provide a reasonable default. It is possible to get around this by extractig the indexed xsmiles.jar file, opening up META-INF/INDEX.LIST, adding META-INF/services under lib/xalan.jar and re-packaging the changes with jar -c0Mf to preserve the original settings. Easier ways to get by this are being tested currently.

Building the installation image

Installation instructions

First you need to acquire and install the SavaJe XE environment on your iPAQ. How to do this is detailed on the SavaJe web-site, so it isn't discussed in further detail here. Next you need to get the MkRomfs tool for extracting and creating SavaJe CramFS filesystem images. Extract the "apps.romfs" partition from the original SavaJe distribution with 'java -classpath romfs.jar com.savaJe.apps.romfs.extract apps apps.romfs'. Create a new directory for X-Smiles distribution, which should look something like:

/xsmilesroot/jnlp/xsmiles.jnlp
/xsmilesroot/xsmiles        - place xsmiles.jar here
/xsmilesroot/xsmiles/cfg    - copy bin/cfg directory here
/xsmilesroot/xsmiles/lib    - place all support .jar's here
/xsmilesroot/security       - copy apps/security/all.p here
/xsmilesroot/jre/savaJe     - copy and edit apps/jre/savaJe/guicfg.xml here
/xsmilesroot/VERSION        - copy apps/VERSION here

A sample xsmiles.jnlp is now included in the X-Smiles CVS repository, at src/xsmiles.jnlp. To add X-Smiles into the SavaJe XE GUI, you need to add the line:

<appbutton>file:///apps/jnlp/xsmiles.jnlp</appbutton>

into guicfg.xml, and remove the other appbutton lines, as they're no longer available.

When you're happy with the contents - if uncompressed, they may amount about 10 megs worth of data - run 'java -classpath romfs.jar com.savaJe.apps.romfs.mkromfs xsmilesroot xsmiles.romfs apps' in the directory right below xsmilesroot. The resulting xsmiles.romfs file should not exceed 5,767,168 (0x580000) bytes in size to fit on the device. Then follow the instructions for software update on SavaJe site to upload the xsmiles.romfs filesystem image into the "apps" partition.

After rebooting the device, run Tools->Lsh, and use the virtual keyboard to type in 'cp -R /apps/xsmiles/cfg .' - this procedure needs to be repeated every time the device loses power completely, by running out of battery, having the battery switch toggled or pressing the reset-button for too long! You could also run X-Smiles directly from the /apps/xsmiles directory, but then you would not be able to use the GUI startup link or save configuration changes.

After this, X-Smiles should be installed on the SavaJe iPAQ. If you want to view the log, open an Lsh window and type 'jnlp /apps/jnlp/xsmiles.jnlp', otherwise just clicking on the X-Smiles icon is enough. If you want to try using additional .jar files, your best bet is to store them on a CF card or load them over the network. In that case, add them to the xsmiles.jar manifest file classpath, or provided you didn't create the class-file index, into the xsmiles.jnlp resources section.