Package org.apache.tapestry5.plastic

Interface InstructionBuilder

  • All Known Implementing Classes:
    InstructionBuilderImpl
    public interface InstructionBuilder
    Simplifies the generation of method instructions for a particular method (or constructor), allowing bytecode to be created with a friendlier API that focuses on Java type names (names as they would appear in Java source) rather than JVM descriptors or internal names. In some limited cases, types may be specified as Java Class instances as well. In addition, there is good support for primitive type boxing and unboxing. Most methods return the same instance of InstructionBuilder, allowing for a "fluid" API. More complex functionality, such as try/catch blocks, is more like a DSL (domain specific language), and is based on callbacks. This looks better in Groovy and will be more reasonable once JDK 1.8 closures are available; in the meantime, it means some deeply nested inner classes, but helps ensure that correct bytecode is generated and helps to limit the amount of bookkeeping is necessary on the part of code using InstructionBuilder.

    • Method Detail

      • returnDefaultValue

        @Opcodes("ACONST_NULL, LCONST_0, FCONST_0, DCONST_0, ICONST_0, RETURN, ARETURN, IRETURN, FRETURN, LRETURN, DRETURN")
InstructionBuilder returnDefaultValue()
        Returns the default value for the method, which may be null, or a specific primitive value.

      • loadArgument

        @Opcodes("ALOAD, ILOAD, LLOAD, FLOAD, DLOAD")
InstructionBuilder loadArgument​(int index)
        Loads an argument onto the stack, using the opcode appropriate to the argument's type. In addition this automatically adjusts for arguments of primitive type long or double (which take up two local variable indexes, rather than one as for all other types)
        Parameters:
        index - to argument (0 is the first argument, not this)

      • loadArguments

        @Opcodes("ALOAD, ILOAD, LLOAD, FLOAD, DLOAD")
InstructionBuilder loadArguments()
        Loads all arguments for the current method onto the stack; this is used when invoking a method that takes the exact same parameters (often, a super-class implementation). A call to loadThis() (or some other way of identifying the target method) should precede this call.

      • invokeSpecial

        @Opcodes("INVOKESPECIAL")
 containingClassName,
                                 MethodDescription description)
        Invokes an instance method of a base class, or a private method of a class, using the target object and parameters already on the stack. Leaves the result on the stack (unless its a void method).
        Parameters:
        containingClassName - class name containing the method
        description - describes the method name, parameters and return type

      • invokeVirtual

        @Opcodes("INVOKEVIRTUAL")
 className,
                                  returnType,
                                  methodName,
                                 ... argumentTypes)
        Invokes a standard virtual method.

      • invokeInterface

        @Opcodes("INVOKEINTERFACE")
 interfaceName,
                                    returnType,
                                    methodName,
                                   ... argumentTypes)
        Invokes a standard virtual method.

      • invokeStatic

        @Opcodes("INVOKESTATIC")
 clazz,
                                 returnType,
                                 methodName,
                                ... argumentTypes)
        Invokes a static method of a class.

      • returnResult

        @Opcodes("ARETURN, IRETURN, LRETURN, FRETURN, DRETURN")
InstructionBuilder returnResult()
        Returns the top value on the stack. For void methods, no value should be on the stack and the method will simply return.

      • boxPrimitive

        @Opcodes("INVOKESTATIC")
 typeName)
        If the type name is a primitive type, adds code to box the type into the equivalent wrapper type, using static methods on the wrapper type. Does nothing if the type is not primitive, or type void.

      • unboxPrimitive

        @Opcodes("INVOKEVIRTUAL")
 typeName)
        Unboxes a wrapper type to a primitive type if typeName is a primitive type name (the value on the stack should be the corresponding wrapper type instance). Does nothing for non-primitive types.
        Parameters:
        typeName - possibly primitive type name

      • getField

        @Opcodes("GETFIELD")
 className,
                             fieldName,
                             typeName)
        Loads an instance field onto the stack. The object containing the field should already be loaded onto the stack (usually, via loadThis()).
        Parameters:
        className - name of class containing the field
        fieldName - name of the field
        typeName - type of field

      • getField

        @Opcodes("GETFIELD")
InstructionBuilder getField​(PlasticField field)
        Loads an instance or static field onto the stack. The plastic class instance containing the field should already be loaded onto the stack (usually, via loadThis()).
        Parameters:
        field - identifies name, type and container of field to load

      • getField

        @Opcodes("GETFIELD")
 className,
                             fieldName,
                             fieldType)
        Loads a field onto the stack. This version is used when the field type is known at build time, rather than discovered at runtime.
        Parameters:
        className - name of class containing the field
        fieldName - name of the field
        fieldType - type of field

      • getStaticField

        @Opcodes("GETSTATIC")
 className,
                                   fieldName,
                                   fieldType)
        Gets a static field; does not consume a value from the stack, but pushes the fields' value onto the stack.
        Parameters:
        className - name of class containing the field
        fieldName - name of the field
        fieldType - type of field

      • getStaticField

        @Opcodes("GETSTATIC")
 className,
                                   fieldName,
                                   typeName)
        Gets a static field; does not consume a value from the stack, but pushes the fields' value onto the stack.
        Parameters:
        className - name of class containing the field
        fieldName - name of the field
        typeName - type of field

      • putStaticField

        @Opcodes("PUTSTATIC")
 className,
                                   fieldName,
                                   fieldType)
        Sets a static field; the new field value should be on top of the stack.
        Parameters:
        className - name of class containing the field
        fieldName - name of the field
        fieldType - type of field

      • putStaticField

        @Opcodes("PUTSTATIC")
 className,
                                   fieldName,
                                   typeName)
        Sets a static field; the new field value should be on top of the stack.
        Parameters:
        className - name of class containing the field
        fieldName - name of the field
        typeName - type of field

      • putField

        @Opcodes("PUTFIELD")
 className,
                             fieldName,
                             typeName)
        Expects the stack to contain the instance to update, and the value to store into the field.

      • putField

        @Opcodes("PUTFIELD")
 className,
                             fieldName,
                             fieldType)

      • loadArrayElement

        @Opcodes("LDC, AALOAD")
InstructionBuilder loadArrayElement​(int index,
                                     elementType)
        Loads a value from an array object, which must be the top element of the stack.
        Parameters:
        index - constant index into the array
        elementType - the type name of the elements of the array Note: currently only reference types (objects and arrays) are supported, not primitives

      • loadArrayElement

        @Opcodes("AALOAD")
InstructionBuilder loadArrayElement()
        Loads a value from an array object. The stack should have the array at depth 1, and an array index on top. Only object arrays (not arrays of primitives) are supported.

      • checkcast

        @Opcodes("CHECKCAST")
 className)
        Adds a check that the object on top of the stack is assignable to the indicated class.
        Parameters:
        className - class to cast to

      • checkcast

        @Opcodes("CHECKCAST")
 clazz)

      • startTryCatch

        InstructionBuilder startTryCatch​(TryCatchCallback tryCatchCallback)
        Defines the start of a block that can have exception handlers and finally blocks applied. Continue using this InstructionBuilder to define code inside the block, then call methods on the InstructionBlock to define the end of the block and set up handlers.
        Parameters:
        tryCatchCallback - allows generation of try, catch, and finally clauses

      • newInstance

        @Opcodes("NEW")
 className)
        Creates a new, uninitialized instance of the indicated class. This should be followed by code to call the new instance's constructor.
        Parameters:
        className - of class to instantiate

      • newInstance

        @Opcodes("NEW")
 clazz)
        A convenience version of newInstance(String) used when the class is known at build time.
        Parameters:
        clazz - to instantiate

      • invokeConstructor

        @Opcodes("INVOKESPECIAL")
 className,
                                     ... argumentTypes)
        Invokes a constructor on a class. The instance should already be on the stack, followed by the right number and type of parameters. Note that a constructor acts like a void method, so you will often follow the sequence: newInstance(), dupe(0), invokeConstructor() so that a reference to the instance is left on the stack.F
        Parameters:
        className - the class containing the constructor
        argumentTypes - java type names for each argument of the constructor

      • invokeConstructor

        @Opcodes("INVOKESPECIAL")
 clazz,
                                     ... argumentTypes)

      • dupe

        @Opcodes("DUP, DUP_X1, DUP_X2")
InstructionBuilder dupe​(int depth)
        Duplicates the top object on the stack, placing the result at some depth.
        Parameters:
        depth - 0 (DUP), 1 (DUP_X1) or 2 (DUP_X2)

      • pop

        InstructionBuilder pop()
        Discards the top value on the stack. Assumes the value is a single word value: an object reference, or a small primitive) and not a double or long.

      • swap

        @Opcodes("SWAP")
InstructionBuilder swap()
        Swaps the top element of the stack with the next element down. Note that this can cause problems if the top element on the stack is a long or double.

      • loadConstant

        @Opcodes("LDC, ICONST_*, LCONST_*, FCONST_*, DCONST_*, ACONST_NULL")
 constant)
        Loads a constant value
        Parameters:
        constant - Integer, Float, Double, Long, String or null

      • loadTypeConstant

        @Opcodes("LDC")
 typeName)
        Loads a Java type (a Class instance) as a constant. This assumes the type name is the name of class (or array) but not a primitive type.
        Parameters:
        typeName - Java class name

      • loadTypeConstant

        @Opcodes("LDC")
 type)
        Loads a Java type (a Class instance) as a constant. This assumes the type name is the name of class (or array) but not a primitive type.
        Parameters:
        type - Java type to load as a constant

      • castOrUnbox

        @Opcodes("CHECKCAST, INVOKEVIRTUAL")
 typeName)
        Casts the object on top of the stack to the indicated type. For primitive types, casts to the wrapper type and invokes the appropriate unboxing static method call, leaving a primitive type value on the stack.
        Parameters:
        typeName - to cast or unbox to

      • throwException

        @Opcodes("NEW, DUP, LDC, INVOKESPECIAL, ATHROW")
 className,
                                   message)
        Throws an exception with a fixed message. Assumes the exception class includes a constructor that takes a single string.
        Parameters:
        className - name of exception class to instantiate
        message - message (passed as first and only parameter to constructor)

      • throwException

        @Opcodes("NEW, DUP, LDC, INVOKESPECIAL, ATHROW")
<? extends > exceptionType,
                                   message)

      • startVariable

         type,
                                 LocalVariableCallback callback)
        Starts a block where the given name is active.
        Parameters:
        type - type of local variable
        callback - generates code used when variable is in effect

      • when

        @Opcodes("IFEQ, etc., GOTO")
InstructionBuilder when​(Condition condition,
                        WhenCallback callback)
        Executes conditional code based on a Condition. The testing opcodes all pop the value off the stack, so this is usually preceded by dupe(0).
        Parameters:
        condition - defines true and false cases
        callback - provides code for true and false blocks
        Returns:
        this builder

      • when

        @Opcodes("IFEQ, etc., GOTO")
InstructionBuilder when​(Condition condition,
                        InstructionBuilderCallback ifTrue)
        Simplified version of when(Condition, WhenCallback) that simply executes the callback code when the condition is true and does nothing if the condition is false (the more general case). The testing opcodes all pop the value off the stack, so this is usually preceded by dupe(0).
        Parameters:
        condition - to evaluate
        ifTrue - generates code for when condition is true
        Returns:
        this builder

      • iterateArray

        @Opcodes("IINC, ARRAYLENGTH, IFEQ, etc., GOTO")
InstructionBuilder iterateArray​(InstructionBuilderCallback callback)
        Expects an array to be the top value on the stack. Iterates the array. The callback generates code that will have each successive value from the array as the top value on the stack. Creates a variable to store the loop index.
        Parameters:
        callback - to invoke. The element will be the top value on the stack. The callback is responsible for removing it from the stack.
        Returns:
        this builder

      • compareSpecial

        @Opcodes("LCMP, FCMPL, DCMPL")
 typeName)
        Special comparison logic for primitive float, double and long. Expect two matching wide values on the stack. Reduces the two wide values to a single int value: -1, 0, or 1 depending on whether the deeper value is less than, equal to, or greater than the top value on the stack.
        Parameters:
        typeName -