org.sandev.basics.structs
Interface SandTransmitMessage

All Superinterfaces:

SandMessage

All Known Subinterfaces:

SandCollectionMessage, SandQueryMessage, SandUpdateMessage, SandVerbMessage

All Known Implementing Classes:

AggregateUpdate, AuthWrapper, BaseUserCollection, BaseUserEmailCollection, BaseUserEmailQuery, BaseUserEmailUpdate, BaseUserQuery, BaseUserUpdate, CacheAction, CacheItemSummaryCollection, CacheItemSummaryQuery, CacheMemSummaryCollection, CacheMemSummaryQuery, CacheStatsCollection, CacheStatsQuery, Configuration, ConfigurationUpdate, DataImportExport, ErrorInfoCollection, FormOutput, Ping, ServerDeclarationCollection, ServerDeclarationQuery, ServerDeclarationUpdate, Stats, StatsQuery, TestActionUpdate, TestConditionUpdate, TestRunStatus, TestScriptUpdate, TestStepUpdate

public interface SandTransmitMessage
extends SandMessage

Interface implemented by all messages that get sent across the wire.

SandMessage

SandInstanceMessage
SandStructMessage
SandPersistMessage
NodeInstance
SandTransmitMessage
SandVerbMessage
SandUpdateMessage
SandQueryMessage
SandCollectionMessage

This interface contains methods and constants used for transmission status and error reporting. The fields are part of the generated verb messages, and any message which is declared to be transmittable by itself.

When a call returns a message, and sandTransmitStatus!=STATUS_NORMAL, then sandTransmitErrorMessage is set to error text describing the problem. This text may contain anything, but the following conventions are recommended:

1. The message text starts with a constant value. This value may be optionally followed by a space character and additional information.
2. Error constant names start with "APPERROR_", "SANDERROR_", or "SYSERROR_".

This allows application code to do tests like:

        if(msg.getSandTransmitErrorMessage().startsWith(
               SandTransmitMessage.APPERROR_NODE_UNAVAILABLE)) {
            //react to node being down
            ...
        }
 

The app may also use SandTransmitMessage.APPERROR_NODE_UNAVAILABLE as a key to lookup localized text.

Error prefix usage:

• SYSERROR constants are reserved for true system failures. This pretty much means VM errors.
• SANDERROR constants are used for errors relating to failures in the framework code or underlying technology.
• APPERROR constants are used for errors which are specific to the application. This includes errors in processing business logic due to data or system state issues.

Most errors are application errors.

Field Summary

static java.lang.String	APPERROR_NODE_UNAVAILABLE Application level error message indicating that the target node is not available.
static java.lang.String	APPERROR_NODE_UNKNOWN Application level error message indicating that the target node is unknown.
static java.lang.String	APPERROR_NODE_UNREACHABLE Application level error message indicating that the target node is unreachable.
static int	STATUS_APPERROR The message status is an error which occurred at the level of the application.
static int	STATUS_NORMAL The message status is normal.
static int	STATUS_SANDERROR The message status is an error which occurred at the level of the development/deployment environment.
static int	STATUS_SYSERROR The message status is an error which occurred at the system level.

Method Summary

int	getSandTransmissionCount() Return the transmission count for this message.
java.util.Locale	getSandTransmissionLocale() Get the Locale in effect for this transmission.
long	getSandTransmitAuthID() Return the ID of messaging user for authorization purposes.
java.lang.String	getSandTransmitErrorCode() Return the code associated with the error message, if set.
java.lang.String	getSandTransmitErrorMessage() Return a full description of the error message, and any accompanying information.
int	getSandTransmitStatus() Return one of the defined STATUS_* values representing the status of the message.
void	setSandTransmissionCount(int val) Set the sandTransmissionCount of the message for tracking purposes.
void	setSandTransmissionLocale(java.util.Locale loc) Set the Locale in effect for this transmission.
void	setSandTransmitAuthID(long ID) Set the ID of the messaging user for authorization purposes.
void	setSandTransmitError(java.lang.String code, java.lang.String errText) Sets both the code and the error in a single method.
void	setSandTransmitErrorCode(java.lang.String code) Sets the code associated with the error message.
void	setSandTransmitErrorMessage(java.lang.String text) Sets the sandTransmitErrorMessage to the given text.
void	setSandTransmitStatus(int status) Sets the sandTransmitStatus to one of the defined STATUS_* values.

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

getBaseMemoryUse, getCollectionMessage, getQueryMessage, getShortName, getStructMessage, getUpdateMessage, isEquivalent

Field Detail

APPERROR_NODE_UNKNOWN

static final java.lang.String APPERROR_NODE_UNKNOWN

Application level error message indicating that the target node is unknown. No node instance was found for the target name specified in the messaging configuration.

When possible, this message text is followed by a space, then "node: ", then the specified target node name.

See Also:

Constant Field Values

APPERROR_NODE_UNREACHABLE

static final java.lang.String APPERROR_NODE_UNREACHABLE

Application level error message indicating that the target node is unreachable. The node instance was found configured, but communication could not be established.

When possible, this message text is followed by a space, then "node: ", then the node instance name.

See Also:

Constant Field Values

APPERROR_NODE_UNAVAILABLE

static final java.lang.String APPERROR_NODE_UNAVAILABLE

Application level error message indicating that the target node is not available. The node instance was found, and communication was established, but the node was not accepting messages.

When possible, this message text is followed by a space, then "node: ", then the node instance name.

See Also:

Constant Field Values

STATUS_NORMAL

static final int STATUS_NORMAL

The message status is normal. Everything went fine.

See Also:

Constant Field Values

STATUS_SYSERROR

static final int STATUS_SYSERROR

The message status is an error which occurred at the system level. System level generally means either the hardware or software that the development/deployment environment relies on to function.

See Also:

Constant Field Values

STATUS_SANDERROR

static final int STATUS_SANDERROR

The message status is an error which occurred at the level of the development/deployment environment. Usually a problem in generated code or data.

See Also:

Constant Field Values

STATUS_APPERROR

static final int STATUS_APPERROR

The message status is an error which occurred at the level of the application.

See Also:

Constant Field Values

Method Detail

getSandTransmitStatus

int getSandTransmitStatus()

Return one of the defined STATUS_* values representing the status of the message.

setSandTransmitStatus

void setSandTransmitStatus(int status)

Sets the sandTransmitStatus to one of the defined STATUS_* values.

getSandTransmitErrorMessage

java.lang.String getSandTransmitErrorMessage()

Return a full description of the error message, and any accompanying information.

setSandTransmitErrorMessage

void setSandTransmitErrorMessage(java.lang.String text)

Sets the sandTransmitErrorMessage to the given text.

getSandTransmitErrorCode

java.lang.String getSandTransmitErrorCode()

Return the code associated with the error message, if set. The code can be any value set in addition to the error message for additional details in error processing.

setSandTransmitErrorCode

void setSandTransmitErrorCode(java.lang.String code)

Sets the code associated with the error message.

setSandTransmitError

void setSandTransmitError(java.lang.String code,
                          java.lang.String errText)

Sets both the code and the error in a single method. Typically the code has corresponding text, so when codes are used it is recommended to use this method to ensure that the code and the message are in sync.

getSandTransmitAuthID

long getSandTransmitAuthID()

Return the ID of messaging user for authorization purposes. A message is authenticated using the encryption information in the AuthWrapper. This ID provides a context for authorizing the action the message represents, or visibility of the contained data.

setSandTransmitAuthID

void setSandTransmitAuthID(long ID)

Set the ID of the messaging user for authorization purposes.

getSandTransmissionCount

int getSandTransmissionCount()

Return the transmission count for this message. A sender or caller may optionally set the sandTransmissionCount in an outbound message for tracking purposes. This is primarily intended for use in asynchronous outbound send, as an aid in verifying sent messages are received in sequence.

setSandTransmissionCount

void setSandTransmissionCount(int val)

Set the sandTransmissionCount of the message for tracking purposes.

getSandTransmissionLocale

java.util.Locale getSandTransmissionLocale()

Get the Locale in effect for this transmission.

setSandTransmissionLocale

void setSandTransmissionLocale(java.util.Locale loc)

Set the Locale in effect for this transmission.