WABA SPECIFICATIONS DOCUMENT DRAFT
**********************************
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
specification"
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"
Authors
=======
Olivier Bornet, Olivier.Bornet@smartdata.ch, SMARTDATA SA
Thanks
======
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
http://waba.sourceforge.net/waba-spec.txt
Terminology
===========
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
WSDD.
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
http://java.sun.com/products/jdk/rmi/index.html
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.
Introduction
============
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
javadocs.
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
java.lang.String)
- 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 :
- waba.xxx is the equivalent to java.xxx
- org.wabavm.xxx are the other "Waba VM Core Classes"
- org.wabavm.platform.xxx are platform dependent packages
- org.wabavm.ext.xxx are extensions supported by WSD
- xxx.xxx are all other extensions
This produces the following class tree :
+
|
+--waba
| |
| +--io
| |
| +--lang
| |
| +--util
|
+--org
| |
| +--wabavm
| |
| +--fx
| |
| +--sys
| |
| +--ui
| |
| +--util
| |
| +--platform
| | |
| | +--palm
| | |
| | +--win32
| | |
| | +--newton
| |
| +--ext
| |
| +--ext_1
| |
| +--ext_2
| |
| +--...
|
+--xxx.xxx
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.
waba.xxx, and org.wabavm.xxx are fully defined in this document.
xxx.xxx are outside of the scope of this document.
The minimal tree needed to run a Waba VM is waba.xxx and
org.wabavm.xxx, 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 org.wabavm.platform.xxx 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
extensions.
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.
Internationalization
--------------------
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
applications.
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
application.
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 :
http://nestroy.wi-inf.uni-essen.de/Forschung/rgf/datergf/
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
http://post-pc.cs.berkeley.edu/rmilite/. Do we incorporate it in the
standard Waba specification ?
Related links
=============
General
-------
Rick Wild: http://waba.sourceforge.net/html/creator/rick_wild.html
WabaSoft: http://www.wabasoft.com/
Discussion groups
----------------
waba-spec mailing list:
http://lists.sourceforge.net/lists/listinfo/waba-spec
pilot.programmer.waba newsgroup:
news://news.massena.com/pilot.programmer.waba
Documentation
--------------
Javadocs Documentation Server by Scott: ...
VM/API Ports
------------
Waba 1.0 VM : http://www.wabasoft.com/
Waba @ SourceForge : http://waba.sourceforge.net/
SuperWaba: http://www.superwaba.org/
WabaCE : http://www.webcom.com/abmss/WabaCE/
Newton Port: http://www.cs.umd.edu/users/seanl/newton/
J9 Port of the Waba API: http://www.skippingrock.com/wabaj9/
WabaJump API: http://wabajump.org/
Jump Software Development Tool: http://sourceforge.net/projects/jump/
Specific Classes Packages
-------------------------
datergf: http://wwwi.wu-wien.ac.at/rgf/tmp/datergf/
Trademarks
==========
Waba, WabaVM and WabaSDK are trademarks of Wabasoft Inc.
Contact information
====================
To contact us, send an email to waba@smartdata.ch, or visit the
waba-spec mailing list.
Happy Waba Programming !
(c) 2001 Olivier Bornet,
All Rights Reserved
http://waba.sourceforge.net/
|
