Main API for runtime code generation. This API generates bytecode dynamically at runtime, allowing direct construction of Class instances from the generated bytecodes. Such classes can then be instantiated and used in a running program. This can be used for a variety of advanced applications aimed at extending the Java language or providing significant performance enhancements.

The supported language is best thought of as a subset of Java 1.0.2. The following features from Java 5 and earlier are currently NOT supported:

• Generics.
• Annotations (this may be added at some point).
• For loops (of any sort, but this may be added through extension at some point).
• Enums.
• Autoboxing.
• Varargs methods.
• Nested classes.
• Compiler generated default constructors.
• Compiler generated calls to super() in a constructor.
• Anonymous classes.
• do loops.
• Static fields in interfaces.
• Labels, or labelled break or continue.

The intent is that dynamically generated code should be a simplified form of Java, much like the original Java 1.0 definition. This moves dynamic code generation to a level much closer to Java than to raw bytecode manipulation.

As much as possible, this class uses standard Java keywords prefixed by "_" as method names. This helps to remember what the method name is for creating an if statement (_if of course). All public methods are static, and using static imports for this class is advisable: simple use

 import static org.glassfish.dynamic.codegen.spi.Wrapper.*
 

to get easy access to all of the _xxx methods.

A typical use of this class looks something like:

 _clear() ;		    // clean up any state from previous uses
			    // optional:
 _setClassLoader(cl) ;    // If you need a specific ClassLoader, set it early
			    // so that your generated code can be checked against
			    // those classes that it references.
 _package( "YYY" ) ;	    // set the package to use for the generated code
 _import( "AAA.BBB" ) ;   // repeat as needed.  As in Java, this makes "BBB"
			    // a synonym for "AAA.BBB".  Collisions are not
			    // permitted.
 _class( ... ) ;	    // _interface is used for interfaces.
 _data( ... )	;	    // define the class data members (repeat as needed)
 _initializer() ;	    // define a static initializer


 _method( ... ) ;	    // define a method (use _constructor for a constructor)
 _arg( ... ) ;	    // repeat as needed for the method arguments.
 _body() ;		    // begin the method body definition.
     // define the contents of the body using any of the available
     // statements.
 _end() ; // of method
 _end() ; // of class
 _end() ; // of package
 Class<?>  newClass = _generate( ... ) ;
 

Alternatively, the last line could be

GenericClass<T> gc = _generate( T.class, props ) ;
 

which makes it easy to create an instance of the generated class by calling:

T instance = gc.create( <constructor args> ) ;
 

Currently only one class can be defined at a time. There is a grammar defined below that gives more detail. One small note: it is necessary to call _expr( expr ) in order to convert expr into a statement that is incorporated into a body. If this call is omitted, the generated code will NOT contain expr, leading to a difficult to find bug. I will probably fix this eventually, and treat all dangling expressions as errors.

This class provides many short utility methods that operate against a current context that is maintained in a ThreadLocal. This removes the bookkeeping that would otherwise be needed to keep track of various internal factories needed for generating statements and expressions. Note that this class is designed to be statically imported.

The point of view of the API of this class is that calls to create expressions are nested, while calls to create statements are not. That is, constructing an expression will often lead to nested method calls, but constructing a statement is done with a sequence of method calls. Note that everything could be done as a single nested method call per class, but this is unnatural and hard to debug in Java (Java is not Lisp, but you could make it look sort of like Lisp if you tried hard enough).

All of the expression methods can be called any place where an expression is valid, which basically means anywhere a statement can be defined. The other methods can only be called if the sequence of method calls is contained in the language defined by the following grammar:

 START	    : _package IMPORTS CLASS _end ;

 IMPORTS	    : _import IMPORTS
		    | empty ;

 CLASS	    : _class CDECLS _end ;

 CDECLS	    : CDECL CDECLS
		    | empty ;

 CDECL	    : _data
		    | _initializer STMTS _end
		    | METHOD
		    | CONSTRUCTOR ;

 METHOD	    : _method ARGS _body STMTS _end ;

 CONSTRUCTOR      : _constructor ARGS _body STMTS _end ;

 ARGS		    : _arg ARGS
		    | empty ;

 STMTS	    : STMT STMTS
		    | empty ;

 STMT		    : IF
		    | TRY
		    | SWITCH
		    | WHILE
		    | SIMPLE ;

 IF		    : _if STMTS _end
		    | _if STMTS _else STMTS _end ;

 TRY		    : _try STMTS CATCHES _end
		    | _try STMTS _finally STMTS _end
		    | _try STMTS CATCHES _finally STMTS _end ;

 CATCHES	    : _catch STMTS CATCHES
		    | empty ;

 SWITCH	    : _switch CASES
		    | _switch CASES _default STMTS _end ;

 CASES	    : _case STMTS CASES
		    | empty ;
 XXX modify this to support multiple case labels per statement list

 WHILE	    : _while STMTS _end ;

 SIMPLE	    : _assign
		    | _define
		    | _return
		    | _throw
		    | _expr ;
 

Any method that requires an expression can use any expression so long as all variables references in the expression are still in scope. This means that:

1. Variables representing data members can be referenced anywhere between the _class _body and _end.
2. Variables representing method parameters can be referenced anywhere between the _method _body and _end.
3. Variables representing _define statements can be referenced with in the scope of their block (that is, until the corresponding "}" in java. Here we don't use "{}" to delimit scope in the generated code).
4. Variables representing _catch statements can be referenced until the next corresponding _catch, _finally, or _end. Any attempt to use an Expression that references a Variable that is out of scope will result in an IllegalStateException.

The _classGenerator() method is used here to get the ClassGeneratorImpl, which can then be used in the CodeGenerator API to create source code or byte code directly. Also note that Util.display can be used to dump the contents of the ClassGeneratorImpl for debugging purposes.

For convenience, methods are provided to display the AST _displayAST, generate source code _sourceCode, and generate byteCode _byteCode.