com.goldencode.p2j.persist.orm

Class RecordMeta

java.lang.Object

com.goldencode.p2j.persist.orm.RecordMeta

public final class RecordMeta
extends java.lang.Object

Metadata which is associated with the concrete subclass implementation of a database record, needed to perform basic CRUD operations on records.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
private static class	RecordMeta.DynamicInitializer A helper object which applies the result of an invocation of a dynamic initial value (e.g., "today" for a date, "now" for a datetime[tz]) to one or more data elements in a newly created record.

Field Summary

Fields

Modifier and Type	Field and Description
(package private) java.util.BitSet	allIndexedProps Bit set which marks the position of each property participating in an index
(package private) java.lang.String[]	deleteSql SQL delete statement(s) which delete a single DMO's data from the database
private DmoMeta	dmoMeta The DmoMeta structure which contains the legacy meta information.
private RecordMeta.DynamicInitializer[]	dynamicInitializers Dynamic initializers, if any.
private Dialect	getIndexKeyCollisionsDialect The Dialect which was used for creating the getIndexKeyCollisionsSQLs statements.
private java.lang.String[]	getIndexKeyCollisionsSQLs The set of SQL query statements used to extract existing records that conflict with a record ready to be inserted.
private java.util.Map<java.lang.String,java.lang.Integer>	indexIdByName Map of index name to index UID (positive for unique indices, negative for non-unique indices)
(package private) java.lang.Object[]	initialData Values to which a newly created record should be set
(package private) java.lang.String[]	insertSql SQL insert statement(s) which insert a single DMO's data into the database
java.lang.String	legacyName The legacy name of the parent table.
(package private) java.lang.String[]	loadSql SQL query statement(s) to access data needed to load a single DMO instance
(package private) int[]	loadSqlIndexes The index in props array where each loadSql statement has the properties (with the same extent) stored.
private static java.lang.ThreadLocal<org.apache.commons.lang3.tuple.Pair<java.lang.Class<? extends DataModelObject>,RecordMeta>>	local Thread-local, temporary association of a DataModelObject interface to its RecordMeta.
private static CentralLogger	log Logger
(package private) java.util.BitSet	nonNullableProps Bit set which marks the position of each non-null column in the backing table
(package private) java.util.BitSet[]	nonuniqueIndices Bit sets which mark the positions of the component columns of non-unique indices
private java.lang.String[]	nonuniqueIndicesLegacyNames The array of legacy names for non-unique indices, with positional correspondents in nonuniqueIndices list.
private java.lang.String[]	nonuniqueIndicesNames The array of names for non-unique indices, with positional correspondents in nonuniqueIndices list.
private int	primaryIndex UID of primary index, if any.
private PropertyMeta[]	props Property metadata, ordered scalar properties first, then the extent properties grouped by their extent size.
private java.lang.String[]	replaceCleanupSql The set of DELETE SQL statements used to remove existing records that conflict with a record ready to be inserted.
private Dialect	replaceCleanupSqlDialect The Dialect which was used for creating the replaceCleanupSql statements.
private java.util.Map<java.lang.String,java.lang.Integer>	reversedIndexProperties
java.lang.String[]	tables Names of the backing database tables
private boolean	temporary Does this object represent metadata for a temporary table?
(package private) java.util.BitSet[]	uniqueIndices Bit sets which mark the positions of the component columns of unique indices
private java.lang.String[]	uniqueIndicesLegacyNames The array of legacy names for unique indices, with positional correspondents in uniqueIndices list.
private java.lang.String[]	uniqueIndicesNames Array of names of unique indices, with positional correspondents in uniqueIndices list
private java.lang.String[]	uniqueSql The SQL statements used to test the uniqueness of the record against each unique index.
private Dialect	uniqueSqlDialect The Dialect which was used for creating the uniqueSql statements.
(package private) java.util.BitSet	validatable Bit set which marks the position of each property that can be validated

Constructor Summary

Constructors

Constructor and Description
RecordMeta(java.lang.Class<? extends DataModelObject> dmoIface, DmoMeta dmoMeta) Initialize the record's metadata.

Method Summary

Modifier and Type	Method and Description
(package private) void	applyInitialValues(java.lang.Object[] data, java.util.BitSet nullProps) Apply all dynamic and static initial values to a record's data array, and record which elements of the array are set to null in the given bit set.
private static java.lang.String	backTickify(java.lang.String name) Enclose a name in back ticks quotes.
private java.lang.String[]	composeFindIndexKeyCollisionsSQL(java.lang.String sqlTableName, Dialect d) Composes a set of SQL query statements that extract conflicting records from the temp-table.
private java.lang.String[]	composeReplaceCleanupSQLs(java.lang.String sqlTableName, Dialect d) Composes a set of SQL statements that delete conflicting records from the temp-table.
private java.lang.String[]	composeValidationSQLs(java.lang.String sqlTableName, Dialect d) Composes a set of SQL query statements that verify if a record can be safely saved to database so there are no conflicts with unique indexes.
static RecordMeta	get(java.lang.Class<? extends DataModelObject> key) Get the last created RecordMeta.
java.util.BitSet	getAllIndexedProperties() Get a bit set representing all DMO properties which participate in indices in the backing table.
DmoMeta	getDmoMeta() Obtain the DmoMeta structure which contains the legacy meta information.
int	getIndexIdByName(java.lang.String name) Obtain the id of an index using its name.
java.lang.String[]	getIndexKeyCollisionsSQLs(Dialect d) Get an array of SQL query statements used to extract existing records which conflict (from the point of view of unique indexes) with a record that is about to be inserted.
java.lang.String	getIndexLegacyName(int pos, boolean unique) Obtain the legacy name of an index, by its order in the list of unique or non-unique lists.
int	getIndexOfProperty(java.lang.String propName) Obtain the index of a property in the data array based on its name.
java.lang.String	getLegacyName() Obtain the legacy name of the parent table.
java.lang.String[]	getNonuniqueIndexNames() Obtain the array of names of unique indices, if any.
java.util.BitSet[]	getNonuniqueIndices() Get an array of bit sets, each of which describes the components of a non-unique index.
int	getPrimaryIndexId()
PropertyMeta[]	getPropertyMeta(boolean nativeOrder) Get the array of property metadata objects which describe how the core data of this record is organized.
java.lang.String[]	getReplaceCleanupSQLs(Dialect d) Get an array of DELETE SQL statements used to remove existing records which conflict (from the point of view of unique indexes) with a record that is about to be inserted.
java.lang.String[]	getUniqueIndexNames() Obtain the array of names of unique indices, if any.
java.util.BitSet[]	getUniqueIndices() Get an array of bit sets, each of which describes the components of an unique index.
java.lang.String[]	getUniqueIndicesValidationSQLs(Dialect d) Get an array of SQL statements, each of which the tests the uniqueness of a record against an unique index.
java.util.BitSet	getValidatableProperties() Get a bit set representing all DMO properties which must be validated when a record is created or updated.
boolean	isTemporary() Indicate whether this object represents metadata for a temporary table.
private static java.util.BitSet	readIndices(java.lang.Class<?> dmoIface, PropertyMeta[] props, java.lang.String[] primary, java.util.BitSet validatable, java.util.List<java.util.BitSet> unique, java.util.List<java.lang.String> uniqueNames, java.util.List<java.lang.String> uniqueLegacyNames, java.util.List<java.util.BitSet> nonUnique, java.util.List<java.lang.String> nonUniqueNames, java.util.List<java.lang.String> nonUniqueLegacyNames) Read the DMO interface's index annotations, if any.
(package private) static PropertyMeta[]	readPropertyMeta(DmoMeta dmoMeta) Read the getter method annotations from the DMO interface and generate property metadata from them.
private static java.lang.String	stripBackTicks(java.lang.String name, java.lang.String dmoName) Strip back tick quotes from a name, if it is enclosed in them.
private static java.lang.String[]	tableNames(DmoMeta dmoMeta, PropertyMeta[] props) Get the array of table names associated with this DMO.

Methods inherited from class java.lang.Object

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

Field Detail

log

private static final CentralLogger log

Logger

local

private static final java.lang.ThreadLocal<org.apache.commons.lang3.tuple.Pair<java.lang.Class<? extends DataModelObject>,RecordMeta>> local

Thread-local, temporary association of a DataModelObject interface to its RecordMeta. They are the last DataModelObject processed and the obtained crtRecordMeta. We do a double check to be sure the initialization of the static field _metadata is correct (and the DMO interface is the right one). This pair of values is kept until get(java.lang.Class<? extends com.goldencode.p2j.persist.DataModelObject>) is called and is reset after the first valid access this static method.

See Also:

get(java.lang.Class<? extends com.goldencode.p2j.persist.DataModelObject>)

tables

public final java.lang.String[] tables

Names of the backing database tables

legacyName

public final java.lang.String legacyName

The legacy name of the parent table.

initialData

final java.lang.Object[] initialData

Values to which a newly created record should be set

nonNullableProps

final java.util.BitSet nonNullableProps

Bit set which marks the position of each non-null column in the backing table

allIndexedProps

final java.util.BitSet allIndexedProps

Bit set which marks the position of each property participating in an index

validatable

final java.util.BitSet validatable

Bit set which marks the position of each property that can be validated

uniqueIndices

final java.util.BitSet[] uniqueIndices

Bit sets which mark the positions of the component columns of unique indices

nonuniqueIndices

final java.util.BitSet[] nonuniqueIndices

Bit sets which mark the positions of the component columns of non-unique indices

loadSql

final java.lang.String[] loadSql

SQL query statement(s) to access data needed to load a single DMO instance

loadSqlIndexes

final int[] loadSqlIndexes

The index in props array where each loadSql statement has the properties (with the same extent) stored. The value of loadSqlIndexes[0] is always zero, as the loadSql's first element is the scalar properties SELET.

insertSql

final java.lang.String[] insertSql

SQL insert statement(s) which insert a single DMO's data into the database

deleteSql

final java.lang.String[] deleteSql

SQL delete statement(s) which delete a single DMO's data from the database

temporary

private final boolean temporary

Does this object represent metadata for a temporary table?

props

private final PropertyMeta[] props

Property metadata, ordered scalar properties first, then the extent properties grouped by their extent size. Each group represents a series, all series are sorted by their common extent size. This is the 'persistence' order.

uniqueIndicesNames

private final java.lang.String[] uniqueIndicesNames

Array of names of unique indices, with positional correspondents in uniqueIndices list

uniqueIndicesLegacyNames

private final java.lang.String[] uniqueIndicesLegacyNames

The array of legacy names for unique indices, with positional correspondents in uniqueIndices list.

nonuniqueIndicesNames

private final java.lang.String[] nonuniqueIndicesNames

The array of names for non-unique indices, with positional correspondents in nonuniqueIndices list.

nonuniqueIndicesLegacyNames

private final java.lang.String[] nonuniqueIndicesLegacyNames

The array of legacy names for non-unique indices, with positional correspondents in nonuniqueIndices list.

dmoMeta

private final DmoMeta dmoMeta

The DmoMeta structure which contains the legacy meta information.

reversedIndexProperties

private final java.util.Map<java.lang.String,java.lang.Integer> reversedIndexProperties

indexIdByName

private final java.util.Map<java.lang.String,java.lang.Integer> indexIdByName

Map of index name to index UID (positive for unique indices, negative for non-unique indices)

primaryIndex

private final int primaryIndex

UID of primary index, if any. A value of 0 indicates no primary index exists

dynamicInitializers

private final RecordMeta.DynamicInitializer[] dynamicInitializers

Dynamic initializers, if any.

uniqueSql

private java.lang.String[] uniqueSql

The SQL statements used to test the uniqueness of the record against each unique index.

replaceCleanupSql

private java.lang.String[] replaceCleanupSql

The set of DELETE SQL statements used to remove existing records that conflict with a record ready to be inserted. Only used for FILL operations in REPLACE mode.

getIndexKeyCollisionsSQLs

private java.lang.String[] getIndexKeyCollisionsSQLs

The set of SQL query statements used to extract existing records that conflict with a record ready to be inserted. Only used for FILL operations in REPLACE mode.

uniqueSqlDialect

private Dialect uniqueSqlDialect

The Dialect which was used for creating the uniqueSql statements.

replaceCleanupSqlDialect

private Dialect replaceCleanupSqlDialect

The Dialect which was used for creating the replaceCleanupSql statements.

Normally this should be H2 as this is the only dialect supported for temp-tables, as the replaceCleanupSql will be used only on _temp database.

getIndexKeyCollisionsDialect

private Dialect getIndexKeyCollisionsDialect

The Dialect which was used for creating the getIndexKeyCollisionsSQLs statements.

Normally this should be H2 as this is the only dialect supported for temp-tables, as the getIndexKeyCollisionsSQLs will be used only on _temp database.

Constructor Detail

RecordMeta

RecordMeta(java.lang.Class<? extends DataModelObject> dmoIface,
           DmoMeta dmoMeta)

Initialize the record's metadata. This should only be called once per concrete DMO implementation subclass, when that class is loaded.

Parameters:

dmoIface - DMO interface; the public API to business logic. Annotations on the getter methods of this interface are used to define the concrete subclass.

dmoMeta - The DmoMeta structure which contains the legacy meta information. May have not been fully filled yet.

Method Detail

get

public static RecordMeta get(java.lang.Class<? extends DataModelObject> key)

Get the last created RecordMeta. After the first access the value is reset.

To avoid processing the readPropertyMeta(com.goldencode.p2j.persist.orm.DmoMeta) twice (one before creating the DMO implementation class and one after, when its _metadata is statically initialized at first access, we store the last created RecordMeta) we store the latest created object in a static member and return it at first call. The RecordMeta is called in a synchronized block so that nobody else will get/reset the result. The key parameter makes sure the new metadata goes to the right class.

Parameters:

key - The DMO interface that was previously processed. It must be the interface that the DMO implementation ask for meta data.

Returns:

The last processed RecordMeta that corresponds to key DMO interface. If the method is called multiple time, null is retuned for subsequent invocation.

readPropertyMeta

static PropertyMeta[] readPropertyMeta(DmoMeta dmoMeta)

Read the getter method annotations from the DMO interface and generate property metadata from them. Return the metadata as an array, ordered as described in the Loader class description. This order is critical to all CRUD operations performed by the loader and persister, and reflects the order of the data stored in the record's core data array.

Parameters:

dmoMeta - DMO metadata.

Returns:

Array of property metadata.

applyInitialValues

void applyInitialValues(java.lang.Object[] data,
                        java.util.BitSet nullProps)

Apply all dynamic and static initial values to a record's data array, and record which elements of the array are set to null in the given bit set.

Parameters:

data - Record's data array.

nullProps - A bit set whose set bits indicate data array elements left null after initial values have been applied.

composeValidationSQLs

private java.lang.String[] composeValidationSQLs(java.lang.String sqlTableName,
                                                 Dialect d)

Composes a set of SQL query statements that verify if a record can be safely saved to database so there are no conflicts with unique indexes. Each statement selects the zero-based position of the index it is meant to validate in the uniqueIndices array, as in:

    select 0 where recid != ? and column1 = ? and column2 = ?
 

for the "0th" index.

Multiple such statements can then be concatenated with the union all operator and the result set will have a row corresponding with each unique index which failed validation, or no rows if validation passed.

Parameters:

sqlTableName - The name of the SQL table.

d - The dialect to be used when creating the queries.

Returns:

An array of SELECT statements for testing a record against all unique indexes.

composeReplaceCleanupSQLs

private java.lang.String[] composeReplaceCleanupSQLs(java.lang.String sqlTableName,
                                                     Dialect d)

Composes a set of SQL statements that delete conflicting records from the temp-table.

Parameters:

sqlTableName - The name of the SQL table.

d - The dialect to be used when creating the queries.

Returns:

An array of SELECT statements for deleting possible conflicting records from database, one statement for each unique index.

composeFindIndexKeyCollisionsSQL

private java.lang.String[] composeFindIndexKeyCollisionsSQL(java.lang.String sqlTableName,
                                                            Dialect d)

Composes a set of SQL query statements that extract conflicting records from the temp-table.

Parameters:

sqlTableName - The name of the SQL table.

d - The dialect to be used when creating the queries.

Returns:

An array of SELECT statements for deleting possible conflicting records from database, one statement for each unique index.

readIndices

private static java.util.BitSet readIndices(java.lang.Class<?> dmoIface,
                                            PropertyMeta[] props,
                                            java.lang.String[] primary,
                                            java.util.BitSet validatable,
                                            java.util.List<java.util.BitSet> unique,
                                            java.util.List<java.lang.String> uniqueNames,
                                            java.util.List<java.lang.String> uniqueLegacyNames,
                                            java.util.List<java.util.BitSet> nonUnique,
                                            java.util.List<java.lang.String> nonUniqueNames,
                                            java.util.List<java.lang.String> nonUniqueLegacyNames)

Read the DMO interface's index annotations, if any. For each such annotation, create an BitSet object which describes the components of each index. Add each such object to the appropriate list of unique or non-unique index descriptors.

In addition, create and return an BitSet object which describes all indexed properties of the DMO.

Parameters:

dmoIface - DMO interface.

props - Array of metadata objects which describe each property in the DMO. The position of each element of this array will correspond with a set bit in an BitSet object which describes an index containing that property.

primary - Single-element string array output parameter, to be filled with the name of the primary index, if any.

validatable - Bit set of property positions in the record's data array of those properties which either are mandatory or which participate in a unique index.

unique - List of BitSet objects for unique indices, if any. Should be empty when this method is invoked; may be empty upon return.

uniqueNames - List of names for unique indices, if any, with positional correspondents in unique list.

uniqueLegacyNames - List of legacy names for unique indices, if any, with positional correspondents in unique list.

nonUnique - List of BitSet objects for non-unique indices, if any. Should be empty when this method is invoked; may be empty upon return.

nonUniqueNames - List of legacy names for non-unique indices, if any, with positional correspondents in nonUnique list.

nonUniqueLegacyNames - List of legacy names for non-unique indices, if any, with positional correspondents in nonUnique list.

Returns:

An BitSet object which describes all properties which participate in any index of the table represented by the DMO.

Throws:

java.lang.IllegalStateException - if the name of an index component stored in an IndexComponent annotation does not match the name of any property in the DMO.

tableNames

private static java.lang.String[] tableNames(DmoMeta dmoMeta,
                                             PropertyMeta[] props)

Get the array of table names associated with this DMO. The primary table is first, followed by secondary tables for extent field data, if this data is normalized. The secondary table names are in ascending order by extent value.

Parameters:

dmoMeta - The DmoMeta structure which contains the legacy meta information.

props - Array of property metadata, ordered as described in the Loader class description.

Returns:

Array of table names as described above.

stripBackTicks

private static java.lang.String stripBackTicks(java.lang.String name,
                                               java.lang.String dmoName)

Strip back tick quotes from a name, if it is enclosed in them. Otherwise, return the same string instance that was passed to this method as the name parameter.

Parameters:

name - Name from which to strip back ticks.

dmoName - DMO interface name (for error reporting only).

Returns:

Name without enclosing back ticks.

Throws:

java.lang.IllegalArgumentException - if a back tick leads or trails the name, but not both (i.e., unbalanced back tick quotes).

backTickify

private static java.lang.String backTickify(java.lang.String name)

Enclose a name in back ticks quotes.

Parameters:

name - Name to enclose.

Returns:

Name in back tick quotes.

getDmoMeta

public DmoMeta getDmoMeta()

Obtain the DmoMeta structure which contains the legacy meta information.

Returns:

DmoMeta structure which contains the legacy meta information

isTemporary

public boolean isTemporary()

Indicate whether this object represents metadata for a temporary table.

Returns:

true if backing, primary, table is a temporary table, else false.

getPropertyMeta

public PropertyMeta[] getPropertyMeta(boolean nativeOrder)

Get the array of property metadata objects which describe how the core data of this record is organized.

Parameters:

nativeOrder - If true the returned array of properties will be sorted by their id-s. This is the 'native' order, in which the records are found in exported (.d dump) files. This view of the properties is only needed when the import process is run.
Otherwise, the array is ordered scalar properties first, then the extent properties grouped by their extent size. Each group represents a series, all series are sorted by their common extent size. This is the 'persistence' order.

Returns:

Array of property metadata objects.

getAllIndexedProperties

public java.util.BitSet getAllIndexedProperties()

Get a bit set representing all DMO properties which participate in indices in the backing table. The 0-based positions of the set bits indicate the 0-based positions of the corresponding data elements in the record's data array.

Returns:

A bitset as described above. The original bit set (not a copy) is returned for maximum performance. It must not be altered.

getValidatableProperties

public java.util.BitSet getValidatableProperties()

Get a bit set representing all DMO properties which must be validated when a record is created or updated. These include properties which either are mandatory or which participate in one or more unique indices in the backing table. The 0-based positions of the set bits indicate the 0-based positions of the corresponding data elements in the record's data array.

Returns:

A bitset as described above. The original bit set (not a copy) is returned for maximum performance. It must not be altered.

getUniqueIndices

public java.util.BitSet[] getUniqueIndices()

Get an array of bit sets, each of which describes the components of an unique index. The 0-based positions of the set bits indicate the 0-based positions of the corresponding data elements in the record's data array. Note that this representation only describes which properties participate in an index, but not the precedence of those properties.

Returns:

An array of bit sets as described above. The original bit sets (not copies) are returned for maximum performance. They must not be altered.

getUniqueIndicesValidationSQLs

public java.lang.String[] getUniqueIndicesValidationSQLs(Dialect d)

Get an array of SQL statements, each of which the tests the uniqueness of a record against an unique index.

Returns:

The set of statements used to check whether a record is unique in the table, according to its unique indexes (one SELECT statement per such index).

getReplaceCleanupSQLs

public java.lang.String[] getReplaceCleanupSQLs(Dialect d)

Get an array of DELETE SQL statements used to remove existing records which conflict (from the point of view of unique indexes) with a record that is about to be inserted.

Only used for FILL operations in REPLACE mode.

Returns:

array of DELETE SQL statements (one for each unique index) that

getIndexKeyCollisionsSQLs

public java.lang.String[] getIndexKeyCollisionsSQLs(Dialect d)

Get an array of SQL query statements used to extract existing records which conflict (from the point of view of unique indexes) with a record that is about to be inserted.

Only used for FILL operations in REPLACE mode.

Returns:

array of DELETE SQL statements (one for each unique index) that

getNonuniqueIndices

public java.util.BitSet[] getNonuniqueIndices()

Get an array of bit sets, each of which describes the components of a non-unique index. The 0-based positions of the set bits indicate the 0-based positions of the corresponding data elements in the record's data array. Note that this representation only describes which properties participate in an index, but not the precedence of those properties.

Returns:

An array of bit sets as described above. The original bit sets (not copies) are returned for maximum performance. They must not be altered.

getIndexLegacyName

public java.lang.String getIndexLegacyName(int pos,
                                           boolean unique)

Obtain the legacy name of an index, by its order in the list of unique or non-unique lists.

Parameters:

pos - The position in the list of unique or non-unique list of indices.

unique - If true, the name of the pos unique index is returned, otherwise the non-unique list is used.

Returns:

The legacy name of the specified index, or null if the index is invalid.

getUniqueIndexNames

public java.lang.String[] getUniqueIndexNames()

Obtain the array of names of unique indices, if any. The order will match the one from getUniqueIndices() and getIndexLegacyName().

Returns:

the array of index names.

getNonuniqueIndexNames

public java.lang.String[] getNonuniqueIndexNames()

Obtain the array of names of unique indices, if any. The order will match the one from getNonuniqueIndices() and getIndexLegacyName().

Returns:

the array of index names.

getLegacyName

public java.lang.String getLegacyName()

Obtain the legacy name of the parent table.

Returns:

the legacy name of the parent table.

getIndexOfProperty

public int getIndexOfProperty(java.lang.String propName)

Obtain the index of a property in the data array based on its name.

NOTE:
Use this method only in non-time-critical code. It uses map access and usage is not recommended.

Parameters:

propName - The name of the property.

Returns:

The base-0 index of the property. If the property is not defined in this DMO, -1 is returned.

getIndexIdByName

public int getIndexIdByName(java.lang.String name)

Obtain the id of an index using its name.

Parameters:

name - The name of the index.

Returns:

The id of the index. If positive, it is an unique index. If negative, it is a non-unique index. If 0, the index could not be found (invalid index name).

getPrimaryIndexId

public int getPrimaryIndexId()