org.sandev.sandbuild
Class SandBuildDriver

java.lang.Object
  org.sandev.sandbuild.SandBuildDriver

All Implemented Interfaces:

LineCounter

public class SandBuildDriver
extends java.lang.Object
implements LineCounter

The SAND build structure for runtime execution. This holds all the component projects in dependency order and all the generator declarations. The SandBuildDriver is accessed as a singleton.

Field Summary

protected java.util.Collection	allGens a collection of all the SandGenDecls for the build
protected SandDecl[]	allNodes all the node declarations for the build
protected SandDecl[]	allStructs all the struct declarations for the build
protected SandDecl[]	allStructsAndNodes all the struct and node declarations for the build
protected SandProject	buildRoot The project to start the build with.
protected SandProject	buildTrigger The project that started the build.
protected java.util.Collection	dirtyFiles a collection of dirty file names
protected int	fileCount
protected int	lineCount
protected int	mode One of the MODE_* values.
static int	MODE_BUILD we are building
static int	MODE_CLEAN we are cleaning
protected SandDeploymentPackager	packager The SandDeploymentPackager that will be used to build the finished SAND application.
protected int	scope One of the SCOPE_* values.
static int	SCOPE_GLOBAL build the entire dependency graph
static int	SCOPE_LOCAL just build the current project
protected static SandBuildDriver	singleton The singleton reference to the SandBuildDriver
protected int	type One of the TYPE_* values.
static int	TYPE_ALL build both static and dynamic targets
static int	TYPE_DYNAMIC build generated targets (generators, envfiles, javadoc)
static int	TYPE_STATIC build only static code targets (compile, .jar etc)

Constructor Summary

protected

SandBuildDriver() Use getSandBuildDriver accessor to retrieve the SandBuildDriver instance.

Method Summary

void	appendProject(java.lang.String sandDir) Like requiredProject, except the specified project is appended to the end of the dependency graph.
void	buildGenerators(SandProject proj) Build the generators for this project and any downstream projects.
void	cleanGenerators(SandProject proj) Clean up the generators for this project and any downstream projects.
void	countFile(java.lang.String filename)
void	countLine(java.lang.String line) Given a line for output, increment the count.
void	doDownstreamFiles(SandProject currProj) Deal with moving jar, war, and sandenvfile declarations for downstream projects.
void	doDownstreamFiles(SandProject proj, java.lang.String filename, boolean isDeclaredEnvFile) recursive workhorse.
protected void	doGen(SandProject proj, java.lang.String declFiles, java.lang.String genPath) Given all the initialized data structures, run the generators for this project and all subprojects.
protected java.util.Collection	doGenerators() Build and run all the declared generators
protected void	doProjectTree(SandProject proj, java.util.Collection dirtyFiles) Walk through the projects in dependency order and build each one.
void	dumpDependencyGraph(SandProject proj, java.lang.String indent) Recursively dump out the given root and it's downstream projects.
SandProject	findProject(java.lang.String projname) Return the SandProject instance matching this name, or null if no instance was found off the buildRoot.
SandProject	findProjectParent(SandProject currProj, java.lang.String childname) Recursive workhorse.
SandProject	findProjectParent(java.lang.String projname) Return the SandProject instance containing the specified project in its requiredBy.
java.util.Collection	getAllGens() accessor for allGens
SandDecl[]	getAllNodes() accessor for allNodes
SandDecl[]	getAllStructs() accessor for allStructs
SandDecl[]	getAllStructsAndNodes() accessor for allStructsAndNodes
SandProject	getBuildRoot() accessor for buildRoot
SandProject	getBuildTrigger() accessor for buildTrigger
protected java.lang.String	getDeclFiles(java.util.Collection allStructs, java.util.Collection allNodes, java.lang.String sandhome) The GenDriverDoclet needs a CSV list of all the struct and node declaration files as input.
java.util.Collection	getDirtyFiles() accessor for dirtyFiles
int	getFileCount()
protected java.lang.String	getGenPath(SandProject root) Build a path specification out of the generator .jar files we have built.
SandProject	getLeafmostProject(SandProject proj) Given a SandProject reference, return the leafmost project in the dependency graph.
int	getLineCount() Return the line count
int	getMode() accessor for mode
SandDeploymentPackager	getPackager() accessor for packager
static SandBuildDriver	getSandBuildDriver()
static java.lang.String	getSandHome(SandProject proj) Use the given project to look up the SAND_HOME property from Ant.
int	getScope() accessor for scope
int	getType() accessor for type
static SandBuildDriver	initializeSandBuildDriverSingleton()
protected void	initSandDecls(SandProject proj, java.util.Collection allGens, java.util.Collection allStructs, java.util.Collection allNodes) Walk the project tree from the given root downwards, setting up the generator, struct and node collections.
void	loadProject(SandProject proj) Given a project, process the SAND build declarations to setup dependencies, generators, and env files.
void	log(java.lang.String text) This is how we dump processing messages and such.
protected boolean	nodoc() If the nodoc flag is set, then return true.
void	requiredProject(java.lang.String reqProject, java.lang.String currProject) Record the given project dependency.
void	runBuild() Do the build processing and return null if everything went fine.
java.util.Collection	runGenerators(SandProject root) Run the generators for this project and any downstream projects, returning the collection of any files that were changed.
void	setAllNodes(java.util.ArrayList decls) convenience wrapper for setAllNodes
void	setAllNodes(SandDecl[] decls) mutator for allNodes
void	setAllStructs(java.util.ArrayList decls) convenience wrapper for setAllStructs
void	setAllStructs(SandDecl[] decls) mutator for allStructs
void	setAllStructsAndNodes(java.util.ArrayList decls) convenience wrapper for setAllStructsAndNodes
void	setAllStructsAndNodes(SandDecl[] decls) mutator for allStructsAndNodes
void	setBuildRoot(SandProject newRoot) mutator for buildRoot.
void	setBuildTrigger(SandProject trigger) mutator for buildTrigger
void	setBuildTriggerDir(java.lang.String buildTriggerDir, SandProject proj) Recursively walk the given project tree, setting the buildTriggerDir property of all projects to the given value.
void	setFileCount(int count)
void	setGenJarDir(java.io.File genJarDir, SandProject proj) Recursively walk the given project tree, setting the genJarDir property of all projects to point to the given root.
void	setLineCount(int count) Set the line count
void	setMode(int mode) mutator for mode
void	setPackager(SandDeploymentPackager val) mutator for packager
void	setScope(int scope) mutator for scope
void	setType(int type) mutator for type
protected void	setupGlobal() Setup for a global scope build.

Methods inherited from class java.lang.Object

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

Field Detail

singleton

protected static SandBuildDriver singleton

The singleton reference to the SandBuildDriver

scope

protected int scope

One of the SCOPE_* values.

SCOPE_GLOBAL

public static final int SCOPE_GLOBAL

build the entire dependency graph

See Also:

Constant Field Values

SCOPE_LOCAL

public static final int SCOPE_LOCAL

just build the current project

See Also:

Constant Field Values

type

protected int type

One of the TYPE_* values.

TYPE_STATIC

public static final int TYPE_STATIC

build only static code targets (compile, .jar etc)

See Also:

Constant Field Values

TYPE_DYNAMIC

public static final int TYPE_DYNAMIC

build generated targets (generators, envfiles, javadoc)

See Also:

Constant Field Values

TYPE_ALL

public static final int TYPE_ALL

build both static and dynamic targets

See Also:

Constant Field Values

mode

protected int mode

One of the MODE_* values.

MODE_BUILD

public static final int MODE_BUILD

we are building

See Also:

Constant Field Values

MODE_CLEAN

public static final int MODE_CLEAN

we are cleaning

See Also:

Constant Field Values

buildRoot

protected SandProject buildRoot

The project to start the build with. After this project, we build each project that required this one directly, then walk each of those projects and build the projects that required them, until all projects have been built. This is essentially a breadth first traversal of the spanning tree for the dependency graph.

Notes:

• If the project dependency graph is not traversable as a tree, then there is a cyclic build dependency structure, which can't be built. We don't generally trap for this case.
• When adding a new project, make sure the root ends up referencing the first node in the graph.

buildTrigger

protected SandProject buildTrigger

The project that started the build. This was the original buildRoot before any required projects were placed ahead of it in the build tree. This is useful if you want to know the triggering build from the generators. Making any sort of code dependencies based on this information is an anti-pattern since it breaks project modularity, but it is useful for documentation or other linkage considerations.

allGens

protected java.util.Collection allGens

a collection of all the SandGenDecls for the build

allStructs

protected SandDecl[] allStructs

all the struct declarations for the build

allNodes

protected SandDecl[] allNodes

all the node declarations for the build

allStructsAndNodes

protected SandDecl[] allStructsAndNodes

all the struct and node declarations for the build

dirtyFiles

protected java.util.Collection dirtyFiles

a collection of dirty file names

lineCount

protected int lineCount

fileCount

protected int fileCount

packager

protected SandDeploymentPackager packager

The SandDeploymentPackager that will be used to build the finished SAND application.

Constructor Detail

SandBuildDriver

protected SandBuildDriver()

Use getSandBuildDriver accessor to retrieve the SandBuildDriver instance.

Method Detail

getSandBuildDriver

public static SandBuildDriver getSandBuildDriver()

initializeSandBuildDriverSingleton

public static SandBuildDriver initializeSandBuildDriverSingleton()

getScope

public int getScope()

accessor for scope

setScope

public void setScope(int scope)

mutator for scope

getType

public int getType()

accessor for type

setType

public void setType(int type)

mutator for type

getMode

public int getMode()

accessor for mode

setMode

public void setMode(int mode)

mutator for mode

getBuildRoot

public SandProject getBuildRoot()

accessor for buildRoot

setBuildRoot

public void setBuildRoot(SandProject newRoot)

mutator for buildRoot. If buildRoot is null, and is being set to something other than null, and buildTrigger is null, then set buildTrigger as well.

getBuildTrigger

public SandProject getBuildTrigger()

accessor for buildTrigger

setBuildTrigger

public void setBuildTrigger(SandProject trigger)

mutator for buildTrigger

getAllGens

public java.util.Collection getAllGens()

accessor for allGens

getAllStructs

public SandDecl[] getAllStructs()

accessor for allStructs

setAllStructs

public void setAllStructs(SandDecl[] decls)

mutator for allStructs

setAllStructs

public void setAllStructs(java.util.ArrayList decls)

convenience wrapper for setAllStructs

getAllNodes

public SandDecl[] getAllNodes()

accessor for allNodes

setAllNodes

public void setAllNodes(SandDecl[] decls)

mutator for allNodes

setAllNodes

public void setAllNodes(java.util.ArrayList decls)

convenience wrapper for setAllNodes

getAllStructsAndNodes

public SandDecl[] getAllStructsAndNodes()

accessor for allStructsAndNodes

setAllStructsAndNodes

public void setAllStructsAndNodes(SandDecl[] decls)

mutator for allStructsAndNodes

setAllStructsAndNodes

public void setAllStructsAndNodes(java.util.ArrayList decls)

convenience wrapper for setAllStructsAndNodes

getDirtyFiles

public java.util.Collection getDirtyFiles()

accessor for dirtyFiles

getLineCount

public int getLineCount()

Description copied from interface: LineCounter

Return the line count

Specified by:

getLineCount in interface LineCounter

setLineCount

public void setLineCount(int count)

Description copied from interface: LineCounter

Set the line count

Specified by:

setLineCount in interface LineCounter

countLine

public void countLine(java.lang.String line)

Description copied from interface: LineCounter

Given a line for output, increment the count. The given line may be null or empty.

Specified by:

countLine in interface LineCounter

getFileCount

public int getFileCount()

setFileCount

public void setFileCount(int count)

countFile

public void countFile(java.lang.String filename)

getPackager

public SandDeploymentPackager getPackager()

accessor for packager

setPackager

public void setPackager(SandDeploymentPackager val)

mutator for packager

log

public void log(java.lang.String text)

This is how we dump processing messages and such.

runBuild

public void runBuild()
              throws SandBuildException

Do the build processing and return null if everything went fine. Otherwise return the error message to display.

Throws:

SandBuildException

doProjectTree

protected void doProjectTree(SandProject proj,
                             java.util.Collection dirtyFiles)
                      throws SandBuildException

Walk through the projects in dependency order and build each one. The generators have been run at this point if this was a global build. If this is a local build, then this is just a single project. Either way, this does the standard compile/jar/doc pass.

The dirtyFiles list is used for incremental javadoc and other tasks where we want to focus on changed files. It contains filenames known to have been changed by generators or other setup processing.

Throws:

SandBuildException

nodoc

protected boolean nodoc()

If the nodoc flag is set, then return true. Otherwise return false.

doDownstreamFiles

public void doDownstreamFiles(SandProject currProj)
                       throws SandBuildException

Deal with moving jar, war, and sandenvfile declarations for downstream projects.

For compilation purposes, jarfiles need to be copied downstream into the requiredBy projects. This movement is downstream only, an upstream project may not link to anything defined downstream. Here's what gets copied downstream:

1. The project .jar file. Since all projects copy their .jar files into all downstream projects, this enables proper compile time linkage and easy cleanup.
2. The project .war file. Since all projects copy their .war files into all downstream projects, the end deployment has all the webapps needed.
3. Any sandenvfile declared files. This can be third party .jar files or anything else that's needed.

Throws:

SandBuildException

doDownstreamFiles

public void doDownstreamFiles(SandProject proj,
                              java.lang.String filename,
                              boolean isDeclaredEnvFile)
                       throws SandBuildException

recursive workhorse.

Throws:

SandBuildException

setupGlobal

protected void setupGlobal()
                    throws SandBuildException

Setup for a global scope build.

Throws:

SandBuildException

doGenerators

protected java.util.Collection doGenerators()
                                     throws SandBuildException

Build and run all the declared generators

Throws:

SandBuildException

buildGenerators

public void buildGenerators(SandProject proj)
                     throws SandBuildException

Build the generators for this project and any downstream projects.

Throws:

SandBuildException

cleanGenerators

public void cleanGenerators(SandProject proj)
                     throws SandBuildException

Clean up the generators for this project and any downstream projects. Also clean up StructDecls.txt and NodeDecls.txt files created by tbe build.

Throws:

SandBuildException

runGenerators

public java.util.Collection runGenerators(SandProject root)
                                   throws SandBuildException

Run the generators for this project and any downstream projects, returning the collection of any files that were changed.

When this method is called, each SandProject has only its genDecls initialized, so the first thing we do is walk the projects setting up the structDecls and nodeDecls for each one. As we walk through, we also create the master declaration lists.

After setting things up, we walk the projects again. For each project, we walk the master list of generators, calling based on whether the runscope matches, and passing in the appropriate input as declared.

Throws:

SandBuildException

initSandDecls

protected void initSandDecls(SandProject proj,
                             java.util.Collection allGens,
                             java.util.Collection allStructs,
                             java.util.Collection allNodes)
                      throws SandBuildException

Walk the project tree from the given root downwards, setting up the generator, struct and node collections.

Throws:

SandBuildException

getDeclFiles

protected java.lang.String getDeclFiles(java.util.Collection allStructs,
                                        java.util.Collection allNodes,
                                        java.lang.String sandhome)
                                 throws SandBuildException

The GenDriverDoclet needs a CSV list of all the struct and node declaration files as input. Since some of the struct declarations reference general message interfaces defined in apps/basics, we need to include those files also.

Throws:

SandBuildException

getGenPath

protected java.lang.String getGenPath(SandProject root)
                               throws SandBuildException

Build a path specification out of the generator .jar files we have built. We need to pass this into the GenDriverDoclet path.

Throws:

SandBuildException

doGen

protected void doGen(SandProject proj,
                     java.lang.String declFiles,
                     java.lang.String genPath)
              throws SandBuildException

Given all the initialized data structures, run the generators for this project and all subprojects. This calls the GenDriverDoclet which initializes the ClassDoc references and calls each of the declared generators appropriately.

Throws:

SandBuildException

loadProject

public void loadProject(SandProject proj)
                 throws SandBuildException

Given a project, process the SAND build declarations to setup dependencies, generators, and env files.

Throws:

SandBuildException

dumpDependencyGraph

public void dumpDependencyGraph(SandProject proj,
                                java.lang.String indent)

Recursively dump out the given root and it's downstream projects.

setGenJarDir

public void setGenJarDir(java.io.File genJarDir,
                         SandProject proj)

Recursively walk the given project tree, setting the genJarDir property of all projects to point to the given root. The generator jar files are accumulated in root/build/env

setBuildTriggerDir

public void setBuildTriggerDir(java.lang.String buildTriggerDir,
                               SandProject proj)

Recursively walk the given project tree, setting the buildTriggerDir property of all projects to the given value.

appendProject

public void appendProject(java.lang.String sandDir)
                   throws SandBuildException

Like requiredProject, except the specified project is appended to the end of the dependency graph.

Assumptions:

• the buildRoot has been properly initialized
• the sandDir is a proper project specification

Throws:

SandBuildException

requiredProject

public void requiredProject(java.lang.String reqProject,
                            java.lang.String currProject)
                     throws SandBuildException

Record the given project dependency. This takes the SAND project name (eg apps/basics) as the first parameter, and the current project name (eg TaskHeap) as the second parameter. This buildRoot must have been properly initialized already.

The algorithm is "insert before with existence check". It is implemented as:

• find the current project (currProj) in the tree.
• if the required project (reqProj) already exists in front of currProj in the tree then return.
• if the reqProj exists after currProj, then we have an inconsitent dependency relationship. Complain.
• insert reqProj in front of currProj in the tree. So if currProj was the root, then reqProj is the new root and currProj is now a child. Otherwise if currProj was not the root, then it is a child of currParent and reqProj is inserted between currParent and currProj.

The algorithm works because the required project declarations are processed from the leafmost declaration (the deployment build) and then working back towards the root of the tree. So if your required project declarations make sense (right order, not circular etc) then it works out.

Throws:

SandBuildException

findProject

public SandProject findProject(java.lang.String projname)

Return the SandProject instance matching this name, or null if no instance was found off the buildRoot. The name in this case is the name of the project as declared in the ant build.xml file.

findProjectParent

public SandProject findProjectParent(java.lang.String projname)

Return the SandProject instance containing the specified project in its requiredBy. So this is the immediate upstream project in the spanning tree for the dependency graph. Note that while the spanning tree is being created, the structure may change, so this method may not always return the same instance. Once the tree is created, this information is static.

findProjectParent

public SandProject findProjectParent(SandProject currProj,
                                     java.lang.String childname)

Recursive workhorse.

getLeafmostProject

public SandProject getLeafmostProject(SandProject proj)

Given a SandProject reference, return the leafmost project in the dependency graph.

getSandHome

public static java.lang.String getSandHome(SandProject proj)
                                    throws SandBuildException

Use the given project to look up the SAND_HOME property from Ant. Remove any trailing file separator character from the result.

Throws:

SandBuildException