The Eve Virtual Machine and SDK

Is Eve an Evolution of Ewe?

The major underlying difference between the old Ewe VM and the new Eve VM is that Eve supports the Java Thread API. This includes the Thread class, and the synchronized/wait()/notify() keyword and methods.

This difference has two major implications:

The native VM had to be rewritten completely.
The Java libraries had to be substantially rewritten.

However the main benefit of supporting Java threading makes the major work involved completely justifiable: now standard java.xxx classes could be used in the library instead of ewe.xxx classes which mimicked their java.xxx counterparts using the workable, but incompatible Ewe threading model. Thus, instead of having eve.io.InputStream classes, the java.io.InputStream class could be used instead. This principal applied to dozens of classes. Hence the main difference in the runtime class libraries are:

Large numbers of ewe.xxx classes have been discarded and replaced with standard java.xxx classes.

This immediately relieves the vast majority of porting problems when writing applications for the Eve VM. Not only do far fewer new classes have to be learned (standard Java classes would work most of the time) but existing applications and libraries could be far more easily ported to the VM.

The other major change is in the GUI. The functionality and look of the GUI in the new VM is almost identical to that of Ewe but with a much better naming convention and better organization of classes into separate independent packages.

What is Eve?

Eve is a portable Virtual Machine that executes Java byte code (i.e. Java “.class” files) and has been specifically designed to run well on mobile devices as well as on the desktop. Standard Java started on the desktop and attempted to scale down to mobile devices with (unsurprisingly) little success. Eve started on mobile devices and scaled up. The result is VM that performs well on all devices and provides APIs that are mobile aware instead of forcing mobile devices to emulate desktop systems. Other mobile oriented features include:

Awareness of the pop-up software Input Panel present on many mobile devices (such as PocketPCs). You actually have control over how your UI elements respond to this instead of being forced to accept the default behavior.
Awareness of devices that may not support multiple windows. The standard Eve UI library allows you to program as if multiple windows are supported and will simulate the windows if necessary. Or you can determine the graphics capabilities at runtime and alter your user screens accordingly.
The VM’s Java class library is embedded in the VM after being modified in a way that allows for direct memory mapping. This means that running a second instance of the VM takes up far less memory than would be using standard Java classes.
An API that allows Eve applications running on Windows Mobile devices to communicate with applications on the desktop over the ActiveSync connection.

Eve Compared to Standard Java

Like other Java Virtual Machines, Eve comprises of a natively executable VM along with a library of Java classes. On Windows and Linux desktop systems the VM is a single executable called eve.exe (on Windows) or eve (on Linux). On Windows Mobile systems it is split between a small executable launcher eve.exe and the VM itself in a DLL called eve.dll.

The Eve VM executes Java class files according to the Java Virtual Machine specifications. However the standard class library associated with the Eve VM does not conform to any of the numerous Java standards. The decision to not follow any particular standard was taken since Eve was designed to be portable from devices as small as Smart Phones to full desktop computers. Currently, no Java standard works well on all devices. Java Micro Edition (JME) is too limited for any device larger than a Smart Phone, the Java Standard Edition (JSE) simply cannot fit and run on the vast majority of mobile devices, and PersonalJava has apparently been abandoned.

The only Java standard that Eve will attempt to eventually implement is MIDP. The class library of the Eve VM is currently being extended to implement the MIDP 2.0 standard since the MIDP’s limited functionality is already a subset of the capabilities of the VM and there are many MIDP applications currently in use.

Important Information on the Eve Class Library

All classes in the Eve class library are either in java.xxx packages or in eve.xxx packages. It is important to note the following points about the java.xxx library.

Although the library contains a number of java.xxx packages, all the classes available in the standard Java 2 package will not necessarily be available in packages of the same name in the Eve library. For example the Java 2 java.util package is very large and only a limited number of those classes are available in the java.util package on the Eve VM.

A java.xxx class in the Eve library may not implement all the methods in the corresponding class in the Java 2 library but will generally implement the majority of the methods.
A java.xxx class in the Eve library will not have methods that are not in the Java 2 library thereby retaining full compatibility.
All methods in java.xxx classes in the Eve library will operate in the same way as those methods in the Java 2 library.

In short, the java.xxx packages and the classes contained therein in the Eve class library can be thought of as a compatible subset of the Java 2 library. This means that a Java application written to specifically target the Eve VM can also be run by a standard Java 2 VM. But applications targeting the Java 2 library will not necessarily work on the Eve VM.

A JAR file is provided (“eve.jar”) which contains all the eve.xxx classes customized as necessary to run on a standard Java 2 VM. Therefore it is possible to use a standard Java 2 VM (such as Sun’s Java VM) to run Eve applications by placing this JAR file within the classpath. In fact, this is the recommended way to test Eve applications during development.

Using a command line you would run an Eve application with the main() method in the class called my.class.name using the native Eve VM like this:

eve -cp <my/class/path> <my.class.name> [program arguments] …

Or you could run the same application using a Java VM like this:

java -cp eve.jar;<my/class/path> Eve <my.class.name> [program arguments] …

Note that the only differences are the inclusion of eve.jar in the classpath and the fact that class that you must always run is Eve (case sensitive). The “Eve” class (contained in eve.jar) initializes critical parts of the Eve VM library and then proceeds to execute the specified application class file my.class.name.

Writing Applications for the Eve VM.

Writing applications for the Eve VM is no different from writing for any other Java VM and virtually any Java IDE or command line compiler will compile Eve applications. Eclipse is recommended because it is powerful, cross-platform and free.

In order to write and compile Eve applications you will need two items, both of which are included in the SDK.

The javadoc generated Eve API documentation.
The file CompileEve.zip which contains the class libraries needed for compilation.

In order to debug Eve applications using a Standard Java VM you will need the file: JavaEve.zip. This file contains the pure Java versions of all classes in the CompileEve.zip file along with their source code. This allows you to trace into the source code of the Eve library if needed. Additionally the DLLs java_eve.dll (on Windows) and libjava_eve.so (on Linux) are included and are needed to allow the Java VM to provide functionality provided by the Eve VM but not in standard Java libraries.

In order to run Eve applications using the native Eve VM you will need to install the desktop version of the Eve VM on your computer.

In order to run Eve applications using the Standard Java VM you can again use JavaEve.zip but you can also use eve.jar which contains the same classes as JavaEve.zip but without the source code and without debugging information. It therefore provides the same runtime library but is much smaller.

For details on how you would setup an IDE such as Eclipse to compile and debug Eve applications please see this file and select Beginners Programming Guide.

Capabilities of the Eve VM.

General Capabilities

Applications (class files) and program resources may be loaded from standard Zip and Jar (Java Archive) files as well as via specially formatted “.eve” files. The Ewe VM would allow an application to access files in a Zip/Jar file at runtime – but these files could not be placed in the “classpath”.

Full TCP/IP network support including support for IPv6. Infra-Red communication over IR-Sockets is also implemented. The Ewe VM did not support IPv6.

A Native Method Interface which allows applications written in Java to access device specific C/C++ APIs via the native Java keyword and a dynamic linked library. This works in the same was as the Java Native Interface (JNI) and applications written in the Eve Native Interface automatically provide a JNI API for use with Java 1.2 compliant VMs.

Mobile Device Specific Features

A full Desktop-to-Portable Device Communication API is provided along with synchronization utility classes. This API works the same over ActiveSync (used for syncing WindowsCE/Windows Mobile devices on a Windows PC) or over a network (used for synchronizing Linux devices). This API allows your Java/Eve applications on the desktop to automatically run, connect to and communicate with your Eve applications on your mobile device through a standard Socket.
Built-in Application Launcher. The Ewe VM contains a built in launcher that lets you add to and edit a list Eve applications and then run them directly from the launcher. There is no need to type or fiddle with cumbersome command lines. After your application is packaged in an .eve (or .zip) file you simply use the VM and built in file browser to locate the application and add it to the list.

Eve applications can be loaded remotely (across a network or across the ActiveSync connection) onto any other computer or device with the Eve VM installed. The Eve VM Launcher (which works on all platforms) can act as a Remote Application Server and provide application classes and resources to another Eve VM running as a Remote Application Loader. This means you can test your application on your mobile device without having to package it or copy it across as individual classes or .eve files.

Mobile devices have very different display and user input issues than desktop computers. Unfortunately, standard Java does not provide you with methods of customizing the drawing surface before the VM begins and sets up its GUI system. In the Eve VM, a pre-main method (called eveMain()) can be defined which will run before the normal main() method. Within this method you have a chance to setup the GUI and windowing system as you wish before the standard UI initializes. This can be used, for example, to rotate the screen (if possible) and disable multiple window support.

Native Text Input is available (and is the default when run on certain devices) allowing the use of the device’s “native” text input methods instead of Java versions of text widgets. This is useful for devices like Smart Phones where simulating the different text inputs natively available on the phone would be too tedious.
Runtime discovery of device capabilities is fully supported. For example you can determine at runtime if the device supports a mouse, or if a stylus and touch screen is used or if only keyboard entry is supported. Many other aspects of the device are also discoverable.

Unique Developer Tools

Mobile Devices can be simulated on the desktop. The desktop version of the VM accepts command line switches that cause it to simulate different devices. Switches like /p indicate that it should emulate a PocketPC (along with simulation of the pop-up input panel) and /s indicate that it should emulate a Microsoft SmartPhone with soft keys. You can also specify the size of the screen and the type of input that is supported.
Native Windows and Linux executables can be created from Eve applications. After you write your Eve application in Java and package it in a “.eve” or “.zip” file you can link with the VM to create a self contained native Windows .exe complete with its own icon. This works for both desktop and mobile versions of Windows.
Automatic conversion to Applets. An Eve application can be run automatically within a Web Browser as an Applet without modifications. A virtual file system can even be set up so that you can fully demo desktop applications over the web complete with file loading and saving. Standard Applet security restrictions on access to local resources and networks will still apply.

Architecture of the Eve VM.

The Eve VM and library is designed to be very modular – far more so than the Ewe VM. The libraries for the VM and the types of devices that are available generally suggest four possible incremental versions of the VM.

Eve Embedded (Command Line)– a version with no GUI interface that would either have no user interaction or interact via a device specific interface (e.g. a serial port). This version is generally only of interest to manufacturers or developers for specific devices.
Eve Mobile Edition – this consists of Eve Embedded along with the full Eve GUI library. This would be suitable for PDAs, PocketPCs and advanced Windows Mobile 5 SmartPhones.
Eve Desktop Edition – this consists of Eve Pocket along with a simple database API, a Printing API and some advanced GUI features.

A Mobile Edition can be upgraded to the full Desktop Edition by simply installing a single eve-extended.eve file into the same installation directory as the VM itself.

The Eve Libraries

Eve Embedded (Command Line) – This include the following packages:

java.lang – Standard Java classes, including Thread, StringBuilder, etc.
java.lang.ref – Standard Weak/Soft/Phantom Reference support.
java.lang.reflect – Standard Reflection API including Proxy.
java.math – Support for BigInteger and BigDecimal classes.
java.io – Standard Java I/O classes.
java.net – Standard Java Network classes (including IPv6 support).
java.util – Standard Java Utility/Collection classes. Not as extensive as the Java 2 java.util library, but with sufficient classes for most applications.
java.util.zip – Standard Java compression classes.
eve.data – Utility Data Classes.
eve.io – File access and extra utility I/O classes.
eve.sys – Eve VM specific system classes.
eve.util – Extra Utility/Collection classes.
eve.math – Alternative support for BigInteger and BigDecimal.
eve.net – Extra Network classes.
eve.zipfile – ZipFile access with a smaller and more flexible API than java.util.zip.

Eve Mobile Edition, contains these additional packages:

eve.fx, eve.fx.gui, eve.fx.sound – These packages provide low-level access to the device graphics, sound and user interface.
eve.net – Provides extra networking utilities as well as the PC to Device communication API.

eve.ui, eve.ui.event – A full GUI implementation, complete with multiple windows, frames, and standard widgets.
eve.ui.table – Support for Table and Tree controls.
eve.ui.filechooser – Support for an advanced FileChooser dialog.
eve.ui.data – Support for the Editor class – a type of Form that allows for direct transfer of data between widgets and class fields.
eve.ui.game – Support for Forms designed to be used with animated images and board based games.
eve.math, eve.security – Together provide classes for encrypted data storage and communication.

Eve Desktop Edition, contains these additional packages:

eve.database, eve.database.implement, eve.ui.advanced.database – Provides the specifications for the simple Eve Database API and a simple file based implementation.
eve.fx.points, eve.fx.print – Provide support for printing documents.
eve.ui.table.registry – Provides more advanced GUI elements and a very simple HTML viewer.

Customizing the Eve VM

Replacing/Reducing the Java Library

The Eve VM consists of a native executable which will vary in size between 700KB to 1MB depending on the target platform, and a Java class library 3MB in size for the full desktop version (a full 1MB of which is used by the eve.ui libraries). In devices where space is at a premium, customized versions of the VM can be produced with a more limited class Library. Utilities to do this customizing will soon be made available to developers.

Customizing/Replacing the UI

The Eve VM implements the user interface in two distinct layers. The lowest levels are contained in the packages: eve.fx, eve.fx.gui, eve.fx.sound. These are very basic APIs and expose the lowest levels of user interface provided by the underlying system. This includes classes representing a Window (or the devices drawing area if true windows are not present), Graphics contexts for drawing onto Windows and Images, and simple event trapping for Window changes, pen/pointer events, key-press events, resize events, paint events, macro text events and input panel events.

The eve.ui packages are all built on top of the eve.fx and eve.fx.gui libraries but are not used by any other packages, allowing them to be completely replaced by any other GUI library. An AWT or SWT or even SWING library could be implemented over the eve.fx packages.