org.sandev.basics.structs
Interface SandInstanceMessage

All Superinterfaces:

SandMessage

All Known Subinterfaces:

AuthUser, BaseUserInterface, IODeclBaseInterface, NodeInstance, SandPersistMessage, SandStructMessage

All Known Implementing Classes:

AggregateUpdate, AuthorizerNodeInstance, AuthWrapper, BaseUser, BaseUserEmail, CacheAction, CacheItemSummary, CacheManagerNodeInstance, CacheMemSummary, CacheStats, Configuration, DataImportExport, DataManagerNodeInstance, ErrorInfo, IODeclBase, IODeclCall, IODeclReceive, IODeclSend, IODeclSubscribe, MessageDescription, MessageDriverNodeInstance, Ping, SandAttrVal, ServerDeclaration, Stats, StringValue, TestAction, TestCondition, TestNodeParamChange, TestRunStatus, TestScript, TestStep, UIDisplayDirective, UIFormContext, UIFormControl, UIFormInitializer, UIFormQuery

public interface SandInstanceMessage
extends SandMessage

Identifies messages that are data instances, as opposed to data actions or collections.

SandMessage

SandInstanceMessage
SandStructMessage
SandPersistMessage
NodeInstance
SandTransmitMessage
SandVerbMessage
SandUpdateMessage
SandQueryMessage
SandCollectionMessage

In order to support editors and other interfaces that work with SandStructMessage instances in a declarative form, the interface provides general modification capabilities similar to those found with reflection. In a typical situation, an editing interface will have found or created a new object instance, which must now be placed into the parent (either as a singular reference or as an array element).

From an editing perspective, what needs to be done is clear, but how to actually make the change is not. Java provides the reflection mechanism, but reflection doesn't provide easy access to the additional declarative information so that capability is provided here.

Note that this general modification mechanism is not intended for general use. When possible, the standard access methods should be used instead, since they are faster and allow for compile time type checking.

Field Summary

static java.lang.String	FIELDCHECK_EMPTYSTRINGPRINTVAL Error messages involving empty string values tend to look like mistakes because the value prints out as a space.
static java.lang.String	FIELDCHECK_INVALIDVAL Declared invalid value
static java.lang.String	FIELDCHECK_NOTAREF Value is not a valid reference ID
static java.lang.String	FIELDCHECK_NOTINRANGE Value is outside the range specified
static java.lang.String	FIELDCHECK_NULLARRAY Arrays can't be null, they can only be empty
static java.lang.String	FIELDCHECK_STRINGOVER This String value is too long
static java.lang.String	FIELDCHECK_UNKNOWNVAL An unknown value for an enumint type
static int	FIELDFLAG_BINARY Constant representing the "binary" field flag.
static int	FIELDFLAG_ENCRYPT Constant representing the "encrypt" field flag.
static int	FIELDFLAG_INTERNAL Constant representing the "internal" field flag.
static int	FIELDFLAG_NOECHO Constant representing the "noecho" field flag.
static int	FIELDFLAG_OBFUSCATE Constant representing the "obfuscate" field flag.
static int	FIELDFLAG_STRINGPERSIST Constant representing the "stringpersist" field flag.
static int	FIELDFLAG_SUMMARYEDIT Constant representing the "summaryedit" field flag.
static int	FIELDFLAG_UNIQUE Constant representing the "unique" field flag.
static int	GENMOD_ACTION_APPEND Indicates that we want to add a new value to the end of an array.
static int	GENMOD_ACTION_INSERT Indicates that we want to insert a new value into an existing array.
static int	GENMOD_ACTION_REMOVE Indicates that we want to remove the current value.
static int	GENMOD_ACTION_SET Indicates that we want to set the specified value.

Method Summary

SandInstanceMessage	cloneMessage() Return a deep copy of this message.
SandInstanceMessage	convertToSuperstructClass() If this class was generated from a struct which extends another struct, then this method converts an instance of this class to an instance of the message class of the superstruct.
void	copyFieldValue(java.lang.String fieldName, SandInstanceMessage other) Downcast the other message and copy the value of the specified field into this instance.
java.lang.String	debugDump(java.lang.String prefix) Returns a dump of this object.
void	defaultField(java.lang.String fieldname) Set the specified field to its default value.
boolean	fieldHasFlag(java.lang.String fieldname, int fieldflag) Return true if the named field declares the indicated flag, false otherwise.
boolean	fieldsValid() If all fields have valid values, return true.
SandAttrVal[]	fieldValidate(SandAttrVal[] checkFields) Return a collection of fieldname-status pairs.
java.lang.Object	generalAccessor(java.lang.String fieldspec) Given a field specification, return the value.
SandAttrVal	generalDereference(java.lang.String fieldspec) Given a field specification, return the reference field name and reference field value.
void	generalModifier(int action, java.lang.String field, int index, java.lang.Object val) Perform the general modification action specified.
java.lang.String[]	getAllFields() Return all the fields declared for this class.
java.lang.String[]	getContainedMessageFields() Return all the contained message fields for this class.
java.lang.String[]	getDisplayFields() Get the summary display field names as declared for the struct.
java.lang.String[]	getDisplayFieldsPrint() Get the print names of the summary display field names as declared for the struct.
java.lang.String	getDisplayID() Returns a unique instance identifier as a string.
java.lang.String[]	getDisplayValues() Returns the values corresponding to the declared display fields.
java.lang.String	getLayoutXML() Returns the fieldlayout XML for this instance if available, null otherwise.
java.lang.String	getPrintnameForField(java.lang.String fieldname) Return the declared printname for the given field, or the given fieldname if no print value is declared.

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

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

Field Detail

GENMOD_ACTION_INSERT

static final int GENMOD_ACTION_INSERT

Indicates that we want to insert a new value into an existing array. To prepend an element to an array, specify an index of zero. You cannot specify an index larger than the last element in the array.

See Also:

Constant Field Values

GENMOD_ACTION_APPEND

static final int GENMOD_ACTION_APPEND

Indicates that we want to add a new value to the end of an array.

See Also:

Constant Field Values

GENMOD_ACTION_SET

static final int GENMOD_ACTION_SET

Indicates that we want to set the specified value. If the field is an array, then we set the element at the index specified. It is an error to specify an index which does not exist. If this is not an array, then the index is ignored and the field is set.

The value must be compatible with the field.

See Also:

Constant Field Values

GENMOD_ACTION_REMOVE

static final int GENMOD_ACTION_REMOVE

Indicates that we want to remove the current value. If the field is an array, then we remove the element at the index specified. It is an error to specify an index which does not exist. If this is not an array, then the field is set to its default value.

See Also:

Constant Field Values

FIELDFLAG_NOECHO

static final int FIELDFLAG_NOECHO

Constant representing the "noecho" field flag. This is passed to the get*Flag method declared for each field, which then returns true or false depending on if the noecho flag was declared for the field. See FieldTagFlags for details.

See Also:

Constant Field Values

FIELDFLAG_UNIQUE

static final int FIELDFLAG_UNIQUE

Constant representing the "unique" field flag. This is passed to the get*Flag method declared for each field, which then returns true or false depending on if the unique flag was declared for the field. See FieldTagFlags for details.

See Also:

Constant Field Values

FIELDFLAG_INTERNAL

static final int FIELDFLAG_INTERNAL

Constant representing the "internal" field flag. This is passed to the get*Flag method declared for each field, which then returns true or false depending on if the internal flag was declared for the field. See FieldTagFlags for details.

See Also:

Constant Field Values

FIELDFLAG_ENCRYPT

static final int FIELDFLAG_ENCRYPT

Constant representing the "encrypt" field flag. This is passed to the get*Flag method declared for each field, which then returns true or false depending on if the encrypt flag was declared for the field. See FieldTagFlags for details.

See Also:

Constant Field Values

FIELDFLAG_OBFUSCATE

static final int FIELDFLAG_OBFUSCATE

Constant representing the "obfuscate" field flag. This is passed to the get*Flag method declared for each field, which then returns true or false depending on if the obfuscate flag was declared for the field. See FieldTagFlags for details.

See Also:

Constant Field Values

FIELDFLAG_STRINGPERSIST

static final int FIELDFLAG_STRINGPERSIST

Constant representing the "stringpersist" field flag. See FieldTagFlags for details.

See Also:

Constant Field Values

FIELDFLAG_BINARY

static final int FIELDFLAG_BINARY

Constant representing the "binary" field flag. See FieldTagFlags for details.

See Also:

Constant Field Values

FIELDFLAG_SUMMARYEDIT

static final int FIELDFLAG_SUMMARYEDIT

Constant representing the "summaryedit" field flag. See FieldTagFlags for details.

See Also:

Constant Field Values

FIELDCHECK_UNKNOWNVAL

static final java.lang.String FIELDCHECK_UNKNOWNVAL

An unknown value for an enumint type

See Also:

Constant Field Values

FIELDCHECK_INVALIDVAL

static final java.lang.String FIELDCHECK_INVALIDVAL

Declared invalid value

See Also:

Constant Field Values

FIELDCHECK_NOTINRANGE

static final java.lang.String FIELDCHECK_NOTINRANGE

Value is outside the range specified

See Also:

Constant Field Values

FIELDCHECK_NOTAREF

static final java.lang.String FIELDCHECK_NOTAREF

Value is not a valid reference ID

See Also:

Constant Field Values

FIELDCHECK_STRINGOVER

static final java.lang.String FIELDCHECK_STRINGOVER

This String value is too long

See Also:

Constant Field Values

FIELDCHECK_NULLARRAY

static final java.lang.String FIELDCHECK_NULLARRAY

Arrays can't be null, they can only be empty

See Also:

Constant Field Values

FIELDCHECK_EMPTYSTRINGPRINTVAL

static final java.lang.String FIELDCHECK_EMPTYSTRINGPRINTVAL

Error messages involving empty string values tend to look like mistakes because the value prints out as a space. This text is used as a substitute to make the error text readable.

See Also:

Constant Field Values

Method Detail

generalModifier

void generalModifier(int action,
                     java.lang.String field,
                     int index,
                     java.lang.Object val)
                     throws SandException

Perform the general modification action specified. Parameters:

• action: one of the GENMOD_ACTION* constants.
• field: the name of the field to be operated on.
• index: if the field is an array, then this specifies the array index to be operated on. Otherwise this parameter is ignored (by convention -1 is passed).
• val: the value for the operation. If the field is a basic type, then this is the "boxed" object (eg Integer, Long, Double), or the value as a String. If the field is a reference field, this may also be the object to be referenced.

Notes on use:

• On GENMOD_ACTION_INSERT, val is inserted in front of the index specified. On GENMOD_ACTION_APPEND index is ignored.
• On GENMOD_ACTION_REMOVE val is ignored.

An exception is thrown if anything goes wrong.

Throws:

SandException

generalDereference

SandAttrVal generalDereference(java.lang.String fieldspec)

Given a field specification, return the reference field name and reference field value. Return null if the field cannot be found. So for example this method might return "uniqueID"|"43" for a long reference, or "someField"|"somevalue" for a String reference.

To support access to array fields, this method also accepts field specifications with the array index specified. So for example if you want to retrieve the third element from an array field called myrefs, you would specify myrefs[2] as the fieldspec.

This method is intended for use with UI programming and other general object access situations where normal access is difficult due to generalized interfaces.

generalAccessor

java.lang.Object generalAccessor(java.lang.String fieldspec)

Given a field specification, return the value. Return null if the field cannot be found, or if the value is null.

To support access to array fields, this method also accepts field specifications with the array index specified. So for example if you want to retrieve the third element from an array called myobjects, you would specify myobjects[2] as the fieldspec. Specifying an array index of -1 for a contained struct array will return a new default instance of the array element object.

This method is intended for use with UI programming and other general object access situations where normal access is difficult due to generalized interfaces.

getDisplayFields

java.lang.String[] getDisplayFields()

Get the summary display field names as declared for the struct.

getDisplayFieldsPrint

java.lang.String[] getDisplayFieldsPrint()

Get the print names of the summary display field names as declared for the struct. Returns the print names for the fields returned from getDisplayFields, the two arrays have identical length and ordering for lookup and conversion purposes.

getDisplayValues

java.lang.String[] getDisplayValues()

Returns the values corresponding to the declared display fields.

getLayoutXML

java.lang.String getLayoutXML()

Returns the fieldlayout XML for this instance if available, null otherwise. Rendering can use this value to create a display matching the layout, or create a default display from the fields and values.

cloneMessage

SandInstanceMessage cloneMessage()

Return a deep copy of this message.

copyFieldValue

void copyFieldValue(java.lang.String fieldName,
                    SandInstanceMessage other)

Downcast the other message and copy the value of the specified field into this instance. The other instance must be of the same class.

getAllFields

java.lang.String[] getAllFields()

Return all the fields declared for this class. This includes fields inherited from other structs.

getContainedMessageFields

java.lang.String[] getContainedMessageFields()

Return all the contained message fields for this class. Includes all fields inherited from other structs. This information is useful for dealing with serialized formats where contained messages get written out inline.

defaultField

void defaultField(java.lang.String fieldname)

Set the specified field to its default value. Useful for filtering data based on authorization.

getPrintnameForField

java.lang.String getPrintnameForField(java.lang.String fieldname)

Return the declared printname for the given field, or the given fieldname if no print value is declared.

convertToSuperstructClass

SandInstanceMessage convertToSuperstructClass()

If this class was generated from a struct which extends another struct, then this method converts an instance of this class to an instance of the message class of the superstruct. For example if ResourceStruct extends ReaderStruct, calling this method on a Resource would return a Reader.

The return value is a new object instance with fields initialized appropriately, or null if this is a root level struct.

debugDump

java.lang.String debugDump(java.lang.String prefix)

Returns a dump of this object. This dumps out multiple lines with one field per line. If a prefix is specified it is prepended to each line. This is to support debugging or log output where it is helpful see what the instance is composed of.

fieldHasFlag

boolean fieldHasFlag(java.lang.String fieldname,
                     int fieldflag)

Return true if the named field declares the indicated flag, false otherwise. The FIELDFLAG* constants define the supported fieldflag values that can be queried.

fieldValidate

SandAttrVal[] fieldValidate(SandAttrVal[] checkFields)

Return a collection of fieldname-status pairs. The field name is the name as it is declared in the struct definition. The status is one of the constant FIELDCHECK_* string values defined here or the empty string "" if the field has a valid value. If checkFields is null or empty, then the returned array will contain all the fields.

While the FIELDCHECK keys are meant to be human readable, they are also constant strings and can be used to look up localized or other custom text within a UI. This method is in support of level 2 message validation, where the levels are:

1. Raw input conversion: converting raw character input into actual field types.
2. Field validation: making sure the field value is valid given the declarations for the field.
3. Inter-field validation and business logic: Making sure the values of the fields make sense together.
4. Persistent state validation: validation of uniqueness constraints and other persistent information.

Other validation methods may leverage the same SandAttrVal[] structure, adding their own status constants. This method supports at least the checking provided by the SAND field tags. The FIELDCHECK_* constants are not intended to be full error descriptions. Level 1 validation will already need to provide information about what kinds of input is valid, so it would be redundent to put it here as well. This method principally enforces the contract between validation levels 1 and 3.

fieldsValid

boolean fieldsValid()

If all fields have valid values, return true. Otherwise return false.

getDisplayID

java.lang.String getDisplayID()

Returns a unique instance identifier as a string. For a persistent class this returns the uniqueID as a string. For a non-persistent class this returns the value of whichever field is tagged as the displayID, otherwise it returns the empty string.