com.amazon.carbonado.gen
Class CodeBuilderUtil

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

public class CodeBuilderUtil
extends Object

Collection of useful utilities for generating Carbonado code.

Since:

1.2

Author:

Don Schneider, Brian S O'Neill

Constructor Summary

CodeBuilderUtil()

Method Summary

static void	addEqualsCall(CodeBuilder b, String fieldName, TypeDesc fieldType, boolean testForNull, Label fail, LocalVariable other) Generates code to compare a field in this object against the same one in a different instance.
static void	addValuesEqualCall(CodeBuilder b, TypeDesc valueType, boolean testForNull, 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(CodeBuilder b, int paramIndex) Generate code to throw an exception if a parameter is null
static TypeDesc	bindQueryParam(Class clazz) Determines which overloaded "with" method on Query should be bound to.
static void	blankValue(CodeBuilder b, TypeDesc type) Generates code to push a blank value to the stack.
static void	callStringBuilderAppendChar(CodeBuilder b) Appends a char to a StringBuilder.
static void	callStringBuilderAppendString(CodeBuilder b) Appends a String to a StringBuilder.
static void	callStringBuilderLength(CodeBuilder b) Calls length on a StringBuilder on the stack, leaving an int on the stack.
static void	callStringBuilderSetLength(CodeBuilder b) Calls setLength on a StringBuilder.
static void	callStringBuilderToString(CodeBuilder b) Calls toString on a StringBuilder.
static void	convertValue(CodeBuilder b, Class from, Class to) Converts a value on the stack.
static <S extends Storable> ClassFile	createStorableClassFile(ClassInjector ci, Class<S> type, boolean isAbstract, String aSourcefileName) Define a classfile appropriate for most Storables.
static void	defineCopyBridges(ClassFile cf, Class leaf) Add copy bridge methods for all classes/interfaces between the leaf (genericised class) and the root (genericised baseclass).
static void	definePrepareBridges(ClassFile cf, Class leaf) Add prepare bridge methods for all classes/interfaces between the leaf (genericised class) and the root (genericised baseclass).
static void	definePrepareMethod(ClassFile cf, Class storableClass, 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(ClassFile cf, Class storableClass, TypeDesc supportCtorType, String supportFieldName, 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 Set<Class>	gatherAllBridgeTypes(Set<Class> set, 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(CodeBuilder b, TypeDesc type) Generates code to increment a version property value, already on the stack.
static void	initialVersion(CodeBuilder b, TypeDesc type, int value) Generates code to push an initial version property value on the stack.
static boolean	isPublicMethodFinal(Class clazz, String name, TypeDesc retType, TypeDesc[] params) Returns true if a public final method exists which matches the given specification.
static void	throwConcatException(CodeBuilder b, Class type, String... messages) Generate code to throw an exception with a message concatenated at runtime.
static void	throwException(CodeBuilder b, Class type, String message) Generate code to throw an exception with an optional message.
static LocalVariable	uneraseGenericParameter(CodeBuilder b, 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(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 LocalVariable uneraseGenericParameter(CodeBuilder b,
                                                    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(CodeBuilder b,
                                  Class type,
                                  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(CodeBuilder b,
                                        Class type,
                                        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 Set<Class> gatherAllBridgeTypes(Set<Class> set,
                                              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(ClassFile cf,
                                     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(ClassFile cf,
                                       Class storableClass,
                                       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(ClassFile cf,
                                       Class storableClass,
                                       TypeDesc supportCtorType,
                                       String supportFieldName,
                                       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(ClassFile cf,
                                        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(Class clazz,
                                          String name,
                                          TypeDesc retType,
                                          TypeDesc[] params)

Returns true if a public final method exists which matches the given specification.

createStorableClassFile

public static <S extends Storable> ClassFile createStorableClassFile(ClassInjector ci,
                                                                     Class<S> type,
                                                                     boolean isAbstract,
                                                                     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.

addEqualsCall

public static void addEqualsCall(CodeBuilder b,
                                 String fieldName,
                                 TypeDesc fieldType,
                                 boolean testForNull,
                                 Label fail,
                                 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(CodeBuilder b,
                                      TypeDesc valueType,
                                      boolean testForNull,
                                      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(CodeBuilder b,
                                Class from,
                                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(CodeBuilder b,
                                  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(CodeBuilder b,
                                    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(CodeBuilder b,
                              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 TypeDesc bindQueryParam(Class clazz)

Determines which overloaded "with" method on Query should be bound to.

callStringBuilderAppendString

public static void callStringBuilderAppendString(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(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(CodeBuilder b)

Calls length on a StringBuilder on the stack, leaving an int on the stack.

callStringBuilderSetLength

public static void callStringBuilderSetLength(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(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.