com.saxonica.bytecode.util

## Class Generator

- java.lang.Object
- - org.objectweb.asm.MethodAdapter
  - - org.objectweb.asm.commons.LocalVariablesSorter
    - - org.objectweb.asm.commons.GeneratorAdapter
      - - com.saxonica.bytecode.util.Generator

- All Implemented Interfaces:
    org.objectweb.asm.MethodVisitor

      public class Generator
      extends org.objectweb.asm.commons.GeneratorAdapter

  This class is an extension of the ASM-supplied GeneratorAdapter library, containing additional utility and shortcut methods for bytecode generation

- - ### Field Summary

    - ### Fields inherited from class org.objectweb.asm.commons.GeneratorAdapter

      `ADD, AND, DIV, EQ, GE, GT, LE, LT, MUL, NE, NEG, OR, REM, SHL, SHR, SUB, USHR, XOR`

    - ### Fields inherited from class org.objectweb.asm.commons.LocalVariablesSorter

      `firstLocal, nextLocal`

    - ### Fields inherited from class org.objectweb.asm.MethodAdapter

      `mv`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Generator(int access, org.objectweb.asm.commons.Method method, org.objectweb.asm.Type[] exceptions, org.objectweb.asm.ClassVisitor cv)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addComment(CompilerService compiler, String message)` Add a comment (in the form of an unused label) to the code listing
    `void` | `checkClass(Class theClass)` Generate a "checking" cast instruction, given a Class the check against.
    `void` | `concatenateStrings(int n)` Generate code to concatenate a sequence of string objects.
    `void` | `getInstanceField(Class theClass, String fieldName)` Helper method to get an instance-level field of an object
    `org.objectweb.asm.Type` | `getLocalType(int local)` Returns the type of the given local variable.
    `void` | `getStaticField(Class theClass, String fieldName, Class fieldClass)` Helper method to generate code that gets a static field
    `void` | `goTo(LabelInfo labelInfo)` Generate code to go to a LabelInfo
    `void` | `ifCmp(org.objectweb.asm.Type type, int mode, org.objectweb.asm.Label label)` Generates the instructions to jump to a label based on the comparison of the top two stack values.
    `void` | `ifFalse(LabelInfo label)` Generate code to test whether the object on top of stack is NOT an instance of a given class
    `void` | `ifInstance(Class theClass, LabelInfo label)` Generate code to test whether the object on top of stack is an instance of a given class
    `void` | `ifNotInstance(Class theClass, LabelInfo label)` Generate code to test whether the object on top of stack is NOT an instance of a given class
    `void` | `ifNotSameObject(LabelInfo label)` Generate code to test whether the two object references on top of stack refer to different objects
    `void` | `ifSameObject(LabelInfo label)` Generate code to test whether the two object references on top of stack refer to the same object
    `void` | `ifTrue(LabelInfo label)` Generate code to test whether the object on top of stack is the boolean true
    `void` | `invokeConstructor(Class theClass, Class... argTypes)` Helper method to generate code that invokes a constructor.
    `void` | `invokeDefaultConstructor(Class theClass)` Helper method for a zero-argument constructor.
    `void` | `invokeInstanceMethod(Class theClass, String methodName, Class... argTypes)` Helper method to generate code that invokes an instance method
    `void` | `invokeStaticMethod(Class theClass, String methodName, Class... argTypes)` Helper method to generate code that invokes a static method
    `void` | `loadArgOrLocal(int slot)` Load a local variable or method argument
    `void` | `loadLocal(int local)` Generates the instruction to load the given local variable on the stack.
    `void` | `newInstance(Class theClass)` Helper method to generate code that creates a new instance of a class
    `int` | `newLocal(Class theClass)` Helper method to generate a local bytecode variable
    `void` | `pushNull()` Push "null" onto the stack
    `void` | `showIntVariable(CompilerService compiler, String name, int slot)` Generate code to output the value of a run-time variable (which must hold an int)
    `void` | `showLongVariable(CompilerService compiler, String name, int slot)` Generate code to output the value of a run-time variable (which must hold a long)
    `void` | `showMessage(CompilerService compiler, String message)` Generate code to output a simple diagnostic message at run-time
    `void` | `showObject(CompilerService compiler, String label)` Generate code to output the value of of the object on the top of the bytecode stack
    `void` | `showObjectVariable(CompilerService compiler, String name, int slot)` Generate code to output the value of a run-time bytecode variable (which must hold an object)
    `void` | `storeArgOrLocal(int slot)` Generate code to store the value from top of stack into a local variable or method argument slot
    `void` | `storeLocal(int local)` Generates the instruction to store the top stack value in the given local variable.
    `void` | `visitTryCatchBlock(LabelInfo start, LabelInfo end, LabelInfo handler, String type)` Process a try/catch block

    - ### Methods inherited from class org.objectweb.asm.commons.GeneratorAdapter

      `arrayLength, arrayLoad, arrayStore, box, cast, catchException, checkCast, dup, dup2, dup2X1, dup2X2, dupX1, dupX2, endMethod, getField, getStatic, goTo, ifICmp, ifNonNull, ifNull, ifZCmp, iinc, instanceOf, invokeConstructor, invokeDynamic, invokeInterface, invokeStatic, invokeVirtual, loadArg, loadArgArray, loadArgs, loadArgs, loadLocal, loadThis, mark, mark, math, monitorEnter, monitorExit, newArray, newInstance, newLabel, not, pop, pop2, push, push, push, push, push, push, push, putField, putStatic, ret, returnValue, setLocalType, storeArg, storeLocal, swap, swap, tableSwitch, tableSwitch, throwException, throwException, unbox, valueOf`

    - ### Methods inherited from class org.objectweb.asm.commons.LocalVariablesSorter

      `newLocal, newLocalMapping, visitFrame, visitIincInsn, visitLocalVariable, visitMaxs, visitVarInsn`

    - ### Methods inherited from class org.objectweb.asm.MethodAdapter

      `visitAnnotation, visitAnnotationDefault, visitAttribute, visitCode, visitEnd, visitFieldInsn, visitInsn, visitIntInsn, visitJumpInsn, visitLabel, visitLdcInsn, visitLineNumber, visitLookupSwitchInsn, visitMethodInsn, visitMultiANewArrayInsn, visitParameterAnnotation, visitTableSwitchInsn, visitTryCatchBlock, visitTypeInsn`

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### Generator

          public Generator(int access,
                   org.objectweb.asm.commons.Method method,
                   org.objectweb.asm.Type[] exceptions,
                   org.objectweb.asm.ClassVisitor cv)

  - ### Method Detail

    - #### ifInstance

          public void ifInstance(Class theClass,
                        LabelInfo label)

      Generate code to test whether the object on top of stack is an instance of a given class
      Parameters:
        `theClass` - the class to be tested
        `label` - the label to jump to if the current object is an instance of the class. If it is not an instance, control passes to the next instruction

    - #### ifNotInstance

          public void ifNotInstance(Class theClass,
                           LabelInfo label)

      Generate code to test whether the object on top of stack is NOT an instance of a given class
      Parameters:
        `theClass` - the class to be tested
        `label` - the label to jump to if the current object is an instance of the class. If it is not an instance, control passes to the next instruction

    - #### goTo

          public void goTo(LabelInfo labelInfo)

      Generate code to go to a LabelInfo
      Parameters:
        `labelInfo` - the label to jump to

    - #### pushNull

          public void pushNull()

      Push "null" onto the stack

    - #### ifTrue

          public void ifTrue(LabelInfo label)

      Generate code to test whether the object on top of stack is the boolean true
      Parameters:
        `label` - the label to jump to if the value on top of stack is true (non-zero)

    - #### ifFalse

          public void ifFalse(LabelInfo label)

      Generate code to test whether the object on top of stack is NOT an instance of a given class
      Parameters:
        `label` - the label to jump to if the current object is false (zero)

    - #### ifSameObject

          public void ifSameObject(LabelInfo label)

      Generate code to test whether the two object references on top of stack refer to the same object
      Parameters:
        `label` - the label to jump to if the two object references are equal

    - #### ifNotSameObject

          public void ifNotSameObject(LabelInfo label)

      Generate code to test whether the two object references on top of stack refer to different objects
      Parameters:
        `label` - the label to jump to if the two object references are different

    - #### checkClass

          public void checkClass(Class theClass)

      Generate a "checking" cast instruction, given a Class the check against.
      Parameters:
        `theClass` - the class to be tested

    - #### addComment

          public void addComment(CompilerService compiler,
                        String message)

      Add a comment (in the form of an unused label) to the code listing
      Parameters:
        `compiler` - the compiler service
        `message` - the comment to be added to the code

    - #### showMessage

          public void showMessage(CompilerService compiler,
                         String message)

      Generate code to output a simple diagnostic message at run-time
      Parameters:
        `compiler` - the compiler service
        `message` - the message to be output at run-time

    - #### showObject

          public void showObject(CompilerService compiler,
                        String label)

      Generate code to output the value of of the object on the top of the bytecode stack
      Parameters:
        `compiler` - the compiler service
        `label` - a label used to prefix the message to be output at run-time

    - #### showObjectVariable

          public void showObjectVariable(CompilerService compiler,
                                String name,
                                int slot)

      Generate code to output the value of a run-time bytecode variable (which must hold an object)
      Parameters:
        `compiler` - the compiler service
        `name` - a label used to prefix the message to be output at run-time, typically the variable name
        `slot` - the slot number on the bytecode stack whose value is to be displayed

    - #### showLongVariable

          public void showLongVariable(CompilerService compiler,
                              String name,
                              int slot)

      Generate code to output the value of a run-time variable (which must hold a long)
      Parameters:
        `compiler` - the compiler service
        `name` - a label used to prefix the message to be output at run-time, typically the variable name
        `slot` - the slot number on the bytecode stack whose value is to be displayed

    - #### showIntVariable

          public void showIntVariable(CompilerService compiler,
                             String name,
                             int slot)

      Generate code to output the value of a run-time variable (which must hold an int)
      Parameters:
        `compiler` - the compiler service
        `name` - a label used to prefix the message to be output at run-time, typically the variable name
        `slot` - the slot number on the bytecode stack whose value is to be displayed

    - #### getStaticField

          public void getStaticField(Class theClass,
                            String fieldName,
                            Class fieldClass)

      Helper method to generate code that gets a static field
      Parameters:
        `theClass` - the class on which the field is defined
        `fieldName` - the name of the field to be fetched
        `fieldClass` - the class of the field to be fetched

    - #### invokeStaticMethod

          public void invokeStaticMethod(Class theClass,
                                String methodName,
                                Class... argTypes)

      Helper method to generate code that invokes a static method
      Parameters:
        `theClass` - the class on which the method is defined
        `methodName` - the name of the method to be invoked
        `argTypes` - the classes of the arguments to the method
      Throws:
        `AssertionError` - if no suitable method is defined on this class

    - #### invokeInstanceMethod

          public void invokeInstanceMethod(Class theClass,
                                  String methodName,
                                  Class... argTypes)

      Helper method to generate code that invokes an instance method
      Parameters:
        `theClass` - the instance class on which the method is defined
        `methodName` - the name of the method to be invoked
        `argTypes` - the classes of the arguments to the method
      Throws:
        `AssertionError` - if no suitable method is defined on this interface

    - #### getInstanceField

          public void getInstanceField(Class theClass,
                              String fieldName)

      Helper method to get an instance-level field of an object
      Parameters:
        `theClass` - the instance class on which the method is defined
        `fieldName` - the name of the field to be obtained
      Throws:
        `AssertionError` - if no suitable method is defined on this interface

    - #### invokeDefaultConstructor

          public void invokeDefaultConstructor(Class theClass)

      Helper method for a zero-argument constructor. Generates code to invoke the constructor, leaving the constructed instance on the top of the bytecode stack
      Parameters:
        `theClass` - the class of object to be constructed

    - #### newInstance

          public void newInstance(Class theClass)

      Helper method to generate code that creates a new instance of a class
      Parameters:
        `theClass` - the class to be instantiated

    - #### invokeConstructor

          public void invokeConstructor(Class theClass,
                               Class... argTypes)

      Helper method to generate code that invokes a constructor. Precondition: the target of the method and all its argments are on the stack (the target must first be created using the newInstance() instruction). Postcondition: the above items are removed from the stack
      Parameters:
        `theClass` - the class on which the method is defined
        `argTypes` - the classes of the arguments to the constructor
      Throws:
        `AssertionError` - if no suitable constructor is defined on this class

    - #### newLocal

          public int newLocal(Class theClass)

      Helper method to generate a local bytecode variable
      Parameters:
        `theClass` - the class of the variable
      Returns:
        the slot number allocated to the variable

    - #### loadLocal

          public void loadLocal(int local)

      Generates the instruction to load the given local variable on the stack.
      Overrides:
        `loadLocal` in class `org.objectweb.asm.commons.GeneratorAdapter`
      Parameters:
        `local` - a local variable identifier, as returned by `newLocal()`.

    - #### loadArgOrLocal

          public void loadArgOrLocal(int slot)

      Load a local variable or method argument
      Parameters:
        `slot` - the slot number to be loaded, which may represent either a method argument or a local variable

    - #### storeLocal

          public void storeLocal(int local)

      Generates the instruction to store the top stack value in the given local variable.
      Overrides:
        `storeLocal` in class `org.objectweb.asm.commons.GeneratorAdapter`
      Parameters:
        `local` - a local variable identifier, as returned by `newLocal()`.

    - #### storeArgOrLocal

          public void storeArgOrLocal(int slot)

      Generate code to store the value from top of stack into a local variable or method argument slot
      Parameters:
        `slot` - the slot number to be used, which may represent either a method argument or a local variable

    - #### getLocalType

          public org.objectweb.asm.Type getLocalType(int local)

      Returns the type of the given local variable.
      Overrides:
        `getLocalType` in class `org.objectweb.asm.commons.GeneratorAdapter`
      Parameters:
        `local` - a local variable identifier, as returned by `newLocal()`.
      Returns:
        the type of the given local variable.

    - #### visitTryCatchBlock

          public void visitTryCatchBlock(LabelInfo start,
                                LabelInfo end,
                                LabelInfo handler,
                                String type)

      Process a try/catch block
      Parameters:
        `start` - the label for the start of the try block
        `end` - the label for the end of the try block
        `handler` - the label for the catch block
        `type` - the type

    - #### concatenateStrings

          public void concatenateStrings(int n)

      Generate code to concatenate a sequence of string objects. The strings must be on the stack, in order. On completion, the concatenated string is on the top of the bytecode stack
      Parameters:
        `n` - the number of strings to be concatenated

    - #### ifCmp

          public void ifCmp(org.objectweb.asm.Type type,
                   int mode,
                   org.objectweb.asm.Label label)

      Generates the instructions to jump to a label based on the comparison of the top two stack values. This method overrides the corresponding method in class GeneratorAdaptor in order to fix bug 1564
      Overrides:
        `ifCmp` in class `org.objectweb.asm.commons.GeneratorAdapter`
      Parameters:
        `type` - the type of the top two stack values.
        `mode` - how these values must be compared. One of EQ, NE, LT, GE, GT, LE.
        `label` - where to jump if the comparison result is `true`.

Copyright (c) 2004-2013 Saxonica Limited. All rights reserved.