JavaVM Project

Taurus Java Virtual Machine v0.16a

The following release notes are applicable to the above version of the Taurus Java Virtual Machive. The copyright notice is applicable to any version of the VM unless stated otherwise.

Copyright notice

Taurus Software hereby grants you a non-exclusive, non-transferable limited licence (without the right to sub-licence) under Taurus Software's intellectual property rights. The licence entitles you to freely use, for personal, non-commercial use only, but not to distribute, the Taurus Java Virtual Machine. All binaries and code remain exclusively copyright Taurus Software.

The Taurus Java Virtual Machine has been produced, as a "clean room" implementation, in accordance with Sun Microsystems, Inc's (SUN) licence agreement for "The Java Virtual Machine" specification. Also, in accordance with this agreement the virtual machine distribution does NOT, to the author's knowledge, contain ANY material which is copyrighted by SUN. As such the class files relied upon by the virtual machine must be obtained separately, directly from SUN. The use of this specifcation does not in any way imply that the software conforms to it, nor does it imply that it will ever wholey do so. The Taurus Java Virtual Machine does not, and will not, ever pretend to be "Java compliant", it will always remain as closer approximation as time and money will allow. Users of this software do so at their own risk. Developers of any Java software should NEVER use this as a reference platform.

Taurus Java Virtual Machine is a trademark of Taurus Software. Sun, Sun Microsystems, the Sun logo, Java, JavaSoft are all trademarks or registered trademarks of Sun Microsystems, Inc. All other product names mentioned herein are the trademarks of their respective owners.

THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRIGEMENT. TAURUS SOFTWARE ACCEPTS NO RESPONSIBILTY FOR ANY DAMANGE, OF ANY KIND, CAUSED BY THE USE, OR MIS-USE OF THIS SOFTWARE. BY USING THIS SOFTWARE YOU AGREE TO THE LICENCING TERMS HEREIN.

TAURUS SOFTWARE RESERVES THE RIGHT TO REVOKE THIS LICENCE AT ANY TIME, FOR ANY REASON. THE "FREE" STATUS IS LIKELY TO CONTINUE AND THE APPLICATION OF THE GNU PUBLIC LICENSE IS BEING CONSIDERED.

All references to Taurus Software directly refer to the non-profit freeware/shareware software development unit run from the UK by myself. Any conflict with names of companies inside or outside of the UK is unintentional and should be disregarded.

Platform Support

The Taurus Java Virtual Machine version 0.16 alpha is provided in binary form only for the following platforms:

80x86 DOS (will run under Win 3.1x, Win 9x, Win NT)
EPOC16 (should run on all SIBO platforms, only tested on Psion Series 3a)

Both of these are early access releases of the real VM, which is still undergoing porting. If you require the full Wintel binary, then please email support at tsac.co.uk . Details of the full version (which the ports will eventually implement), can be found in the release notes.

Java Support

This early access release provides a limited subset implementation of the SUN Java Virtual Machine Specification. The key features of this release are as follows:

Loading and execution of Java applications - the VM can load and begin executing any Java application:
- For the DOS version this must be in a file called Hello.cla.
- For the SIBO version you should create an additional empty file of the same name as the class file, but with the extension .jvm. e.g. Hello.jvm
Dynamic loading - classes are loaded as needed, exceptions or errors are reported when a class cannot be found
Limited ability to write text to the screen.
Limited graphics capability in SIBO version through Taurus OPL library.

There are few major restrictions on this demo release:

Can interpret only around 60% of Java virtual instructions (the majority of the 40% remainder are long, float and double operations, which have been intentionally left out) - see Appendix I
Classfiles must be named using 8.3 filenames - the file extension for classes is .cla (NOT .class)
Package names and CLASSPATH are ignored - all files are loaded from the same directory
No support for Java Exceptions, Applets, AWT, Threads or Garbage Collection

Windows Installation

Unpack the downloaded ZIP file containing the VM into a suitable directory (e.g. C:\JavaVM). The VM executable is called javavm.com and the classes it loads are in the subdirectory classes. Run the VM from this directory (it looks for the classes directory relative to where you start it!). The DOS version does not accept command line arguments.

SIBO Installation

Unpack the downloaded ZIP file containing the VM into a temporary directory (e.g. C:\Temp). The VM executable is called javavm.img, in the subdirectory app, and the Java classes it loads are in the subdirectory classes.

Copy the executable into the APP directory on the Psion (create one if you don't have one). Copy the classes into a new directory called CLASSES on your Psion. Note that the VM uses the absolute path to find classes, so CLASSES must be created on the RamDisk (M:).

To run the VM you first need to install it. Select Install from the System menu. Now select Javavm.img in the install dialog and press return. You may wish to choose to install the icon in the "Last" psoition. You should now have a JavaVM icon on you screen.

The SIBO version lists all .JVM files in the CLASSES directory. [This file will eventually contain the command line used to start the application - for the moment, just create an empty file for each Java application you wish to run.] Select one of these files and the corresponding class file will be loaded and executed.

Minimum requirements

The VM functions in a much smaller environment than provided by the JDK classes. The classes provided are: a simple System class, providing a single out stream; a cut down Object class; and a natively implemented PrintStream class. This should give you the basis to do some computation and show the output.

To make your own environment, you need to implement a set of Java classes similar to those provided by Sun. The main reason for doing this on a small platform is to cut down the amount of crap that gets loaded before any of your classes, and to cut out the surplus junk you will never use. I am currently looking at SUN's Personal Java and Embedded Java specifications, and the ideas behing the KVM and Java 2 Micro Edition for some approved ways of shrinking the VM - System.out loads an awful lot of classes!

My personal environment includes cut down versions of the String and StringBuffer classes so that I can use String concatention, as produced by the Java compiler. This includes Sun code, so they cannot be shipped with the VM.

Memory and diskspace requirements are as follows:

Description SIBO DOS

Executable (disk) 40 Kbytes 61 Kbytes

Class files (disk) ? bytes ? bytes

Runtime (memory)
   Screen
   Code
   Static area
   Data ? Kb
? Kb
? Kb
? Kb
? bytes ? Kb
? Kb
? Kb
? Kb
? bytes

Description	SIBO	DOS
Executable (disk)	40 Kbytes	61 Kbytes
Class files (disk)	? bytes	? bytes
Runtime (memory) Screen Code Static area Data	? Kb ? Kb ? Kb ? Kb ? bytes	? Kb ? Kb ? Kb ? Kb ? bytes

Taurus OPL Library

The 0.16 release of the Taurus Java Virtual Machine sees the addition of a new class library to allow the use of simple graphics from Java on SIBO machines. This library was originally created as part of the opl2java project. The original version of this library provided an emulation of built-in OPL functions under Java, allowing OPL application to be deployed as a Java applet. The same API is used here, but is implemented natively on the SIBO machine.

Using opl2java it is possible to do a round-trip: 1) take an OPL program which runs on a Psion; 2) run it through opl2java; 3) run the resulting java code on the Taurus JavaVM on your Psion. At the moment this only works in a limited capacity, but it proves that useful Java applications could be run on a Series 3.

See Appendix II for a list of supported methods and the associated Javadoc documentation provided for detailed programming information.

Support

The VM is offered with no warranty and no support. I cannot guarentee it will run on your machine, and any programs written specifically to run on the Taurus VM are not guarenteed to run on future versions. One or two strange problems showed up which caused the VM to hang - I suspect lack of memory on my 256k 3a - but it could be killed from the System screen. Another problem also prevented the VM from running until it was re-installed. The VM should not corrupt any files on your machine, but I cannot make any guarentees, and will not be held liable to damage caused either directly or indirectly by this software. If you have valuable data on your machine, then please back it up first.

Missing features, bugs etc. will be fixed as part of the porting procedure, so keep checking the website for updates.

Feedback

The primary reason for releasing such an early access release is to get feedback aimed at getting the features you want working on the platforms you want. This early access is quite restrictive I know, but most of the core functionality is in place, it really only remains to finish porting the VM instruction set (mainly conversion from ANSI to K&R C) and native methods (which mostly require a re-write).

Please feel free to send any CONSTRUCTIVE comments to support at tsac.co.uk .

Appendix I - Instruction Set

This early access release does not implement certain virtual instructions. These are mainly long, float and double operations, but some array, stack and type conversion operations are also missing. Missing instructions will cause the VM to exit and report the error "unknown instruction". If you run the DOS version with the same classes, it will report both the name and number of the offending instruction.

Appendix II - Native Methods

The VM implements the following native methods. You need to provide an appropriate native declaration in you classes to use them:

Class	Method	Purpose
java.lang.Class	getName( String )	Class_getName
java.lang.Class	getPrimitiveClass( String )	Class_getPrimitiveClass
java.lang.Object	clone()	Object_clone
	getClass()	Object_getClass
	hashCode()	Object_hashCode
java.io.PrintStream	newLine()	PrintStream_newLine
	write( String )	PrintStream_writeLString
	write( int )	PrintStream_writeI
java.lang.System	arraycopy( Object, int, Object, int, int )	System_arraycopy

Appendix III - Taurus OPL Library

The following native methods are also provided for use with the Taurus OPL library:

Class	Method	Purpose
psion.opl.OPL	gAt( int, int )	gAT x%, y%
	gBox( int, int )	gBOX w%, h%
	gCreate( int, int, int, int, int, int )	gCREATE x%, y%, w%, h%, g%, v%
	gFill( int, int, int )	gFILL w%, h%, m%,
	gGrey( int )	gGREY m%
	gLineBy( int, int )	gLINEBY w%, h%
	gPrint( String )	gPRINT s$

Last updated 18th Oct 1999
Comments support at tsac.co.uk