org.glassfish.pfl.dynamic.codegen.spi

Class Wrapper

java.lang.Object

org.glassfish.pfl.dynamic.codegen.spi.Wrapper

public final class Wrapper
extends Object

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 gc = _generate( T.class, props ) ;
 

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

 T instance = gc.create(  ) ;
 

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 (@see _displayAST), generate source code (@see _sourceCode), and generate byteCode (@see _byteCode).

Field Summary

Fields

Modifier and Type	Field and Description
static String	CLASS_GENERATION_DIRECTORY Set this to enable dumping the generated byte codes to a class file in the given directory.
static String	DUMP_AFTER_SETUP_VISITOR Debugging option used to dump the contents of the AST after the setup visitor runs.
static String	DUMP_CONSTANT_POOL Causes contents of constant pool to be dumped.
static String	SOURCE_GENERATION_DIRECTORY Option used to enable generation of source files while generating bytecode.
static String	TRACE_BYTE_CODE_GENERATION Debugging option used to trace the byte code generation.
static String	USE_ASM_VERIFIER Debugging option used to enable the ASM verifier, which can be helpful for debugging errors in the code generation.

Method Summary

Methods

Modifier and Type	Method and Description
static Expression	_add(Expression left, Expression right) Create an expression representing the application of the + operator to the left and right expressions in the form (left op right).
static Expression	_and(Expression left, Expression right) Create an expression representing the application of the && operator to the left and right expressions in the form (left op right).
static Expression	_arg(Type type, String name) Add an argument to the current method.
static Type	_array(Type type) Return a representation of the array type with the given component type.
static void	_assign(Expression var, Expression expr) Indicates an assignment statement of the form var = expr.
static void	_body() Indicates the start of the definition of the body of a method.
static Type	_boolean() Return a representation of the boolean type.
static void	_break() Indicates a break statement, that should transfer control out of the nearest enclosing _switch or _while statement.
static Type	_byte() Return a representation of the byte type.
static byte[]	_byteCode(ClassGenerator cgen, ClassLoader cl, Properties options) Generate byte codes for the ClassGenerator.
static byte[]	_byteCode(ClassLoader cl, Properties options) Generate byte codes for the current ClassGenerator.
static Expression	_call(Expression target, String ident, Expression... args) Generate a call to an instance method, using the Java method overload resolution algorithm to determine the signature.
static Expression	_call(Expression target, String ident, List<Expression> args) Generate a call to an instance method, using the Java method overload resolution algorithm to determine the signature.
static Expression	_call(Expression target, String ident, Signature signature, Expression... args) Generate a call to an instance method.
static Expression	_call(Expression target, String ident, Signature signature, List<Expression> args) Generate a call to an instance method.
static Expression	_call(Type target, String ident, Expression... args) Generate a call to a static method, using the Java method overload resolution algorithm to determine the signature.
static Expression	_call(Type target, String ident, List<Expression> args) Generate a call to a static method, using the Java method overload resolution algorithm to determine the signature.
static Expression	_call(Type target, String ident, Signature signature, Expression... args) Generate a call to a static method.
static Expression	_call(Type target, String ident, Signature signature, List<Expression> args) Generate a call to a static method.
static void	_case(int value) Indicate the start of a particular case in a switch statement.
static Expression	_cast(Type type, Expression expr) Create an expression representing the type cast of expr to type.
static Expression	_catch(Type type, String name) Indicate the start of a catch clause in a try statement.
static Type	_char() Return a representation of the char type.
static Type	_Class() Return a representation of the java.lang.Class type.
static void	_class(int modifiers, String name, Type superClass, List<Type> impls) Define a class.
static void	_class(int modifiers, String name, Type superClass, Type... impls) Define a class.
static ClassGenerator	_classGenerator() Obtain the ClassGeneratorImpl that is constructed by the Wrapper methods.
static void	_clear() Discard the current Class generated by Wrapper calls, so that another Class may be generated.
static Expression	_const(boolean c) Return a constant expression representing the value c.
static Expression	_const(byte c) Return a constant expression representing the value c.
static Expression	_const(char c) Return a constant expression representing the value c.
static Expression	_const(double c) Return a constant expression representing the value c.
static Expression	_const(float c) Return a constant expression representing the value c.
static Expression	_const(int c) Return a constant expression representing the value c.
static Expression	_const(long c) Return a constant expression representing the value c.
static Expression	_const(short c) Return a constant expression representing the value c.
static Expression	_const(String c) Return a constant expression representing the value c.
static Expression	_const(Type c) Return a constant expression representing the value c.
static void	_constructor(int modifiers, List<Type> exceptions) Begin defining a constructor in the current class.
static void	_constructor(int modifiers, Type... exceptions) Begin defining a constructor in the current class.
static Expression	_data(int modifiers, Type type, String name) Define a data member in a class.
static void	_default() Indicate the start of the default case in a switch statement.
static Expression	_define(Type type, String name, Expression expr) Indicates the introduction of a new local variable initialized to the given expression.
static void	_displayAST(ClassGenerator cg, PrintStream ps) Dump the contents of the AST for the current Class defined by Wrapper calls.
static void	_displayAST(PrintStream ps) Dump the contents of the AST for the current Class defined by Wrapper calls.
static Expression	_div(Expression left, Expression right) Create an expression representing the application of the + operator to the left and right expressions in the form (left op right).
static Type	_double() Return a representation of the double type.
static void	_else() Indicate the start of the false branch of an if statement.
static void	_end() Terminates the definition of the current statement, method, constructor, initializer, class, or package.
static Expression	_eq(Expression left, Expression right) Create an expression representing the application of the == operator to the left and right expressions in the form (left op right).
static void	_expr(Expression expr) Indicate that expr should be executed as a statement for its side effects.
static Expression	_field(Expression expr, String fieldName) Return an expression used to access a field in an object given by expr.
static Expression	_field(Type type, String fieldName) Return an expression used to access a static data member in a class given by the type.
static void	_finally() Indicate the start of a finally clause in a try statement.
static Type	_float() Return a representation of the float type.
static Expression	_ge(Expression left, Expression right) Create an expression representing the application of the >= operator to the left and right expressions in the form (left op right).
static <T> GenericClass<T>	_generate(Class<T> cls, Properties props) Return a GenericClass instance so that we can easily create an instance of the generated class.
static <T> GenericClass<T>	_generate(ClassGenerator cg, Class<T> cls, Properties props) Return a GenericClass instance so that we can easily create an instance of the generated class.
static Class<?>	_generate(ClassGenerator cg, ClassLoader cl, ProtectionDomain pd, Properties props) Generate a class for the current ClassGenerator.
static Class<?>	_generate(ClassGenerator cg, ClassLoader cl, ProtectionDomain pd, Properties props, PrintStream debugOutput) Generate a class for the ClassGenerator.
static Class<?>	_generate(ClassLoader cl, ProtectionDomain pd, Properties props) Generate a class for the current ClassGenerator.
static Class<?>	_generate(ClassLoader cl, ProtectionDomain pd, Properties props, PrintStream debugOutput) Generate a class for the current ClassGenerator.
static Expression	_gt(Expression left, Expression right) Create an expression representing the application of the > operator to the left and right expressions in the form (left op right).
static void	_if(Expression expr) Indicate the start of an if statement with the given expression as the condition.
static ImportList	_import() Return an ImportList that can be shared across multiple class generations.
static void	_import(ImportList ilist) Set the ImportList for the current class generation.
static Type	_import(String name) Used to create short names for types.
static Expression	_index(Expression expr, Expression index) Return an expression used to access an element in an array given by expr.
static void	_initializer()
static Expression	_instanceof(Expression expr, Type type) Create an expression representing the instanceof test of expr and type (expr instanceof type).
static Type	_int() Return a representation of the int type.
static void	_interface(int modifiers, String name, List<Type> impls) Define an interface.
static void	_interface(int modifiers, String name, Type... impls) Define an interface.
static Expression	_le(Expression left, Expression right) Create an expression representing the application of the <= operator to the left and right expressions in the form (left op right).
static Expression	_length(Expression expr) Return an expression that gets the length of expr.
static Type	_long() Return a representation of the long type.
static Expression	_lt(Expression left, Expression right) Create an expression representing the application of the < operator to the left and right expressions in the form (left op right).
static Class<?>	_makeClass(byte[] data, String name, ClassLoader cl, ProtectionDomain pd) Convert an array of bytes into a Class using the given ClassLoader and ProtectionDomain.
static void	_method(int modifiers, Type type, String name, List<Type> exceptions) Begin defining a method in the current class.
static void	_method(int modifiers, Type type, String name, Type... exceptions) Begin defining a method in the current class.
static Expression	_mul(Expression left, Expression right) Create an expression representing the application of the + operator to the left and right expressions in the form (left op right).
static Expression	_ne(Expression left, Expression right) Create an expression representing the application of the != operator to the left and right expressions in the form (left op right).
static Expression	_new_array_init(Type type, Expression... args) Create an expression representing the construction of a new array with the given component type using the given expressions to initialize the array.
static Expression	_new_array_init(Type type, List<Expression> args) Create an expression representing the construction of a new array with the given component type using the given expressions to initialize the array.
static Expression	_new_array(Type type, Expression size) Create an expression representing the construction of a new array of the given size with the given component type.
static Expression	_new(Type type, Expression... args) Create an expression representing the construction of a new instance of the given type using the constructor with the signature determined by the Java method overload resolution algorithm and the list of expressions as arguments.
static Expression	_new(Type type, List<Expression> args) Create an expression representing the construction of a new instance of the given type using the constructor with the signature determined by the Java method overload resolution algorithm and the list of expressions as arguments.
static Expression	_new(Type type, Signature signature, Expression... args) Create an expression representing the construction of a new instance of the given type using the constructor with the given signature and the list of expressions as arguments.
static Expression	_new(Type type, Signature signature, List<Expression> args) Create an expression representing the construction of a new instance of the given type using the constructor with the given signature and the list of expressions as arguments.
static Expression	_not(Expression expr)
static Expression	_null() Return the null expression.
static Type	_nullType() Return a representation of the null type.
static Type	_Object() Return a representation of the java.lang.Object type.
static Expression	_or(Expression left, Expression right) Create an expression representing the application of the || operator to the left and right expressions in the form (left op right).
static void	_package() Same as _package( "" ).
static void	_package(String name) _package must be called first to set the package name for this class.
static Expression	_rem(Expression left, Expression right) Create an expression representing the application of the + operator to the left and right expressions in the form (left op right).
static void	_return() Indicates the end of execution in a method.
static void	_return(Expression expr) Indicates the end of execution in a method with a return of the value of the expression.
static Signature	_s(Type rtype, List<Type> types) Create a signature that may be used for calling a method or constructor.
static Signature	_s(Type rtype, Type... types) Create a signature that may be used for calling a method or constructor.
static void	_setClassLoader(ClassLoader cl) Set the ClassLoader for this thread that will be used for validating references to pre-existing classes from generated code.
static Type	_short() Return a representation of the short type.
static void	_sourceCode(ClassGenerator cg, PrintStream ps, Properties options) Generate the Java source code for the ClassGenerator.
static void	_sourceCode(ClassGenerator cg, Properties options) Generate source code into a specified output directory.
static void	_sourceCode(PrintStream ps, Properties options) Generate the Java source code for the current Class defined by Wrapper calls.
static void	_sourceCode(Properties options) Generate source code into a specified output directory.
static Type	_String() Return a representation of the java.lang.String type.
static Expression	_sub(Expression left, Expression right) Create an expression representing the application of the + operator to the left and right expressions in the form (left op right).
static Expression	_super(Expression... exprs) Invoke a superclass constructor as the first statement in a constructor for a class using the Java method overload resolution algorithm to determine the signature.
static Expression	_super(List<Expression> exprs) Invoke a superclass constructor as the first statement in a constructor for a class using the Java method overload resolution algorithm to determine the signature.
static Expression	_super(Signature signature, Expression... exprs) Invoke a superclass constructor as the first statement in a constructor for a class.
static Expression	_super(Signature signature, List<Expression> exprs) Invoke a superclass constructor as the first statement in a constructor for a class.
static Expression	_super(String ident, Expression... exprs) Generate a call to an instance method in the current super class using the Java method overload resolution algorithm to determine the signature.
static Expression	_super(String ident, List<Expression> exprs) Generate a call to an instance method in the current super class using the Java method overload resolution algorithm to determine the signature.
static Expression	_super(String ident, Signature signature, Expression... exprs) Generate a call to an instance method in the current super class.
static Expression	_super(String ident, Signature signature, List<Expression> exprs) Generate a call to an instance method in the current super class.
static void	_switch(Expression expr) Indicate the start of a switch statement with the given expression at the switch expression.
static Type	_t(String name) Return the reference type for the given class name.
static Expression	_this() Return an expression representing "this".
static Expression	_this(Expression... exprs) Invoke another constructor as the first statement in a constructor for a class using the Java method overload resolution algorithm to determine the signature.
static Expression	_this(List<Expression> exprs) Invoke another constructor as the first statement in a constructor for a class using the Java method overload resolution algorithm to determine the signature.
static Expression	_this(Signature signature, Expression... exprs) Invoke another constructor as the first statement in a constructor for a class.
static Expression	_this(Signature signature, List<Expression> exprs) Invoke another constructor as the first statement in a constructor for a class.
static Type	_thisClass() Return the type of the current class.
static void	_throw(Expression expr) Indicates a throw statement that throws the given expression.
static void	_try() Indicate the start of a try statement.
static Expression	_v(String name) Construct the expression that refers to the variable named name.
static Type	_void() Return a representation of the void type.
static void	_while(Expression expr) Indicate the start of a while loop with the given expression as its condition.
static Pair<String,String>	splitClassName(String name) Split the class name into a pair of the package name and the unqualified class name.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

CLASS_GENERATION_DIRECTORY

public static final String CLASS_GENERATION_DIRECTORY

Set this to enable dumping the generated byte codes to a class file in the given directory.

See Also:

Constant Field Values

SOURCE_GENERATION_DIRECTORY

public static final String SOURCE_GENERATION_DIRECTORY

Option used to enable generation of source files while generating bytecode. Set to name of directory that should contain the generated source file.

See Also:

Constant Field Values

DUMP_AFTER_SETUP_VISITOR

public static final String DUMP_AFTER_SETUP_VISITOR

Debugging option used to dump the contents of the AST after the setup visitor runs.

See Also:

Constant Field Values

TRACE_BYTE_CODE_GENERATION

public static final String TRACE_BYTE_CODE_GENERATION

Debugging option used to trace the byte code generation.

See Also:

Constant Field Values

DUMP_CONSTANT_POOL

public static final String DUMP_CONSTANT_POOL

Causes contents of constant pool to be dumped.

See Also:

Constant Field Values

USE_ASM_VERIFIER

public static final String USE_ASM_VERIFIER

Debugging option used to enable the ASM verifier, which can be helpful for debugging errors in the code generation.

See Also:

Constant Field Values

Method Detail

_classGenerator

public static ClassGenerator _classGenerator()

Obtain the ClassGeneratorImpl that is constructed by the Wrapper methods. This is only needed for using Wrapper with custom vistors.

_setClassLoader

public static void _setClassLoader(ClassLoader cl)

Set the ClassLoader for this thread that will be used for validating references to pre-existing classes from generated code. Applications that use special ClassLoaders (such as the app server) should call this method before starting to generate a new Class. A good place to do this is just before the _package call.

_byteCode

public static byte[] _byteCode(ClassLoader cl,
               Properties options)

Generate byte codes for the current ClassGenerator. cl is used to resolve any references to other classes. options may be used to control some aspects of the code generation, such as debugging options. Supported options include DUMP_AFTER_SETUP_VISITOR, TRACE_BYTE_CODE_GENERATION, USE_ASM_VERIFIER.

_byteCode

public static byte[] _byteCode(ClassGenerator cgen,
               ClassLoader cl,
               Properties options)

Generate byte codes for the ClassGenerator. cl is used to resolve any references to other classes. options may be used to control some aspects of the code generation, such as debugging options. Supported options include DUMP_AFTER_SETUP_VISITOR, TRACE_BYTE_CODE_GENERATION, USE_ASM_VERIFIER.

_makeClass

public static Class<?> _makeClass(byte[] data,
                  String name,
                  ClassLoader cl,
                  ProtectionDomain pd)

Convert an array of bytes into a Class using the given ClassLoader and ProtectionDomain. Use of this method requires the suppressAccessChecks ReflectionPermission.

_generate

public static Class<?> _generate(ClassLoader cl,
                 ProtectionDomain pd,
                 Properties props,
                 PrintStream debugOutput)

Generate a class for the current ClassGenerator. Basically equivalent to _byteCode followed by _makeClass. cl is used to resolve any references to other classes and to load the class given by the current ClassGenerator. options may be used to control some aspects of the code generation, such as debugging options.

_generate

public static Class<?> _generate(ClassGenerator cg,
                 ClassLoader cl,
                 ProtectionDomain pd,
                 Properties props,
                 PrintStream debugOutput)

Generate a class for the ClassGenerator. Basically equivalent to _byteCode followed by _makeClass. cl is used to resolve any references to other classes and to load the class given by the current ClassGenerator. options may be used to control some aspects of the code generation, such as debugging options.

_generate

public static Class<?> _generate(ClassLoader cl,
                 ProtectionDomain pd,
                 Properties props)

Generate a class for the current ClassGenerator. Basically equivalent to _byteCode followed by _makeClass. cl is used to resolve any references to other classes and to load the class given by the current ClassGenerator. options may be used to control some aspects of the code generation, such as debugging options.

_generate

public static Class<?> _generate(ClassGenerator cg,
                 ClassLoader cl,
                 ProtectionDomain pd,
                 Properties props)

Generate a class for the current ClassGenerator. Basically equivalent to _byteCode followed by _makeClass. cl is used to resolve any references to other classes and to load the class given by the current ClassGenerator. options may be used to control some aspects of the code generation, such as debugging options.

_generate

public static <T> GenericClass<T> _generate(Class<T> cls,
                            Properties props)
                                 throws ClassNotFoundException

Return a GenericClass instance so that we can easily create an instance of the generated class. This form should be used as an abbreviation, where the context ClassLoader and associated ProtectionDomain are all that is needed.

Throws:

ClassNotFoundException

_generate

public static <T> GenericClass<T> _generate(ClassGenerator cg,
                            Class<T> cls,
                            Properties props)
                                 throws ClassNotFoundException

Return a GenericClass instance so that we can easily create an instance of the generated class. This form should be used as an abbreviation, where the context ClassLoader and associated ProtectionDomain are all that is needed.

Throws:

ClassNotFoundException

_sourceCode

public static void _sourceCode(PrintStream ps,
               Properties options)
                        throws IOException

Generate the Java source code for the current Class defined by Wrapper calls. options may be used to control some aspects of the formatting of the source code, but no options are currently defined. The generate source code is written to the PrintStream.

Throws:

IOException

_sourceCode

public static void _sourceCode(ClassGenerator cg,
               PrintStream ps,
               Properties options)
                        throws IOException

Generate the Java source code for the ClassGenerator. options may be used to control some aspects of the formatting of the source code, but no options are currently defined. The generate source code is written to the PrintStream.

Throws:

IOException

_sourceCode

public static void _sourceCode(Properties options)
                        throws IOException

Generate source code into a specified output directory. options must set SOURCE_GENERATION_DIRECTORY to the name of the output directory.

Throws:

IOException

_sourceCode

public static void _sourceCode(ClassGenerator cg,
               Properties options)
                        throws IOException

Generate source code into a specified output directory. options must set SOURCE_GENERATION_DIRECTORY to the name of the output directory.

Throws:

IOException

_displayAST

public static void _displayAST(PrintStream ps)

Dump the contents of the AST for the current Class defined by Wrapper calls. The AST is dumped to the PrintStream.

_displayAST

public static void _displayAST(ClassGenerator cg,
               PrintStream ps)

Dump the contents of the AST for the current Class defined by Wrapper calls. The AST is dumped to the PrintStream.

_clear

public static void _clear()

Discard the current Class generated by Wrapper calls, so that another Class may be generated.

_s

public static Signature _s(Type rtype,
           Type... types)

Create a signature that may be used for calling a method or constructor. rtype is the return type, and types gives all of the argument types. types is empty if there are no arguments.

_s

public static Signature _s(Type rtype,
           List<Type> types)

Create a signature that may be used for calling a method or constructor. rtype is the return type, and types gives all of the argument types. types is empty if there are no arguments.

_t

public static final Type _t(String name)

Return the reference type for the given class name. name may be either the Class name, if the full name has been imported using an _import statement, or a fully qualified Class name.

_void

public static final Type _void()

Return a representation of the void type. This is used whenever a method has a void return type.

_nullType

public static final Type _nullType()

Return a representation of the null type. This is the type of the null value. The null type is assignment compatible with any reference type. This is not normally needed in dynamically generated code.

_boolean

public static final Type _boolean()

Return a representation of the boolean type.

_byte

public static final Type _byte()

Return a representation of the byte type.

_short

public static final Type _short()

Return a representation of the short type.

_char

public static final Type _char()

Return a representation of the char type.

_int

public static final Type _int()

Return a representation of the int type.

_long

public static final Type _long()

Return a representation of the long type.

_float

public static final Type _float()

Return a representation of the float type.

_double

public static final Type _double()

Return a representation of the double type.

_Object

public static final Type _Object()

Return a representation of the java.lang.Object type.

_String

public static final Type _String()

Return a representation of the java.lang.String type.

_Class

public static final Type _Class()

Return a representation of the java.lang.Class type.

_array

public static final Type _array(Type type)

Return a representation of the array type with the given component type.

splitClassName

public static final Pair<String,String> splitClassName(String name)

Split the class name into a pair of the package name and the unqualified class name. If name is the name of a class in the anonymous global package, the package name is "".

_package

public static final void _package(String name)

_package must be called first to set the package name for this class. After _package, all required _import calls must be made, followed by one _class call. name may be "", in which case the generated class is in the default package.

_package

public static final void _package()

Same as _package( "" ). Note that this method MUST be called before _class or _interface. This is a bit surprising, since Java allows omission of the package statement, but codegen requires an explicit package call.

_import

public static final Type _import(String name)

Used to create short names for types. Name must be a fully qualified class name. The last name becomes the short name used in _t to look up the full type. The result Type can also be used directly.

_import

public static final ImportList _import()

Return an ImportList that can be shared across multiple class generations.

_import

public static final void _import(ImportList ilist)

Set the ImportList for the current class generation. Mainly useful for generating source code.

_class

public static final void _class(int modifiers,
          String name,
          Type superClass,
          Type... impls)

Define a class. This must be followed by calls to _data, _initializer, or _method in any order.

_class

public static final void _class(int modifiers,
          String name,
          Type superClass,
          List<Type> impls)

Define a class. This must be followed by calls to _data, _initializer, or _method in any order.

_interface

public static final void _interface(int modifiers,
              String name,
              Type... impls)

Define an interface. This must be followed by calls to _method only. All _method calls must define abstract methods. Note that static data in interfaces is not currently supported.

_interface

public static final void _interface(int modifiers,
              String name,
              List<Type> impls)

Define an interface. This must be followed by calls to _method only. All _method calls must define abstract methods. Note that static data in interfaces is not currently supported.

_data

public static final Expression _data(int modifiers,
               Type type,
               String name)

Define a data member in a class. If static, it must be initialized in the class initializer, otherwise it must be initialized in a constructor.

_initializer

public static final void _initializer()

_method

public static final void _method(int modifiers,
           Type type,
           String name,
           Type... exceptions)

Begin defining a method in the current class. Must be followed first be all _arg calls for the method, then by _body(), then by any statements, and finally by _end(). _body() may be followed immediately by _end(), in which case the method has an empty body. Abstract methods must have an empty body.

_method

public static final void _method(int modifiers,
           Type type,
           String name,
           List<Type> exceptions)

Begin defining a method in the current class. Must be followed first by all _arg calls for the method, then by _body(), then by any statements, and finally by _end(). _body() may be followed immediately by _end(), in which case the method has an empty body. Abstract methods must have an empty body.

_constructor

public static final void _constructor(int modifiers,
                Type... exceptions)

Begin defining a constructor in the current class. Must be followed first by all _arg calls for the constructor, then by _body(), then by optional statements, and finally by _end(). Note that the first statement in any constructor must be a this() or super() call. Constructors may not have empty bodies.

_constructor

public static final void _constructor(int modifiers,
                List<Type> exceptions)

Begin defining a constructor in the current class. Must be followed first by all _arg calls for the constructor, then by _body(), then by any statements, and finally by _end(). Note that the first statement in any constructor must be a _this() or _super() call. Constructors may not have empty bodies. Note that no default constructor is automatically generated using this API.

_arg

public static final Expression _arg(Type type,
              String name)

Add an argument to the current method.

_body

public static final void _body()

Indicates the start of the definition of the body of a method. Must be followed by 0 or more statements, and be terminated by _end().

_end

public static final void _end()

Terminates the definition of the current statement, method, constructor, initializer, class, or package. Restores the context for the previous definition.

_expr

public static final void _expr(Expression expr)

Indicate that expr should be executed as a statement for its side effects.

_assign

public static final void _assign(Expression var,
           Expression expr)

Indicates an assignment statement of the form var = expr. Var must be an assignable expression, such as a local variable, a non-final field reference, ior an array index expression.

_define

public static final Expression _define(Type type,
                 String name,
                 Expression expr)

Indicates the introduction of a new local variable initialized to the given expression.

_break

public static final void _break()

Indicates a break statement, that should transfer control out of the nearest enclosing _switch or _while statement.

_return

public static final void _return()

Indicates the end of execution in a method. Can only occur inside a definition of a method with a void return type.

_return

public static final void _return(Expression expr)

Indicates the end of execution in a method with a return of the value of the expression. The type of the expression must be assignment compatible with the return type of the enclosing method.

_throw

public static final void _throw(Expression expr)

Indicates a throw statement that throws the given expression. The type of expr must support Throwable.

_if

public static final void _if(Expression expr)

Indicate the start of an if statement with the given expression as the condition. All subsequent statements until the next matching _else are part of the true branch of this if statement.

_else

public static final void _else()

Indicate the start of the false branch of an if statement. All subsequent statements until the next matching _end are part of the false branch of the corresponding if statement.

_try

public static final void _try()

Indicate the start of a try statement. All subsequent statements until the next matching _catch or _finally are part of this try statement.

_catch

public static final Expression _catch(Type type,
                String name)

Indicate the start of a catch clause in a try statement. All subsequent statements until the next matching _catch or _finally are part of this catch clause.

_finally

public static final void _finally()

Indicate the start of a finally clause in a try statement. All subsequent statements until the next matching _end are part of this finally clause.

_switch

public static final void _switch(Expression expr)

Indicate the start of a switch statement with the given expression at the switch expression. expr must have type int. Must be followed by a _case or _default call.

_case

public static final void _case(int value)

Indicate the start of a particular case in a switch statement. All statements until the next corresponding _case or _default are part of this case.

_default

public static final void _default()

Indicate the start of the default case in a switch statement. All statements until the next corresponding _end are part of the default case.

_while

public static final void _while(Expression expr)

Indicate the start of a while loop with the given expression as its condition. All statements until the next corresponding _end are part of the while loop.

_v

public static final Expression _v(String name)

Construct the expression that refers to the variable named name. This is looked up following the Java name scope rules.

_null

public static final Expression _null()

Return the null expression.

_const

public static final Expression _const(boolean c)

Return a constant expression representing the value c.

_const

public static final Expression _const(char c)

Return a constant expression representing the value c.

_const

public static final Expression _const(byte c)

Return a constant expression representing the value c.

_const

public static final Expression _const(short c)

Return a constant expression representing the value c.

_const

public static final Expression _const(int c)

Return a constant expression representing the value c.

_const

public static final Expression _const(long c)

Return a constant expression representing the value c.

_const

public static final Expression _const(float c)

Return a constant expression representing the value c.

_const

public static final Expression _const(double c)

Return a constant expression representing the value c.

_const

public static final Expression _const(String c)

Return a constant expression representing the value c.

_const

public static final Expression _const(Type c)

Return a constant expression representing the value c. Here c is a type, and this corresponds to the Java ".class" reference.

_call

public static final Expression _call(Expression target,
               String ident,
               Signature signature,
               Expression... args)

Generate a call to an instance method. The full signature must be specified.

_call

public static final Expression _call(Expression target,
               String ident,
               Signature signature,
               List<Expression> args)

Generate a call to an instance method. The full signature must be specified.

_call

public static final Expression _call(Expression target,
               String ident,
               Expression... args)

Generate a call to an instance method, using the Java method overload resolution algorithm to determine the signature.

_call

public static final Expression _call(Expression target,
               String ident,
               List<Expression> args)

Generate a call to an instance method, using the Java method overload resolution algorithm to determine the signature.

_call

public static final Expression _call(Type target,
               String ident,
               Signature signature,
               Expression... args)

Generate a call to a static method. The full signature must be specified.

_call

public static final Expression _call(Type target,
               String ident,
               Signature signature,
               List<Expression> args)

Generate a call to a static method. The full signature must be specified.

_call

public static final Expression _call(Type target,
               String ident,
               Expression... args)

Generate a call to a static method, using the Java method overload resolution algorithm to determine the signature.

_call

public static final Expression _call(Type target,
               String ident,
               List<Expression> args)

Generate a call to a static method, using the Java method overload resolution algorithm to determine the signature.

_super

public static final Expression _super(String ident,
                Signature signature,
                Expression... exprs)

Generate a call to an instance method in the current super class. The full signature must be specified.

_super

public static final Expression _super(String ident,
                Signature signature,
                List<Expression> exprs)

Generate a call to an instance method in the current super class. The full signature must be specified.

_super

public static final Expression _super(String ident,
                Expression... exprs)

Generate a call to an instance method in the current super class using the Java method overload resolution algorithm to determine the signature.

_super

public static final Expression _super(String ident,
                List<Expression> exprs)

Generate a call to an instance method in the current super class using the Java method overload resolution algorithm to determine the signature.

_super

public static final Expression _super(Signature signature,
                Expression... exprs)

Invoke a superclass constructor as the first statement in a constructor for a class. The full signature must be specified. This may only be used as the first expression in a constructor. Every constructor must begin with either a super(...) call or a this(...) call.

_super

public static final Expression _super(Signature signature,
                List<Expression> exprs)

Invoke a superclass constructor as the first statement in a constructor for a class. The full signature must be specified. This may only be used as the first expression in a constructor. Every constructor must begin with either a super(...) call or a this(...) call.

_super

public static final Expression _super(List<Expression> exprs)

Invoke a superclass constructor as the first statement in a constructor for a class using the Java method overload resolution algorithm to determine the signature. This may only be used as the first expression in a constructor. Every constructor must begin with either a super(...) call or a this(...) call.

_super

public static final Expression _super(Expression... exprs)

Invoke a superclass constructor as the first statement in a constructor for a class using the Java method overload resolution algorithm to determine the signature. This may only be used as the first expression in a constructor. Every constructor must begin with either a super(...) call or a this(...) call.

_this

public static final Expression _this(Signature signature,
               Expression... exprs)

Invoke another constructor as the first statement in a constructor for a class. The full signature must be specified. This may only be used as the first expression in a constructor. Every constructor must begin with either a super(...) call or a this(...) call.

_this

public static final Expression _this(Signature signature,
               List<Expression> exprs)

Invoke another constructor as the first statement in a constructor for a class. The full signature must be specified. This may only be used as the first expression in a constructor. Every constructor must begin with either a super(...) call or a this(...) call.

_this

public static final Expression _this(Expression... exprs)

Invoke another constructor as the first statement in a constructor for a class using the Java method overload resolution algorithm to determine the signature. This may only be used as the first expression in a constructor. Every constructor must begin with either a super(...) call or a this(...) call.

_this

public static final Expression _this(List<Expression> exprs)

Invoke another constructor as the first statement in a constructor for a class using the Java method overload resolution algorithm to determine the signature. This may only be used as the first expression in a constructor. Every constructor must begin with either a super(...) call or a this(...) call.

_not

public static final Expression _not(Expression expr)

_add

public static final Expression _add(Expression left,
              Expression right)

Create an expression representing the application of the + operator to the left and right expressions in the form (left op right).

_sub

public static final Expression _sub(Expression left,
              Expression right)

Create an expression representing the application of the + operator to the left and right expressions in the form (left op right).

_mul

public static final Expression _mul(Expression left,
              Expression right)

Create an expression representing the application of the + operator to the left and right expressions in the form (left op right).

_div

public static final Expression _div(Expression left,
              Expression right)

Create an expression representing the application of the + operator to the left and right expressions in the form (left op right).

_rem

public static final Expression _rem(Expression left,
              Expression right)

Create an expression representing the application of the + operator to the left and right expressions in the form (left op right).

_lt

public static final Expression _lt(Expression left,
             Expression right)

Create an expression representing the application of the < operator to the left and right expressions in the form (left op right).

_gt

public static final Expression _gt(Expression left,
             Expression right)

Create an expression representing the application of the > operator to the left and right expressions in the form (left op right).

_le

public static final Expression _le(Expression left,
             Expression right)

Create an expression representing the application of the <= operator to the left and right expressions in the form (left op right).

_ge

public static final Expression _ge(Expression left,
             Expression right)

Create an expression representing the application of the >= operator to the left and right expressions in the form (left op right).

_eq

public static final Expression _eq(Expression left,
             Expression right)

Create an expression representing the application of the == operator to the left and right expressions in the form (left op right).

_ne

public static final Expression _ne(Expression left,
             Expression right)

Create an expression representing the application of the != operator to the left and right expressions in the form (left op right).

_and

public static final Expression _and(Expression left,
              Expression right)

Create an expression representing the application of the && operator to the left and right expressions in the form (left op right).

_or

public static final Expression _or(Expression left,
             Expression right)

Create an expression representing the application of the || operator to the left and right expressions in the form (left op right).

_cast

public static final Expression _cast(Type type,
               Expression expr)

Create an expression representing the type cast of expr to type.

_instanceof

public static final Expression _instanceof(Expression expr,
                     Type type)

Create an expression representing the instanceof test of expr and type (expr instanceof type).

_new

public static final Expression _new(Type type,
              Signature signature,
              Expression... args)

Create an expression representing the construction of a new instance of the given type using the constructor with the given signature and the list of expressions as arguments.

_new

public static final Expression _new(Type type,
              Signature signature,
              List<Expression> args)

Create an expression representing the construction of a new instance of the given type using the constructor with the given signature and the list of expressions as arguments.

_new

public static final Expression _new(Type type,
              Expression... args)

Create an expression representing the construction of a new instance of the given type using the constructor with the signature determined by the Java method overload resolution algorithm and the list of expressions as arguments.

_new

public static final Expression _new(Type type,
              List<Expression> args)

Create an expression representing the construction of a new instance of the given type using the constructor with the signature determined by the Java method overload resolution algorithm and the list of expressions as arguments.

_new_array_init

public static final Expression _new_array_init(Type type,
                         Expression... args)

Create an expression representing the construction of a new array with the given component type using the given expressions to initialize the array. We really only support single dimensional arrays here. The size of the resulting array is the number of expressions given here.

_new_array_init

public static final Expression _new_array_init(Type type,
                         List<Expression> args)

Create an expression representing the construction of a new array with the given component type using the given expressions to initialize the array. We really only support single dimensional arrays here. The size of the resulting array is the number of expressions given here. Equivalent to new A[] = { exprList }.

_new_array

public static final Expression _new_array(Type type,
                    Expression size)

Create an expression representing the construction of a new array of the given size with the given component type. Equivalent to new A[x].

_thisClass

public static final Type _thisClass()

Return the type of the current class.

_this

public static final Expression _this()

Return an expression representing "this".

_field

public static final Expression _field(Expression expr,
                String fieldName)

Return an expression used to access a field in an object given by expr. This expression may appear on the left side of an assignment statement.

_field

public static final Expression _field(Type type,
                String fieldName)

Return an expression used to access a static data member in a class given by the type. This expression may appear on the left side of an assignment statement (but probably shouldn't).

_index

public static final Expression _index(Expression expr,
                Expression index)

Return an expression used to access an element in an array given by expr. This expression may appear on the left side of an assignment statement.

_length

public static final Expression _length(Expression expr)

Return an expression that gets the length of expr. expr must be an array type.