org.sandev.generator
Class GeneratorCommon

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

Direct Known Subclasses:

AggregateGeneratorBase, DataManagerInfoGenerator, FileGeneratorBase, FuncSpecGenerator, HelpFileGenerator, SandStringPersistConverterGenerator

public class GeneratorCommon
extends java.lang.Object

Common generator utilities, extend from here or call directly

Field Summary

static int	CONTEXT_CONFIGURATION
static int	CONTEXT_CONTROL
static int	CONTEXT_FRAMEWORK
static int	CONTEXT_MESSAGING
static int	CONTEXT_PERSISTENCE
static int	CONTEXT_UI
static int	DEFAULT_LINE_LENGTH Default value at which to wrap comments and other output text.
static java.lang.String[]	MESSAGE_INTERFACES

Constructor Summary

GeneratorCommon()

Method Summary

static java.lang.String	capitalize(java.lang.String str) Capitalizes the first letter of a string
void	copyfile(java.lang.String srcfile, java.lang.String destdir) Wrapper to access copyfile utility in the SandProject class.
void	deletefile(java.lang.String filespec) Wrapper to access deletefile utility in the SandProject class.
protected java.lang.String	filterHTMLLine(java.lang.String line) Called from writeHTMLContents for each line being written to provide an opportunity to change the text.
org.sandev.sandbuild.SandDecl	findStructDeclByShortname(java.lang.String shortname) Find a struct decl by its short name.
static java.util.ArrayList	getDeclaredFields(com.sun.javadoc.ClassDoc cd, boolean inherit, int context) Return an ArrayList containing all the fields for this class, including inherited fields if requested.
static com.sun.javadoc.FieldDoc[]	getFields(com.sun.javadoc.ClassDoc cd, boolean inherit, int context) Given a ClassDoc, return all the fields for it, including any synthetic fields generated for SAND.
static com.sun.javadoc.ClassDoc[]	getInheritanceHierarchy(com.sun.javadoc.ClassDoc cd, boolean includeAbstract) Returns the inheritance hierarchy for the given ClassDoc.
protected org.sandev.sandbuild.SandProject	getLastAppProject() Return the SandProject just before the triggering build project.
protected java.lang.String	getLastUtilDir() Return the name of the util directory of the last project before the triggering deployment build.
static java.lang.String	getLongInstanceName(java.lang.String declname) Given the fully qualified name of a struct or node declaration, return the fully qualified name of the corresponding instance message.
static java.io.PrintStream	getPrintStream(java.lang.String filename) Given a filename, return a PrintStream for it.
protected org.sandev.sandbuild.SandProject	getSandProject(java.io.File projDir) Return the current SandProject.
static java.lang.String	getShortInstanceName(java.lang.String declname) Given either a short or fully qualified name of a struct or node declaration, return the short name of the associated instance message.
protected java.lang.String	getUtilPackage(org.sandev.sandbuild.SandProject proj) Return the name of the util package for the given project.
static java.util.ArrayList	getVisibleFields(com.sun.javadoc.ClassDoc cd, boolean inherit, int context) Return an ArrayList of the fields for the given class.
static boolean	hasSubStructs(org.sandev.sandbuild.SandDecl sd) Return true if the given struct declaration has other struct declarations that extend it, false otherwise.
static boolean	isArray(com.sun.javadoc.FieldDoc fd) Return true if the type of this field is an array, false otherwise.
static boolean	isBasic(java.lang.String typeName) Returns true if the field type is a SAND basic type.
static boolean	isLongReferenceArray(com.sun.javadoc.FieldDoc fd) Return true if this field is a reference array, false otherwise
static boolean	isMessageInterface(java.lang.String typeName) Returns true if the field type is SAND message interface type such as SandStructMessage, SandVerbMessage etc.
static boolean	isParentAbstract(com.sun.javadoc.ClassDoc cd) Returns true if the parent class is an abstract struct definition.
static boolean	isPrimitive(java.lang.String typeName) Returns true if the field type is a primitive type.
static boolean	isRootStruct(com.sun.javadoc.ClassDoc cd) Returns true if this struct definition does not extend any other struct, or extends an abstract struct.
static boolean	isVowel(char letter) Returns true if the character is an English vowel.
static void	log(java.lang.String text) Dump some text out to the build log.
static java.lang.String	nextToken(java.util.StringTokenizer toker) Wraps StringTokenizer's nextToken method to support quoted strings.
static java.lang.String	pluralize(java.lang.String base) Returns the plural form of a string.
static java.lang.String	rangeEscape(java.lang.String rangeSpec) When working with a range specification, or other match expression, some of the characters can be problematic within the context of standard markup processing like XML, XHTML etc.
protected org.sandev.sandbuild.SandDecl[]	removePlatformDecls(org.sandev.sandbuild.SandDecl[] decls) Remove any platform specific declarations and return the resulting array.
void	trackFileDelete(java.lang.String filespec) Log the fact that we are deleting the specified file.
void	trackFileWrite(java.lang.String filespec) Log the fact that we are writing the specified file
static java.lang.String	uncapitalize(java.lang.String str) Converts the first character of a string to lowercase.
static void	writeDefaultCtor(java.io.PrintStream out, java.lang.String classname) Write a default ctor for the specified classname.
static void	writeDescription(java.io.PrintStream out, java.lang.String prefix, java.lang.String text) Write the given text to the stream, beginning each line with the prefix.
void	writeHTMLContents(java.lang.String filespec, java.io.PrintStream out) Write everything between the body open line and the body close line to the given output stream.
static void	writeMessageImports(java.io.PrintStream out, org.sandev.sandbuild.SandDecl[] decls) Write out the import statements for the messages we are dealing with so the generated code can use the short names.
static void	writeSectionName(java.io.PrintStream out, java.lang.String sectionName) Writes a commented source code section header.
static void	writeStandardCommentID(java.io.PrintStream out, com.sun.javadoc.ClassDoc cd, org.sandev.sandbuild.SandGenerator gen) Write a standard comment line identifying this as autogenerated code, what the source declaration was, which generator wrote it, and when.
protected void	writeXHTMLFooter(java.io.PrintStream out) Write the standard XHTML file postamble.
protected void	writeXHTMLFooter(java.io.PrintStream out, boolean includeBodyTag) Write the standard XHTML file postamble.
protected void	writeXHTMLHeader(java.io.PrintStream out, java.lang.String title) Write the standard XHTML file preamble.
protected void	writeXHTMLHeader(java.io.PrintStream out, java.lang.String title, boolean includeBodyTag, java.lang.String bgcolor) Write the standard XHTML file preamble.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_LINE_LENGTH

public static final int DEFAULT_LINE_LENGTH

Default value at which to wrap comments and other output text. A value less than 80 is helpful when printing, so this is set somewhat below that for headroom.

See Also:

Constant Field Values

MESSAGE_INTERFACES

public static final java.lang.String[] MESSAGE_INTERFACES

CONTEXT_MESSAGING

public static final int CONTEXT_MESSAGING

See Also:

Constant Field Values

CONTEXT_PERSISTENCE

public static final int CONTEXT_PERSISTENCE

See Also:

Constant Field Values

CONTEXT_CONFIGURATION

public static final int CONTEXT_CONFIGURATION

See Also:

Constant Field Values

CONTEXT_CONTROL

public static final int CONTEXT_CONTROL

See Also:

Constant Field Values

CONTEXT_UI

public static final int CONTEXT_UI

See Also:

Constant Field Values

CONTEXT_FRAMEWORK

public static final int CONTEXT_FRAMEWORK

See Also:

Constant Field Values

Constructor Detail

GeneratorCommon

public GeneratorCommon()

Method Detail

log

public static void log(java.lang.String text)

Dump some text out to the build log.

trackFileWrite

public void trackFileWrite(java.lang.String filespec)

Log the fact that we are writing the specified file

trackFileDelete

public void trackFileDelete(java.lang.String filespec)

Log the fact that we are deleting the specified file.

getPrintStream

public static java.io.PrintStream getPrintStream(java.lang.String filename)
                                          throws org.sandev.sandbuild.SandGeneratorException

Given a filename, return a PrintStream for it.

Throws:

org.sandev.sandbuild.SandGeneratorException

writeStandardCommentID

public static void writeStandardCommentID(java.io.PrintStream out,
                                          com.sun.javadoc.ClassDoc cd,
                                          org.sandev.sandbuild.SandGenerator gen)

Write a standard comment line identifying this as autogenerated code, what the source declaration was, which generator wrote it, and when. This method takes the ClassDoc and the generator directly (rather than just the names), so we have the possibility of lifting more info into this comment later.

nextToken

public static java.lang.String nextToken(java.util.StringTokenizer toker)

Wraps StringTokenizer's nextToken method to support quoted strings. So anything enclosed in double quotes is returned as a single token, subject to the limitations of what StringTokenizer can do.

capitalize

public static java.lang.String capitalize(java.lang.String str)

Capitalizes the first letter of a string

uncapitalize

public static java.lang.String uncapitalize(java.lang.String str)

Converts the first character of a string to lowercase.

pluralize

public static java.lang.String pluralize(java.lang.String base)

Returns the plural form of a string. This method is relatively brain-dead and does not handle the wonderful variety of irregular plural forms that English is so fond of. For a correct implementation of this method, irregular plural forms should be handled so we don't wind up telling people that the plural of "fireman" is "firemans".

I suppose it goes without saying that this method is not internationalized.

See Also:

List of irregular English plural nouns

isVowel

public static boolean isVowel(char letter)

Returns true if the character is an English vowel. The letter 'y' is not counted as a vowel. Technically this isn't a string utility but a Character utility. Move this to a separate class if you want.

rangeEscape

public static java.lang.String rangeEscape(java.lang.String rangeSpec)

When working with a range specification, or other match expression, some of the characters can be problematic within the context of standard markup processing like XML, XHTML etc. This method converts things like greater-than and less-than operators into their escape sequences for proper handling, while leaving spaces and other harmless stuff intact.

At the time of this writing, the URLEncoder, URI, and URL classes don't really address this particularly well. They are also seem a bit too heavy-handed for this simple conversion. We just do a simple iterative replacement of the problematic characters.

writeSectionName

public static void writeSectionName(java.io.PrintStream out,
                                    java.lang.String sectionName)

Writes a commented source code section header. This is useful for breaking up large swaths of generated source code into sections so that humans have an easier time finding things.

writeDefaultCtor

public static void writeDefaultCtor(java.io.PrintStream out,
                                    java.lang.String classname)

Write a default ctor for the specified classname.

isPrimitive

public static boolean isPrimitive(java.lang.String typeName)

Returns true if the field type is a primitive type.

isBasic

public static boolean isBasic(java.lang.String typeName)

Returns true if the field type is a SAND basic type. A Locale is not really a fundamental type, but is treated that way so it can be a part of a SandTransmitMessage definition.

isArray

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

Return true if the type of this field is an array, false otherwise.

isMessageInterface

public static boolean isMessageInterface(java.lang.String typeName)

Returns true if the field type is SAND message interface type such as SandStructMessage, SandVerbMessage etc.

writeDescription

public static void writeDescription(java.io.PrintStream out,
                                    java.lang.String prefix,
                                    java.lang.String text)

Write the given text to the stream, beginning each line with the prefix. This method dumps the prefix, then dumps characters from the text. On reading a newline, it prints the line and dumps the prefix again.

getShortInstanceName

public static java.lang.String getShortInstanceName(java.lang.String declname)

Given either a short or fully qualified name of a struct or node declaration, return the short name of the associated instance message.

getLongInstanceName

public static java.lang.String getLongInstanceName(java.lang.String declname)

Given the fully qualified name of a struct or node declaration, return the fully qualified name of the corresponding instance message.

writeMessageImports

public static void writeMessageImports(java.io.PrintStream out,
                                       org.sandev.sandbuild.SandDecl[] decls)

Write out the import statements for the messages we are dealing with so the generated code can use the short names.

isParentAbstract

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

Returns true if the parent class is an abstract struct definition.

isRootStruct

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

Returns true if this struct definition does not extend any other struct, or extends an abstract struct.

isLongReferenceArray

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

Return true if this field is a reference array, false otherwise

copyfile

public void copyfile(java.lang.String srcfile,
                     java.lang.String destdir)
              throws org.sandev.sandbuild.SandGeneratorException

Wrapper to access copyfile utility in the SandProject class.

Throws:

org.sandev.sandbuild.SandGeneratorException

deletefile

public void deletefile(java.lang.String filespec)
                throws org.sandev.sandbuild.SandGeneratorException

Wrapper to access deletefile utility in the SandProject class.

Throws:

org.sandev.sandbuild.SandGeneratorException

writeHTMLContents

public void writeHTMLContents(java.lang.String filespec,
                              java.io.PrintStream out)
                       throws org.sandev.sandbuild.SandGeneratorException

Write everything between the body open line and the body close line to the given output stream.

Throws:

org.sandev.sandbuild.SandGeneratorException

filterHTMLLine

protected java.lang.String filterHTMLLine(java.lang.String line)
                                   throws org.sandev.sandbuild.SandGeneratorException

Called from writeHTMLContents for each line being written to provide an opportunity to change the text. Override this method in a class extending from here to provide the filtering capabilities. The default implementation just returns the original input.

Throws:

org.sandev.sandbuild.SandGeneratorException

writeXHTMLHeader

protected void writeXHTMLHeader(java.io.PrintStream out,
                                java.lang.String title)

Write the standard XHTML file preamble.

writeXHTMLHeader

protected void writeXHTMLHeader(java.io.PrintStream out,
                                java.lang.String title,
                                boolean includeBodyTag,
                                java.lang.String bgcolor)

Write the standard XHTML file preamble.

writeXHTMLFooter

protected void writeXHTMLFooter(java.io.PrintStream out)

Write the standard XHTML file postamble.

writeXHTMLFooter

protected void writeXHTMLFooter(java.io.PrintStream out,
                                boolean includeBodyTag)

Write the standard XHTML file postamble.

getSandProject

protected org.sandev.sandbuild.SandProject getSandProject(java.io.File projDir)
                                                   throws org.sandev.sandbuild.SandGeneratorException

Return the current SandProject.

Throws:

org.sandev.sandbuild.SandGeneratorException

removePlatformDecls

protected org.sandev.sandbuild.SandDecl[] removePlatformDecls(org.sandev.sandbuild.SandDecl[] decls)

Remove any platform specific declarations and return the resulting array. This pulls anything starting with org.sandev.tools and returns the resulting decl array. Useful for aggregate generators targeting source in the triggering build.

getLastAppProject

protected org.sandev.sandbuild.SandProject getLastAppProject()

Return the SandProject just before the triggering build project. For example in the TaskHeapDemo deployment, this would return the apps/TaskHeap project.

getUtilPackage

protected java.lang.String getUtilPackage(org.sandev.sandbuild.SandProject proj)
                                   throws org.sandev.sandbuild.SandGeneratorException

Return the name of the util package for the given project. This method assumes there is at least one struct declaration in the given project which it uses as a base package specification. It then returns that package with the .structs part replaced with .util instead. So for example this might return org.sandev.basics.taskheap.util

Throws:

org.sandev.sandbuild.SandGeneratorException

getLastUtilDir

protected java.lang.String getLastUtilDir()
                                   throws org.sandev.sandbuild.SandGeneratorException

Return the name of the util directory of the last project before the triggering deployment build. For example in the TaskHeapDemo deployment, this would return the src util directory for TaskHeap.

The returned util directory may or may not already exist. This method does not create it.

Throws:

org.sandev.sandbuild.SandGeneratorException

getFields

public static com.sun.javadoc.FieldDoc[] getFields(com.sun.javadoc.ClassDoc cd,
                                                   boolean inherit,
                                                   int context)

Given a ClassDoc, return all the fields for it, including any synthetic fields generated for SAND. This method is pretty large, but the complexity resulting from lots of declarations and submethods everywhere gets very ugly, very fast. Especially from the documentation, which is what most people use to figure out what utility methods are available. So this is long, but central.

Each field has its own logic about when it should be added. For consistency, we are using equality tests for relevant contexts, so it is easier to read.

Parameters:

inherit - If true, then the inherited FieldDocs are included in the result array. Otherwise only the fields for the specific class will be returned. Synthetic fields are part of the message, not the struct, and are therefore not inherited.

context - One of the CONTEXT_* constants. See the SAND overview for details.

getDeclaredFields

public static java.util.ArrayList getDeclaredFields(com.sun.javadoc.ClassDoc cd,
                                                    boolean inherit,
                                                    int context)

Return an ArrayList containing all the fields for this class, including inherited fields if requested.

getVisibleFields

public static java.util.ArrayList getVisibleFields(com.sun.javadoc.ClassDoc cd,
                                                   boolean inherit,
                                                   int context)

Return an ArrayList of the fields for the given class. Transient fields are visible but not persistent. If a transient field should be hidden from view then mark it as NODISP in the authorization.

getInheritanceHierarchy

public static com.sun.javadoc.ClassDoc[] getInheritanceHierarchy(com.sun.javadoc.ClassDoc cd,
                                                                 boolean includeAbstract)

Returns the inheritance hierarchy for the given ClassDoc. Useful for traversing the inheritance path for defined fields. If the class is a struct declared with the abstract structmessage flag, and includeAbstract is false, then inheritance stops at the first concrete class.

findStructDeclByShortname

public org.sandev.sandbuild.SandDecl findStructDeclByShortname(java.lang.String shortname)

Find a struct decl by its short name. Returns the named StructDecl or null if not found.

hasSubStructs

public static boolean hasSubStructs(org.sandev.sandbuild.SandDecl sd)

Return true if the given struct declaration has other struct declarations that extend it, false otherwise.