com.goldencode.p2j.persist.orm

Class UniqueTracker

java.lang.Object

com.goldencode.p2j.persist.orm.UniqueTracker

public class UniqueTracker
extends java.lang.Object

Implements a tracker for records in unique indices in uncommitted transactions. This enables a proactive, synchronized check to ensure the insertion or update of a record will not cause a unique constraint violation, with respect to any uncommitted changes across FWD sessions. Otherwise, such a failure would not occur until the latter of two transactions containing a conflicting insert/update were committed. This would be too late in terms of legacy compatibility, since the 4GL reports this failure at the moment of the index update, not at the eventual transaction commit.

The overall structure of the UniqueTracker architecture is one map instance per unique index, per table/DMO type. The maps are keyed by Key which emulate the P4GL constraints from the point of view of the unique indexes. The values mapped are the ids of the records.

The exposed API allows to:

• add new Record to tracking;
• test whether a specified Record is tracked;
• remove a specified Record (or using its id) from tracking;

The tracker also keeps track of the transactions and all elements associated with a transaction are processed when the transaction is committed (or rolled back).

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	UniqueTracker.Context Context-local API through which UniqueTracker functionality should be accessed.
static class	UniqueTracker.Token An object which holds information about the set of UniqueIndex objects locked and updated by an operation on a particular UniqueTracker instance.
private static class	UniqueTracker.UniqueIndex The data related to a specified unique index.

Field Summary

Fields

Modifier and Type	Field and Description
private static ContextLocal<UniqueTracker.Context>	context Context local state for this session's uncommitted transaction data
private static java.util.Map<java.lang.Class<? extends BaseRecord>,UniqueTracker>	instances Cache of DMO implementation classes to instances of this class
private static CentralLogger	LOG Logger
private UniqueTracker.UniqueIndex[]	uniqueIndexes The list of UniqueIndex for a DataModelObject.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	UniqueTracker() Default constructor, used only by no-op subclass.
private	UniqueTracker(DmoMeta dmoInfo) Creates a new tracker for a designated BaseRecord.

Method Summary

Modifier and Type	Method and Description
static UniqueTracker.Context	getContext() Get the context-local helper object which is the local session's access to the UniqueTracker API.
static UniqueTracker	getInstance(DmoMeta dmoInfo) Get a UniqueTracker for a specified DataModelObject.
private static UniqueTracker	instantiate(DmoMeta dmoInfo) Instantiate the appropriate form of this class for the given DMO implementation class.
protected UniqueTracker.Token	lockAndChange(BaseRecord dmo, UniqueTracker.Context context, java.lang.String bufferName, boolean flush) Check the given record's state and update the minimal, necessary unique index(es), based on any dirty properties in the record, or update all unique indexes in the case that dmo has been newly created and was not previously persisted.
protected UniqueTracker.Token	lockAndDelete(BaseRecord dmo, UniqueTracker.Context context) The given DMO has been deleted in the current transaction.
private void	reportUniqueConstraintViolation(BaseRecord dmo, UniqueTracker.UniqueIndex.Key key, java.lang.String bufferName) Report a unique constraint violation using the expected, legacy error message.
private void	rollbackChange(java.lang.Long id, java.util.List<org.apache.commons.lang3.tuple.Pair<java.lang.Integer,UniqueTracker.UniqueIndex.Key>> affected) Roll back an update operation on zero or more unique keys in this tracker, presumably in response to a unique constraint violation either generated by this tracker or which occurred during a database insert or update.
protected void	rollbackChange(UniqueTracker.Token token) Roll back an update operation on zero or more unique keys in this tracker, presumably in response to a unique constraint violation either generated by this tracker or which occurred during a database insert or update.
private void	unlock(java.util.List<org.apache.commons.lang3.tuple.Pair<java.lang.Integer,UniqueTracker.UniqueIndex.Key>> affected) Unlock the UniqueIndex instances specified in the given list of pairs.
protected void	unlock(UniqueTracker.Token token) Complete the operation begun by lockAndChange(com.goldencode.p2j.persist.orm.BaseRecord, com.goldencode.p2j.persist.orm.UniqueTracker.Context, java.lang.String, boolean) or by lockAndDelete(BaseRecord, Context), using the token returned by the respective method.

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

instances

private static final java.util.Map<java.lang.Class<? extends BaseRecord>,UniqueTracker> instances

Cache of DMO implementation classes to instances of this class

context

private static final ContextLocal<UniqueTracker.Context> context

Context local state for this session's uncommitted transaction data

uniqueIndexes

private final UniqueTracker.UniqueIndex[] uniqueIndexes

The list of UniqueIndex for a DataModelObject. When an UniqueTracker is created the DMO class is analyzed and the list of unique indexes is extracted. For each index there an UniqueIndex is created and added to this array.

Constructor Detail

UniqueTracker

protected UniqueTracker()

Default constructor, used only by no-op subclass.

See Also:

instantiate(DmoMeta)

UniqueTracker

private UniqueTracker(DmoMeta dmoInfo)

Creates a new tracker for a designated BaseRecord. The dmoClass is used to extract the unique indexes and create an optimized internal data structure.

Parameters:

dmoInfo - The DMO meta information for DMO implementation class.

Method Detail

getContext

public static UniqueTracker.Context getContext()

Get the context-local helper object which is the local session's access to the UniqueTracker API.

Returns:

Context-local helper object.

getInstance

public static UniqueTracker getInstance(DmoMeta dmoInfo)

Get a UniqueTracker for a specified DataModelObject. If this is the first call for a specified class, a new instance is created.

Parameters:

dmoInfo - The DMO meta information for DMO implementation class.

Returns:

The UniqueTracker for the specified DataModelObject.

instantiate

private static UniqueTracker instantiate(DmoMeta dmoInfo)

Instantiate the appropriate form of this class for the given DMO implementation class. This returns a no-op version for use with temp-table DMOs, and fully functioning version for persistent table DMOs. Temp-tables operate only in a single context. Therefore, validating against the database is sufficient to detect any unique constraint violation.

Parameters:

dmoInfo - The DMO meta information for DMO implementation class.

Returns:

A new instance of this class, possibly with some methods neutered.

lockAndChange

protected UniqueTracker.Token lockAndChange(BaseRecord dmo,
                                            UniqueTracker.Context context,
                                            java.lang.String bufferName,
                                            boolean flush)
                                     throws ValidationException

Check the given record's state and update the minimal, necessary unique index(es), based on any dirty properties in the record, or update all unique indexes in the case that dmo has been newly created and was not previously persisted.

If the data within dmo violates an existing unique constraint, an error is raised. Any changes made up to that point are rolled back automatically.

Parameters:

dmo - Record whose state is driving an update to this tracker.

context - Uncommitted data managed for the current context.

bufferName - The name of the buffer. It is used when printing the error message, if any.

flush - Whether to flush the record; false to validate only.

Returns:

A token which contains information about the update operation. This token must be passed to either unlock(Token) or to rollbackChange(Token) in order to commit or roll back the update, respectively, and to ensure any locks acquired by the update are released.

Throws:

ValidationException - if the data in dmo represent a unique constraint violation within any session's uncommitted transactions.

lockAndDelete

protected UniqueTracker.Token lockAndDelete(BaseRecord dmo,
                                            UniqueTracker.Context context)

The given DMO has been deleted in the current transaction. If a unique index already is being tracked for this DMO, it indicates that the DMO previously was inserted or updated in the same transaction. In this case, remove its earlier unique index entry, but remember it in case we need to roll back this delete later. In the event there is no unique index already being tracked, it indicates that the record deleted was not previously inserted or updated during the current transaction. In this case, we store null for the key in the deletes we are tracking. Rollback code must tolerate this null.

This operation performs no validation, as no unique constraint can be violated by a delete.

Parameters:

dmo - DMO which was deleted.

context - Uncommitted data managed for the current context.

Returns:

A token which contains information about the update operation. This token must be passed to either unlock(Token) or to rollbackChange(Token) in order to commit or roll back the update, respectively, and to ensure any locks acquired by the update are released.

unlock

protected void unlock(UniqueTracker.Token token)

Complete the operation begun by lockAndChange(com.goldencode.p2j.persist.orm.BaseRecord, com.goldencode.p2j.persist.orm.UniqueTracker.Context, java.lang.String, boolean) or by lockAndDelete(BaseRecord, Context), using the token returned by the respective method. A commit is no more than the absence of a rollback and an unlocking of any UniqueIndex instances locked by the update or delete.

This method should be invoked when no unique constraint violation has occurred during a record validation event.

Parameters:

token - A token returned by lockAndChange(com.goldencode.p2j.persist.orm.BaseRecord, com.goldencode.p2j.persist.orm.UniqueTracker.Context, java.lang.String, boolean) or by lockAndDelete(BaseRecord, Context), used to unlock any UniqueIndex instances instances locked by those methods.

rollbackChange

protected void rollbackChange(UniqueTracker.Token token)

Roll back an update operation on zero or more unique keys in this tracker, presumably in response to a unique constraint violation either generated by this tracker or which occurred during a database insert or update.

This method should be invoked when a unique constraint violation has occurred during a record validation event.

Parameters:

token - A token returned by lockAndChange(com.goldencode.p2j.persist.orm.BaseRecord, com.goldencode.p2j.persist.orm.UniqueTracker.Context, java.lang.String, boolean), used to rollback any partial or full updates made and to unlock any UniqueIndex instances locked by the update.

rollbackChange

private void rollbackChange(java.lang.Long id,
                            java.util.List<org.apache.commons.lang3.tuple.Pair<java.lang.Integer,UniqueTracker.UniqueIndex.Key>> affected)

Roll back an update operation on zero or more unique keys in this tracker, presumably in response to a unique constraint violation either generated by this tracker or which occurred during a database insert or update.

Parameters:

id - Primary key of the record for which the update operation was performed.

affected - A list of pairs of UniqueIndex positions in the uniqueIndexes array and corresponding Key instances to be restored (or null if the operation represented a new record insert).

unlock

private void unlock(java.util.List<org.apache.commons.lang3.tuple.Pair<java.lang.Integer,UniqueTracker.UniqueIndex.Key>> affected)

Unlock the UniqueIndex instances specified in the given list of pairs.

Parameters:

affected - A list of zero or more pairs of UniqueIndex positions in the uniqueIndexes array and Key instances. The UniqueIndex instances at the given positions are to be unlocked.

reportUniqueConstraintViolation

private void reportUniqueConstraintViolation(BaseRecord dmo,
                                             UniqueTracker.UniqueIndex.Key key,
                                             java.lang.String bufferName)
                                      throws ValidationException

Report a unique constraint violation using the expected, legacy error message.

Parameters:

dmo - Record which violated constraint.

key - Unique index key which contains the non-unique data.

bufferName - The name of the buffer. It is used when printing the error message, if any.

Throws:

ValidationException - always; describes the unique constraint violation.