SandUpdateMessage

A SandUpdateMessage represents an update to a single SandStructMessage instance (updates to NodeInstances are managed through a deployment configuration). To update several instances within a single transaction, use an AggregateUpdate.

If the instance is outdated, then the update will fail (at least for persistent messages). This can be due to a transaction collision, or more commonly to someone else modifying the same information in the interim. If this happens, getSandTransmitStatus will return STATUS_APPERROR, and the value of getSandTransmitErrorMessage will start with the value of APPERROR_UPDATE_OUTDATED, with any additional information appended afterwards. For an overview of error message conventions, see SandTransmitMessage.

In SAND, there is no concept of "locking" persistent data to prevent interim changes. If necessary, this type of "pessimistic" data locking can be implemented at the application level by declaring a "lock" field in the struct definition. An appliction node would submit an update to set the lock, then submit a second update to change the data and clear the lock. This type of locking is not recommended due to the possibility of lost locks and other maintenance. A variation, where the first update marks the instance as reserved for a fixed time period, is a significant improvement but should only be used when absolutely necessary.

Field Summary
`static int`	`ACTION_ADD` This update is an addition of a new data instance to the system.
`static int`	`ACTION_DELETE` This is a deletion of an instance from the system.
`static int`	`ACTION_UNDEFINED` ACTION_UNDEFINED is considered an invalid value and represents an update message that has not been fully initialized.
`static int`	`ACTION_UPDATE` This update is a change to an existing data instance.
`static java.lang.String`	`APPERROR_UPDATEFAIL_OLDVERSION` The error text for a SandUpdateMessage processing failure due to the update specifying the wrong revisionNumber.
`static java.lang.String`	`APPERROR_UPDATEFAIL_UNIQUEVIO` The error text for a SandUpdateMessage processing failure due to the update specifying a duplicate value for a field that was declared unique.

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

APPERROR_NODE_UNAVAILABLE, APPERROR_NODE_UNKNOWN, APPERROR_NODE_UNREACHABLE, STATUS_APPERROR, STATUS_NORMAL, STATUS_SANDERROR, STATUS_SYSERROR

Method Summary
`java.lang.String`	`actionValueToLabel(int action)` Return a text representation of the action.
`int`	`getAction()` Returns one of the ACTION_* constants indicating what kind of update action this is.
`SandStructMessage`	`getInstance()` Generalized access to the updated instance information.
`long`	`getInstanceID()` Return the uniqueID of the instance to be updated, or -1 if it is not a persistent message.
`java.lang.String`	`getSource()` An update message may have the name of the node that is the source for an update.
`void`	`setAction(int action)` Sets the action for this instance to be one of the ACTION_* constants.
`void`	`setInstance(SandStructMessage msg)` Generalized mutator for setting the specific message instance information.
`void`	`setSource(java.lang.String source)` Sets the source for this update message.

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

getSandTransmissionCount, getSandTransmitAuthID, getSandTransmitErrorMessage, getSandTransmitStatus, setSandTransmissionCount, setSandTransmitAuthID, setSandTransmitErrorMessage, setSandTransmitStatus

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

getCollectionMessage, getQueryMessage, getShortName, getStructMessage, getUpdateMessage, isEquivalent

Field Detail

ACTION_ADD

public static final int ACTION_ADD

This update is an addition of a new data instance to the system.

See Also:: Constant Field Values

ACTION_UPDATE

public static final int ACTION_UPDATE

This update is a change to an existing data instance.

See Also:: Constant Field Values

ACTION_DELETE

public static final int ACTION_DELETE

This is a deletion of an instance from the system. For a persistent message, the expectation is that the DataManager will mark the recordStatus of the instance as deleted. Other contexts may differ. It is recommended that persistent data never actually be deleted except under highly specialized circumstances such as initialization or archiving procedures. See the DataManager and Perister implementation for details.

For a delete action, instance information is still required by most automated processing, to identify the instance to be deleted. In the case of a persistent object, at least the uniqueID and revisionNumber must be present and accurate in the update instance.

See Also:: Constant Field Values

ACTION_UNDEFINED

public static final int ACTION_UNDEFINED

ACTION_UNDEFINED is considered an invalid value and represents an update message that has not been fully initialized.

See Also:: Constant Field Values

APPERROR_UPDATEFAIL_OLDVERSION

public static final java.lang.String APPERROR_UPDATEFAIL_OLDVERSION

The error text for a SandUpdateMessage processing failure due to the update specifying the wrong revisionNumber. The tokens are replaced during processing.

See Also:: Constant Field Values

APPERROR_UPDATEFAIL_UNIQUEVIO

public static final java.lang.String APPERROR_UPDATEFAIL_UNIQUEVIO

The error text for a SandUpdateMessage processing failure due to the update specifying a duplicate value for a field that was declared unique. The tokens are replaced during processing.

See Also:: Constant Field Values

Method Detail

getAction

public int getAction()

Returns one of the ACTION_* constants indicating what kind of update action this is.

setAction

public void setAction(int action)

Sets the action for this instance to be one of the ACTION_* constants.

getInstance

public SandStructMessage getInstance()

Generalized access to the updated instance information. The instance information is stored in a data member of the specific message type, but some processing requires access to just the SandStructMessage. This method wraps the type specific access within a general accessor.

setInstance

public void setInstance(SandStructMessage msg)

Generalized mutator for setting the specific message instance information.

getSource

public java.lang.String getSource()

An update message may have the name of the node that is the source for an update. This is helpful for straightening out the derivation of complex AggregateUpdates where additional updates may be added by filter nodes in the process to implement application logic.

setSource

public void setSource(java.lang.String source)

Sets the source for this update message. By convention this is the instance name of the node that created the update.

actionValueToLabel

public java.lang.String actionValueToLabel(int action)

Return a text representation of the action. Useful for debugging or log output. Returns null if the action value is invalid.

getInstanceID

public long getInstanceID()

Return the uniqueID of the instance to be updated, or -1 if it is not a persistent message.

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.sandev.basics.structs Interface SandUpdateMessage