[Waba-spec] About the "javalike" classes

[Sean L. <se...@cs...>]

Zeroth off, the classes we're referring to can be found at 
http://www.cs.gmu.edu/~sean/newton/waba/dev/wababase.zip

First off, these classes are NOT intended to provide a clean-room 
implementation of the CLDC; they're separate and have no relationship 
with it.  The classes are derived directly from kaffe's gnu sources.  
Heavily modifying this basic set, I have subsequently produced a set of 
classes approximately filling the same stuff as the CLDC spec, but have 
not released them because I'm concerned about Sun's intellectual 
property response.  I don't believe that Sun has a claim here, but I 
want to be careful.  Anyway, I don't really think we should attempt to 
clean-room copy the CLDC:  due to Microsoft's encroachment, Sun is 
rightly paranoid about clean-room implementations, and we're much 
smaller than they are (and have no money), no matter how pure our 
intentions.

Anyway, allow me to give a run-down of the classes in this "base set". 
These classes have many fewer methods than the "typical" Java classes, 
but a few more than that Waba equivalents.  This set is about 41221 
bytes of unzipped .class files, and I imagine it can get about 10% 
smaller as I didn't compile these with -O on.  So they're not all that 
big frankly.

I have noted some "Open Questions" at the beginning of Character.java, 
Double.java, Float.java, and Integer.java.

Here's how the classes break out, plus some notes on their necessity and 
use:

THROWABLE CLASSES
-----------------
ArithmeticException
ArrayIndexOutOfBoundsException
ArrayStoreException
ClassCastException
ClassNotFoundException
Error
Exception
IllegalAccessException
IllegalArgumentException
IndexOutOfBoundsException
InstantiationException
NegativeArraySizeException
NullPointerException
NumberFormatException
RuntimeException
StringIndexOutOfBoundsException
EmptyStackException
NoSuchElementException
Throwable

The throwable classes would only be useful if your VM supports throws.  
As iot stands, Waba does not presently support throwing, which should be 
high on our list.  If you implement throwing, these classes are tiny in 
size anyway; they have basically no code in them at all, and only exist 
so that their names might be useful.

Throwable is the sole exception, requiring three new native functions:
	private native void determineStackTrace();
	private native String getStackTrace();
	public native void printStackTrace();


WRAPPER CLASSES
---------------
Boolean
Byte
Character
Double
Float
Integer
Long
Short

The wrapper classes are not super small, but they're also not required 
unless you want to do parsing mostly.  You should be able to Just Use 
Them (TM) without any need to implement the SYSTEM CLASSES described 
below.  Also, you don't need to have Long or Double or Float in your 
library, they can be taken out independent of each other, in this 
implementation.  Short and Byte require Integer tho.

These classes have been coded such that they both throw on error AND 
return an error value (if throwing is ignored).  They should be useful 
both in throwing and non-throwing versions.  Use javac to compile them; 
don't use jikes, it issues errors in the non-throwing sections.

UTILITY CLASSES
---------------
Math
Enumeration
Hashtable
Random
Stack
Vector

All of these utility classes are ready to go.  Random uses my 
implementation of ran0.   You should be able to Just Use Them (TM) 
without any need to implement the SYSTEM CLASSES described below -- 
except that Hashtable requires that you have implemented hashValue() in 
your Object class -- if you haven't, shame on you, I provided code for 
that months ago.  :-)  Math is a simplified version of the 
tried-and-true Maths class.  Vector and Stack and Enumeration should 
simply be drop-in usable.  Just like the wrapper classes, these classes 
have been coded such that they both throw on error AND return an error 
value (if throwing is ignored), so they can be used with either kind of 
VM.

SYSTEM CLASSES
--------------
Class
Object
String
StringBuffer
System

These are the nasty classes to implement: they'll require some native 
functions.  But it's important to note that, with the exception of 
Object.hashCode(), all of the other classes should be perfectly usable 
WITHOUT the system classes implemented.  So they're the last thing to 
add into the VM.

String and StringBuffer have significantly better functionality than the 
Waba defaults, and are supposed to be much more compatible (Waba's 
default implementations are riddled with bugs).  Note that this is an 
untested claim: I've not used them, just gotten 'em to compile.  :-)  
The ugliest parts to deal with is implementing the Class class...

Class will require the following native functions:
	public native static Class forName(String className)
		throws ClassNotFoundException;
	native public String getName();
	native static Class getPrimitiveClass(String name);
	native public boolean isArray();
	native public boolean isAssignableFrom(Class cls);
	native public boolean isInstance(Object obj);
	native public boolean isInterface();
	native public Object newInstance()
		throws InstantiationException, IllegalAccessException;

Some of these are pretty simple to handle.  Others are ickier.  The 
toughest part will be implementing the functionality of Class, 
particularly in respect to arrays, which Java treats as full Objects but 
Waba does not (underneath anyway).  We've gone over how to handle that 
in the past, and I've mentioned some bug fixes which should simplify the 
process.

Additionally, Object requires the following native function:

	final native public Class getClass();

...easy once you've gotten Class written.  Also String needs this one:

	private native int indexOf(char[] substring,
			char[] findInsideThisString, int startIndex);

...which should be trivial to implement.  Lastly, System requires this 
one:

	native public static int identityHashCode(Object x);

...this one is also really simple:  it just does the same thing that 
Object's default hashCode() function does.


MODIFIED WABA CLASSES
---------------------
waba.sys.Convert
waba.sys.Vm

waba.sys.Vm has two methods which I've implemented in Waba for the 
Newton to do rudimentary classname access and programatic 
instantiation.  I've given non-native implementations of these methods, 
mostly for my own benefit.  I don't think there's anything else in Vm, 
so if you don't care about those methods, you don't actually need to 
change anything there I think.

waba.sys.Convert has been modified significantly, though it's still 
backward compatible.  The intent here is to support the additional 
conversion functionality that's required by the wrapper classes without 
requiring them to be loaded (they instead load Convert to do the job).  
There are a few places in Integer which could be redirected to Convert, 
but I didn't in the name of portability.


Now to some specifics that Guilherme asked:

>     Are we trying to reinvent the wheel? Aren't there other tools that
> implements the full set of Java in the devices? Why are we going in the 
> same
> direction?

Olivier probably didn't understand: these classes are already finished, 
they just need to be debugged.


>     My opinion regarding this is: keep waba small as possible. 
> Implementing
> too much classes wont make it powerful. People like Waba bc it is small 
> and
> powerful.

My opinion on this is: Waba is too different from the Java standard.  
It's making porting difficult.  SuperWaba is pushing us even further in 
this direction.  I think that if we're trying to establish a good 
standard set of classes, we should bite the bullet and implement a good 
set of basic classes rather than try to modify the noncompatible ones we 
presently have.  We only have to do this once.

That being said, I've worked hard to make these classes as 
backward-compatible as possible.  In fact, they should be implementable 
without *any* modifications to existing applications.

The other nice feature of these classes is I've worked hard to make 
them, for the most part, modular with respect to one another.  You can 
remove all or some of the wrapper classes.  You can remove all or some 
of the utility classes.  Etc.  This means that apps which use Vector 
don't have to also include, say, Integer.  Note that this is different 
from standard Java implementations, where Integer *must* be loaded as 
soon as Object is loaded (because Object traditionally relies on Integer 
to do some hexadecimal stringification).

Sean