SourceForge Logo
  [overview]  [Waba]  [status]  [links]  [screenshots]  [survey]  [SF:summary]   [SF:downloads]  [SF:CVS]


History of this document

2001.04.02 First draft of the WSDD.
2001.04.03 Add Internationalization topic.
2001.04.09 Add some new topics : Long and Double implementation, and a
           new "date" class.
2001.04.09 Start discussion for defining Priority. Due Date: 2001.04.16
2001.04.16 Start discussion for Topic "Define the scope of this
2001.04.17 Add comments from Guich.
2001.04.24 Start discussion for Topic "1.0 Compatibility issues"
2001.04.30 Start discussion for Topic "Package Naming Convention"
2001.05.07 Start discussion for Topic "Version Numbering scheme"
2001.05.14 Start discussion for Topic "Long and double implementation"
2001.05.21 - Start discussion for Topic "Internationalization"
           - Add comments from Sean.
2001.05.30 Start discussion for Topics "Threads implementation" and
           "Exceptions Handling"
2001.06.18 - Start discussion for Topics "Dynamic Class Loading" and
             "Applet Support"
           - Add a global time table (see section "Planning for the
             whole WSDD")
2001.07.02 - Correction of the english by Tom Hollins
           - Add topic "RMI Support" in Topics F (request of Noel)
	   - Add class MainWindow in topic "Classes to modify" (request
	     of Scott)
	   - Add comment for "class Class" about Reflection
           - Start discussion for Topic "Class File Format"


Olivier Bornet,, SMARTDATA SA


Before anything else, we warmly thank Rick Wild, creator of the first
Waba Virtual Machine.

New versions of this document

The last version of this file is available on the Word Wide Web at


To clarify this document, some terms need explanation.

Waba : in this document, Waba is used to designate the Common Waba
  Specification. When we talk about a specific implementation, this will
  be mentioned.

WSDD : Waba Specification Document Draft. This file/document IS the

WSD : Waba Specification Document. This designates the final document.
  It will be different than this file because only the final decisions
  will be contained in that file in order to have a clear specification.

VM : Virtual Machine. There are several virtual machines with different
  features and machine requirements. See the web site cited in the
  Virtual Machine's documentation for more information. We will not
  explore their features in this document. Examples of virtual machines:
  WabaVM, SuperWabaVM. WabaVM is the core and the others extend this
  core functionality (hence this document).

Waba VM : Virtual Machine implementing the Waba API. Although WSDD/WSD
  have nothing to do with implementations, many implementations are
  cited in the WSDD/WSD. The mention of the VM in this document in no
  way certifies that the VM is "Waba Compliant".  A list of the Waba
  Compliant VMs will be done in the future.

RMI : Remote Method Invocation. More information is available at

Planning for the whole WSDD

Topics A: General
    Due date  : Monday 14 May 2001.
    Finalized : Monday 14 May 2001.

Topics B: Core VM
    Due date  : Mid July 2001.
    Finalized :

Topics C: Core API
    Due date  : Mid August 2001.
    Finalized :

Topics D: Extensions API
    Due date  : Mid September 2001.
    Finalized :

Topics E: Platform Specific API
    Due date  : Mid October 2001.
    Finalized :

Topics F: Specific Features
    Due date  : Mid November 2001.
    Finalized :

Resources involved in this specification

Discussion on the Waba Specification described in this document is done
mainly via the mailing list waba-spec. The current projects of Waba VM
(or related projects) with persons involved in the discussions are :

    - WabaSoft
    - Waba @ SourceForge
    - SuperWaba
    - WabaCE
    - Newton Port
    - J9 Port of the Waba API
    - WabaJump API
    - Jump Software Development Tool

The newsgroup pilot.programmer.waba will be keep informed of the
evolution of the WSDD at every main points. Everyone interested in the
details are welcome to subscribe to the mailing list waba-spec.


This document will define the specification of the next Waba API.

The standardization of the Waba API is now a must-have, due to different
implementations which exist. It's time to have a standard base for the
evolution, so programs using this standard base can run on every "Waba
Compliant" implementation.

The base of discussion is the Waba 1.0 API from Wabasoft, and the
"Javadocs Documentation Server" setup by Scott.

High level definition of the Waba API

Before having discussions, the Waba API must follow these requirements :

0. Open Source.

We strongly believe the Open Source model is necessary for this project.

1. Portability.

The first priority of the Waba API is portability. Regardless of the
platform, operating system, or Waba VM, an application written to the
specification outlined in this document must run.

2. Small and fast.

The Waba VM is designed for running on small devices with limited
resources. It is very important to use a minimal amount of memory and to
run on low end CPUs. Your program should take into account the number of
processing cycles it uses.

Planning of the WSDD/WSD

This chapter will explains the current state of planning. We are now
working on point 4, but points 2 and 3 are not yet finalized.

1. Objective : Planning approval.
   Decision  : No objection, so the planning is approved.
   Due date  : Thursday 29 March 2001.
   Finalized : Monday 02 April 2001.

2. Objective : Setting up a "documentation server" with all the
   Decision  : 
   Due date  : ( Scott ? )
   Finalized :

3. Objective : Select one guy which will be the "Final Judge" which make
   decisions when people do not agree. This will be either a neutral
   person (not the developer of a specific implementation) or
   responsible for the "Official Waba" (currently Rick).
   Decision  :
   Due date  : Monday 2 April 2001.
   Finalized :

4. Objective : Making an initial list of all topics to discuss.
   The topics are not final, and will continue to evolve.
   Decision  : See chapters "Topics" for more information.
   Due date  : Monday 9 April 2001.
   Finalized : Monday 9 April 2001.

5. Objective : Assign priority to the topics.
   Decision  : No special comment, so my proposed priority is accepted.
   Due date  : Monday 16 April 2001
   Finalized : Monday 16 April 2001

6. Objective : Begin discussion of every topic.
   Open Topic(s)          : "Define the scope of this specification"
   Decision               : See the current topic for details.
   Due date (all topics)  :
   Finalized (all topics) :

7. Objective : Release the WSD.
   Decision  :
   Due date  :
   Finalized :

8. Objective : Implementation of the Waba API
   Decision  : See Waba VM specific projects.
   Due date  :
   Finalized :

9. Objective : Maintain a list of "Compliant Waba Implementations".
   Decision  :
   Due date  :
   Finalized :

Topics A: General

Define the scope of this specification
   Due date  : Monday 23 April 2001
   Finalized : Tuesday 24 April 2001

   WSD will :

    - cover the core classes
    - give some hints for persons who will write extension classes
      (like package name, what we can do and what we can't do, ...)
    - don't cover platform specific classes, but give hints similar to
      the extension classes, especially for package naming

1.0 Compatibility issues
   Due date  : Monday 30 April 2001
   Finalized : Monday 30 April 2001

The New API must be compatible with the Waba 1.0 API from Wabasoft as
much as the hardware allows. Compatibility problems must be very well
documented, and if possible isolated in code for easier porting.

To help a user migrate their applications, every Waba Virtual Machine
implementing the WSD must give to the user the possibility to run an
old 1.0 application either by giving flags at startup, or by using
directly the 1.0 classes. This migration help must be re-evaluated at
every major release of the WSD.

Due to the number of diverging VMs (like SuperWaba, WabaCE,
Waba for the Newton, ...), no demands are made for compatibility with
all implementations except for the official Wabasoft 1.0 API. Of
course, new implementations can give the user some compatibility
hints and methods, but this is not a requirement.

Existing VMs are not obligated to throw out code they  have added to
their API's to be considered compatible with the spec, but it is
highly recommended they document which features are not compatible.

Existing VMs also will have to conform to the new conventions for
extending the Waba environment, and that means that their extensions
must either follow the "Package Naming Convention" or go outside the
waba and org.wabavm trees.

Package Naming Convention
   Due date  : Monday 07 May 2001
   Finalized : Monday 07 May 2001

Package naming must follow these points :

    - what is in the "core classes"
    - what follows the java.* classes (like for example
    - what is platform-dependent
    - how to name extensions of the API
    - what is the minimal API

To agree with this rules, class naming will follow this syntax :

    -                   is the equivalent to
    -             are the other "Waba VM Core Classes"
    -    are platform dependent packages
    -         are extensions supported by WSD
    -                    are all other extensions

This produces the following class tree :

|  |
|  +--io
|  |
|  +--lang
|  |
|  +--util
|  |
|  +--wabavm
|     |
|     +--fx
|     |
|     +--sys
|     |
|     +--ui
|     |
|     +--util
|     |
|     +--platform
|     |  |
|     |  +--palm
|     |  |
|     |  +--win32
|     |  |
|     |  +--newton
|     |
|     +--ext
|        |
|        +--ext_1
|        |
|        +--ext_2
|        |
|        +--...

This tree is not fully defined, and is given only for clarification
of the current ideas. Every main branch can have more (or less)
children and will depend on future class discussions. Please note:
ext_1 and ext_2 are just sample names. The real extension will have a
name which will describe clearly what the extension is., and are fully defined in this document. are outside of the scope of this document.

The minimal tree needed to run a Waba VM is and, without org.wabavm.platform and org.wabavm.ext. It
should also be possible to remove the graphical branch of the tree
(like fx and ui) to run applications which don't use graphics. Examples
of these programs would be standard embedded platforms which only have
communications interfaces and no other i/o.

An effort will be done to make the branch as
small as possible. Remember: one of the main goals of Waba is to be
platform independent.

A compatibility mode must be available translating every 1.0 waba.fx,
waba.sys, etc to the corresponding org.wabavm.fx, org.wabavm.sys, etc in
every Waba Compatible Virtual Machine.

Version Numbering scheme
   Due date  : Monday 14 May 2001
   Finalized : Monday 14 May 2001

This document specifies the version 2.x of the Waba API. No specific
version numbering exists to separate the minimal API and the

Minor release (eg. 2.00 to 2.01) reflects minor changes to the API, like
adding some methods, or incorporating a useful extension. Minor releases
do not break compatibility. This means a program designed for version
2.03 will continue to run without modification on version 2.04 or 2.05
and so on.

Major release (e.g. 2.x to 3.x) reflects changes in the API, like
modification of existing methods, suppression of methods/classes which
break compatibility.

Virtual Machines have their separate numbering schemes and are free to
do so.

To reflect this, the waba.sys.Vm package needs to be extended and have
at least this methods :

    - getVersion()     for compatibility only. Use getAPIVersion() or
                       getVmVersion() when possible.
    - getVmVersion()   return the version of the Virtual Machine
    - getAPIVersion()  return the version of the implemented Waba API.
    - getExtensions()  return the list of available extensions.

getVersion() and getAPIVersion() will return an int. The major version
is base 100. For example, version 1.0 has value 100. Version 2.0 has a
version value of 200. A beta 0.8 VM will have version 80.

    int Vm.getVersion();
    int Vm.getAPIVersion();

To accomodate every implementation, getVmVersion() will return a
String. This String depends on the Virtual Machine implementation.
For example, SuperWaba 2.0 can have "superwaba 2.0",
WabaCE can have "WabaCE xxx"...

    String Vm.getVMVersion();

getExtensions() will return a String array with the list of all the
available standard extensions. The returned Strings correspond to the
short package names. For example, if we have these packages :
org.wabavm.ext.ext_1 and org.wabavm.ext.ext_2, getExtensions() will
return an array of 2 elements : "ext_1" and "ext_2".

    String[] Vm::getExtensions() { };

Topics B: Core VM

Long and double implementation
   Decision  :
   Due date  : Monday 21 May 2001
   Finalized : Monday 21 May 2001

The long and double implementation will be done as follows:

- if the system supports doubles, do doubles. Otherwise treat doubles as
  floats.  You don't want to get involved in emulating double math
  arithmetic if you don't need to.

- if the system supports longs, do longs. Otherwise store a struct
  internally like struct _LONG { signed int hi; unsigned int low; }, and
  implement the math opcodes to do the math.  Have the programmer use a
  #define _LONG 1 to implement/include the long structure.

   Due date  : Monday 28 May 2001
   Finalized : Wednesday 30 May 2001

Every implementation must support internationalization. At least, one
code page must be implemented.  The documentation of each
implementation must clearly list which code pages are supported.

Threads implementation
   Due date  : Monday 11 June 2001
   Finalized : Monday 18 June 2001

Waba doesn't need to implement threads at this time. If a specific VM
implements threads, you must clearly document how to use them.  Also,
implementing threads must not break execution of non-threaded

Exception Handling
   Due date  : Monday 11 June 2001
   Finalized : Monday 18 June 2001

Waba doesn't implement exception handling at this time, but this will be
the next "major improvement" in the specification.

Dynamic Class Loading
   Due date  : Monday 02 July 2001
   Finalized : Monday 02 July 2001

Waba support Dynamic Class Loading. For this, two new methods exist in
the waba.sys.Vm class :

    public Object createInstanceForClassname( String classname );
    public String className( Object instance );

An example of utilisation will be added here in the future.

Applet/Java Support
   Due date  : Monday 02 July 2001
   Finalized : Monday 02 July 2001

To simplify the development of Waba Applications, bridge classes must
be implemented. With the help of this classes, you can run the Waba
Application directly from a standard Java Application. No
modifications must be made to the original Waba Application.

Running the Waba Application as an Applet must also be possble with
the bridge classes.

Class File Format
   Decision  : Will wait on the result of discussions with Rick
	       before taking a decision
   Due date  : Monday 07 July 2001
   Finalized :

The Class File Format is the same a the Java Class Format. This
feature give to the developer the ability to create/modify application
with standard Java developement tools.

Common File System or Database format
   Decision  :
   Due date  : 23 July 2001
   Finalized :

Do we use a common file system or database format ? And for what ?
Only classes, or also data applications ?

Topics C: Core API

"Java-like" classes to implement
   Decision  :
   Due date  :
   Finalized :

Selection of the standard Java classes to implement.

Selection of the classes to put in the minimal Waba API (core class)
   Decision  :
   Due date  :
   Finalized :

We need to select the minimum set of classes for running a Waba

If the scope of the WSD is also optional classes and/or platform
specific classes, we also need to define the classes of every set.

Classes to modify
   Decision  :
   Due date  :
   Finalized :

The following classes need to be extended/modified :

    - class Object
    - class Catalog
    - class Font
    - class Stream
    - class SerialPort
    - class MainWindow : pass command line parameters
    - ...

When we open this point, we will discuss only one class at a time.

New Classes
   Decision  :
   Due date  :
   Finalized :

The following classes need to be implemented :

    - class Class : to support Reflection
    - ...

When we open this point, we will discuss one class at a time.

Separation between classes in the VM or not
   Decision  :
   Due date  :
   Finalized :

Do we make separation between Core classes , some classes directly in
the VM, and others not ? And, for classes not in the VM, where to put
them ? In the application or in a separate "library" ? If we decide to
make some separation, we must also make the decision for every class
where to put them.

Topics D: Extensions API

Date Handling
   Decision  :
   Due date  :
   Finalized :

Thanks to Rony G. Flatscher, a package for handling the date is
available at :

We need to decide if this must be in the core classes, in the
optional classes, or if it will stay a separate package.

Topics E: Platform Specific API

No point for the moment. This will surely change in the future.

Topics F: Specific Features

IRDA handling
   Decision  :
   Due date  :
   Finalized :

Do we put infra-red handling in the WSD ? If yes, how ?

J2ME Compliance

What is necessary to get Waba J2ME certified like Sun's KVM ?  How far
should we go in achieving this goal ?

RMI Support

An RMI lite implementation for waba exist at Do we incorporate it in the
standard Waba specification ?

Related links

Rick Wild:

Discussion groups
waba-spec mailing list:
pilot.programmer.waba newsgroup:

Javadocs Documentation Server by Scott: ...

VM/API Ports
Waba 1.0 VM :
Waba @ SourceForge :
WabaCE :
Newton Port:
J9 Port of the Waba API:
WabaJump API:
Jump Software Development Tool:

Specific Classes Packages


Waba, WabaVM and WabaSDK are trademarks of Wabasoft Inc.

Contact information

To contact us, send an email to, or visit the
waba-spec mailing list.

Happy Waba Programming !

(c) 2001 Olivier Bornet,
All Rights Reserved

  © 2000-2001   Last Update: July 16, 2001