CodeBuilderUtil (Carbonado 1.2.3 API)

java.lang.Object
+
- com.amazon.carbonado.gen.CodeBuilderUtil
+

+
+
+
```
public class CodeBuilderUtil
+extends java.lang.Object
```
+
Collection of useful utilities for generating Carbonado code.
+
Since:
+
1.2
+
Author:
+
Don Schneider, Brian S O'Neill
+

+ +

+ + +
Constructor Summary
+ + + + + + + + +
Constructors
Constructor and Description
CodeBuilderUtil()
+

Constructors
Constructor and Description
`CodeBuilderUtil()`

+ +

Method Summary

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Methods
Modifier and Type	Method and Description
`static void`	`addEqualsCall(org.cojen.classfile.CodeBuilder b, + java.lang.String fieldName, + org.cojen.classfile.TypeDesc fieldType, + boolean testForNull, + org.cojen.classfile.Label fail, + org.cojen.classfile.LocalVariable other)` + Generates code to compare a field in this object against the same one in a + different instance. +
`static void`	`addValueHashCodeCall(org.cojen.classfile.CodeBuilder b, + org.cojen.classfile.TypeDesc valueType, + boolean testForNull, + boolean mixIn)` + Generates code to compute a hashcode for a value on the stack, consuming + the value. +
`static void`	`addValuesEqualCall(org.cojen.classfile.CodeBuilder b, + org.cojen.classfile.TypeDesc valueType, + boolean testForNull, + org.cojen.classfile.Label label, + boolean choice)` + Generates code to compare two values on the stack, and branch to the + provided Label if they are not equal. +
`static void`	`assertParameterNotNull(org.cojen.classfile.CodeBuilder b, + int paramIndex)` + Generate code to throw an exception if a parameter is null +
`static org.cojen.classfile.TypeDesc`	`bindQueryParam(java.lang.Class clazz)` + Determines which overloaded "with" method on Query should be bound to. +
`static void`	`blankValue(org.cojen.classfile.CodeBuilder b, + org.cojen.classfile.TypeDesc type)` + Generates code to push a blank value to the stack. +
`static void`	`callStringBuilderAppendChar(org.cojen.classfile.CodeBuilder b)` + Appends a char to a StringBuilder. +
`static void`	`callStringBuilderAppendString(org.cojen.classfile.CodeBuilder b)` + Appends a String to a StringBuilder. +
`static void`	`callStringBuilderLength(org.cojen.classfile.CodeBuilder b)` + Calls length on a StringBuilder on the stack, leaving an int on the stack. +
`static void`	`callStringBuilderSetLength(org.cojen.classfile.CodeBuilder b)` + Calls setLength on a StringBuilder. +
`static void`	`callStringBuilderToString(org.cojen.classfile.CodeBuilder b)` + Calls toString on a StringBuilder. +
`static void`	`convertValue(org.cojen.classfile.CodeBuilder b, + java.lang.Class from, + java.lang.Class to)` + Converts a value on the stack. +
`static <S extends Storable> org.cojen.classfile.ClassFile`	`createStorableClassFile(org.cojen.util.ClassInjector ci, + java.lang.Class<S> type, + boolean isAbstract, + java.lang.String aSourcefileName)` + Define a classfile appropriate for most Storables. +
`static void`	`defineCopyBridges(org.cojen.classfile.ClassFile cf, + java.lang.Class leaf)` + Add copy bridge methods for all classes/interfaces between the leaf + (genericised class) and the root (genericised baseclass). +
`static void`	`definePrepareBridges(org.cojen.classfile.ClassFile cf, + java.lang.Class leaf)` + Add prepare bridge methods for all classes/interfaces between the leaf + (genericised class) and the root (genericised baseclass). +
`static void`	`definePrepareMethod(org.cojen.classfile.ClassFile cf, + java.lang.Class storableClass, + org.cojen.classfile.TypeDesc supportCtorType)` + Defines a Storable prepare method, which assumes that a support field + exists and a single-argument constructor exists which accepts a support + instance. +
`static void`	`definePrepareMethod(org.cojen.classfile.ClassFile cf, + java.lang.Class storableClass, + org.cojen.classfile.TypeDesc supportCtorType, + java.lang.String supportFieldName, + org.cojen.classfile.TypeDesc supportFieldType)` + Defines a Storable prepare method, which assumes that a support field + exists and a single-argument constructor exists which accepts a support + instance. +
`static java.util.Set<java.lang.Class>`	`gatherAllBridgeTypes(java.util.Set<java.lang.Class> set, + java.lang.Class leaf)` + Collect a set of all the interfaces and recursively all superclasses for the leaf + (genericised class) and root (genericised base class). +
`static void`	`incrementVersion(org.cojen.classfile.CodeBuilder b, + org.cojen.classfile.TypeDesc type)` + Generates code to increment a version property value, already on the stack. +
`static void`	`initialVersion(org.cojen.classfile.CodeBuilder b, + org.cojen.classfile.TypeDesc type, + int value)` + Generates code to push an initial version property value on the stack. +
`static boolean`	`isPublicMethodFinal(java.lang.Class clazz, + java.lang.String name, + org.cojen.classfile.TypeDesc retType, + org.cojen.classfile.TypeDesc[] params)` + Returns true if a public final method exists which matches the given + specification. +
`static void`	`throwConcatException(org.cojen.classfile.CodeBuilder b, + java.lang.Class type, + java.lang.String... messages)` + Generate code to throw an exception with a message concatenated at runtime. +
`static void`	`throwException(org.cojen.classfile.CodeBuilder b, + java.lang.Class type, + java.lang.String message)` + Generate code to throw an exception with an optional message. +
`static org.cojen.classfile.LocalVariable`	`uneraseGenericParameter(org.cojen.classfile.CodeBuilder b, + org.cojen.classfile.TypeDesc paramType, + int paramIndex)` + Generate code to create a local variable containing the specified parameter coerced + to the specified type. +

+ + +
Methods inherited from class java.lang.Object
+clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

+ +
- + + +
  Constructor Detail
  + + + +
  - +
    CodeBuilderUtil
    +
```
public CodeBuilderUtil()
```
    +
  +
+ +
- + + +
  Method Detail
  + + + +
  - +
    assertParameterNotNull
    +
```
public static void assertParameterNotNull(org.cojen.classfile.CodeBuilder b,
+                          int paramIndex)
```
    +
    Generate code to throw an exception if a parameter is null
    +
    Parameters:
    b - CodeBuilder into which to append the code
    paramIndex - index of the parameter to check
    +
  + + + +
  - +
    uneraseGenericParameter
    +
```
public static org.cojen.classfile.LocalVariable uneraseGenericParameter(org.cojen.classfile.CodeBuilder b,
+                                                        org.cojen.classfile.TypeDesc paramType,
+                                                        int paramIndex)
```
    +
    Generate code to create a local variable containing the specified parameter coerced + to the specified type. This is useful for re-interpreting erased generics into + the more specific genericized type.
    +
    Parameters:
    b - CodeBuilder into which to append the code
    paramType - the more specific type which was erased during compilation
    paramIndex - index of the parameter to unerase
    +
    Returns:
    a local variable referencing the type-cast parameter
    +
  + + + +
  - +
    throwException
    +
```
public static void throwException(org.cojen.classfile.CodeBuilder b,
+                  java.lang.Class type,
+                  java.lang.String message)
```
    +
    Generate code to throw an exception with an optional message.
    +
    Parameters:
    b - CodeBuilder to which to add code
    type - type of the object to throw
    message - optional message to provide to the constructor
    +
  + + + +
  - +
    throwConcatException
    +
```
public static void throwConcatException(org.cojen.classfile.CodeBuilder b,
+                        java.lang.Class type,
+                        java.lang.String... messages)
```
    +
    Generate code to throw an exception with a message concatenated at runtime.
    +
    Parameters:
    b - CodeBuilder to which to add code
    type - type of the object to throw
    messages - messages to concat at runtime
    +
  + + + +
  - +
    gatherAllBridgeTypes
    +
```
public static java.util.Set<java.lang.Class> gatherAllBridgeTypes(java.util.Set<java.lang.Class> set,
+                                                  java.lang.Class leaf)
```
    +
    Collect a set of all the interfaces and recursively all superclasses for the leaf + (genericised class) and root (genericised base class). Eg, for Object, all + classes and implemented interfaces for every superclass between foo (the leaf) and + Object (the base). +
    A copy must be coercible into any of these types, and copy bridge methods must be + provided to do so. + +
    Note that the official documentation for this is in draft form, and you have to be + psychic to have figured out the necessity in the first place.
    +
    Parameters:
    set - set into which the class types will be collected
    leaf - leaf class
    +
    Returns:
    same set as was passed in
    +
  + + + +
  - +
    defineCopyBridges
    +
```
public static void defineCopyBridges(org.cojen.classfile.ClassFile cf,
+                     java.lang.Class leaf)
```
    +
    Add copy bridge methods for all classes/interfaces between the leaf + (genericised class) and the root (genericised baseclass).
    +
    Parameters:
    cf - file to which to add the copy bridge
    leaf - leaf class
    +
  + + + +
  - +
    definePrepareMethod
    +
```
public static void definePrepareMethod(org.cojen.classfile.ClassFile cf,
+                       java.lang.Class storableClass,
+                       org.cojen.classfile.TypeDesc supportCtorType)
```
    +
    Defines a Storable prepare method, which assumes that a support field + exists and a single-argument constructor exists which accepts a support + instance.
    +
    Parameters:
    cf - file to which to add the prepare method
    Since:
    +
    1.2
    +
  + + + +
  - +
    definePrepareMethod
    +
```
public static void definePrepareMethod(org.cojen.classfile.ClassFile cf,
+                       java.lang.Class storableClass,
+                       org.cojen.classfile.TypeDesc supportCtorType,
+                       java.lang.String supportFieldName,
+                       org.cojen.classfile.TypeDesc supportFieldType)
```
    +
    Defines a Storable prepare method, which assumes that a support field + exists and a single-argument constructor exists which accepts a support + instance.
    +
    Parameters:
    cf - file to which to add the prepare method
    Since:
    +
    1.2
    +
  + + + +
  - +
    definePrepareBridges
    +
```
public static void definePrepareBridges(org.cojen.classfile.ClassFile cf,
+                        java.lang.Class leaf)
```
    +
    Add prepare bridge methods for all classes/interfaces between the leaf + (genericised class) and the root (genericised baseclass).
    +
    Parameters:
    cf - file to which to add the prepare bridge
    leaf - leaf class
    Since:
    +
    1.2
    +
  + + + +
  - +
    isPublicMethodFinal
    +
```
public static boolean isPublicMethodFinal(java.lang.Class clazz,
+                          java.lang.String name,
+                          org.cojen.classfile.TypeDesc retType,
+                          org.cojen.classfile.TypeDesc[] params)
```
    +
    Returns true if a public final method exists which matches the given + specification.
    +
  + + + +
  - +
    createStorableClassFile
    +
```
public static <S extends Storable> org.cojen.classfile.ClassFile createStorableClassFile(org.cojen.util.ClassInjector ci,
+                                                                         java.lang.Class<S> type,
+                                                                         boolean isAbstract,
+                                                                         java.lang.String aSourcefileName)
```
    +
    Define a classfile appropriate for most Storables. Specifically: +
    - implements Storable
    - implements Cloneable +
    - abstract if appropriate +
    - marked synthetic +
    - targetted for java version 1.5 +
    +
    Parameters:
    ci - ClassInjector for the storable
    type - specific Storable implementation to generate
    isAbstract - true if the class should be abstract
    aSourcefileName - identifier for the classfile, typically the factory class name
    +
    Returns:
    ClassFile object ready to have methods added.
    +
  + + + +
  - +
    addValueHashCodeCall
    +
```
public static void addValueHashCodeCall(org.cojen.classfile.CodeBuilder b,
+                        org.cojen.classfile.TypeDesc valueType,
+                        boolean testForNull,
+                        boolean mixIn)
```
    +
    Generates code to compute a hashcode for a value on the stack, consuming + the value. After the code executes, the stack contains an int hashcode.
    +
    Parameters:
    b - CodeBuilder to which to add the code
    valueType - the type of the value
    testForNull - if true and the value is a reference and might be null
    mixIn - if true, stack has an existing hashcode followed by a value
    Since:
    +
    1.2.2
    +
  + + + +
  - +
    addEqualsCall
    +
```
public static void addEqualsCall(org.cojen.classfile.CodeBuilder b,
+                 java.lang.String fieldName,
+                 org.cojen.classfile.TypeDesc fieldType,
+                 boolean testForNull,
+                 org.cojen.classfile.Label fail,
+                 org.cojen.classfile.LocalVariable other)
```
    +
    Generates code to compare a field in this object against the same one in a + different instance. Branch to the provided Label if they are not equal.
    +
    Parameters:
    b - CodeBuilder to which to add the code
    fieldName - the name of the field
    fieldType - the type of the field
    testForNull - if true and the values are references, they will be considered + unequal unless neither or both are null. If false, assume neither is null.
    fail - the label to branch to
    other - the other instance to test
    +
  + + + +
  - +
    addValuesEqualCall
    +
```
public static void addValuesEqualCall(org.cojen.classfile.CodeBuilder b,
+                      org.cojen.classfile.TypeDesc valueType,
+                      boolean testForNull,
+                      org.cojen.classfile.Label label,
+                      boolean choice)
```
    +
    Generates code to compare two values on the stack, and branch to the + provided Label if they are not equal. Both values must be of the same + type. If they are floating point values, NaN is considered equal to NaN, + which is inconsistent with the usual treatment for NaN. + +
    The generated instruction consumes both values on the stack.
    +
    Parameters:
    b - CodeBuilder to which to add the code
    valueType - the type of the values
    testForNull - if true and the values are references, they will be considered + unequal unless neither or both are null. If false, assume neither is null.
    label - the label to branch to
    choice - when true, branch to label if values are equal, else + branch to label if values are unequal.
    +
  + + + +
  - +
    convertValue
    +
```
public static void convertValue(org.cojen.classfile.CodeBuilder b,
+                java.lang.Class from,
+                java.lang.Class to)
```
    +
    Converts a value on the stack. If "to" type is a String, then conversion + may call the String.valueOf(from).
    +
  + + + +
  - +
    initialVersion
    +
```
public static void initialVersion(org.cojen.classfile.CodeBuilder b,
+                  org.cojen.classfile.TypeDesc type,
+                  int value)
+                           throws SupportException
```
    +
    Generates code to push an initial version property value on the stack.
    +
    Throws:
    +
    SupportException - if version type is not supported
    +
  + + + +
  - +
    incrementVersion
    +
```
public static void incrementVersion(org.cojen.classfile.CodeBuilder b,
+                    org.cojen.classfile.TypeDesc type)
+                             throws SupportException
```
    +
    Generates code to increment a version property value, already on the stack.
    +
    Throws:
    +
    SupportException - if version type is not supported
    +
  + + + +
  - +
    blankValue
    +
```
public static void blankValue(org.cojen.classfile.CodeBuilder b,
+              org.cojen.classfile.TypeDesc type)
```
    +
    Generates code to push a blank value to the stack. For objects, it is + null, and for primitive types it is zero or false.
    +
  + + + +
  - +
    bindQueryParam
    +
```
public static org.cojen.classfile.TypeDesc bindQueryParam(java.lang.Class clazz)
```
    +
    Determines which overloaded "with" method on Query should be bound to.
    +
  + + + +
  - +
    callStringBuilderAppendString
    +
```
public static void callStringBuilderAppendString(org.cojen.classfile.CodeBuilder b)
```
    +
    Appends a String to a StringBuilder. A StringBuilder and String must be + on the stack, and a StringBuilder is left on the stack after the call.
    +
  + + + +
  - +
    callStringBuilderAppendChar
    +
```
public static void callStringBuilderAppendChar(org.cojen.classfile.CodeBuilder b)
```
    +
    Appends a char to a StringBuilder. A StringBuilder and char must be on + the stack, and a StringBuilder is left on the stack after the call.
    +
  + + + +
  - +
    callStringBuilderLength
    +
```
public static void callStringBuilderLength(org.cojen.classfile.CodeBuilder b)
```
    +
    Calls length on a StringBuilder on the stack, leaving an int on the stack.
    +
  + + + +
  - +
    callStringBuilderSetLength
    +
```
public static void callStringBuilderSetLength(org.cojen.classfile.CodeBuilder b)
```
    +
    Calls setLength on a StringBuilder. A StringBuilder and int must be on + the stack, and both are consumed after the call.
    +
  + + + +
  - +
    callStringBuilderToString
    +
```
public static void callStringBuilderToString(org.cojen.classfile.CodeBuilder b)
```
    +
    Calls toString on a StringBuilder. A StringBuilder must be on the stack, + and a String is left on the stack after the call.
    +
  +
+

Class CodeBuilderUtil

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

CodeBuilderUtil

Method Detail

assertParameterNotNull

uneraseGenericParameter

throwException

throwConcatException

gatherAllBridgeTypes

defineCopyBridges

definePrepareMethod

definePrepareMethod

definePrepareBridges

isPublicMethodFinal

createStorableClassFile

addValueHashCodeCall

addEqualsCall

addValuesEqualCall

convertValue

initialVersion

incrementVersion

blankValue

bindQueryParam

callStringBuilderAppendString

callStringBuilderAppendChar

callStringBuilderLength

callStringBuilderSetLength

callStringBuilderToString