Package com.svincent.smalljava

Provides an API for generating Java source code and JVM bytecodes.

See:
Description

Class Summary

Examples	Provides a number of informative examples of how to use the Smalljava framework.
Examples.HelloWorld	Generates (in bytecode and source format), and runs, a simple HelloWorld program.
Examples.Loop	Generates (in bytecode and source format), and runs, a simple counter loop program.
Expr	Expr represents an executable expression.
Expr.Begin	Execute a series of expressions, one after another.
Expr.BooleanConst	Return the given boolean constant.
Expr.Call	Call a method.
Expr.Comment	A comment.
Expr.DoubleConst	Return the given double constant.
Expr.EQ	The normal == binary operator.
Expr.GE	The normal >= binary operator.
Expr.GetField	Get the value from an instance field
Expr.GetLocal	Get the value from a local variable
Expr.GetStatic	Get the value from a static field
Expr.GT	The normal > binary operator.
Expr.If	If condition evaluates to true, evaluate the then clase.
Expr.IntConst	Return the given integer constant.
Expr.LE	The normal <= binary operator.
Expr.LT	The normal < binary operator.
Expr.Minus	The normal - binary operator.
Expr.NE	The normal != binary operator.
Expr.New	Construct a new instance of the named class.
Expr.NewArray	Construct a new array instance for containing the given type (Only makes single-dimensional arrays, for now) Also ignores types of initializer things.
Expr.NullConst	Return the null constant..
Expr.Plus	The normal + binary operator.
Expr.Return	Return a value from a method.
Expr.SetArray	Assign a value to an array slot
Expr.SetField	Assign a value to an instance field
Expr.SetLocal	Assign a value to a local variable
Expr.StringConst	Return the given String constant.
Expr.SuperConstructor	call the null-arg super constructor..
Expr.This	Access the magic variable 'this'.
Expr.While	Loop around, executing instructions until the given condition evaluates to 'true'.
SmallClass	Represents a class in SmallJava.
SmallClassLoader	Allows dynamic loading and execution of Smalljava code.
SmallConstructor	Represents a constructor declaration.
SmallField	Represents a field on a class.
SmallJavaUtil	Various utility methods used by (and to help use) Smalljava.
SmallMacro	A small library of useful expression generators for SmallJava.
SmallMember	Represents a member of a class.
SmallMethod	Represents a method declaration.
SmallMethod.Local	Represents a local variable.
SmallType	The SmallJava API uses two internal representations for types.
SmallType.ArrayType	A type which represents an array type.
SmallType.MethodType	Represents a type for a method.
SmallType.ObjectType	An instance of a class.
SmallType.PrimitiveType	Reprsents a primitive type, such as int or boolean.

Exception Summary

InvalidDescriptorException	Thrown when parsing a type descriptor goes badly.
SmallJavaBuildingException	Thrown if errors occur while building SmallJava data structures.
SmallJavaValidationException	Thrown if errors occur while finalizing a SmallJava data structure.

Package com.svincent.smalljava Description

Provides an API for generating Java source code and JVM bytecodes.

Motivation

Smalljava was motivated by my attempts to write an efficient and elegant Prolog environment in Java, work on which is ongoing. I decided that what I wanted to do was automatically generate bytecode from Prolog predicates, and execute the bytecode directly, thereby gaining all the benefits of all the JIT and HotSpot engineers in my own code.

However, generating JVM code is slow and tedious. Working with assembly language has been largely abandoned by the computer industry for good reason! So, I wanted a tool that could act as a simple backend for my Prolog environment. Thus arose Smalljava.

Architecture

Smalljava is based on a subset of Java, called Smalljava. Smalljava is pretty much exactly a Java compiler with a few hard-to-implement language features removed, such as overload resolution. As a result, it's way more tedious to program in Smalljava than in Java, but as a compiler backend, it works gloriously, as you can use high-level programming constructs like loops and control structures, and Smalljava will happily compile the code into bytecodes.

Another thing that comes out of this approach is a feature which may or may not be useful. Since Smalljava is very similar to Java, it was the work of a few moments to allow it to generate Java source as well as JVM code. This way, the back end of your favorite compiler environment can generate source code: either to debug the compiler (the JVM code is awfully hard to read), or for other, more insidious purposes (you tell me).

Using Smalljava

The basic mode of use of Smalljava is as follows. First, create a Smalljava data structure, representing a Smalljava class, using the provided builder APIs. Call a finalize method on the data structure, and call a method to spew as Java source or as JVM bytecode. Nothing could be simpler.

You need an example? Well, there is one example in SmallClass, but another one is given here, just to be nice.

{
  SmallClass c = new SmallClass ("Dog");
  c.instanceField ("Ljava.lang.String;", "name");

  SmallMethod getName =
    c.method ("getName()Ljava.lang.String;", Util.EmptyStringArray);

  // ... define getName ...

  SmallMethod setName =
    c.method ("setName(Ljava.lang.String;)V", new String[] {"_name"});
  setName.add (new Expr.AssignField ("Dog", "Ljava.lang.String;", "name", 
                                     new Expr.GetLocal (setName, "_name")));

  // --- finalize the class.                                    
  c.finalize ();

  // --- write as a Java program.
  c.writeAsJava ("Dog.java");

  // --- write as a classfile
  c.writeAsBytecodes ("Dog.class");
}

The class generated will be the same as the following class

public class Dog extends java.lang.Object
{
  String name;

  public Dog () { super (); }
  public String getName () { /* ... define getName ... */ }
  public void setName (String _setName) { name = _name; }
}

Where do I start?

The best place to start using Smalljava is probably the SmallClass class. The builder API and examples are largely self-explanatory.

This is crap! How do I complain!?

Although I try to maintain the highest standards of quality in my programming, occassionally, things slip by. If you have any complaints about Smalljava, or have suggestions about where you'd like to see it taken, you can send me mail, and I'll promise to give your ideas careful consideration.

Licensing

Smalljava and all its related libraries are being released by me under the GNU General Public License. See the license for more information. The Main GNU website has lots more information about free software, if you're interested.

Future directions

Eventually, I'd like to put a parser front-end onto Smalljava, so you don't have to build the data structures by hand. Overloading will probably also eventually be implemented, but don't hold your breath.

More short-term, I intend to write a ClassLoader for SmallJava, so that in addition to spewing Java source and JVM classfiles, SmallJava classes can be run more or less directly. Some engineering effort will have to go into this before I'm all done. This is definitely going to happen, as I need this functionality for my Prolog environment.

Change History

Version 0.2 - Monday, June 7th/1999

• addition of SmallClassLoader
• addition of ClassLoader.toByteArray, in support of new SmallClassLoader.

Version 0.1 - Sunday, June 6th/1999

• initial release