org.sandev.basics.structs
Interface SandTransmitMessage

All Superinterfaces:

SandMessage

All Known Subinterfaces:

SandCollectionMessage, SandQueryMessage, SandUpdateMessage, SandVerbMessage

All Known Implementing Classes:

AggregateUpdate, AuthWrapper, BaseUserCollection, BaseUserQuery, BaseUserUpdate, CacheAction, Configuration, ConfigurationUpdate, DataImportExport, Ping, ServerDeclarationCollection, ServerDeclarationQuery, Stats, StatsQuery

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.
long	getSandTransmitAuthID() Return the ID of messaging user for authorization purposes.
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	setSandTransmitAuthID(long ID) Set the ID of the messaging user for authorization purposes.
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

getCollectionMessage, getQueryMessage, getShortName, getStructMessage, getUpdateMessage, isEquivalent

Field Detail

APPERROR_NODE_UNKNOWN

public 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

public 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

public 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

public static final int STATUS_NORMAL

The message status is normal. Everything went fine.

See Also:

Constant Field Values

STATUS_SYSERROR

public 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

public 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

public 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

public int getSandTransmitStatus()

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

setSandTransmitStatus

public void setSandTransmitStatus(int status)

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

getSandTransmitErrorMessage

public java.lang.String getSandTransmitErrorMessage()

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

setSandTransmitErrorMessage

public void setSandTransmitErrorMessage(java.lang.String text)

Sets the sandTransmitErrorMessage to the given text.

getSandTransmitAuthID

public 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

public void setSandTransmitAuthID(long ID)

Set the ID of the messaging user for authorization purposes.

getSandTransmissionCount

public 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

public void setSandTransmissionCount(int val)

Set the sandTransmissionCount of the message for tracking purposes.