org.sandev.basics.structs
Interface SandPersistMessage

All Superinterfaces:

SandInstanceMessage, SandMessage, SandStructMessage

All Known Implementing Classes:

BaseUser

public interface SandPersistMessage

extends SandStructMessage

Interface to identify those SandStructMessages which are persistent.

SandMessage

SandInstanceMessage
SandStructMessage
SandPersistMessage
NodeInstance
SandTransmitMessage
SandVerbMessage
SandUpdateMessage
SandQueryMessage
SandCollectionMessage

A SandPersistMessage contains automatically generated fields used for instance identification and tracking over time. These fields are reflected through the accessor methods defined by this interface. With the exception of lastModifiedReason (which may be used for any purpose by the application code), these fields are the responsibility of the DataManager and are only modified within a Persister implementation.

The uniqueID (primary key) for an instance is immutable. The setUniqueID method is provided to support temporary IDs for reference structures in an AggregateUpdate message.

See Persist.html in the top level documentation for more information on persistency.

Field Summary

static int	RECORDSTATUS_ACTIVE Indicates everything is normal.
static int	RECORDSTATUS_ARCHIVED Historical information can accumulate significantly over time.
static int	RECORDSTATUS_DELETED Indicates this instance no longer exists.

Fields inherited from interface org.sandev.basics.structs.SandInstanceMessage

FIELDCHECK_INVALIDVAL, FIELDCHECK_NOTAREF, FIELDCHECK_NOTINRANGE, FIELDCHECK_NULLARRAY, FIELDCHECK_STRINGOVER, FIELDCHECK_UNKNOWNVAL, FIELDFLAG_BINARY, FIELDFLAG_ENCRYPT, FIELDFLAG_INTERNAL, FIELDFLAG_NOECHO, FIELDFLAG_OBFUSCATE, FIELDFLAG_STRINGPERSIST, FIELDFLAG_UNIQUE, GENMOD_ACTION_APPEND, GENMOD_ACTION_INSERT, GENMOD_ACTION_REMOVE, GENMOD_ACTION_SET

Method Summary

java.util.Date	getCreationTime() Return the immutable timestamp generated by the DataManager when the instance was first created.
java.lang.String	getLastModifiedReason() Return the arbitrary text optionally supplied by the application as part of the last update message.
java.util.Date	getLastModifiedTime() Return the immutable timestamp generated by the DataManager when the instance was last updated.
int	getRecordStatus() Returns the RECORDSTATUS_* value for this instance.
long	getRevisionNumber() Return the number of times this instance has been updated.
long	getUniqueID() Returns the immutable unique identifier generated by the DataManager when the instance was first created.
void	setLastModifiedReason(java.lang.String reason) Set the last modified reason.
void	setRevisionNumber(long val) Set the number of times this instance has been updated.
void	setUniqueID(long id) Sets the immutable unique identifier generated by the DataManager when the instance was first created.

Methods inherited from interface org.sandev.basics.structs.SandInstanceMessage

cloneMessage, convertToSuperstructClass, copyFieldValue, debugDump, defaultField, fieldHasFlag, fieldsValid, fieldValidate, generalAccessor, generalDereference, generalModifier, getAllFields, getDisplayFields, getDisplayValues

Methods inherited from interface org.sandev.basics.structs.SandMessage

getCollectionMessage, getQueryMessage, getShortName, getStructMessage, getUpdateMessage, isEquivalent

Field Detail

RECORDSTATUS_ACTIVE

public static final int RECORDSTATUS_ACTIVE

Indicates everything is normal. The instance exists.

See Also:

Constant Field Values

RECORDSTATUS_DELETED

public static final int RECORDSTATUS_DELETED

Indicates this instance no longer exists. The DataManager will never retrieve deleted instances in response to a normal query. For a historical query, the latest instance information may indicate that the instance was deleted.

Anything that is RECORDSTATUS_DELETED, which does not track history, can be permanently removed from persistent storage. If a deleted instance is removed from permanent storage, it will generally not be possible for the application to distinguish between the deletion and the instance never having been created.

See Also:

Constant Field Values

RECORDSTATUS_ARCHIVED

public static final int RECORDSTATUS_ARCHIVED

Historical information can accumulate significantly over time. How historical information storage is maintained varies widely based on application requirements and the data storage technology in use. Typically, older historical records are periodically transitioned to slower access and eventually offline.

When removing records from active storage, the first historical record of the removed block is left in active storage with RECORDSTATUS_ARCHIVED. This allows the DataManager to realize this is not a case of missing or bad data, and it allows the application to smoothly pick up where the current DataManager left off (possibly by querying an archive DataManager).

It is recommended, though not required, that the tagging of information as archived be done through the DataManager. The DataManager will mark all active records older than the cutoff as archived.

See Also:

Constant Field Values

Method Detail

getUniqueID

public long getUniqueID()

Returns the immutable unique identifier generated by the DataManager when the instance was first created.

setUniqueID

public void setUniqueID(long id)

Sets the immutable unique identifier generated by the DataManager when the instance was first created. This method is used when reconstructing an instance from a serialized form. The uniqueID cannot be changed once set by the DataManager.

getCreationTime

public java.util.Date getCreationTime()

Return the immutable timestamp generated by the DataManager when the instance was first created.

getLastModifiedTime

public java.util.Date getLastModifiedTime()

Return the immutable timestamp generated by the DataManager when the instance was last updated. This is initially set to the same value as the creation time.

getLastModifiedReason

public java.lang.String getLastModifiedReason()

Return the arbitrary text optionally supplied by the application as part of the last update message.

setLastModifiedReason

public void setLastModifiedReason(java.lang.String reason)

Set the last modified reason.

getRevisionNumber

public long getRevisionNumber()

Return the number of times this instance has been updated. The initial instance creation is revision zero. This field is only modified by the DataManager.

This is declared as a long because it avoids the question of whether any application will exceed 2,147,483,647 revisions.

setRevisionNumber

public void setRevisionNumber(long val)

Set the number of times this instance has been updated. The revision numbers are managed by the DataManager, so this method should only be used in Persister implementations, merging data forward, or other similar operations.

getRecordStatus

public int getRecordStatus()

Returns the RECORDSTATUS_* value for this instance. Under most normal circumstances this will return RECORDSTATUS_ACTIVE.