org.sandev.basics.structs
Interface SandInstanceMessage

All Superinterfaces:

SandMessage

All Known Subinterfaces:

AuthUser, NodeInstance, SandPersistMessage, SandStructMessage

All Known Implementing Classes:

AuthorizerNodeInstance, AuthWrapper, BaseUser, CacheAction, CacheManagerNodeInstance, CallResponse, Configuration, DataImportExport, DataManagerNodeInstance, DeliveryStream, IODeclCall, IODeclReceive, IODeclSend, IODeclSubscribe, MessageDescription, MessageDriverNodeInstance, Ping, ReceiveReturn, SandAttrVal, ServerDeclaration, Stats, TestScript, 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

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 the editor's perspective, what needs to be done is clear, but how to actually make the change is not. Java provides the reflection mechanism, but reflection is cumbersome. It also makes the access harder to read and maintain. This mechanism is intended to provide a faster and easier way.

Note that this general modification mechanism is not intended for general use. Wherever possible, the standard access methods should be used instead.

Field Summary

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_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[]	getDisplayFields() Get default description values.
java.lang.String[]	getDisplayValues() Returns the values corresponding to the declared display fields.

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

getCollectionMessage, getQueryMessage, getShortName, getStructMessage, getUpdateMessage, isEquivalent

Field Detail

GENMOD_ACTION_INSERT

public 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

public 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

public 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

public 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

public 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

public 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

public 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

public 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

public 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

public static final int FIELDFLAG_STRINGPERSIST

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

See Also:

Constant Field Values

FIELDFLAG_BINARY

public static final int FIELDFLAG_BINARY

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

See Also:

Constant Field Values

FIELDCHECK_UNKNOWNVAL

public static final java.lang.String FIELDCHECK_UNKNOWNVAL

An unknown value for an enumint type

See Also:

Constant Field Values

FIELDCHECK_INVALIDVAL

public static final java.lang.String FIELDCHECK_INVALIDVAL

Declared invalid value

See Also:

Constant Field Values

FIELDCHECK_NOTINRANGE

public static final java.lang.String FIELDCHECK_NOTINRANGE

Value is outside the range specified

See Also:

Constant Field Values

FIELDCHECK_NOTAREF

public static final java.lang.String FIELDCHECK_NOTAREF

Value is not a valid reference ID

See Also:

Constant Field Values

FIELDCHECK_STRINGOVER

public static final java.lang.String FIELDCHECK_STRINGOVER

This String value is too long

See Also:

Constant Field Values

FIELDCHECK_NULLARRAY

public static final java.lang.String FIELDCHECK_NULLARRAY

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

See Also:

Constant Field Values

Method Detail

generalModifier

public 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

public 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

public 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.

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

public java.lang.String[] getDisplayFields()

Get default description values. If this struct has @display and @displayadd declarations, then return an array of the fields used for those declarations.

getDisplayValues

public java.lang.String[] getDisplayValues()

Returns the values corresponding to the declared display fields.

cloneMessage

public SandInstanceMessage cloneMessage()

Return a deep copy of this message.

copyFieldValue

public 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

public java.lang.String[] getAllFields()

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

defaultField

public void defaultField(java.lang.String fieldname)

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

convertToSuperstructClass

public 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

public 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

public 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

public 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

public boolean fieldsValid()

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