Interface MethodBuilder
-
- All Known Implementing Classes:
BCMethod
public interface MethodBuilder
MethodBuilder is used to generate the code for a method.The code for a method is built in a way that corresponds to the layout of the stack machine that is the Java Virtual Machine. Values are pushed on the stack, moved about on the stack and then popped off the stack by operations such as method calls. An understanding of hoe the JVM operates is useful before using this class.
All the method descriptions below are generating bytecode to achieved the desired behaviour when the generated class is loaded. None of this class's methods calls actually invoke methods or create objects described by the callers.
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description void
addThrownException(java.lang.String exceptionClass)
Declare the method throws an exception.int
callMethod(short type, java.lang.String declaringClass, java.lang.String methodName, java.lang.String returnType, int numArgs)
Call a method.int
callMethod(java.lang.Object methodDescriptor)
Call a method previously described by describeMethod().void
callSuper()
Call super().void
cast(java.lang.String className)
Cast the top stack value.void
complete()
Indicate the method is complete.void
completeConditional()
Complete a conditional which completes the false code path.void
conditionalIf()
Initiate a conditional sequence.void
conditionalIfNull()
Initiate a conditional sequence.java.lang.Object
describeMethod(short opcode, java.lang.String declaringClass, java.lang.String methodName, java.lang.String returnType)
Return an object that efficiently (to the implementation) describes a zero-argument method and can be used with the single argument callMethod().void
dup()
Duplicate the top value on the stack.void
endStatement()
End a statement.void
getArrayElement(int element)
Pop an array refrence off the stack and push an element from that array.void
getField(java.lang.String declaringClass, java.lang.String fieldName, java.lang.String fieldType)
Push the contents of the described field onto the stack.void
getField(LocalField field)
Push the contents of the local field onto the stack.java.lang.String
getName()
return the name of the method.void
getParameter(int id)
Push a parameter value.void
getStaticField(java.lang.String declaringClass, java.lang.String fieldName, java.lang.String fieldType)
Push the contents of the described static field onto the stack.void
isInstanceOf(java.lang.String className)
Pop the top stack value and push a boolean that is the result of an instanceof check on the popped reference.void
methodReturn()
Return from a method, optionally with a value.void
pop()
Pop the top value off the stackvoid
push(boolean value)
Push a boolean constant onto the stackvoid
push(byte value)
Push a byte constant onto the stackvoid
push(double value)
Push a double constant onto the stackvoid
push(float value)
Push a float constant onto the stackvoid
push(int value)
Push a int constant onto the stackvoid
push(long value)
Push a long constant onto the stackvoid
push(short value)
Push a short constant onto the stackvoid
push(java.lang.String value)
Push a String constant onto the stackvoid
pushNewArray(java.lang.String className, int size)
Create an instance of an array and push it onto the stack.void
pushNewComplete(int numArgs)
Complete the sequence that was started with pushNewStart().void
pushNewStart(java.lang.String className)
Initiate a sequence that calls a constructor, equivalent to the new operator in Java.void
pushNull(java.lang.String className)
Push a typed null onto the stackvoid
pushThis()
Push this onto the stack.void
putField(java.lang.String fieldName, java.lang.String fieldType)
Pop the top stack value and store it in the instance field of this class.void
putField(java.lang.String declaringClass, java.lang.String fieldName, java.lang.String fieldType)
Pop the top stack value and store it in the field.void
putField(LocalField field)
Pop the top stack value and store it in the local field.void
setArrayElement(int element)
Pop an array reference off the stack, store a value in the array at the passed in offset.void
setField(LocalField field)
Pop the top stack value and store it in the local field.void
startElseCode()
Complete the true code path of a conditional.boolean
statementNumHitLimit(int noStatementsAdded)
Tell if statement number in this method builder hits limit.void
swap()
Swap the top two values on the stack.void
upCast(java.lang.String className)
Upcast the top stack value.
-
-
-
Method Detail
-
addThrownException
void addThrownException(java.lang.String exceptionClass)
Declare the method throws an exception. Must be called before any code is added to the method.
-
getName
java.lang.String getName()
return the name of the method.
-
complete
void complete()
Indicate the method is complete. Once this call has been made the caller must discard the reference to this object.
-
getParameter
void getParameter(int id)
Push a parameter value.Stack ... => ...,param_value
- Parameters:
id
- position of the parameter (zero based).
-
push
void push(byte value)
Push a byte constant onto the stackStack ... => ...,byte_value
-
push
void push(boolean value)
Push a boolean constant onto the stackStack ... => ...,boolean_value
-
push
void push(short value)
Push a short constant onto the stackStack ... => ...,short_value
-
push
void push(int value)
Push a int constant onto the stackStack ... => ...,int_value
-
push
void push(long value)
Push a long constant onto the stackStack ... => ...,long_value
-
push
void push(float value)
Push a float constant onto the stackStack ... => ...,float_value
-
push
void push(double value)
Push a double constant onto the stackStack ... => ...,double_value
-
push
void push(java.lang.String value)
Push a String constant onto the stackStack ... => ...,String_value
-
pushNull
void pushNull(java.lang.String className)
Push a typed null onto the stackStack ... => ...,null
-
getField
void getField(LocalField field)
Push the contents of the local field onto the stack. This call pushes the this instance required to access the field itself.Stack ... => ...,field_value
-
getField
void getField(java.lang.String declaringClass, java.lang.String fieldName, java.lang.String fieldType)
Push the contents of the described field onto the stack. This call requires the instance (reference) to be pushed by the caller.Stack ...,field_ref => ...,field_value
-
getStaticField
void getStaticField(java.lang.String declaringClass, java.lang.String fieldName, java.lang.String fieldType)
Push the contents of the described static field onto the stack.Stack ... => ...,field_value
-
setField
void setField(LocalField field)
Pop the top stack value and store it in the local field. This call pushes the this instance required to access the field itself. This call does not leave any value on the stack.Stack ...,value => ...
-
putField
void putField(LocalField field)
Pop the top stack value and store it in the local field. This call pushes the this instance required to access the field itself. Like the Java language 'field = value', this leaves the value on the stack.Stack ...,value => ...,value
-
putField
void putField(java.lang.String fieldName, java.lang.String fieldType)
Pop the top stack value and store it in the instance field of this class. This call pushes the this instance required to access the field itself. Like the Java language 'field = value', this leaves the value on the stack.Stack ...,value => ...,value
-
putField
void putField(java.lang.String declaringClass, java.lang.String fieldName, java.lang.String fieldType)
Pop the top stack value and store it in the field. This call requires the instance to be pushed by the caller. Like the Java language 'field = value', this leaves the value on the stack.Stack ...,field_ref,value => ...,value
-
pushNewStart
void pushNewStart(java.lang.String className)
Initiate a sequence that calls a constructor, equivalent to the new operator in Java. After this call, the caller must push any arguments and then complete the construction with a call to pushNewComplete(). Only arguments to the constructor can be pushed onto the stack between the pushNewStart() and pushNewComplete() method calls.Stack ... => [unchanged] ...
- Parameters:
className
- class name of object to be created.
-
pushNewComplete
void pushNewComplete(int numArgs)
Complete the sequence that was started with pushNewStart(). Pop the arguments to the constructor and push the reference to the newly created object.Stack ...,value* => [numArgs number of values will be popped] ...,new_ref
- Parameters:
numArgs
- number of arguments to the constructor (can be 0).
-
pushNewArray
void pushNewArray(java.lang.String className, int size)
Create an instance of an array and push it onto the stack.Stack ... => ...,array_ref
- Parameters:
className
- - type of array.size
- - number of elements in the array
-
pushThis
void pushThis()
Push this onto the stack.Stack ... => ...,this_ref
-
upCast
void upCast(java.lang.String className)
Upcast the top stack value. This is used for correct method resolution by upcasting method parameters. It does not put any casting code into the byte code stream. Can only be used for refrences.Stack ...,ref => ...,ref
-
cast
void cast(java.lang.String className)
Cast the top stack value. Correctly down-casts a reference or casts a primitive type (e.g. int to short).Stack ...,value => ...,cast_value
- Parameters:
className
- type (primitive, interface or class) to cast to.
-
isInstanceOf
void isInstanceOf(java.lang.String className)
Pop the top stack value and push a boolean that is the result of an instanceof check on the popped reference.Stack ...,ref => ...,boolean_value
.
-
pop
void pop()
Pop the top value off the stackStack ..., value => ...
.
-
endStatement
void endStatement()
End a statement. Pops the top-word of the stack, if any. Must only be called if zero or one item exists on the stack.Stack value => :empty: or Stack :empty: => :empty:
.
-
methodReturn
void methodReturn()
Return from a method, optionally with a value. Must only be called if zero or one item exists on the stack. If the stack contains a single value then that is popped and used as the returned value.Stack value => :empty: or Stack :empty: => :empty:
.
-
conditionalIfNull
void conditionalIfNull()
Initiate a conditional sequence. The top value on the stack (a reference) is popped and compared to 'null'. If the value is null then the code following this call until the startElseCode() will be executed at runtime, otherwise the code following startElseCode() until the completeConditional() is called.
E.g.mb.callMethod(...); // pushes an object onto the stack mb.conditionalIfNull(); mb.push(3); mb.startElseCode(); mb.push(5); mb.completeConditional(); // at this point 3 or 5 will be on the stack
Each path through the ?: statement must leave the stack at the same depth as the other.
If the if or else code pops values from the stack that were before the conditional value, then they must use the same number of values from the stack.Stack ...,ref => ...
.
-
conditionalIf
void conditionalIf()
Initiate a conditional sequence. The top value on the stack must be a boolean and will be popped. If it is true then the code following this call until the startElseCode() will be executed at runtime, otherwise the code following startElseCode() until the completeConditional() is called. See conditionalIfNull() for example and restrictions.Stack ...,boolean_value => ...
.
-
startElseCode
void startElseCode()
Complete the true code path of a conditional.
-
completeConditional
void completeConditional()
Complete a conditional which completes the false code path.
-
callMethod
int callMethod(short type, java.lang.String declaringClass, java.lang.String methodName, java.lang.String returnType, int numArgs)
Call a method. The instance (receiver or reference) for non-static methods must be pushed by the caller. The instance (for non-static) and the arguments are popped of the stack, and the return value (if any) is pushed onto the stack.
The type needs to be one of:- VMOpcode.INVOKESTATIC - call a static method
- VMOpcode.INVOKEVIRTUAL - call method declared in the class or super-class.
- VMOpcode.INVOKEINTERFACE - call a method declared in an interface
static methods Stack ...,value* => [numArgs number of values will be popped] ...,return_value [void methods will not push a value] non-static methods Stack ...,ref,value* => [numArgs number of values will be popped] ...,return_value [void methods will not push a value]
The type of the arguments to the methods must exactly match the declared types of the parameters to the methods. If a argument is of the incorrect type the caller must up cast it or down cast it.- Parameters:
type
- type of method invocationdeclaringClass
- Class or interface the method is declared in. If it is a non-static method call then if declaringClass is null, the declared type is taken to be the type of the reference that will be popped.methodName
- name of the methodreturnType
- class name or primitive type (including "void") of the return type of the method, can not be null.numArgs
- number of arguments to the method (can be 0).
-
describeMethod
java.lang.Object describeMethod(short opcode, java.lang.String declaringClass, java.lang.String methodName, java.lang.String returnType)
Return an object that efficiently (to the implementation) describes a zero-argument method and can be used with the single argument callMethod(). Descriptions for the parameters to this method are the same as the five argument callMethod(). This allows the caller to cache frequently used methods. The returned object is only valid for use by this MethodBuilder.
This call does not affect the Stack.
-
callMethod
int callMethod(java.lang.Object methodDescriptor)
Call a method previously described by describeMethod().static methods Stack ...,value* => [numArgs number of values will be popped] ...,return_value [void methods will not push a value] non-static methods Stack ...,ref,value* => [numArgs number of values will be popped] ...,return_value [void methods will not push a value]
-
callSuper
void callSuper()
Call super(). Caller must only add this to a constructor.Stack ... => ...
-
getArrayElement
void getArrayElement(int element)
Pop an array refrence off the stack and push an element from that array.Stack ...,array_ref => ...,value
- Parameters:
element
- Offset into the array (zero based)
-
setArrayElement
void setArrayElement(int element)
Pop an array reference off the stack, store a value in the array at the passed in offset.Stack ...,array_ref, value => ...
- Parameters:
element
- Offset into the array (zero based)
-
swap
void swap()
Swap the top two values on the stack.Stack ...,valueA,valueB => ...,valueB,valueA
-
dup
void dup()
Duplicate the top value on the stack.Stack ...,value => ...,value,value
-
statementNumHitLimit
boolean statementNumHitLimit(int noStatementsAdded)
Tell if statement number in this method builder hits limit. This method builder keeps a counter of how many statements are added to it. Caller should call this function every time it tries to add a statement to this method builder (counter is increased by 1), then the function returns whether the accumulated statement number hits a limit. The reason of doing this is that Java compiler has a limit of 64K code size for each method. We might hit this limit if an extremely long insert statement is issued, for example (see beetle 4293). Counting statement number is an approximation without too much overhead.
-
-