org.sandev.generator.tags
Class FieldTagFlags

java.lang.Object
  org.sandev.generator.tags.AbstractSandBaseTag
      org.sandev.generator.tags.AbstractSandFieldTag
          org.sandev.generator.tags.FieldTagFlags

All Implemented Interfaces:

com.sun.tools.doclets.Taglet

public class FieldTagFlags

extends AbstractSandFieldTag

Handle @sand.flags field declarations.

Declares zero or more field flags as being set. The purpose is to provide all the utility functions that don't require parameters. This keeps the total number of tags less daunting and hides the more esoteric processing.

Some of these flags (those which need to be queried at runtime) are exposed through constants defined in the SandInstanceMessage interface.

You can specify zero or more of the following flag values:

• isbool
• hasbool
• noecho
• unique
• internal
• encrypt
• obfuscate
• stringpersist
• stack
• dynamicselect
• binary
• treeparent/treechildren
• norefdisplay

Comments are not supported for this tag.

isbool:

Provides support for "is" style boolean logic from enumint values. For example, consider a situation where an initial data model requires a boolean crisisStatusOnFire data member and an associated isCrisisStatusOnFire() method:

To model this situation using SAND, we declare a struct field int crisisStatus with the following declarations:

@sand.enumint 0 ALLCLEAR "AllClear"
@sand.enumint 1 ONFIRE "OnFire"
@sand.enumint 2 UNKNOWN "Unknown"
@sand.default 2
@sand.flags isbool

This will cause the following methods to be generated in the message:

boolean isCrisisStatusAllClear()
boolean isCrisisStatusOnFire()
boolean isCrisisStatusUnknown()

which provides equivalent functionality while providing for ternary logic and other possible data values.

The isbool flag can also be referenced in persistence processing, UI mapping, and other generators.

hasbool:

Provides support for "has" style boolean logic from enumint values. This is equivalent to isbool except the methods start with "has" rather than "is". For example consider a struct field int developmentSpeed with the following declararations:

@sand.enumint 0 SLOW "slow"
@sand.enumint 1 FAST "fast"
@sand.enumint 2 UNKNOWN "unknown"
@sand.default 2
@sand.flags hasbool

This will cause the following methods to be generated in the message:

boolean hasDevelopmentSpeedSlow()
boolean hasDevelopmentSpeedFast()
boolean hasDevelopmentSpeedUnknown()

noecho:

Declares that the value of this field should not be displayed in a user interface. Typically things like passwords are flagged as noecho so their values get replaced with asterisks or the equivalent when being entered or displayed.

Credit card numbers are typically partially filtered as part of authorization processing and are not declared as noecho.

unique:

Declares that the value of this field must be globally unique. If unique is used in a non-persistent struct, then it may not be enforced in any way. Within a persistent struct, unique declares an alternate key, however the primary key is always the uniqueID.

internal:

At the struct level, if you want to expose a struct for messaging from an external source, you simply publish the corresponding schema and set up a node instance to handle incoming messages. If you don't do these steps, then the struct definition has limited scope.

If you want to externally expose some, but not all of the fields of a struct, the "correct" solution is to expose a base struct and then add the additional fields for internal processing into a struct that extends the base. But that can be a bit overkill sometimes. By flagging a field as internal, you essentially hide it from the external interface definition.

If you end up marking more than a couple of fields internal, you should probably consider separating out your struct definitions. Also, you need to be careful that the default value is valid, or the external messaging won't be able to create a valid instance from the published interface.

encrypt:

Declares that this field should be immediately encrypted at the earliest possible point of receipt of plaintext (typically in the UI), and left encrypted after that. Since the system is encrypting the data, the plaintext can be recovered, but will not typically be visible during normal processing by trusted nodes.

The encrypt flag is outside the scope of SAND security and authorization processing. It is inadequate as a security approach and is provided only for implementation flexibility.

Be sure the maximum length of the field is adequate to hold the resulting ciphertext.

obfuscate:

Declares that this field should be immediately encrypted at the earliest possible point of receipt of plaintext, such that the plaintext cannot be recovered. Subsequent plaintext can be encrypted and compared for equality with previous ciphertext but that's it.

This field is typically used for very high security systems where only the end user should ever know the plaintext of a password or similar field.

stringpersist:

Indicates this field should be converted to a single String value for persistence, using the conversion utility configured for the DataManager. Using stringpersist allows a persistent struct to directly contain dependent objects (or arrays of dependent objects) which is otherwise not possible for a persistent struct.

A dependent object declared via the stringpersist mechanism cannot itself be persistent, nor can it be authorization filtered, deferred for load, cached or shared. The dependent object data will probably not be easily accessible via the underlying database either. This mechanism should only be used in cases where the child is truly dependent, and cannot reasonably exist on its own. For example a contained SandAttrVal[].

stack:

Indicates this array field functions as a stack. Basically this means that push and pop mutators should be available in addition to the standard getter/setter methods.

dynamicselect:

Indicates that when editing, possible values for this field will be determined by the UIFormOwner. This allows for dynamic selection values based on the value of another field for example.

This flag may be used in conjunction with other flags/tags, but takes precedence in the display.

binary:

Indicates that the field (typically a string) is an encoded binary value. This flag is normally used in conjunction with a custom UIFormAdaptor that knows how to provide viewing and editing capabilities for the binary type, possibly in conjunction with a metatype declaration.

treeparent/treechildren:

The treeparent tag indicates that the field is a back reference to the parent of this message in a tree of messages. It triggers the generation of a getTreeParent method which returns an instance of the message class. The treechild tag indicates that the field is an array of references to children. It triggers the generation of a getTreeChildren method which returns an array of instances of this message type.

norefdisplay:

The norefdisplay tag is applied to a reference field to indicate that display processing does not need to display any information about the referenced object. For example consider a batch process instance that contains an array of references to many other objects: A display will normally resolve each reference to provide summary information, which is very useful in traversing a relatively small number of reference links, but the query overhead can become overwhelming for large numbers of references. This flag provides an indication that retrieving the additional summary information should be skipped.

Field Summary

static java.lang.String	CORENAME The core name of this tag.
protected java.lang.String	fieldName The name of the field which had these flag associations.
protected boolean	flagBinary Flag for binary
protected boolean	flagDynamicSelect Flag for dynamicselect
protected boolean	flagEncrypt Flag for encrypt
protected boolean	flagHasbool Flag for hasbool
protected boolean	flagInternal Flag for internal
protected boolean	flagIsbool Flag for isbool
protected boolean	flagNoecho Flag for noecho
protected boolean	flagNorefdisplay Flag for flagNorefdisplay
protected boolean	flagObfuscate Flag for obfuscate
protected boolean	flagStack Flag for stack
protected boolean	flagStringpersist Flag for stringpersist
protected boolean	flagTreeChildren Flag for treechildren
protected boolean	flagTreeParent Flag for treeparent
protected boolean	flagUnique Flag for unique
static java.lang.String	TAGNAME Our fixed name, used for hash lookup and text parsing.

Fields inherited from class org.sandev.generator.tags.AbstractSandBaseTag

PREFIX

Constructor Summary

FieldTagFlags()

Method Summary

static boolean	exists(com.sun.javadoc.FieldDoc fd) Returns true if the given field contains this tag, false otherwise.
java.lang.String	getFieldName() accessor for fieldName
static FieldTagFlags	getFieldTagFlags(com.sun.javadoc.FieldDoc fd) Factory method for retrieving a new instance given a FieldDoc.
java.lang.String	getName() Return our tag name
boolean	hasFlagBinary() accessor for flagBinary
boolean	hasFlagDynamicSelect() accessor for flagDynamicSelect
boolean	hasFlagEncrypt() accessor for flagEncrypt
boolean	hasFlagHasbool() accessor for flagHasbool
boolean	hasFlagInternal() accessor for flagInternal
boolean	hasFlagIsbool() accessor for flagIsbool
boolean	hasFlagNoecho() accessor for flagNoecho
boolean	hasFlagNorefdisplay() accessor for flagNorefdisplay
boolean	hasFlagObfuscate() accessor for flagObfuscate
boolean	hasFlagStack() accessor for flagStack
boolean	hasFlagStringpersist() accessor for flagStringpersist
boolean	hasFlagTreeChildren() accessor for flagTreeChildren
boolean	hasFlagTreeParent() accessor for flagTreeParent
boolean	hasFlagUnique() accessor for flagUnique
void	init(com.sun.javadoc.Tag tag) Initialize this instance from the tag information.
static void	register(java.util.Map tagletMap) Registers this taglet when triggered by the taglet declaration being loaded in as part of the build.
void	setFieldName(java.lang.String val) mutator for fieldName
void	setFlagBinary(boolean val) mutator for flagBinary
void	setFlagDynamicSelect(boolean val) mutator for flagDynamicSelect
void	setFlagEncrypt(boolean val) mutator for flagEncrypt
void	setFlagHasbool(boolean val) mutator for flagHasbool
void	setFlagInternal(boolean val) mutator for flagInternal
void	setFlagIsbool(boolean val) mutator for flagIsbool
void	setFlagNoecho(boolean val) mutator for flagNoecho
void	setFlagNorefdisplay(boolean val) mutator for flagNorefdisplay
void	setFlagObfuscate(boolean val) mutator for flagObfuscate
void	setFlagStack(boolean val) mutator for flagStack
void	setFlagStringpersist(boolean val) mutator for flagStringpersist
void	setFlagTreeChildren(boolean val) mutator for flagTreeChildren
void	setFlagTreeParent(boolean val) mutator for flagTreeParent
void	setFlagUnique(boolean val) mutator for flagUnique
java.lang.String	toString(com.sun.javadoc.Tag tag) Return a documentation description of this tag.
java.lang.String	toString(com.sun.javadoc.Tag[] tags) Return the documentation text for when several of these tags are present

Methods inherited from class org.sandev.generator.tags.AbstractSandFieldTag

inField

Methods inherited from class org.sandev.generator.tags.AbstractSandBaseTag

inConstructor, inMethod, inOverview, inPackage, inType, isInlineTag, registerHelper

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

CORENAME

public static final java.lang.String CORENAME

The core name of this tag.

See Also:

Constant Field Values

flagIsbool

protected boolean flagIsbool

Flag for isbool

flagHasbool

protected boolean flagHasbool

Flag for hasbool

flagNoecho

protected boolean flagNoecho

Flag for noecho

flagUnique

protected boolean flagUnique

Flag for unique

flagInternal

protected boolean flagInternal

Flag for internal

flagEncrypt

protected boolean flagEncrypt

Flag for encrypt

flagObfuscate

protected boolean flagObfuscate

Flag for obfuscate

flagStringpersist

protected boolean flagStringpersist

Flag for stringpersist

flagStack

protected boolean flagStack

Flag for stack

flagDynamicSelect

protected boolean flagDynamicSelect

Flag for dynamicselect

flagBinary

protected boolean flagBinary

Flag for binary

flagTreeParent

protected boolean flagTreeParent

Flag for treeparent

flagTreeChildren

protected boolean flagTreeChildren

Flag for treechildren

flagNorefdisplay

protected boolean flagNorefdisplay

Flag for flagNorefdisplay

fieldName

protected java.lang.String fieldName

The name of the field which had these flag associations. Note that field information is only available when this instance had access to the FieldDoc. If you initialize an instance of this class from only the tags (such as in a taglet), then this information is not available.

TAGNAME

public static final java.lang.String TAGNAME

Our fixed name, used for hash lookup and text parsing.

See Also:

Constant Field Values

Constructor Detail

FieldTagFlags

public FieldTagFlags()

Method Detail

hasFlagIsbool

public boolean hasFlagIsbool()

accessor for flagIsbool

setFlagIsbool

public void setFlagIsbool(boolean val)

mutator for flagIsbool

hasFlagHasbool

public boolean hasFlagHasbool()

accessor for flagHasbool

setFlagHasbool

public void setFlagHasbool(boolean val)

mutator for flagHasbool

hasFlagNoecho

public boolean hasFlagNoecho()

accessor for flagNoecho

setFlagNoecho

public void setFlagNoecho(boolean val)

mutator for flagNoecho

hasFlagUnique

public boolean hasFlagUnique()

accessor for flagUnique

setFlagUnique

public void setFlagUnique(boolean val)

mutator for flagUnique

hasFlagInternal

public boolean hasFlagInternal()

accessor for flagInternal

setFlagInternal

public void setFlagInternal(boolean val)

mutator for flagInternal

hasFlagEncrypt

public boolean hasFlagEncrypt()

accessor for flagEncrypt

setFlagEncrypt

public void setFlagEncrypt(boolean val)

mutator for flagEncrypt

hasFlagObfuscate

public boolean hasFlagObfuscate()

accessor for flagObfuscate

setFlagObfuscate

public void setFlagObfuscate(boolean val)

mutator for flagObfuscate

hasFlagStringpersist

public boolean hasFlagStringpersist()

accessor for flagStringpersist

setFlagStringpersist

public void setFlagStringpersist(boolean val)

mutator for flagStringpersist

hasFlagStack

public boolean hasFlagStack()

accessor for flagStack

setFlagStack

public void setFlagStack(boolean val)

mutator for flagStack

hasFlagDynamicSelect

public boolean hasFlagDynamicSelect()

accessor for flagDynamicSelect

setFlagDynamicSelect

public void setFlagDynamicSelect(boolean val)

mutator for flagDynamicSelect

hasFlagBinary

public boolean hasFlagBinary()

accessor for flagBinary

setFlagBinary

public void setFlagBinary(boolean val)

mutator for flagBinary

hasFlagTreeParent

public boolean hasFlagTreeParent()

accessor for flagTreeParent

setFlagTreeParent

public void setFlagTreeParent(boolean val)

mutator for flagTreeParent

hasFlagTreeChildren

public boolean hasFlagTreeChildren()

accessor for flagTreeChildren

setFlagTreeChildren

public void setFlagTreeChildren(boolean val)

mutator for flagTreeChildren

hasFlagNorefdisplay

public boolean hasFlagNorefdisplay()

accessor for flagNorefdisplay

setFlagNorefdisplay

public void setFlagNorefdisplay(boolean val)

mutator for flagNorefdisplay

getFieldName

public java.lang.String getFieldName()

accessor for fieldName

setFieldName

public void setFieldName(java.lang.String val)

mutator for fieldName

init

public void init(com.sun.javadoc.Tag tag)

Initialize this instance from the tag information.

getName

public java.lang.String getName()

Return our tag name

register

public static void register(java.util.Map tagletMap)

Registers this taglet when triggered by the taglet declaration being loaded in as part of the build.

toString

public java.lang.String toString(com.sun.javadoc.Tag tag)

Return a documentation description of this tag.

Specified by:

toString in interface com.sun.tools.doclets.Taglet

Specified by:

toString in class AbstractSandBaseTag

Parameters:

tag - the Tag representation of this custom tag.

toString

public java.lang.String toString(com.sun.javadoc.Tag[] tags)

Return the documentation text for when several of these tags are present

Specified by:

toString in interface com.sun.tools.doclets.Taglet

Specified by:

toString in class AbstractSandBaseTag

Parameters:

tags - the array of Tags representing of this custom tag.

getFieldTagFlags

public static FieldTagFlags getFieldTagFlags(com.sun.javadoc.FieldDoc fd)

Factory method for retrieving a new instance given a FieldDoc. Returns an initialized instance if the tag was found, or an instance with all flags false if no flags were specified.

exists

public static boolean exists(com.sun.javadoc.FieldDoc fd)

Returns true if the given field contains this tag, false otherwise.