org.sandev.generator
Class InstanceGeneratorBase

java.lang.Object
  org.sandev.generator.GeneratorCommon
      org.sandev.generator.FileGeneratorBase
          org.sandev.generator.InstanceGeneratorBase

All Implemented Interfaces:

org.sandev.sandbuild.SandGenerator

Direct Known Subclasses:

MessageClassGenerator, NodeClassGenerator, NodeInstClassGenerator

public class InstanceGeneratorBase

extends FileGeneratorBase

Factored common methods for instance generators. The generators responsible for creating struct message classes, node base classes, and node instance classes all have common needs in terms of declared fields and associated utilities. These are factored here for ease of use.

Field Summary

Fields inherited from class org.sandev.generator.GeneratorCommon

CONTEXT_CONFIGURATION, CONTEXT_CONTROL, CONTEXT_FRAMEWORK, CONTEXT_MESSAGING, CONTEXT_PERSISTENCE, CONTEXT_UI, DEFAULT_LINE_LENGTH, MESSAGE_INTERFACES

Constructor Summary

InstanceGeneratorBase()

Method Summary

static java.lang.String	getInstanceName(java.lang.String declName) Given the name of a NodeDecl, return the name of the instance.
void	writeAccMut(java.io.PrintStream out, com.sun.javadoc.FieldDoc fd) Write out appropriate accessors and mutators for the given field.
static void	writeArrayAccMut(java.io.PrintStream out, java.lang.String fieldName, java.lang.String fieldType) Write the array accessor/mutators so they do not end up being null.
static void	writeArrayAppend(java.io.PrintStream out, java.lang.String fieldName, java.lang.String fieldType) Writes code to append a value to an array.
static void	writeArrayClear(java.io.PrintStream out, java.lang.String fieldName, java.lang.String fieldType) Writes code to clear an array.
static void	writeArrayContains(java.io.PrintStream out, java.lang.String fieldName, java.lang.String fieldType) Write the standard array contains test.
static void	writeArrayGet(java.io.PrintStream out, java.lang.String fieldName, java.lang.String fieldType) Writes code to return an element from an array.
static void	writeArrayInsert(java.io.PrintStream out, java.lang.String fieldName, java.lang.String fieldType) Write the standard array insertion code
static void	writeArrayRemove(java.io.PrintStream out, java.lang.String fieldName, java.lang.String fieldType) Writes code to remove an element from an array.
static void	writeArrayRemoveIndex(java.io.PrintStream out, java.lang.String fieldName, java.lang.String fieldType) Write the standard array removal code
static void	writeArraySet(java.io.PrintStream out, java.lang.String fieldName, java.lang.String fieldType) Write the standard array element set code
static void	writeArraySize(java.io.PrintStream out, java.lang.String fieldName) Writes code to return the size of an array
void	writeCloneMessage(java.io.PrintStream out, com.sun.javadoc.FieldDoc[] fields, java.lang.String classname) Write the cloneMessage and cloneMyStruct methods.
static void	writeConstantsAndConversions(java.io.PrintStream out, com.sun.javadoc.FieldDoc fd, java.lang.String classname) Write out constant values declared for this field.
protected static void	writeCoreValidityCheck(java.io.PrintStream out, java.lang.String indent, com.sun.javadoc.FieldDoc fd, FieldTagStringlength fts, FieldTagEnumint[] ftes, FieldTagRange ftr) Workhorse method for writeValidityCheck, which writes the actual checks for a single element.
void	writeCtorAndInit(java.io.PrintStream out, com.sun.javadoc.FieldDoc[] fields, java.lang.String name) Write constructor and init method
void	writeDebugDump(java.io.PrintStream out, com.sun.javadoc.FieldDoc[] fields, java.lang.String classname) Write the debugDump method.
static void	writeDecimalAccMut(java.io.PrintStream out, FieldTagDecimalize ftd) Write accessor mutators to convert integer and decimal values for this field.
static void	writeDefaultValueAccessor(java.io.PrintStream out, com.sun.javadoc.FieldDoc fd, FieldTagEnumint[] ftes) Write the method for accessing the field default value.
void	writeDisplayCode(java.io.PrintStream out, com.sun.javadoc.FieldDoc[] fields, java.lang.String classname, StructTagSummaryfields sts) Write the getDisplayFields and getDisplayValues methods.
static void	writeEnumintBools(java.io.PrintStream out, FieldTagEnumint[] ftes, FieldTagFlags ftf) Write out the boolean access methods for each of the enum values if flagged.
static void	writeEnumintConsts(java.io.PrintStream out, FieldTagEnumint[] ftes) Write the enum constants for the field
static void	writeEnumintTrans(java.io.PrintStream out, FieldTagEnumint[] ftes, java.lang.String classname) Write out an array of possible labels used with this enumerated integer, along with conversion utilities.
void	writeEquivalenceCheck(java.io.PrintStream out, java.lang.String fieldName, java.lang.String fieldType, boolean isStruct, boolean isArray) Workhorse for writeIsEquivalent..
static void	writeField(java.io.PrintStream out, com.sun.javadoc.FieldDoc fd) Write out the given field as a protected data member.
void	writeFieldFiltering(java.io.PrintStream out, com.sun.javadoc.FieldDoc[] fields, java.lang.String classname) Write the getAllFields and defaultField methods.
protected void	writeFieldsAndAccess(java.io.PrintStream out, com.sun.javadoc.FieldDoc[] fields, java.lang.String classname) Write out accessor and mutator mthods for all the fields.
static void	writeFlagAccessor(java.io.PrintStream out, FieldTagFlags ftf) Write the method for accessing the field flags.
protected void	writeGenAccess(java.io.PrintStream out, com.sun.javadoc.FieldDoc[] fields, java.lang.String classname) Write out the generalAccessor method specified by the SandInstanceMessage interface.
protected void	writeGenDeref(java.io.PrintStream out, com.sun.javadoc.FieldDoc[] fields, java.lang.String classname) Write out the generalDereference method specified by the SandInstanceMessage interface.
void	writeGenMod(java.io.PrintStream out, com.sun.javadoc.FieldDoc[] fields, java.lang.String classname) Write out the generalModifier method specified by the SandInstanceMessage interface.
static void	writeInvalidValueAccessor(java.io.PrintStream out, com.sun.javadoc.FieldDoc fd, FieldTagEnumint[] ftes) Write the method for accessing the field invalid value.
void	writeIsEquivalent(java.io.PrintStream out, java.lang.String classname, com.sun.javadoc.FieldDoc[] fields) Write the isEquivalent method part of the SandMessage interface.
static void	writeLengthAccessors(java.io.PrintStream out, FieldTagStringlength fts) Write constants for the normal and maximum charcter lengths of a String field.
static void	writeLongRefResolution(java.io.PrintStream out, java.lang.String fieldname, java.lang.String classname, boolean isArray) Workhorse for writeReferenceResolution.
static void	writeMetatypeAccess(java.io.PrintStream out, com.sun.javadoc.FieldDoc fd, FieldTagMetatype ftm) Write accessor method to retrieve the declared metatype.
static void	writePrintValueAccessor(java.io.PrintStream out, com.sun.javadoc.FieldDoc fd) Write the method for accessing the current field value as a print String.
static void	writeRangeRetrieval(java.io.PrintStream out, com.sun.javadoc.FieldDoc fd, FieldTagRange ftr) The UI and validators need access to the range specification.
static void	writeReferenceResolution(java.io.PrintStream out, FieldTagRef ftr) Write the utility methods to transform references into instances.
void	writeSandInstanceMessageImpl(java.io.PrintStream out, com.sun.javadoc.ClassDoc cd, java.lang.String classname, com.sun.javadoc.FieldDoc[] fields, StructTagSummaryfields sts) Write the SandInstanceMessage implementation.
void	writeSandMessageImpl(java.io.PrintStream out, StructTagVerbforms stv, java.lang.String msgClassName, java.lang.String structClassName, com.sun.javadoc.FieldDoc[] equivalenceFields) Write out the methods required by the SandMessage interface.
static void	writeStackOperations(java.io.PrintStream out, com.sun.javadoc.FieldDoc fd, FieldTagFlags ftf) Write out the stack mutator methods if flagged.
void	writeStandardAccMut(java.io.PrintStream out, java.lang.String fieldName, java.lang.String fieldType) Write the standard accessor and mutator methods for a given field which is not an array.
static void	writeStringRefResolution(java.io.PrintStream out, java.lang.String fieldname, java.lang.String refclass, java.lang.String reffield, boolean isArray) Workhorse for writeReferenceResolution.
void	writeSuperstructConversion(java.io.PrintStream out, com.sun.javadoc.ClassDoc cd, java.lang.String classname) Write the superstruct conversion method.
protected static void	writeTreeAccessors(java.io.PrintStream out, com.sun.javadoc.FieldDoc fd, FieldTagFlags ftf) Write out the tree accessor methods if flagged.
void	writeValidation(java.io.PrintStream out, com.sun.javadoc.FieldDoc[] fields, java.lang.String classname) Write the field validation methods.
static void	writeValidityCheck(java.io.PrintStream out, com.sun.javadoc.FieldDoc fd, FieldTagStringlength fts, FieldTagEnumint[] ftes, FieldTagRange ftr) write the validity check method for this field
void	writeVerbFormAccessors(java.io.PrintStream out, StructTagVerbforms stv, java.lang.String classname) Write the methods to access the verb forms for this message.

Methods inherited from class org.sandev.generator.FileGeneratorBase

cleanup, delete, generate, trackFileWrite, write

Methods inherited from class org.sandev.generator.GeneratorCommon

capitalize, copyfile, deletefile, filterHTMLLine, getDeclaredFields, getFields, getInheritanceHierarchy, getLastAppProject, getLastUtilDir, getLongInstanceName, getPrintStream, getSandProject, getShortInstanceName, getUtilPackage, getVisibleFields, isBasic, isLongReferenceArray, isMessageInterface, isParentAbstract, isPrimitive, isRootStruct, isVowel, log, nextToken, pluralize, rangeEscape, removePlatformDecls, trackFileDelete, uncapitalize, writeDefaultCtor, writeDescription, writeHTMLContents, writeMessageImports, writeSectionName, writeStandardCommentID, writeXHTMLFooter, writeXHTMLFooter, writeXHTMLHeader, writeXHTMLHeader

Methods inherited from class java.lang.Object

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

Constructor Detail

InstanceGeneratorBase

public InstanceGeneratorBase()

Method Detail

writeFieldsAndAccess

protected void writeFieldsAndAccess(java.io.PrintStream out,
                                    com.sun.javadoc.FieldDoc[] fields,
                                    java.lang.String classname)
                             throws org.sandev.sandbuild.SandGeneratorException

Write out accessor and mutator mthods for all the fields. If the field is synthesized, then write it out. Write out all associated constants and utility methods.

Throws:

org.sandev.sandbuild.SandGeneratorException

writeField

public static void writeField(java.io.PrintStream out,
                              com.sun.javadoc.FieldDoc fd)
                       throws org.sandev.sandbuild.SandGeneratorException

Write out the given field as a protected data member.

Throws:

org.sandev.sandbuild.SandGeneratorException

writeAccMut

public void writeAccMut(java.io.PrintStream out,
                        com.sun.javadoc.FieldDoc fd)
                 throws org.sandev.sandbuild.SandGeneratorException

Write out appropriate accessors and mutators for the given field.

Throws:

org.sandev.sandbuild.SandGeneratorException

writeArrayAccMut

public static void writeArrayAccMut(java.io.PrintStream out,
                                    java.lang.String fieldName,
                                    java.lang.String fieldType)

Write the array accessor/mutators so they do not end up being null. Arrays can be empty but not null (otherwise all the access becomes unduly error prone for no good reason).

writeArrayAppend

public static void writeArrayAppend(java.io.PrintStream out,
                                    java.lang.String fieldName,
                                    java.lang.String fieldType)

Writes code to append a value to an array.

writeArrayGet

public static void writeArrayGet(java.io.PrintStream out,
                                 java.lang.String fieldName,
                                 java.lang.String fieldType)

Writes code to return an element from an array.

writeArrayClear

public static void writeArrayClear(java.io.PrintStream out,
                                   java.lang.String fieldName,
                                   java.lang.String fieldType)

Writes code to clear an array.

writeArrayContains

public static void writeArrayContains(java.io.PrintStream out,
                                      java.lang.String fieldName,
                                      java.lang.String fieldType)

Write the standard array contains test.

writeArraySet

public static void writeArraySet(java.io.PrintStream out,
                                 java.lang.String fieldName,
                                 java.lang.String fieldType)

Write the standard array element set code

writeArrayInsert

public static void writeArrayInsert(java.io.PrintStream out,
                                    java.lang.String fieldName,
                                    java.lang.String fieldType)

Write the standard array insertion code

writeArrayRemoveIndex

public static void writeArrayRemoveIndex(java.io.PrintStream out,
                                         java.lang.String fieldName,
                                         java.lang.String fieldType)

Write the standard array removal code

writeArrayRemove

public static void writeArrayRemove(java.io.PrintStream out,
                                    java.lang.String fieldName,
                                    java.lang.String fieldType)

Writes code to remove an element from an array. This relies on the object's equals method.

writeArraySize

public static void writeArraySize(java.io.PrintStream out,
                                  java.lang.String fieldName)

Writes code to return the size of an array

writeStandardAccMut

public void writeStandardAccMut(java.io.PrintStream out,
                                java.lang.String fieldName,
                                java.lang.String fieldType)

Write the standard accessor and mutator methods for a given field which is not an array.

writeConstantsAndConversions

public static void writeConstantsAndConversions(java.io.PrintStream out,
                                                com.sun.javadoc.FieldDoc fd,
                                                java.lang.String classname)
                                         throws org.sandev.sandbuild.SandGeneratorException

Write out constant values declared for this field. Constant values include enumerations, default and invalid values, length constants etc.

We used to write constants for the name of each field, but this isn't really meta-data and it wasn't getting used anywhere. So that's gone. Seems kind of circular to need the constant name of a field, if you could look that up, then you could have used the lookup text you had. We weren't providing an array of this or anything, and it really overlaps with reflection at that point anyway. Use the struct/node declaration, or use reflection, if you need this info.

Throws:

org.sandev.sandbuild.SandGeneratorException

getInstanceName

public static java.lang.String getInstanceName(java.lang.String declName)

Given the name of a NodeDecl, return the name of the instance.

writeEnumintConsts

public static void writeEnumintConsts(java.io.PrintStream out,
                                      FieldTagEnumint[] ftes)

Write the enum constants for the field

writeEnumintTrans

public static void writeEnumintTrans(java.io.PrintStream out,
                                     FieldTagEnumint[] ftes,
                                     java.lang.String classname)

Write out an array of possible labels used with this enumerated integer, along with conversion utilities. Some notes:

• The methods which access the static arrays are not static themselves. This is intentional. I want to leave open the possibility of overrides.
• The static arrays are private. I want to make sure everyone is using the accessors. Plus it reduces javadoc clutter.
• The conversion methods have a "To" in them. The transformation methods have a "2" in them. You may or may not find that helpful, but that's how it evolved.
• Yes we could use hashtable lookups for the "2" transforms, but that would be total overkill and a waste of memory. This is more readable to boot.
• When we have to return something as a default, we don't worry about it too much since you are not translating to/from enum values on a hunch. This is primarily to support more generated code like UIFormAdaptors. So sometimes we return things from here like Integer.MIN_VALUE or null.

writeEnumintBools

public static void writeEnumintBools(java.io.PrintStream out,
                                     FieldTagEnumint[] ftes,
                                     FieldTagFlags ftf)

Write out the boolean access methods for each of the enum values if flagged.

writeStackOperations

public static void writeStackOperations(java.io.PrintStream out,
                                        com.sun.javadoc.FieldDoc fd,
                                        FieldTagFlags ftf)

Write out the stack mutator methods if flagged.

writeLengthAccessors

public static void writeLengthAccessors(java.io.PrintStream out,
                                        FieldTagStringlength fts)

Write constants for the normal and maximum charcter lengths of a String field.

writeFlagAccessor

public static void writeFlagAccessor(java.io.PrintStream out,
                                     FieldTagFlags ftf)

Write the method for accessing the field flags.

writeTreeAccessors

protected static void writeTreeAccessors(java.io.PrintStream out,
                                         com.sun.javadoc.FieldDoc fd,
                                         FieldTagFlags ftf)

Write out the tree accessor methods if flagged.

writeDefaultValueAccessor

public static void writeDefaultValueAccessor(java.io.PrintStream out,
                                             com.sun.javadoc.FieldDoc fd,
                                             FieldTagEnumint[] ftes)

Write the method for accessing the field default value.

writeInvalidValueAccessor

public static void writeInvalidValueAccessor(java.io.PrintStream out,
                                             com.sun.javadoc.FieldDoc fd,
                                             FieldTagEnumint[] ftes)

Write the method for accessing the field invalid value.

writePrintValueAccessor

public static void writePrintValueAccessor(java.io.PrintStream out,
                                           com.sun.javadoc.FieldDoc fd)

Write the method for accessing the current field value as a print String. Arrays are not supported because they are not allowed when generating a summary description for an instance. This is left for code at the UI/Messaging/Serialization level, where the representation and reference lookup is possible, and the context for what should be output is clearer.

writeDecimalAccMut

public static void writeDecimalAccMut(java.io.PrintStream out,
                                      FieldTagDecimalize ftd)

Write accessor mutators to convert integer and decimal values for this field.

writeRangeRetrieval

public static void writeRangeRetrieval(java.io.PrintStream out,
                                       com.sun.javadoc.FieldDoc fd,
                                       FieldTagRange ftr)

The UI and validators need access to the range specification.

writeReferenceResolution

public static void writeReferenceResolution(java.io.PrintStream out,
                                            FieldTagRef ftr)

Write the utility methods to transform references into instances.

writeLongRefResolution

public static void writeLongRefResolution(java.io.PrintStream out,
                                          java.lang.String fieldname,
                                          java.lang.String classname,
                                          boolean isArray)

Workhorse for writeReferenceResolution.

writeStringRefResolution

public static void writeStringRefResolution(java.io.PrintStream out,
                                            java.lang.String fieldname,
                                            java.lang.String refclass,
                                            java.lang.String reffield,
                                            boolean isArray)

Workhorse for writeReferenceResolution.

writeValidityCheck

public static void writeValidityCheck(java.io.PrintStream out,
                                      com.sun.javadoc.FieldDoc fd,
                                      FieldTagStringlength fts,
                                      FieldTagEnumint[] ftes,
                                      FieldTagRange ftr)

write the validity check method for this field

writeCoreValidityCheck

protected static void writeCoreValidityCheck(java.io.PrintStream out,
                                             java.lang.String indent,
                                             com.sun.javadoc.FieldDoc fd,
                                             FieldTagStringlength fts,
                                             FieldTagEnumint[] ftes,
                                             FieldTagRange ftr)

Workhorse method for writeValidityCheck, which writes the actual checks for a single element.

writeMetatypeAccess

public static void writeMetatypeAccess(java.io.PrintStream out,
                                       com.sun.javadoc.FieldDoc fd,
                                       FieldTagMetatype ftm)

Write accessor method to retrieve the declared metatype.

writeCtorAndInit

public void writeCtorAndInit(java.io.PrintStream out,
                             com.sun.javadoc.FieldDoc[] fields,
                             java.lang.String name)

Write constructor and init method

writeSandMessageImpl

public void writeSandMessageImpl(java.io.PrintStream out,
                                 StructTagVerbforms stv,
                                 java.lang.String msgClassName,
                                 java.lang.String structClassName,
                                 com.sun.javadoc.FieldDoc[] equivalenceFields)

Write out the methods required by the SandMessage interface. The fields are the fields to be used for equivalence testing, so for a SandStructMessage this does NOT include any synthetic fields.

writeVerbFormAccessors

public void writeVerbFormAccessors(java.io.PrintStream out,
                                   StructTagVerbforms stv,
                                   java.lang.String classname)

Write the methods to access the verb forms for this message. The classname parameter is the short name of the SandStructMessage.

writeIsEquivalent

public void writeIsEquivalent(java.io.PrintStream out,
                              java.lang.String classname,
                              com.sun.javadoc.FieldDoc[] fields)

Write the isEquivalent method part of the SandMessage interface. Note that this method by definition doesn't use any synthetic fields, so it will skip these if included.

writeEquivalenceCheck

public void writeEquivalenceCheck(java.io.PrintStream out,
                                  java.lang.String fieldName,
                                  java.lang.String fieldType,
                                  boolean isStruct,
                                  boolean isArray)

Workhorse for writeIsEquivalent..

writeSandInstanceMessageImpl

public void writeSandInstanceMessageImpl(java.io.PrintStream out,
                                         com.sun.javadoc.ClassDoc cd,
                                         java.lang.String classname,
                                         com.sun.javadoc.FieldDoc[] fields,
                                         StructTagSummaryfields sts)

Write the SandInstanceMessage implementation. Note that this method assumes inherited CONTEXT_MESSAGING for field lookup. Given that we're generating the SandInstanceMessage interface implementation, that shouldn't be a stretch.

This method does NOT call to generate the SandMessage interface. See writeSandMessageImpl for that. There's a separate method for that in GeneratorCommon.

writeGenMod

public void writeGenMod(java.io.PrintStream out,
                        com.sun.javadoc.FieldDoc[] fields,
                        java.lang.String classname)

Write out the generalModifier method specified by the SandInstanceMessage interface.

writeGenDeref

protected void writeGenDeref(java.io.PrintStream out,
                             com.sun.javadoc.FieldDoc[] fields,
                             java.lang.String classname)

Write out the generalDereference method specified by the SandInstanceMessage interface. This was originally written to match fields using startsWith("fieldname") so that it would work with specifications like myRef.myOtherRefField.whatever and support multiple levels of dereferencing that way. Unfortunately if I have one reference field called "myRef" and another reference field called "myRefUser" which refers to something else, then using a startsWith match is not sufficiently specific. So the two cases are now handled separately with the first case being an exact match and the second using startsWith.

For array references, the index has to be specified so it is safe to look for startsWith the fieldname and an open square bracket.

writeGenAccess

protected void writeGenAccess(java.io.PrintStream out,
                              com.sun.javadoc.FieldDoc[] fields,
                              java.lang.String classname)

Write out the generalAccessor method specified by the SandInstanceMessage interface. Analogous to writeGenDeref, see the comments there for details.

writeDisplayCode

public void writeDisplayCode(java.io.PrintStream out,
                             com.sun.javadoc.FieldDoc[] fields,
                             java.lang.String classname,
                             StructTagSummaryfields sts)

Write the getDisplayFields and getDisplayValues methods.

writeFieldFiltering

public void writeFieldFiltering(java.io.PrintStream out,
                                com.sun.javadoc.FieldDoc[] fields,
                                java.lang.String classname)

Write the getAllFields and defaultField methods.

writeCloneMessage

public void writeCloneMessage(java.io.PrintStream out,
                              com.sun.javadoc.FieldDoc[] fields,
                              java.lang.String classname)

Write the cloneMessage and cloneMyStruct methods.

writeValidation

public void writeValidation(java.io.PrintStream out,
                            com.sun.javadoc.FieldDoc[] fields,
                            java.lang.String classname)

Write the field validation methods.

writeSuperstructConversion

public void writeSuperstructConversion(java.io.PrintStream out,
                                       com.sun.javadoc.ClassDoc cd,
                                       java.lang.String classname)

Write the superstruct conversion method.

writeDebugDump

public void writeDebugDump(java.io.PrintStream out,
                           com.sun.javadoc.FieldDoc[] fields,
                           java.lang.String classname)

Write the debugDump method.