org.sandev.basics.structs
Interface SandPersistMessage

All Superinterfaces:

SandInstanceMessage, SandMessage, SandStructMessage

All Known Subinterfaces:

BaseUserInterface

All Known Implementing Classes:

BaseUser, BaseUserEmail

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.
static int	WRITEACCESS_NORMAL Indicates this instance can be modified.
static int	WRITEACCESS_READONLY Indicates this instance may not be modified.

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

FIELDCHECK_EMPTYSTRINGPRINTVAL, 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_SUMMARYEDIT, 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.
int	getInstanceWriteAccess() Return the write access for this instance.
java.util.Date	getLastAccessedTime() Return the time this persistent instance was last accessed.
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	setInstanceWriteAccess(int access) Set the write access for this instance.
void	setLastAccessedTime(java.util.Date lastAccessed) Set the lastAccessedTime for this instance.
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.SandStructMessage

find, getInstance, getInstance, getPrintname

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

cloneMessage, convertToSuperstructClass, copyFieldValue, debugDump, defaultField, fieldHasFlag, fieldsValid, fieldValidate, generalAccessor, generalDereference, generalModifier, getAllFields, getContainedMessageFields, getDisplayFields, getDisplayFieldsPrint, getDisplayID, getDisplayValues, getPrintnameForField

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

getCollectionMessage, getQueryMessage, getShortName, getStructMessage, getUpdateMessage, isEquivalent

Field Detail

WRITEACCESS_NORMAL

static final int WRITEACCESS_NORMAL

Indicates this instance can be modified.

See Also:

Constant Field Values

WRITEACCESS_READONLY

static final int WRITEACCESS_READONLY

Indicates this instance may not be modified. Calls to mutator methods other than to set this flag or the last accessed time will result in an exception being thrown.

See Also:

Constant Field Values

RECORDSTATUS_ACTIVE

static final int RECORDSTATUS_ACTIVE

Indicates everything is normal. The instance exists.

See Also:

Constant Field Values

RECORDSTATUS_DELETED

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

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

long getUniqueID()

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

setUniqueID

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

java.util.Date getCreationTime()

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

getLastModifiedTime

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

java.lang.String getLastModifiedReason()

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

setLastModifiedReason

void setLastModifiedReason(java.lang.String reason)

Set the last modified reason.

getRevisionNumber

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

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.

getLastAccessedTime

java.util.Date getLastAccessedTime()

Return the time this persistent instance was last accessed. This is initialized to the current time when a new instance is created or retrieved from persistent storage. It may also be updated when an instance is retrieved from cache and/or by the application as needed for age tracking or other purposes. Implemented using a transient data member.

setLastAccessedTime

void setLastAccessedTime(java.util.Date lastAccessed)

Set the lastAccessedTime for this instance.

getInstanceWriteAccess

int getInstanceWriteAccess()

Return the write access for this instance.

setInstanceWriteAccess

void setInstanceWriteAccess(int access)

Set the write access for this instance.

getRecordStatus

int getRecordStatus()

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