The JavaClassCreator API is used by the Jamaica
language to create JVM classes and interfaces. Jamaica is a JVM Macro Assembler language,
which uses Java syntax to define a JVM class structure and symbolic names for bytecode
instructions. This API is modeled after the Jamaica language, making it very easy to
dynamically create Java classes. It supports the Jamaica-style symbolic assembling, and
supports all the bytecode instructions and Jamaica macros, along with declarative class
construction. It is an abstract class that delegates a handful of methods to its
implementation while implementing the rest such as macros, etc. One difference between
this API and Jamaica is that the API does not support package and
import, so all class names must be complete with their package prefixes.
The class name for the API is com.judoscript.jamaica.JavaClassCreator.
Currently two implementations are provided: class
com.judoscript.jamaica.ASMJavaClassCreartor that utilizes the ASM package,
and class com.judoscript.jamaica.BCELJavaClassCreator that utilizes the
Jakarter-BCEL package.
Class JavaClassCreator has methods that starts a class or interface, creates
data fields, constants and methods, and finishes the declaration. Therefore, many methods
are context sensitive, i.e., they can only be called before or after certain events have
happened. For instance, all the bytecode instruction and macro creation methods can only
be called after a method is started and before that method is closed. During the process,
all type names are Java names, e.g., "int" for primitive integer, "java.lang.String" for
class names and "double[][]" for array types.
The following is the flow to create a JVM class using JavaClassCreator's
key methods:
Call startClass() or startInterface() to start.
After this, the following methods are allowed:
setSourceFileName(), getSourceFileName(),
getClassName(), getRootClassName(),
getSuperclassName() and getInterfaceNames().
Create data fields and/or constants via calls to addField() and
addConstant(). For the defined variables, can call
getFieldType() and isStaticField().
If a default constructor with no extra logic is intended, call
addDefaultConstructor().
For abstract methods, call addAbstractMethod().
If there are static fields to initialize, create a static method named "<clinit>"
that takes no parameters and returns void to initialize them.
Create concrete methods. See below.
Call endClass() or endClassToFile() to finish.
To create more classes and/or interfaces, go to 1.
This is the flow to create a concrete method:
Call startMethod() to start. After this, can call
getMethodAccessFlags() and getMethodName() on the defined
methods.
Call addLocalVariable() to add local variables. This can be mixed with other
code, but variables must be created before can be used by the instructions or macros.
Note that method parameters are also variables so avoid name clashes. For non-static
methods, the JVM specification mandates the this instance is the first on the
operand stack. You can access it via this as well. Once defined, can call
getLocalVariableIndex() and getVariableType() on the defined
variables in this method.
Add instructions and/or macros. They are presented in a
dedicated section. Instructions can be preceeded by labels
created by calls to setLabel().
All methods must create a return instruction at the end, including those with a
void return type.
Before finishing the method, zero or more catch clauses can be created via the call to
addCatchClause(). All the labels must be valid within this method. There is
no explicit "finally clause" in JVM; you can use jump instructions to emulate a Java
finally clause.
Here is a list of the methods mentioned so far. Most of them are merely listed along with
their parameter names; some are briefly annotated with Java comments.
JavaClassCreator has methods to create each and every JVM bytecode instruction
directly. The naming convention for these methods are inst_xxxx(),
where xxxx is the mnemonic. Based on their parameters, they are grouped as below.
For a functional grouping, refer to the Jamaica language
and/or other sources.
Group 1 includes simple instructions with no parameters:
where value is a Java primitive type wrapper or a String, and
type is the intended type. The constant will be added to the constant
pool. For certain values, implementation may optimize to such as bipush
or iconst_0, etc.
Group 6 are for jump instructions; they all take a target label as parameter:
Beyond individual instructions, JavaClassCreator has defined a number of macros
for commonly used patterns. They can interpret a name to be a variable or field based on the
context, and use the strong-type system to figure out what to do. They take an array element
syntax, so array access is much simpler. In general, these macros will greatly shorten your
programs and make them more readable. It is not uncommon that a method is implemented
completely by variables and macros.
Access to variables, fields and arrays is represented in JavaClassCreator by
one of its inner class, VarAccess.
public class JavaClassCreator {
public static class VarAccess {
public VarAccess(String name, int lineNum);
public VarAccess(String name);
public boolean isArray();
public void setIndex(Object index);
public String toString();
}
}
If it is a single name, the API will try to find a variable in the current method or a field
in the class. When its index is set, this is an array element accessing operation. The index
can be a number or a VarAccess, or can be an array of those as a
multi-dimensional array access.
Macros can be classified into two categories: Jamaica Macros and non-Jamaica ones. Jamaica
macros are direct counterparts of those defined in the Jamaica language. They are all quite
sophisticated. Other macros are simpler, usually are expanded into just one instruction,
which is almost always context-sensitive. Most of them are used to implement Jamaica macros.
void macroSet(Object dest, Object value);
// dest can be a String, a VarAccess or null;
// if null, the value is left on the stack;
// otherwise, the value is set to the dest.
void macroPrint(String cmd, String target, Object[] params);
// Prints to java.lang.System.out or err.
// cmd is "print", "println" or "flush".
// target is null, "out" or "err".
// params can be values or VarAccess's.
void macroObject(String type, String[] paramTypes, Object[] paramValues);
// creates an object on the stack.
void macroArray(String type, int dims, Object[] sizes);
// creates an array on the stack.
void macroStringConcat(Object[] vals);
// vals can be values or VarAccess's. The concatenated string is left on stack.
void macroIterate(VarAccess coll, String var, String id);
// coll must reference either a java.util.Iterator or Enumeration.
// var must reference an Object, holding the object during each iteration.
// var can be null, where the object is left on the stack.
// This macro must be ended by a call to macroEndIterator() with a matchin id.
void macroEndIterate(String id);
void macroArrayIterate(VarAccess array, String var, String id);
// array must reference an array.
// var must reference an int to serve as the index used by the iteration.
// The stack is not used.
// This macro must be ended by a call to macroEndArrayIterator() with a matching id.
void macroEndArrayIterate(String, String id);
void macroIf(String op, Object left, Object right, String id, boolean hasElse);
// op is one of these: <, <=, >, >=, == or !=.
// left and right can be constants or references.
// This macro must be ended by a macroElse() or macroEndIf() with a matching id.
void macroElse(String id);
// This macro must be proceded by a macroIf() and
// ended by a macroEndIf() with a matching id.
void macroEndIf(String id);
// This macro must be proceeded by a macroIf() or macroElse() and
// ended by a macroEndIf() with a matching id.
Non-Jamaica Macros are simple ones that do "intelligent" instruction generation.
void macroTypeCast(String fromType, String toType);
String macroGetField(String name);
// Returns the type of the value loaded on the stack.
String macroLoadConstantOrVarOrField(Object value, String intendedType);
// value can be a constant (including String) or a VarAccess.
// Returns the type of the value loaded on the stack.
String macroLoadVarOrField(String name, String intendedType);
// Returns the type of the value loaded on the stack.
String macroLoadVarOrField(VarAccess var, String intendedType);
// Returns the type of the value loaded on the stack.
In addition to the direct bytecode instructions and powerful macros,
JavaClassCreator provides a number of flexible methods to create bytecode
instructions. In fact, most direct instructions are delegated to these, as noted below:
void inst(int opcode);
// For all group 1 instructions.
void instLoadStoreRet(int opcode, String varName);
// For all group 2 instructions.
void instType(int opcode, String type);
// For all group 3 instructions.
void instGetPut(int opcode, String className, String fieldName, String type);
// For all group 4 instructions.
void instLdc(int opcode, Object value, String type);
// For all group 5 instructions.
void instJump(int opcode, String label);
// For all group 6 instructions.
void instInvoke(int opcode, String className, String methodName,
String[] paramTypes, String returnType);
// For all group 7 instructions.
JavaClassCreator does not define constants for the JVM bytecode opcodes,
because all implementation packages have a collection of those. For instance, in the
Jakarta-BCEL package, interface org.apache.bcel.Constants defines constants
for all the bytecode opcodes.
Let's write some Java code to generate a Java class and use it instantly. The generated
class will be like the following class written in Jamaica:
Listing 1. DynaHandler Genereated Within JCCTest.java
// We will write a Java class called JCCTest to generate this one.
// JCCTest has an inner interface, EventHandler, that is implemented here.
public class DynaHandler implements JCCTest$EventHandler
{
.default_constructor
public void event(String e) {
%println "String event: ", e
}
public void event(int e) {
%println "int event: ", e
}
public void event(int[] e) {
int i;
%set i = 0
%if e != null
aload e
arraylength
istore i
%end_if
%println "Array event: length=", i
%if i > 0
%array_iterate e i
%println " e[", i, "]=", e[i]
%end_array_iterate
%end_if
}
}
This is the Java code that generates and uses a created class:
