Chapter 2. Oolong
This chapter introduces Oolong, an assembly language for the Java virtual machine. The JVM uses a binary format called class files for communicating programs. Because it is difficult to edit and visualize class files, the Oolong language was created. It is nearly equivalent to the class file format but easier to read and write. The Oolong language takes care of certain bits-and-bytes-level details while allowing almost complete control of the class file.
To actually execute an Oolong program, it must be
You can edit Oolong source with any text editor. By convention, Oolong source file
This chapter provides a quick introduction to the overall structure of Oolong. The
2.1 Hello, World
Let's look at an Oolong program in action. This is the source to the "Hello, world" program written in Oolong, as it would appear in an Oolong source file hello.j :
.class public hello .super java/lang/Object .method public static main([Ljava/lang/String;)V .limit stack 2 .limit locals 1 getstatic java/lang/System/out Ljava/io/PrintStream; ldc "Hello, world" invokevirtual java/io/PrintStream/println (Ljava/lang/String;)V return .end method .end class
2.1.1 .class and .super Directives
Lines that begin with periods (.) are called
. The first directive is .
The .class directive may also contain a set of modifiers that control access to the class. This class is declared public , meaning that it may be accessed from any other class in the JVM. This is identical to declaring a class public in Java.
The rest of the file up to the
The next line after the .class directive contains a .super directive. The . super directive tells Oolong the name of the superclass of this class. This example declares the superclass to be java/lang/Object , which is the default. The .super directive works like the extends clause in a Java program.
The .class and .super directives in this example are equivalent to the Java
public class hello extends java.lang.Object
In Oolong, you must use the full name of the class. In Java, this line is equivalent to
public class hello extends Object
because Java assumes that by Object you mean the particular Object found in the package java.lang . The class file does not make this assumption, so you must write out the full name of every class. That can get tiring, but it ensures that the class file is not ambiguous. This saves the JVM time trying to figure out which class you mean, and it ensures that you get the same result each time, even if new classes are added to the system.
2.1.2 main Method
The .method directive marks the beginning of a new method. Every line after that is a part of the method until the .end method directive. The .method directive here is
.method public static main([Ljava/lang/String;)V
The .method directive names the method being created. In this case, the method is named main .
Before the method name is a list of
which control how the class can be used. This method is
Also unlike Java, the return type of the method does not appear at the end of the list of keywords. Instead, the arguments and return types are written together in the
following the method name. The descriptor is a way of
Most types are represented by a single character:
, and so on. A left
The descriptor of main is ([Ljava/lang/String;)V . This says that main takes an array of strings, and returns a void .
The .limit directives tell how much space to allocate for the execution of this method: .limit stack puts an upper limit on how many slots on the operand stack the program will use; .limit locals specifies the number of local variable slots that will be used. The Oolong assembler will guess if the directive isn't given.
The remaining lines up to
represent JVM instructions. The Oolong assembler
Let's look at what the instructions mean, one by one. The first instruction is
getstatic java/lang/System/out Ljava/io/PrintStream;
This instruction tells the JVM to get the value of the field out from the class java/lang/System . This is a static field, meaning that it is a property of the class as a whole instead of any individual object. The value of the object obtained from this operation is expected to be a java/io/PrintStream object. A reference to this object is placed on the stack.
The second instruction is
ldc "Hello, world"
This causes the JVM to create a java/lang/String object with the value Hello, world . This object is placed on the stack above the out object. The stack now looks like this:
The next instruction is
The invokevirtual instruction is used to invoke a method on an object. The arguments to the instruction name the method to be called ( println ), the class in which the method is to be found ( java/io/PrintStream ), and the descriptor of the method ( (Ljava/lang/String;)V ).
The JVM checks that the arguments that actually appear on the stack
The final instruction is
This instruction terminates the method and causes control to return to whoever called the method.