com.amazon.carbonado.raw
Class GenericEncodingStrategy<S extends Storable>

java.lang.Object
  com.amazon.carbonado.raw.GenericEncodingStrategy<S>

Direct Known Subclasses:

CompressedEncodingStrategy

public class GenericEncodingStrategy<S extends Storable>
extends Object

Generates bytecode instructions for encoding/decoding Storable properties to/from raw bytes.

Note: subclasses must override and specialize the hashCode and equals methods. Failure to do so interferes with StorableCodecFactory's generated code cache.

Author:

Brian S O'Neill

Constructor Summary

GenericEncodingStrategy(Class<S> type, StorableIndex<S> pkIndex)

GenericEncodingStrategy(Class<S> type, StorableIndex<S> pkIndex, int keyPrefixPadding, int keySuffixPadding, int dataPrefixPadding, int dataSuffixPadding)

Method Summary

void	buildDataDecoding(CodeAssembler assembler, StorableProperty<S>[] properties, LocalVariable instanceVar, Class<?> adapterInstanceClass, boolean useWriteMethods, int generation, Label altGenerationHandler, LocalVariable encodedVar) Generates bytecode instructions to decode properties.
LocalVariable	buildDataEncoding(CodeAssembler assembler, StorableProperty<S>[] properties, LocalVariable instanceVar, Class<?> adapterInstanceClass, boolean useReadMethods, int generation) Generates bytecode instructions to encode properties.
void	buildKeyDecoding(CodeAssembler assembler, OrderedProperty<S>[] properties, LocalVariable instanceVar, Class<?> adapterInstanceClass, boolean useWriteMethods, LocalVariable encodedVar) Generates bytecode instructions to decode properties.
LocalVariable	buildKeyEncoding(CodeAssembler assembler, OrderedProperty<S>[] properties, LocalVariable instanceVar, Class<?> adapterInstanceClass, boolean useReadMethods, LocalVariable partialStartVar, LocalVariable partialEndVar) Generates bytecode instructions to encode properties.
void	buildSerialDecoding(CodeAssembler assembler, StorableProperty<S>[] properties, LocalVariable encodedVar) Generates bytecode instructions to decode properties and their states.
LocalVariable	buildSerialEncoding(CodeAssembler assembler, StorableProperty<S>[] properties) Generates bytecode instructions to encode properties and their states.
protected StorablePropertyInfo	checkSupport(StorableProperty<S> property)
protected StorablePropertyInfo[]	checkSupport(StorableProperty<S>[] properties)
boolean	equals(Object obj)
protected void	extraDataDecoding(CodeAssembler a, LocalVariable dataVar, int prefix, int suffix) Second phase decoding, which does nothing by default.
protected void	extraDataEncoding(CodeAssembler a, LocalVariable dataVar, int prefix, int suffix) Second phase encoding, which does nothing by default.
protected StorableProperty<S>[]	gatherAllDataProperties() Returns all non-derived data properties for storable.
protected OrderedProperty<S>[]	gatherAllKeyProperties() Returns all key properties as ordered properties, possibly with unspecified directions.
protected StorableProperty<S>[]	gatherAllProperties() Returns all non-join, non-derived properties for storable.
int	getConstantKeyPrefixLength() Returns amount of prefix key bytes that encoding strategy instance produces which are always the same.
int	getDataPrefixPadding()
int	getDataSuffixPadding()
int	getKeyPrefixPadding()
int	getKeySuffixPadding()
protected StorableIndex<S>	getPrimaryKeyIndex() Returns all key properties in the form of an index.
Class<S>	getType() Returns the type of Storable that code is generated for.
int	hashCode()
boolean	isSupported(Class<?> propertyType) Returns true if the type of the given property type is supported.
boolean	isSupported(TypeDesc propertyType) Returns true if the type of the given property type is supported.
protected boolean	loadPropertyValue(CodeAssembler a, StorablePropertyInfo info, int ordinal, boolean useReadMethod, LocalVariable instanceVar, Class<?> adapterInstanceClass, LocalVariable partialStartVar) Generates code to load a property value onto the operand stack.
protected boolean	loadPropertyValue(LocalVariable[] stashedProperties, Boolean[] stashedFromInstances, CodeAssembler a, StorablePropertyInfo info, int ordinal, boolean useReadMethod, LocalVariable instanceVar, Class<?> adapterInstanceClass, LocalVariable partialStartVar) Generates code to load a property value onto the operand stack.
protected void	pushDecodingInstanceVar(CodeAssembler a, int ordinal, LocalVariable instanceVar) Push decoding instanceVar to stack in preparation to calling storePropertyValue.
protected void	pushRawSupport(CodeAssembler a, LocalVariable instanceVar) Generates code to push RawSupport instance to the stack.
protected void	storePropertyValue(CodeAssembler a, StorablePropertyInfo info, boolean useWriteMethod, LocalVariable instanceVar, Class<?> adapterInstanceClass) Generates code to store a property value into an instance which is already on the operand stack.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

GenericEncodingStrategy

public GenericEncodingStrategy(Class<S> type,
                               StorableIndex<S> pkIndex)

Parameters:

type - type of Storable to generate code for

pkIndex - specifies sequence and ordering of key properties (optional)

GenericEncodingStrategy

public GenericEncodingStrategy(Class<S> type,
                               StorableIndex<S> pkIndex,
                               int keyPrefixPadding,
                               int keySuffixPadding,
                               int dataPrefixPadding,
                               int dataSuffixPadding)

Parameters:

type - type of Storable to generate code for

pkIndex - specifies sequence and ordering of key properties (optional)

keyPrefixPadding - amount of padding bytes at start of keys

keySuffixPadding - amount of padding bytes at end of keys

dataPrefixPadding - amount of padding bytes at start of data values

dataSuffixPadding - amount of padding bytes at end of data values

Method Detail

buildKeyEncoding

public LocalVariable buildKeyEncoding(CodeAssembler assembler,
                                      OrderedProperty<S>[] properties,
                                      LocalVariable instanceVar,
                                      Class<?> adapterInstanceClass,
                                      boolean useReadMethods,
                                      LocalVariable partialStartVar,
                                      LocalVariable partialEndVar)
                               throws SupportException

Generates bytecode instructions to encode properties. The encoding is suitable for "key" encoding, which means it is correctly comparable.

Note: if a partialStartVar is provided and this strategy has a key prefix, the prefix is allocated only if the runtime value of partialStartVar is zero. Likewise, if a partialEndVar is provided and this strategy has a key suffix, the suffix is allocated only of the runtime value of partialEndVar is one less than the property count.

Parameters:

assembler - code assembler to receive bytecode instructions

properties - specific properties to encode, defaults to all key properties if null

instanceVar - local variable referencing Storable instance, defaults to "this" if null. If variable type is an Object array, then property values are read from the runtime value of this array instead of a Storable instance.

adapterInstanceClass - class containing static references to adapter instances - defaults to instanceVar

useReadMethods - when true, access properties by public read methods instead of protected fields - should be used if class being generated doesn't have access to these fields

partialStartVar - optional variable for supporting partial key generation. It must be an int, whose runtime value must be less than the properties array length. It marks the range start of the partial property range.

partialEndVar - optional variable for supporting partial key generation. It must be an int, whose runtime value must be less than or equal to the properties array length. It marks the range end (exclusive) of the partial property range.

Returns:

local variable referencing a byte array with encoded key

Throws:

SupportException - if any property type is not supported

IllegalArgumentException - if assembler is null, or if instanceVar is not the correct instance type, or if partial variable types are not ints

buildKeyDecoding

public void buildKeyDecoding(CodeAssembler assembler,
                             OrderedProperty<S>[] properties,
                             LocalVariable instanceVar,
                             Class<?> adapterInstanceClass,
                             boolean useWriteMethods,
                             LocalVariable encodedVar)
                      throws SupportException

Generates bytecode instructions to decode properties. A CorruptEncodingException may be thrown from generated code.

Parameters:

assembler - code assembler to receive bytecode instructions

properties - specific properties to decode, defaults to all key properties if null

instanceVar - local variable referencing Storable instance, defaults to "this" if null. If variable type is an Object array, then property values are placed into the runtime value of this array instead of a Storable instance.

adapterInstanceClass - class containing static references to adapter instances - defaults to instanceVar

useWriteMethods - when true, set properties by public write methods instead of protected fields - should be used if class being generated doesn't have access to these fields

encodedVar - required variable, which must be a byte array. At runtime, it references an encoded key.

Throws:

SupportException - if any property type is not supported

IllegalArgumentException - if assembler is null, or if instanceVar is not the correct instance type, or if encodedVar is not a byte array

buildDataEncoding

public LocalVariable buildDataEncoding(CodeAssembler assembler,
                                       StorableProperty<S>[] properties,
                                       LocalVariable instanceVar,
                                       Class<?> adapterInstanceClass,
                                       boolean useReadMethods,
                                       int generation)
                                throws SupportException

Generates bytecode instructions to encode properties. The encoding is suitable for "data" encoding, which means it is not correctly comparable, but it is more efficient than key encoding. Partial encoding is not supported.

Parameters:

assembler - code assembler to receive bytecode instructions

properties - specific properties to encode, defaults to all non-key properties if null

instanceVar - local variable referencing Storable instance, defaults to "this" if null. If variable type is an Object array, then property values are read from the runtime value of this array instead of a Storable instance.

adapterInstanceClass - class containing static references to adapter instances - defaults to instanceVar

useReadMethods - when true, access properties by public read methods instead of protected fields

generation - when non-negative, write a storable layout generation value in one or four bytes. Generation 0..127 is encoded in one byte, and 128..max is encoded in four bytes, with the most significant bit set.

Returns:

local variable referencing a byte array with encoded data

Throws:

SupportException - if any property type is not supported

IllegalArgumentException - if assembler is null, or if instanceVar is not the correct instance type

buildDataDecoding

public void buildDataDecoding(CodeAssembler assembler,
                              StorableProperty<S>[] properties,
                              LocalVariable instanceVar,
                              Class<?> adapterInstanceClass,
                              boolean useWriteMethods,
                              int generation,
                              Label altGenerationHandler,
                              LocalVariable encodedVar)
                       throws SupportException

Generates bytecode instructions to decode properties. A CorruptEncodingException may be thrown from generated code.

Parameters:

assembler - code assembler to receive bytecode instructions

properties - specific properties to decode, defaults to all non-key properties if null

instanceVar - local variable referencing Storable instance, defaults to "this" if null. If variable type is an Object array, then property values are placed into the runtime value of this array instead of a Storable instance.

adapterInstanceClass - class containing static references to adapter instances - defaults to instanceVar

useWriteMethods - when true, set properties by public write methods instead of protected fields - should be used if class being generated doesn't have access to these fields

generation - when non-negative, decoder expects a storable layout generation value to match this value. Otherwise, it throws a CorruptEncodingException.

altGenerationHandler - if non-null and a generation is provided, this label defines an alternate generation handler. It is executed instead of throwing a CorruptEncodingException if the generation doesn't match. The actual generation is available on the top of the stack for the handler to consume.

encodedVar - required variable, which must be a byte array. At runtime, it references encoded data.

Throws:

SupportException - if any property type is not supported

IllegalArgumentException - if assembler is null, or if instanceVar is not the correct instance type, or if encodedVar is not a byte array

buildSerialEncoding

public LocalVariable buildSerialEncoding(CodeAssembler assembler,
                                         StorableProperty<S>[] properties)
                                  throws SupportException

Generates bytecode instructions to encode properties and their states. This encoding is suitable for short-term serialization only.

Parameters:

assembler - code assembler to receive bytecode instructions

properties - specific properties to decode, defaults to all properties if null

Returns:

local variable referencing a byte array with encoded data

Throws:

SupportException - if any property type is not supported

Since:

1.2

buildSerialDecoding

public void buildSerialDecoding(CodeAssembler assembler,
                                StorableProperty<S>[] properties,
                                LocalVariable encodedVar)
                         throws SupportException

Generates bytecode instructions to decode properties and their states. A CorruptEncodingException may be thrown from generated code.

Parameters:

assembler - code assembler to receive bytecode instructions

properties - specific properties to decode, defaults to all properties if null

encodedVar - required variable, which must be a byte array. At runtime, it references encoded data.

Throws:

SupportException - if any property type is not supported

IllegalArgumentException - if encodedVar is not a byte array

Since:

1.2

getType

public final Class<S> getType()

Returns the type of Storable that code is generated for.

isSupported

public boolean isSupported(Class<?> propertyType)

Returns true if the type of the given property type is supported. The types currently supported are primitives, primitive wrapper objects, Strings, and byte arrays.

isSupported

public boolean isSupported(TypeDesc propertyType)

Returns true if the type of the given property type is supported. The types currently supported are primitives, primitive wrapper objects, Strings, byte arrays and Lobs.

getKeyPrefixPadding

public int getKeyPrefixPadding()

getKeySuffixPadding

public int getKeySuffixPadding()

getDataPrefixPadding

public int getDataPrefixPadding()

getDataSuffixPadding

public int getDataSuffixPadding()

getConstantKeyPrefixLength

public int getConstantKeyPrefixLength()

Returns amount of prefix key bytes that encoding strategy instance produces which are always the same. Default implementation returns 0.

hashCode

public int hashCode()

Overrides:

hashCode in class Object

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

getPrimaryKeyIndex

protected StorableIndex<S> getPrimaryKeyIndex()

Returns all key properties in the form of an index.

gatherAllKeyProperties

protected OrderedProperty<S>[] gatherAllKeyProperties()

Returns all key properties as ordered properties, possibly with unspecified directions.

gatherAllDataProperties

protected StorableProperty<S>[] gatherAllDataProperties()

Returns all non-derived data properties for storable.

gatherAllProperties

protected StorableProperty<S>[] gatherAllProperties()

Returns all non-join, non-derived properties for storable.

checkSupport

protected StorablePropertyInfo checkSupport(StorableProperty<S> property)
                                     throws SupportException

Throws:

SupportException

checkSupport

protected StorablePropertyInfo[] checkSupport(StorableProperty<S>[] properties)
                                       throws SupportException

Throws:

SupportException

extraDataEncoding

protected void extraDataEncoding(CodeAssembler a,
                                 LocalVariable dataVar,
                                 int prefix,
                                 int suffix)

Second phase encoding, which does nothing by default.

Parameters:

dataVar - local variable referencing a byte array with data

prefix - prefix of byte array to preserve

suffix - suffix of byte array to preserve

extraDataDecoding

protected void extraDataDecoding(CodeAssembler a,
                                 LocalVariable dataVar,
                                 int prefix,
                                 int suffix)

Second phase decoding, which does nothing by default.

Parameters:

dataVar - local variable referencing a byte array with data

loadPropertyValue

protected boolean loadPropertyValue(LocalVariable[] stashedProperties,
                                    Boolean[] stashedFromInstances,
                                    CodeAssembler a,
                                    StorablePropertyInfo info,
                                    int ordinal,
                                    boolean useReadMethod,
                                    LocalVariable instanceVar,
                                    Class<?> adapterInstanceClass,
                                    LocalVariable partialStartVar)

Generates code to load a property value onto the operand stack.

Parameters:

info - info for property to load

ordinal - zero-based property ordinal, used only if instanceVar refers to an object array.

useReadMethod - when true, access property by public read method instead of protected field

instanceVar - local variable referencing Storable instance, defaults to "this" if null. If variable type is an Object array, then property values are read from the runtime value of this array instead of a Storable instance.

adapterInstanceClass - class containing static references to adapter instances - defaults to instanceVar

partialStartVar - optional variable for supporting partial key generation. It must be an int, whose runtime value must be less than the properties array length. It marks the range start of the partial property range.

Returns:

true if property was loaded from instance, false if loaded from value array

loadPropertyValue

protected boolean loadPropertyValue(CodeAssembler a,
                                    StorablePropertyInfo info,
                                    int ordinal,
                                    boolean useReadMethod,
                                    LocalVariable instanceVar,
                                    Class<?> adapterInstanceClass,
                                    LocalVariable partialStartVar)

Generates code to load a property value onto the operand stack.

Parameters:

info - info for property to load

ordinal - zero-based property ordinal, used only if instanceVar refers to an object array.

useReadMethod - when true, access property by public read method instead of protected field

instanceVar - local variable referencing Storable instance, defaults to "this" if null. If variable type is an Object array, then property values are read from the runtime value of this array instead of a Storable instance.

adapterInstanceClass - class containing static references to adapter instances - defaults to instanceVar

partialStartVar - optional variable for supporting partial key generation. It must be an int, whose runtime value must be less than the properties array length. It marks the range start of the partial property range.

Returns:

true if property was loaded from instance, false if loaded from value array

pushRawSupport

protected void pushRawSupport(CodeAssembler a,
                              LocalVariable instanceVar)
                       throws SupportException

Generates code to push RawSupport instance to the stack. RawSupport is available only in Storable instances. If instanceVar is an Object[], a SupportException is thrown.

Parameters:

instanceVar - Storable instance or array of property values. Null is storable instance of "this".

Throws:

SupportException

pushDecodingInstanceVar

protected void pushDecodingInstanceVar(CodeAssembler a,
                                       int ordinal,
                                       LocalVariable instanceVar)

Push decoding instanceVar to stack in preparation to calling storePropertyValue.

Parameters:

ordinal - zero-based property ordinal, used only if instanceVar refers to an object array.

instanceVar - local variable referencing Storable instance, defaults to "this" if null. If variable type is an Object array, then property values are written to the runtime value of this array instead of a Storable instance.

See Also:

storePropertyValue

storePropertyValue

protected void storePropertyValue(CodeAssembler a,
                                  StorablePropertyInfo info,
                                  boolean useWriteMethod,
                                  LocalVariable instanceVar,
                                  Class<?> adapterInstanceClass)

Generates code to store a property value into an instance which is already on the operand stack. If instance is an Object array, index into array must also be on the operand stack.

Parameters:

info - info for property to store to

useWriteMethod - when true, set property by public write method instead of protected field

instanceVar - local variable referencing Storable instance, defaults to "this" if null. If variable type is an Object array, then property values are written to the runtime value of this array instead of a Storable instance.

adapterInstanceClass - class containing static references to adapter instances - defaults to instanceVar

See Also:

pushDecodingInstanceVar