org.sandev.generator.tags
Class StructTagFieldlayout

java.lang.Object
  org.sandev.generator.tags.AbstractSandBaseTag
      org.sandev.generator.tags.AbstractSandClassTag
          org.sandev.generator.tags.AbstractSandStructTag
              org.sandev.generator.tags.StructTagFieldlayout

All Implemented Interfaces:

com.sun.tools.doclets.Taglet, java.util.Comparator

public class StructTagFieldlayout
extends AbstractSandStructTag
implements java.util.Comparator

Handle the @sand.fieldlayout declaration.

Declares a general layout for the fields in this struct using an XML notation of the general form

 <fieldlayout>
     <layrow><fieldA/><fieldB/></layrow>
     <layrow><fieldC/></layrow>
 </fieldlayout>
 

will cause the default display to have fieldA and fieldB in the first row, fieldC in the second row, and any remaining fields authorized for display after that using the default layout. The default layout is one field per row (field + value = 1 row).

Implementation of attributes should be supported when practical. The defined attributes are:

• overunder applies to a row or the fieldlayout as a whole specifying that the value should be displayed below the field name. Any row containing a large text field or an array is automatically overrunder in the display.
• colspan is allowed for a field.
• width/height in chars for a textarea field
• notitle means just display the field value without the accompanying field name.
• valprefix specifies text to be inserted immediately before the value display. For example a currency symbol.
• valsuffix specifies text to be inserted immediately ater the value display. For example a units designator.
• tab sets the tab index for the given field. If the field requires more than one imput control widget, then all inputs will have the specified tab index. See tabbing in HTML forms http://www.w3.org/TR/html4/interact/forms.html#h-17.11.1 for more information.

A fieldname of <blank/> can be used as a column value placeholder.

The valprefix and valsuffix tags may be extended to allow for dynamic values retrieved via call to any static method accepting the UIFormAdaptorCallback reference, locale, message instance and field name. This is done by specifying $callback$ followed by an assignment operator followed by the fully qualified name of the method to be called. So for example: valprefix="$callback$=org.sandev.basic.SomeUtil.prefixMaker" would signal that the static prefixMaker method of the SomeUtil class should be called to retrieve the prefix value.

Unfortunately we do not have access to an XML parser at build time.

Field Summary

protected java.lang.String	classname The name of the class that declared this layout.
static java.lang.String	CORENAME The core name of this tag.
protected java.lang.String	layoutXML The layout declaration XML.
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

StructTagFieldlayout()

Method Summary

int	compare(java.lang.Object obj1, java.lang.Object obj2) Compare two fields based on their declared layout ordering.
int	convertToInt(java.lang.String strval) Convert the given string to an integer and return it.
void	debug(java.lang.String text) Debug output utility.
boolean	endsRow(java.lang.String fieldname) Return true if the given field ends a row, false otherwise.
static boolean	exists(com.sun.javadoc.ClassDoc cd) Return true if the give struct contains this tag, false otherwise.
int	getAttrIntValue(char[] chars, int index, java.lang.String attrname) Return the value of the specified attribute as an integer.
java.lang.String	getAttrStringValue(char[] chars, int index, java.lang.String attrname) Return the value of the given attribute or null if not available.
java.lang.String	getClassname() accessor for classname
int	getFieldAttrIntVal(java.lang.String fieldname, java.lang.String attrname, int failval) Return the value of the attribute specified for the given fieldname or the failval if the attribute is not specified or cannot be converted to an int.
java.lang.String	getFieldAttrVal(java.lang.String fieldname, java.lang.String attrname) Return the value of the given attribute of the given field, or null if not found.
int	getFieldStartIndex(char[] chars, java.lang.String fieldname) Return the starting index for this attribute declaration.
static StructTagFieldlayout	getInstance(com.sun.javadoc.ClassDoc cd) Factory method for retrieving a new instance given a ClassDoc.
java.lang.String	getLayoutXML() accessor for layoutXML
java.lang.String	getLayoutXMLNoSpace() Remove extraneous formatting space from the layoutXML and return the result.
int	getMaxCols() Return the maximum number of columns used by the declared layout.
java.lang.String	getName() Return our tag name
java.lang.String	getTagString(char[] chars, int index) Read from the given index to the the closing tag bracket and return the result.
boolean	hasAttr(char[] chars, int index, java.lang.String attrname) Read forward from the given index searching for the given attrname.
boolean	hasField(java.lang.String fieldname) Return true if the given layout includes the given fieldname, false otherwise.
boolean	hasFieldAttr(java.lang.String fieldname, java.lang.String attrname) Return true if the given field has the given attribute specified, false otherwise.
boolean	hasFieldlayout() Returns true if there is a fieldlayout defined, false otherwise.
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	setClassname(java.lang.String classname) mutator for classname
void	setLayoutXML(java.lang.String layoutXML) mutator for layoutXML
boolean	sharesRow(java.lang.String fieldname) Return true if the given field shares a row with another field, false otherwise.
void	sort(com.sun.javadoc.FieldDoc[] fields) Sort the given field array based on the declared field layout.
boolean	startsRow(java.lang.String fieldname) Return true if the given field begins a row, false otherwise.
boolean	tokenMatch(char[] chars, int index, char[] tokchars) Return true if the characters from the given index match the characters of the token string.
boolean	tokenMatch(char[] chars, int index, java.lang.String token) Return true if the characters from the given index match the characters of the token string.
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 for when several of these tags are present.

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

inType

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

inConstructor, inField, inMethod, inOverview, inPackage, isInlineTag, registerHelper

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.util.Comparator

equals

Field Detail

CORENAME

public static final java.lang.String CORENAME

The core name of this tag.

See Also:

Constant Field Values

layoutXML

protected java.lang.String layoutXML

The layout declaration XML.

classname

protected java.lang.String classname

The name of the class that declared this layout. Useful for debug.

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

StructTagFieldlayout

public StructTagFieldlayout()

Method Detail

getLayoutXML

public java.lang.String getLayoutXML()

accessor for layoutXML

setLayoutXML

public void setLayoutXML(java.lang.String layoutXML)

mutator for layoutXML

getClassname

public java.lang.String getClassname()

accessor for classname

setClassname

public void setClassname(java.lang.String classname)

mutator for classname

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

Specified by:

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

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

getInstance

public static StructTagFieldlayout getInstance(com.sun.javadoc.ClassDoc cd)

Factory method for retrieving a new instance given a ClassDoc. Returns an initialized instance in all cases.

exists

public static boolean exists(com.sun.javadoc.ClassDoc cd)

Return true if the give struct contains this tag, false otherwise.

hasFieldlayout

public boolean hasFieldlayout()

Returns true if there is a fieldlayout defined, false otherwise.

sort

public void sort(com.sun.javadoc.FieldDoc[] fields)

Sort the given field array based on the declared field layout. Any fields declared in the fieldlayout are moved to the beginning of the array in the order they are declared, any remaining fields are left in their original order.

compare

public int compare(java.lang.Object obj1,
                   java.lang.Object obj2)

Compare two fields based on their declared layout ordering.

Specified by:

compare in interface java.util.Comparator

getMaxCols

public int getMaxCols()

Return the maximum number of columns used by the declared layout. If no declared layout then this returns 2, for the standard 2 column fieldname/value display.

tokenMatch

public boolean tokenMatch(char[] chars,
                          int index,
                          java.lang.String token)

Return true if the characters from the given index match the characters of the token string.

tokenMatch

public boolean tokenMatch(char[] chars,
                          int index,
                          char[] tokchars)

Return true if the characters from the given index match the characters of the token string.

hasAttr

public boolean hasAttr(char[] chars,
                       int index,
                       java.lang.String attrname)

Read forward from the given index searching for the given attrname. Return true if found, false if not. Search terminates at end of chars or closing bracket. We actually do the search here rather than using getAttrStringValue, since we want to return true if the attr was specified without a value.

getAttrStringValue

public java.lang.String getAttrStringValue(char[] chars,
                                           int index,
                                           java.lang.String attrname)

Return the value of the given attribute or null if not available.

getAttrIntValue

public int getAttrIntValue(char[] chars,
                           int index,
                           java.lang.String attrname)

Return the value of the specified attribute as an integer.

convertToInt

public int convertToInt(java.lang.String strval)

Convert the given string to an integer and return it. Returns 0 if there is a parsing exception.

getTagString

public java.lang.String getTagString(char[] chars,
                                     int index)

Read from the given index to the the closing tag bracket and return the result.

hasField

public boolean hasField(java.lang.String fieldname)

Return true if the given layout includes the given fieldname, false otherwise.

hasFieldAttr

public boolean hasFieldAttr(java.lang.String fieldname,
                            java.lang.String attrname)

Return true if the given field has the given attribute specified, false otherwise.

getFieldStartIndex

public int getFieldStartIndex(char[] chars,
                              java.lang.String fieldname)

Return the starting index for this attribute declaration.

getFieldAttrVal

public java.lang.String getFieldAttrVal(java.lang.String fieldname,
                                        java.lang.String attrname)

Return the value of the given attribute of the given field, or null if not found.

getFieldAttrIntVal

public int getFieldAttrIntVal(java.lang.String fieldname,
                              java.lang.String attrname,
                              int failval)

Return the value of the attribute specified for the given fieldname or the failval if the attribute is not specified or cannot be converted to an int.

sharesRow

public boolean sharesRow(java.lang.String fieldname)

Return true if the given field shares a row with another field, false otherwise.

startsRow

public boolean startsRow(java.lang.String fieldname)

Return true if the given field begins a row, false otherwise.

endsRow

public boolean endsRow(java.lang.String fieldname)

Return true if the given field ends a row, false otherwise.

debug

public void debug(java.lang.String text)

Debug output utility.

getLayoutXMLNoSpace

public java.lang.String getLayoutXMLNoSpace()

Remove extraneous formatting space from the layoutXML and return the result.