org.sandev.generator
Class SandFieldDoc

java.lang.Object
  org.sandev.generator.SandFieldDoc

All Implemented Interfaces:

com.sun.javadoc.Doc, com.sun.javadoc.FieldDoc, com.sun.javadoc.MemberDoc, com.sun.javadoc.ProgramElementDoc, java.lang.Comparable<java.lang.Object>

public class SandFieldDoc
extends java.lang.Object
implements com.sun.javadoc.FieldDoc

Basic FieldDoc implementation used for adding synthesized fields to an existing ClassDoc. It would be nice to use whatever Sun uses, but since they don't provide access to the FieldDoc used by the Standard Doclet, we roll our own. Note that this implementation is designed only to support synthesized fields for doclets; as a result, most functionality of the FieldDoc API is not implemented.

All SAND synthesized fields are SandFieldDoc classes, so you can use instanceof to distinguish between generated fields and declared fields. You can also use the isSynthetic() method, which always returns true for a SandFieldDoc, and should never return true for a proper struct or node field declaration.

SAND generated fields are triggered by the presence of struct tags (like @persist or @transmit), or node tags (like @call, @subscribe etc). Whether a particular generated field is relevant to any given code generator depends on the context. That context determines whether the field exists, and also whether the field is generally modified within that context. When a field is not normally modified within a given context, the isFinal() method will return true.

Since declaring a struct or node field with any modifier other than "protected" is invalid, the re-use of isFinal() to indicate that a field should be read-only seemed like the best option.

Note that the read-only designation is not strict. For example, the uniqueID field is read-only except in CONTEXT_PERSISTENCE, but it requires a set method to be reconstructed from a UI context, or sent over the wire in a MESSAGING context. The read-only indication means that there is no ownership of the field within a context, so modification would be innapropriate. Unfortunately there is no easy differentiation between modifying a value and restoring a value while working at the code level. However a generator can leave indications in comments, and behavior can be enforced at the level of code analysis (whether automated or not).

This class makes the following assumptions:

1. All fields are protected.
2. Fields don't have weird decorators. If you have to ask, it's weird.

Field Summary

protected java.lang.String	comments
protected java.lang.String	fieldName
protected boolean	readOnly We override final to indicate read-only for a given context.
protected java.util.HashMap	tagmap where we keep our synthetic Tag arrays
protected boolean	transientField
protected com.sun.javadoc.Type	type

Constructor Summary

SandFieldDoc(java.lang.String fieldName, java.lang.String comments, com.sun.javadoc.Type type)

Method Summary

void	addTag(com.sun.javadoc.Tag tag) Add a Tag to our collection.
com.sun.javadoc.AnnotationDesc[]	annotations() Returns null.
com.sun.javadoc.AnnotationTypeDoc	asAnnotationTypeDoc() Returns null.
com.sun.javadoc.ParameterizedType	asParameterizedType() Returns null.
com.sun.javadoc.TypeVariable	asTypeVariable() Returns null.
com.sun.javadoc.WildcardType	asWildcardType() Returns null.
java.lang.String	commentText()
int	compareTo(java.lang.Object obj) Not implemented; always returns 0.
java.lang.Object	constantValue() Constant objects aren't supported, so always return null
java.lang.String	constantValueExpression() Constant values aren't supported, so always return null
com.sun.javadoc.ClassDoc	containingClass() All classes are assumed to be outer classes so return null
com.sun.javadoc.PackageDoc	containingPackage() Not implemented; returns null
com.sun.javadoc.Tag[]	firstSentenceTags() Not implemented; returns null.
java.lang.String	getRawCommentText() Equivalent to commentText().
protected java.util.HashMap	getTagMap() accessor for tagmap
com.sun.javadoc.Tag[]	inlineTags() Not implemented; returns null.
boolean	isAnnotationType() Returns false.
boolean	isAnnotationTypeElement() Returns false.
boolean	isClass()
boolean	isConstructor()
boolean	isEnum() Returns false.
boolean	isEnumConstant() Returns false.
boolean	isError()
boolean	isException()
boolean	isField()
boolean	isFinal()
boolean	isIncluded()
boolean	isInterface()
boolean	isMethod()
boolean	isOrdinaryClass()
boolean	isPackagePrivate() Private packages aren't supported, so return false
boolean	isPrimitive() Returns false.
boolean	isPrivate() All fields are assumed to be protected, so return false
boolean	isProtected() All fields are assumed to be protected, so return true
boolean	isPublic() All fields are assumed to be protected, so return false
boolean	isStatic() Static fields aren't supported, so return false
boolean	isSynthetic() Return true since this class is only designed to work with fields synthesized by doclets.
boolean	isTransient() Return true if this is a transient field, false otherwise.
boolean	isVolatile() Volatile fields aren't supported, so return false
java.lang.String	modifiers() Returns modifiers for the field; all fields are assumed to be protected
int	modifierSpecifier() Stupid Sun
java.lang.String	name()
com.sun.javadoc.SourcePosition	position() Not applicable; returns null.
java.lang.String	qualifiedName() Gets the fully qualified name of the field type
com.sun.javadoc.SeeTag[]	seeTags() No @see tags, so returns null.
com.sun.javadoc.SerialFieldTag[]	serialFieldTags() No @serial fields are expected, so always return null
void	setRawCommentText(java.lang.String rawDocumentation)
void	setReadOnly(boolean readOnly)
void	setTransient(boolean val) Mutator for transientField flag.
java.lang.String	simpleTypeName() Returns typeName.
com.sun.javadoc.Tag[]	tags() Not implemented; returns empty Tag[]
com.sun.javadoc.Tag[]	tags(java.lang.String tagname) Look up the tagname in our map.
com.sun.javadoc.Type	type() Returns the type of the field

Methods inherited from class java.lang.Object

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

Field Detail

fieldName

protected java.lang.String fieldName

comments

protected java.lang.String comments

type

protected com.sun.javadoc.Type type

transientField

protected boolean transientField

tagmap

protected java.util.HashMap tagmap

where we keep our synthetic Tag arrays

readOnly

protected boolean readOnly

We override final to indicate read-only for a given context. See the class comments for details.

Constructor Detail

SandFieldDoc

public SandFieldDoc(java.lang.String fieldName,
                    java.lang.String comments,
                    com.sun.javadoc.Type type)

Method Detail

getTagMap

protected java.util.HashMap getTagMap()

accessor for tagmap

constantValue

public java.lang.Object constantValue()

Constant objects aren't supported, so always return null

Specified by:

constantValue in interface com.sun.javadoc.FieldDoc

constantValueExpression

public java.lang.String constantValueExpression()

Constant values aren't supported, so always return null

Specified by:

constantValueExpression in interface com.sun.javadoc.FieldDoc

isTransient

public boolean isTransient()

Return true if this is a transient field, false otherwise. Transient fields are set explicitely.

Specified by:

isTransient in interface com.sun.javadoc.FieldDoc

setTransient

public void setTransient(boolean val)

Mutator for transientField flag.

isVolatile

public boolean isVolatile()

Volatile fields aren't supported, so return false

Specified by:

isVolatile in interface com.sun.javadoc.FieldDoc

serialFieldTags

public com.sun.javadoc.SerialFieldTag[] serialFieldTags()

No @serial fields are expected, so always return null

Specified by:

serialFieldTags in interface com.sun.javadoc.FieldDoc

type

public com.sun.javadoc.Type type()

Returns the type of the field

Specified by:

type in interface com.sun.javadoc.FieldDoc

isSynthetic

public boolean isSynthetic()

Return true since this class is only designed to work with fields synthesized by doclets.

Specified by:

isSynthetic in interface com.sun.javadoc.MemberDoc

containingClass

public com.sun.javadoc.ClassDoc containingClass()

All classes are assumed to be outer classes so return null

Specified by:

containingClass in interface com.sun.javadoc.ProgramElementDoc

containingPackage

public com.sun.javadoc.PackageDoc containingPackage()

Not implemented; returns null

Specified by:

containingPackage in interface com.sun.javadoc.ProgramElementDoc

isFinal

public boolean isFinal()

Specified by:

isFinal in interface com.sun.javadoc.ProgramElementDoc

setReadOnly

public void setReadOnly(boolean readOnly)

isPackagePrivate

public boolean isPackagePrivate()

Private packages aren't supported, so return false

Specified by:

isPackagePrivate in interface com.sun.javadoc.ProgramElementDoc

isPrivate

public boolean isPrivate()

All fields are assumed to be protected, so return false

Specified by:

isPrivate in interface com.sun.javadoc.ProgramElementDoc

isProtected

public boolean isProtected()

All fields are assumed to be protected, so return true

Specified by:

isProtected in interface com.sun.javadoc.ProgramElementDoc

isPublic

public boolean isPublic()

All fields are assumed to be protected, so return false

Specified by:

isPublic in interface com.sun.javadoc.ProgramElementDoc

isStatic

public boolean isStatic()

Static fields aren't supported, so return false

Specified by:

isStatic in interface com.sun.javadoc.ProgramElementDoc

modifiers

public java.lang.String modifiers()

Returns modifiers for the field; all fields are assumed to be protected

Specified by:

modifiers in interface com.sun.javadoc.ProgramElementDoc

modifierSpecifier

public int modifierSpecifier()

Stupid Sun

Specified by:

modifierSpecifier in interface com.sun.javadoc.ProgramElementDoc

qualifiedName

public java.lang.String qualifiedName()

Gets the fully qualified name of the field type

Specified by:

qualifiedName in interface com.sun.javadoc.ProgramElementDoc

annotations

public com.sun.javadoc.AnnotationDesc[] annotations()

Returns null. Required in 1.5 and kills 1.4 compilation. Simplest workaround for 1.4 is probably to create AnnotationDesc.java with package com.sun.javadoc and an empty class declaration in this local directory.

Specified by:

annotations in interface com.sun.javadoc.ProgramElementDoc

commentText

public java.lang.String commentText()

Specified by:

commentText in interface com.sun.javadoc.Doc

compareTo

public int compareTo(java.lang.Object obj)

Not implemented; always returns 0.

Specified by:

compareTo in interface com.sun.javadoc.Doc

Specified by:

compareTo in interface java.lang.Comparable<java.lang.Object>

firstSentenceTags

public com.sun.javadoc.Tag[] firstSentenceTags()

Not implemented; returns null.

Specified by:

firstSentenceTags in interface com.sun.javadoc.Doc

getRawCommentText

public java.lang.String getRawCommentText()

Equivalent to commentText(). I hope nobody minds.

Specified by:

getRawCommentText in interface com.sun.javadoc.Doc

inlineTags

public com.sun.javadoc.Tag[] inlineTags()

Not implemented; returns null.

Specified by:

inlineTags in interface com.sun.javadoc.Doc

isClass

public boolean isClass()

Specified by:

isClass in interface com.sun.javadoc.Doc

isConstructor

public boolean isConstructor()

Specified by:

isConstructor in interface com.sun.javadoc.Doc

isError

public boolean isError()

Specified by:

isError in interface com.sun.javadoc.Doc

isException

public boolean isException()

Specified by:

isException in interface com.sun.javadoc.Doc

isField

public boolean isField()

Specified by:

isField in interface com.sun.javadoc.Doc

isIncluded

public boolean isIncluded()

Specified by:

isIncluded in interface com.sun.javadoc.Doc

isInterface

public boolean isInterface()

Specified by:

isInterface in interface com.sun.javadoc.Doc

isMethod

public boolean isMethod()

Specified by:

isMethod in interface com.sun.javadoc.Doc

isOrdinaryClass

public boolean isOrdinaryClass()

Specified by:

isOrdinaryClass in interface com.sun.javadoc.Doc

name

public java.lang.String name()

Specified by:

name in interface com.sun.javadoc.Doc

position

public com.sun.javadoc.SourcePosition position()

Not applicable; returns null.

Specified by:

position in interface com.sun.javadoc.Doc

seeTags

public com.sun.javadoc.SeeTag[] seeTags()

No @see tags, so returns null.

Specified by:

seeTags in interface com.sun.javadoc.Doc

setRawCommentText

public void setRawCommentText(java.lang.String rawDocumentation)

Specified by:

setRawCommentText in interface com.sun.javadoc.Doc

tags

public com.sun.javadoc.Tag[] tags()

Not implemented; returns empty Tag[]

Specified by:

tags in interface com.sun.javadoc.Doc

tags

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

Look up the tagname in our map. If we find something, return it, otherwise return an empty array.

Specified by:

tags in interface com.sun.javadoc.Doc

isAnnotationType

public boolean isAnnotationType()

Returns false. Required in 1.5

Specified by:

isAnnotationType in interface com.sun.javadoc.Doc

isEnum

public boolean isEnum()

Returns false. Required in 1.5

Specified by:

isEnum in interface com.sun.javadoc.Doc

isAnnotationTypeElement

public boolean isAnnotationTypeElement()

Returns false. Required in 1.5

Specified by:

isAnnotationTypeElement in interface com.sun.javadoc.Doc

isEnumConstant

public boolean isEnumConstant()

Returns false. Required in 1.5

Specified by:

isEnumConstant in interface com.sun.javadoc.Doc

asAnnotationTypeDoc

public com.sun.javadoc.AnnotationTypeDoc asAnnotationTypeDoc()

Returns null. Required in 1.5 and kills 1.4 compilation since this is new. Simplest workaround for 1.4 is probably to create AnnotationTypeDoc.java with package com.sun.javadoc and an empty class declaration in this local directory.

asWildcardType

public com.sun.javadoc.WildcardType asWildcardType()

Returns null. Required in 1.5 and kills 1.4 compilation since this is new. Simplest workaround for 1.4 is probably to create WildcardType.java with package com.sun.javadoc and an empty class declaration in this local directory.

asTypeVariable

public com.sun.javadoc.TypeVariable asTypeVariable()

Returns null. Required in 1.5 and kills 1.4 compilation since this is new. Simplest workaround for 1.4 is probably to create TypeVariable.java with package com.sun.javadoc and an empty class declaration in this local directory.

asParameterizedType

public com.sun.javadoc.ParameterizedType asParameterizedType()

Returns null. Required in 1.5 and kills 1.4 compilation. Simplest workaround for 1.4 is probably to create ParameterizedType.java with package com.sun.javadoc and an empty class declaration in this local directory.

isPrimitive

public boolean isPrimitive()

Returns false. Required in 1.5

simpleTypeName

public java.lang.String simpleTypeName()

Returns typeName. Required in 1.5

addTag

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

Add a Tag to our collection.