org.sandev.generator
Class ProjectIndexGenerator

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

All Implemented Interfaces:

org.sandev.sandbuild.SandGenerator

public class ProjectIndexGenerator
extends org.sandev.generator.GeneratorCommon
implements org.sandev.sandbuild.SandGenerator

Write out a navigable web of documentation through interlinked index pages. The index pages have a navigable tree of the build, with SAND_HOME as the root. The index.html file for a given project is regenerated if any structs or nodes have been added or deleted, but this generator does not track changes in documentation source. If you delete the index.html file, it will be rebuilt.

Index page construction hooks:

• The contents of docs/intro.html (if found) are placed into the main display portion of the page.
• documents in the project docs directory are linked into the navigation bar
• loclink.html is used to create the local links for any given project.
• SAND_HOME/docs/globlink.html is used to create the global links for all projects.

The index page automatically provides:

• links to generator javadoc (if any)
• links to source javadoc (if any)
• a summary of struct and node declarations (if any)
• links to local deployment management tools (deployments only)

The structure and look of the index page may change between SAND environments, which is why this is part of the platform code.

Field Summary

protected org.sandev.sandbuild.SandProject[]	elemprojects An array of projects corresponding to the webelems elements.
static java.lang.String	FILE_GLOBLINK The name of the one file stored in the top level docs directory which contains links useful for all defined projects.
static java.lang.String	FILE_LOCLINK The name of the file which is defined in the local project's docs directory to hold useful links to other projects.
static int	MODE_CONDWRITE
static int	MODE_DELETE
static int	MODE_FORCEWRITE
protected java.lang.String	sandhome The directory specification for SAND_HOME.
protected java.lang.String[]	webelems Holds all the navtree elements as a list of canonical paths.

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

ProjectIndexGenerator()

Method Summary

void	cleanup(org.sandev.sandbuild.SandDecl[] decls, java.io.File baseDir, boolean changed, java.lang.String extra) Clean up the index html files.
protected int	countSlashes(java.lang.String val) Count the number of forward slashes in the given String.
protected void	dumpDeployTools(int elemindex, java.io.PrintStream out) If this is a deployment, dump links to the local deployment tools.
protected void	dumpDocwebSummary(int elemindex, java.io.PrintStream out) Dump out a summary of what project drove this build and what the overall structure is.
protected void	dumpIntroContents(int elemindex, java.io.PrintStream out) Retrieve the contents of the intro html file to display as the contents here.
protected void	dumpLink(java.io.PrintStream out, java.io.File file) Write out a link to this file, including the description if this is an html file.
protected void	dumpStructNodeSummary(int elemindex, java.io.PrintStream out) Dump a summary of the struct and node declarations for this project.
protected java.lang.String	filterHTMLLine(java.lang.String line) If the given line contains a node documentation link to be substituted then make that happen.
void	generate(org.sandev.sandbuild.SandDecl[] decls, java.io.File baseDir, boolean changed, java.util.Collection dirtyFiles, java.lang.String extra) Write the index html files.
protected java.lang.String	getCoreSpec(int elemindex) Returns the core specification for a webelem.
protected java.lang.String	getFileNameForWebElem(java.lang.String elem) Given a canonical webelem specification, return a platform appropriate filename.
protected java.lang.String	getIndent(int depth) Return a String with the appropriate amount of indenting for the depth given.
protected java.lang.String	getIntroFileSpec(int elemindex) Return the full file spec of the intro.html file
protected java.lang.String	getLinkForNodeName(java.lang.String nodename) Given a general node project name, return a relative link to the docs for it.
protected java.lang.String	getLinkFromSourceDecl(java.lang.String nodename, org.sandev.sandbuild.SandDecl currnode) Given a node name and the corresponding SandDecl, return a link to the docs for it.
protected java.lang.String	getRelSandHome(int elemindex) Return the relative path from a current element to SAND_HOME.
protected java.lang.String	getSandHome(java.io.File baseDir) Return the SAND_HOME directory with no trailing file separator.
protected org.sandev.sandbuild.SandProject[]	getSandProjects() Return an array of SandProjects for this build
protected void	getSandProjectsRec(java.util.ArrayList al, org.sandev.sandbuild.SandProject proj) Recursive workhorse for getSandProjects that walks the project tree and adds each element to the given ArrayList.
protected java.lang.String	getTitleForElem(int elemindex) Given a web element index, return the title for it.
protected void	initNavTreeElements() Set up the webelems and elemprojects arrays.
protected boolean	isGenDocFile(java.lang.String filespec) Return true if the given filename is a known generator file.
protected java.lang.String	makelink(int rootindex, int targindex, java.lang.String val) Return a hyperlink for the given entry.
protected boolean	projectChanged(org.sandev.sandbuild.SandProject proj, int elemindex) Return true if the given project exists, and a struct or node declaration was added or deleted, or the intro was changed.
protected void	writeBuildFileLink(int elemindex, java.io.PrintStream out) Write a link to the local build xml file if there is one.
protected void	writeDocLinks(int elemindex, java.io.PrintStream out) Write out links to the local top level docs.
protected void	writeGeneratorDocLink(int elemindex, java.io.PrintStream out) If there are generators defined for this project, then dump a link out to their javadoc.
protected void	writeGlobLinks(int elemindex, java.io.PrintStream out) Write the global links.
protected void	writeIndexFile(int elemindex) Write the web index file specified by the web element at the given index.
protected void	writeIndexFileContents(int elemindex, java.io.PrintStream out) Write the bulk of the index file.
protected void	writeLocalLinks(int elemindex, java.io.PrintStream out) Write the local links.
protected void	writeMainContents(int elemindex, java.io.PrintStream out) Write the contents of the right hand "main" area.
protected void	writeNavBarContents(int elemindex, java.io.PrintStream out) Write the contents of the left hand "navbar" area.
protected void	writeNavTree(int elemindex, java.io.PrintStream out) Write the navigation tree for the build
protected void	writeNodeTableEntry(org.sandev.sandbuild.SandDecl decl, java.lang.String docbase, java.io.PrintStream out) Write out a node entry cell for the struct and node summary table.
protected void	writeProjectLinks(int elemindex, java.io.PrintStream out) Write the navigation tree for the build
void	writeSandWeb(int mode, java.io.File baseDir) Starting from SAND_HOME, update the index pages according to the mode specified.
protected void	writeSourceDocLink(int elemindex, java.io.PrintStream out) If there is source defined for this project, then dump a link out to the javadoc for it.
protected void	writeStructTableEntry(org.sandev.sandbuild.SandDecl decl, java.lang.String docbase, java.io.PrintStream out) Write out a struct entry cell for the struct and node summary table.

Methods inherited from class org.sandev.generator.GeneratorCommon

capitalize, copyfile, deletefile, findStructDeclByShortname, getDeclaredFields, getFields, getInheritanceHierarchy, getLastAppProject, getLastUtilDir, getLongInstanceName, getPrintStream, getSandProject, getShortInstanceName, getUtilPackage, getVisibleFields, hasSubStructs, isArray, isBasic, isLongReferenceArray, isMessageInterface, isParentAbstract, isPrimitive, isRootStruct, isVowel, log, nextToken, pluralize, rangeEscape, removePlatformDecls, trackFileDelete, trackFileWrite, 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

Field Detail

MODE_FORCEWRITE

public static final int MODE_FORCEWRITE

See Also:

Constant Field Values

MODE_CONDWRITE

public static final int MODE_CONDWRITE

See Also:

Constant Field Values

MODE_DELETE

public static final int MODE_DELETE

See Also:

Constant Field Values

FILE_GLOBLINK

public static final java.lang.String FILE_GLOBLINK

The name of the one file stored in the top level docs directory which contains links useful for all defined projects. Current value is "globlink.html"

See Also:

Constant Field Values

FILE_LOCLINK

public static final java.lang.String FILE_LOCLINK

The name of the file which is defined in the local project's docs directory to hold useful links to other projects. Same format as FILE_GLOBLINK. Current value is "loclink.html"

See Also:

Constant Field Values

webelems

protected java.lang.String[] webelems

Holds all the navtree elements as a list of canonical paths. The paths all start with SAND_HOME and use forward slash notation. The elements are then manipulated at display time to write out the tree in HTML. An example value:

[0] "SAND_HOME/docs/index.html" [1] "SAND_HOME/apps/docs/index.html" [2] "SAND_HOME/apps/basics/docs/index.html" [3] "SAND_HOME/apps/TaskHeap/docs/index.html" [4] "SAND_HOME/deploy/docs/index.html" [5] "SAND_HOME/deploy/TaskHeapDemo/docs/index.html" [6] "SAND_HOME/platform/docs/index.html" [7] "SAND_HOME/platform/tools/docs/index.html"

Where "SAND_HOME" will vary depending on the environment.

elemprojects

protected org.sandev.sandbuild.SandProject[] elemprojects

An array of projects corresponding to the webelems elements. If there is no corresponding project, then the element is null.

sandhome

protected java.lang.String sandhome

The directory specification for SAND_HOME.

Constructor Detail

ProjectIndexGenerator

public ProjectIndexGenerator()

Method Detail

generate

public void generate(org.sandev.sandbuild.SandDecl[] decls,
                     java.io.File baseDir,
                     boolean changed,
                     java.util.Collection dirtyFiles,
                     java.lang.String extra)
              throws org.sandev.sandbuild.SandGeneratorException

Write the index html files. We are called once from the tools build, and we generate all the files in one pass. At the time of this call, the generator javadoc will have been done, but no source will have been compiled yet.

Specified by:

generate in interface org.sandev.sandbuild.SandGenerator

Throws:

org.sandev.sandbuild.SandGeneratorException

cleanup

public void cleanup(org.sandev.sandbuild.SandDecl[] decls,
                    java.io.File baseDir,
                    boolean changed,
                    java.lang.String extra)
             throws org.sandev.sandbuild.SandGeneratorException

Clean up the index html files.

Specified by:

cleanup in interface org.sandev.sandbuild.SandGenerator

Throws:

org.sandev.sandbuild.SandGeneratorException

writeSandWeb

public void writeSandWeb(int mode,
                         java.io.File baseDir)
                  throws org.sandev.sandbuild.SandGeneratorException

Starting from SAND_HOME, update the index pages according to the mode specified. This method is used by both SandGenerator interface methods, but may also be called directly.

Throws:

org.sandev.sandbuild.SandGeneratorException

getSandHome

protected java.lang.String getSandHome(java.io.File baseDir)

Return the SAND_HOME directory with no trailing file separator. This method assumes we are being called from the platform/tools project, so baseDir is SAND_HOME/platform/tools/build and we just need to walk upwards three levels.

initNavTreeElements

protected void initNavTreeElements()

Set up the webelems and elemprojects arrays.

getSandProjects

protected org.sandev.sandbuild.SandProject[] getSandProjects()

Return an array of SandProjects for this build

getSandProjectsRec

protected void getSandProjectsRec(java.util.ArrayList al,
                                  org.sandev.sandbuild.SandProject proj)

Recursive workhorse for getSandProjects that walks the project tree and adds each element to the given ArrayList.

getFileNameForWebElem

protected java.lang.String getFileNameForWebElem(java.lang.String elem)

Given a canonical webelem specification, return a platform appropriate filename. Since the SAND_HOME portion of the web element is set, this pretty much means changing the path separator characters from forward slash to backslash if windoze.

projectChanged

protected boolean projectChanged(org.sandev.sandbuild.SandProject proj,
                                 int elemindex)

Return true if the given project exists, and a struct or node declaration was added or deleted, or the intro was changed. Otherwise return false.

writeIndexFile

protected void writeIndexFile(int elemindex)
                       throws org.sandev.sandbuild.SandGeneratorException

Write the web index file specified by the web element at the given index.

Throws:

org.sandev.sandbuild.SandGeneratorException

getTitleForElem

protected java.lang.String getTitleForElem(int elemindex)

Given a web element index, return the title for it.

writeIndexFileContents

protected void writeIndexFileContents(int elemindex,
                                      java.io.PrintStream out)
                               throws org.sandev.sandbuild.SandGeneratorException

Write the bulk of the index file.

Throws:

org.sandev.sandbuild.SandGeneratorException

writeNavBarContents

protected void writeNavBarContents(int elemindex,
                                   java.io.PrintStream out)
                            throws org.sandev.sandbuild.SandGeneratorException

Write the contents of the left hand "navbar" area.

Throws:

org.sandev.sandbuild.SandGeneratorException

writeNavTree

protected void writeNavTree(int elemindex,
                            java.io.PrintStream out)
                     throws org.sandev.sandbuild.SandGeneratorException

Write the navigation tree for the build

Throws:

org.sandev.sandbuild.SandGeneratorException

getCoreSpec

protected java.lang.String getCoreSpec(int elemindex)

Returns the core specification for a webelem. This returns things like "" for the root, "apps" for a subarea, or "apps/basics" for a project.

makelink

protected java.lang.String makelink(int rootindex,
                                    int targindex,
                                    java.lang.String val)

Return a hyperlink for the given entry. These have to be relative paths so the links work both off files or off a webserver. We get the relative path to the root from where we are, and then tack on the unprefixed spec for the target doc to form the link URL.

getRelSandHome

protected java.lang.String getRelSandHome(int elemindex)

Return the relative path from a current element to SAND_HOME. This will return ".." or "../.." or "../../.." since each element starts in the /docs directory.

countSlashes

protected int countSlashes(java.lang.String val)

Count the number of forward slashes in the given String. Used for computing the depth of a directory off of SAND_HOME.

getIndent

protected java.lang.String getIndent(int depth)

Return a String with the appropriate amount of indenting for the depth given.

writeProjectLinks

protected void writeProjectLinks(int elemindex,
                                 java.io.PrintStream out)
                          throws org.sandev.sandbuild.SandGeneratorException

Write the navigation tree for the build

Throws:

org.sandev.sandbuild.SandGeneratorException

writeGlobLinks

protected void writeGlobLinks(int elemindex,
                              java.io.PrintStream out)
                       throws org.sandev.sandbuild.SandGeneratorException

Write the global links. These are from SAND_HOME/docs/globlink.html which we fetch from disk and dump out here. We need to translate this contents relative to each page, so we read it each time.

Throws:

org.sandev.sandbuild.SandGeneratorException

writeGeneratorDocLink

protected void writeGeneratorDocLink(int elemindex,
                                     java.io.PrintStream out)

If there are generators defined for this project, then dump a link out to their javadoc.

writeSourceDocLink

protected void writeSourceDocLink(int elemindex,
                                  java.io.PrintStream out)

If there is source defined for this project, then dump a link out to the javadoc for it.

writeBuildFileLink

protected void writeBuildFileLink(int elemindex,
                                  java.io.PrintStream out)

Write a link to the local build xml file if there is one.

writeLocalLinks

protected void writeLocalLinks(int elemindex,
                               java.io.PrintStream out)
                        throws org.sandev.sandbuild.SandGeneratorException

Write the local links. These are from the loclink.html in the current project which we fetch from disk and dump it out here.

Throws:

org.sandev.sandbuild.SandGeneratorException

writeDocLinks

protected void writeDocLinks(int elemindex,
                             java.io.PrintStream out)
                      throws org.sandev.sandbuild.SandGeneratorException

Write out links to the local top level docs.

Throws:

org.sandev.sandbuild.SandGeneratorException

dumpLink

protected void dumpLink(java.io.PrintStream out,
                        java.io.File file)
                 throws org.sandev.sandbuild.SandGeneratorException

Write out a link to this file, including the description if this is an html file.

Throws:

org.sandev.sandbuild.SandGeneratorException

isGenDocFile

protected boolean isGenDocFile(java.lang.String filespec)

Return true if the given filename is a known generator file. Otherwise return false. This is used to filter out known filenames that are part of the infrastructure.

writeMainContents

protected void writeMainContents(int elemindex,
                                 java.io.PrintStream out)
                          throws org.sandev.sandbuild.SandGeneratorException

Write the contents of the right hand "main" area.

Throws:

org.sandev.sandbuild.SandGeneratorException

dumpDocwebSummary

protected void dumpDocwebSummary(int elemindex,
                                 java.io.PrintStream out)
                          throws org.sandev.sandbuild.SandGeneratorException

Dump out a summary of what project drove this build and what the overall structure is.

Throws:

org.sandev.sandbuild.SandGeneratorException

dumpStructNodeSummary

protected void dumpStructNodeSummary(int elemindex,
                                     java.io.PrintStream out)

Dump a summary of the struct and node declarations for this project.

writeStructTableEntry

protected void writeStructTableEntry(org.sandev.sandbuild.SandDecl decl,
                                     java.lang.String docbase,
                                     java.io.PrintStream out)

Write out a struct entry cell for the struct and node summary table.

writeNodeTableEntry

protected void writeNodeTableEntry(org.sandev.sandbuild.SandDecl decl,
                                   java.lang.String docbase,
                                   java.io.PrintStream out)

Write out a node entry cell for the struct and node summary table.

dumpDeployTools

protected void dumpDeployTools(int elemindex,
                               java.io.PrintStream out)

If this is a deployment, dump links to the local deployment tools.

getIntroFileSpec

protected java.lang.String getIntroFileSpec(int elemindex)

Return the full file spec of the intro.html file

dumpIntroContents

protected void dumpIntroContents(int elemindex,
                                 java.io.PrintStream out)
                          throws org.sandev.sandbuild.SandGeneratorException

Retrieve the contents of the intro html file to display as the contents here.

Throws:

org.sandev.sandbuild.SandGeneratorException

filterHTMLLine

protected java.lang.String filterHTMLLine(java.lang.String line)

If the given line contains a node documentation link to be substituted then make that happen. Node doc links look like $NODEDOC(TaskHeapUI).

Overrides:

filterHTMLLine in class org.sandev.generator.GeneratorCommon

getLinkForNodeName

protected java.lang.String getLinkForNodeName(java.lang.String nodename)

Given a general node project name, return a relative link to the docs for it. Finds the appropriate SandDecl and calls through to getLinkFromSourceDecl.

getLinkFromSourceDecl

protected java.lang.String getLinkFromSourceDecl(java.lang.String nodename,
                                                 org.sandev.sandbuild.SandDecl currnode)

Given a node name and the corresponding SandDecl, return a link to the docs for it. Works by using the corresponding source file, or guessing based on the qualified name if the source file is not available. The returned link is relative to our current directory, which is assumed to be something like sand/deploy/TaskHeapDemo/docs.