com.amazon.carbonado.gen
Class StorableGenerator<S extends Storable>

java.lang.Object
  com.amazon.carbonado.gen.StorableGenerator<S>

public final class StorableGenerator<S extends Storable>
extends Object

Generates and caches abstract implementations of Storable types. This greatly simplifies the process of defining new kinds of Repositories, since most of the mundane code generation is taken care of.

Since:

1.2

Author:

Brian S O'Neill, Don Schneider, Tobias Holgers

See Also:

MasterStorableGenerator, DelegateStorableGenerator

Field Summary

static String	ADAPTER_FIELD_ELEMENT Adapter field names are propertyName + "$adapter$" + number
static String	CHECK_PK_FOR_DELETE_METHOD_NAME Name of protected method in generated storable which checks that primary keys are initialized, throwing an exception otherwise.
static String	CHECK_PK_FOR_INSERT_METHOD_NAME Name of protected method in generated storable which checks that primary keys are initialized, throwing an exception otherwise.
static String	CHECK_PK_FOR_UPDATE_METHOD_NAME Name of protected method in generated storable which checks that primary keys are initialized, throwing an exception otherwise.
static String	CONSTRAINT_FIELD_ELEMENT Constraint field names are propertyName + "$constraint$" + number
static String	DO_TRY_DELETE_METHOD_NAME Name of protected abstract method in generated storable
static String	DO_TRY_INSERT_METHOD_NAME Name of protected abstract method in generated storable
static String	DO_TRY_LOAD_METHOD_NAME Name of protected abstract method in generated storable
static String	DO_TRY_UPDATE_METHOD_NAME Name of protected abstract method in generated storable
static String	IS_ALT_KEY_INITIALIZED_PREFIX Name prefix of protected method in generated storable that returns false if a specific alternate key is uninitialized.
static String	IS_PK_INITIALIZED_METHOD_NAME Name of protected method in generated storable that returns false if any primary keys are uninitialized.
static String	IS_REQUIRED_DATA_INITIALIZED_METHOD_NAME Name of protected method in generated storable that returns false if any non-nullable, non-pk properties are uninitialized.
static String	IS_VERSION_INITIALIZED_METHOD_NAME Name of protected method in generated storable that returns false if version property is uninitialized.
static String	LOAD_COMPLETED_METHOD_NAME Name of protected method which must be called after load to identify all properties as valid and to fire any load triggers.
static int	PROPERTY_STATE_CLEAN Property state indicating that property value reflects a clean value
static int	PROPERTY_STATE_DIRTY Property state indicating that property has been set, but not saved
static String	PROPERTY_STATE_FIELD_NAME Prefix of protected field in generated storable that holds property states.
static int	PROPERTY_STATE_MASK Property state mask is 3, to cover the two bits used by a property state
static int	PROPERTY_STATE_UNINITIALIZED Property state indicating that property has never been set, loaded, or saved
static String	SUPPORT_FIELD_NAME Reference to TriggerSupport instance

Method Summary

static <S extends Storable> Class<? extends S>

getAbstractClass(Class<S> type) Returns an abstract implementation of the given Storable type, which is fully thread-safe.

Methods inherited from class java.lang.Object

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

Field Detail

DO_TRY_LOAD_METHOD_NAME

public static final String DO_TRY_LOAD_METHOD_NAME

Name of protected abstract method in generated storable

See Also:

Constant Field Values

DO_TRY_INSERT_METHOD_NAME

public static final String DO_TRY_INSERT_METHOD_NAME

Name of protected abstract method in generated storable

See Also:

Constant Field Values

DO_TRY_UPDATE_METHOD_NAME

public static final String DO_TRY_UPDATE_METHOD_NAME

Name of protected abstract method in generated storable

See Also:

Constant Field Values

DO_TRY_DELETE_METHOD_NAME

public static final String DO_TRY_DELETE_METHOD_NAME

Name of protected abstract method in generated storable

See Also:

Constant Field Values

CHECK_PK_FOR_INSERT_METHOD_NAME

public static final String CHECK_PK_FOR_INSERT_METHOD_NAME

Name of protected method in generated storable which checks that primary keys are initialized, throwing an exception otherwise.

See Also:

Constant Field Values

CHECK_PK_FOR_UPDATE_METHOD_NAME

public static final String CHECK_PK_FOR_UPDATE_METHOD_NAME

Name of protected method in generated storable which checks that primary keys are initialized, throwing an exception otherwise.

See Also:

Constant Field Values

CHECK_PK_FOR_DELETE_METHOD_NAME

public static final String CHECK_PK_FOR_DELETE_METHOD_NAME

Name of protected method in generated storable which checks that primary keys are initialized, throwing an exception otherwise.

See Also:

Constant Field Values

IS_PK_INITIALIZED_METHOD_NAME

public static final String IS_PK_INITIALIZED_METHOD_NAME

Name of protected method in generated storable that returns false if any primary keys are uninitialized.

See Also:

Constant Field Values

IS_ALT_KEY_INITIALIZED_PREFIX

public static final String IS_ALT_KEY_INITIALIZED_PREFIX

Name prefix of protected method in generated storable that returns false if a specific alternate key is uninitialized. The complete name is formed by the prefix appended with the zero-based alternate key number.

See Also:

Constant Field Values

IS_REQUIRED_DATA_INITIALIZED_METHOD_NAME

public static final String IS_REQUIRED_DATA_INITIALIZED_METHOD_NAME

Name of protected method in generated storable that returns false if any non-nullable, non-pk properties are uninitialized.

See Also:

Constant Field Values

IS_VERSION_INITIALIZED_METHOD_NAME

public static final String IS_VERSION_INITIALIZED_METHOD_NAME

Name of protected method in generated storable that returns false if version property is uninitialized. If no version property exists, then this method is not defined.

See Also:

Constant Field Values

LOAD_COMPLETED_METHOD_NAME

public static final String LOAD_COMPLETED_METHOD_NAME

Name of protected method which must be called after load to identify all properties as valid and to fire any load triggers.

Since:

1.2

See Also:

Constant Field Values

PROPERTY_STATE_FIELD_NAME

public static final String PROPERTY_STATE_FIELD_NAME

Prefix of protected field in generated storable that holds property states. Each property consumes two bits to hold its state, and so each 32-bit field holds states for up to 16 properties.

See Also:

Constant Field Values

ADAPTER_FIELD_ELEMENT

public static final String ADAPTER_FIELD_ELEMENT

Adapter field names are propertyName + "$adapter$" + number

See Also:

Constant Field Values

CONSTRAINT_FIELD_ELEMENT

public static final String CONSTRAINT_FIELD_ELEMENT

Constraint field names are propertyName + "$constraint$" + number

See Also:

Constant Field Values

SUPPORT_FIELD_NAME

public static final String SUPPORT_FIELD_NAME

Reference to TriggerSupport instance

See Also:

Constant Field Values

PROPERTY_STATE_UNINITIALIZED

public static final int PROPERTY_STATE_UNINITIALIZED

Property state indicating that property has never been set, loaded, or saved

See Also:

Constant Field Values

PROPERTY_STATE_DIRTY

public static final int PROPERTY_STATE_DIRTY

Property state indicating that property has been set, but not saved

See Also:

Constant Field Values

PROPERTY_STATE_CLEAN

public static final int PROPERTY_STATE_CLEAN

Property state indicating that property value reflects a clean value

See Also:

Constant Field Values

PROPERTY_STATE_MASK

public static final int PROPERTY_STATE_MASK

Property state mask is 3, to cover the two bits used by a property state

See Also:

Constant Field Values

Method Detail

getAbstractClass

public static <S extends Storable> Class<? extends S> getAbstractClass(Class<S> type)
                                                            throws IllegalArgumentException

Returns an abstract implementation of the given Storable type, which is fully thread-safe. The Storable type itself may be an interface or a class. If it is a class, then it must not be final, and it must have a public, no-arg constructor. The constructor signature for the returned abstract class is defined as follows:

 /**
  * @param support  Access to triggers
  */
 public <init>(TriggerSupport support);
 

Subclasses must implement the following abstract protected methods, whose exact names are defined by constants in this class:

 // Load the object by examining the primary key.
 protected abstract boolean doTryLoad() throws FetchException;

 // Insert the object into the storage layer.
 protected abstract boolean doTryInsert() throws PersistException;

 // Update the object in the storage.
 protected abstract boolean doTryUpdate() throws PersistException;

 // Delete the object from the storage layer by the primary key.
 protected abstract boolean doTryDelete() throws PersistException;
 

A set of protected hook methods are provided which ensure that all primary keys are initialized before performing a repository operation. Subclasses may override them, if they are capable of filling in unspecified primary keys. One such example is applying a sequence on insert.

 // Throws exception if any primary keys are uninitialized.
 // Actual method name defined by CHECK_PK_FOR_INSERT_METHOD_NAME.
 protected void checkPkForInsert() throws IllegalStateException;

 // Throws exception if any primary keys are uninitialized.
 // Actual method name defined by CHECK_PK_FOR_UPDATE_METHOD_NAME.
 protected void checkPkForUpdate() throws IllegalStateException;

 // Throws exception if any primary keys are uninitialized.
 // Actual method name defined by CHECK_PK_FOR_DELETE_METHOD_NAME.
 protected void checkPkForDelete() throws IllegalStateException;
 

Each property value is defined as a protected field whose name and type matches the property. Subclasses should access these fields directly during loading and storing. For loading, it bypasses constraint checks. For both, it provides better performance.

Subclasses also have access to a set of property state bits stored in protected int fields. Subclasses are not responsible for updating these values. The intention is that these states may be used by subclasses to support partial updates. They may otherwise be ignored.

As a convenience, protected methods are provided to test and alter the property state bits. Subclass constructors that fill all properties with loaded values must call loadCompleted to ensure all properties are identified as being valid and to fire any load triggers.

 // Returns true if all primary key properties have been set.
 protected boolean isPkInitialized();

 // Returns true if all required data properties are set.
 // A required data property is a non-nullable, non-primary key.
 protected boolean isRequiredDataInitialized();

 // Returns true if a version property has been set.
 // Note: This method is not generated if there is no version property.
 protected boolean isVersionInitialized();

 // Must be called after load to identify all properties as valid
 // and to fire any load triggers.
 // Actual method name defined by LOAD_COMPLETED_METHOD_NAME.
 protected void loadCompleted() throws FetchException;
 

Property state field names are defined by the concatenation of PROPERTY_STATE_FIELD_NAME and a zero-based decimal number. To determine which field holds a particular property's state, the field number is computed as the property number divided by 16. The specific two-bit state position is the remainder of this division times 2.

Throws:

MalformedTypeException - if Storable type is not well-formed

IllegalArgumentException - if type is null