org.sandev.sandbuild
Interface SandGenerator

public interface SandGenerator

A class implementing the SandGenerator interface can be invoked as part of the sandbox build. It is used to generate code and/or docs from the struct and/or node declarations, a process referred to as "metacoding". A generator declaration specifies:

• classname: the fully qualified name of SandGenerator implementor
• source: "structs" | "nodes" | "structsAndNodes" | "none"
  The input to a generator can be the struct declarations, the node declarations, or both, or none.
• sourcescope: "project" | "build"
  The scope of a generator may be the current project (in which case only the struct/node declarations for this project will be passed in), or the scope may be the entire build (in which case all the struct/node declarations for all projects in this build will be passed in).
• runscope: "project" | "build"
  This generator may be run once for only the current project, or it can be run once for each project in the build. By specifying a "build" runscope, a generator can affect every project that makes up a build. So for example, a generator with runscope="build" and sourcescope="project" will be run once for each project in the build, using the structs/nodes declared for that project (among other things, this is how messages are generated for structs across all projects in a build). A generator with runscope="project" and sourcescope="build" will be run for the current project only, with the declarations for all projects (among other things this is how the XMLSerializer is written).
• extra:
  Any extra information to be passed into the generator at runtime.

A SandGenerator is bound in scope to creating source code or source documentation. It is not intended for use with postprocessing of .class files, or other modifier actions. These are supported implicitely via the optional build targets on a per-project basis. A generator may not add or delete struct/node declarations, and is discouraged from modifying them. Again, use the optional build targets to hook high-level build processing.

Code generation is based on javadoc technology. See the doclet documentation, or existing generator classes, for details.

Notes on implementation:

1. Generators are expected to optimize their work. If no input to a generator has changed, then it should not produce new output. This optimization is critical to avoid ghost changes, and to avoid cascading work from other generators.
2. A generator is solely and fully responsible for cleaning up any files that it creates. Use platform-independent file access via relative path from the specified baseDir.
3. The code generation phase of the build is assumed to be a logical one-pass operation (the build calls all the generators and then it's done, it doesn't cycle until things stabilize). Use of cascading or dependent generators is allowed, but strongly cautioned except in the following known cases:
   • explicit call: one generator explicitely calls another on completion in order to continue work (possibly with additional state information).
   • catchall: a platform generator builds on the work from previous generators. Catchalls within a project are strongly discouraged since they limit modularity. A catchall generator within a deployment may be reasonable depending on circumstances.
4. By convention, generators *should* log a message when they write or delete a file. They *should not* generally log messages otherwise. This allows the person running the build to monitor the effects without having to be concerned with the internals or be flooded with information.

Method Summary

void	cleanup(SandDecl[] decls, java.io.File baseDir, boolean changed, java.lang.String extra) Delete generated files.
void	generate(SandDecl[] decls, java.io.File baseDir, boolean changed, java.util.Collection dirtyFiles, java.lang.String extra) Generate the code.

Method Detail

generate

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

Generate the code. The array of SAND declarations reflects the input as declared for the generator via the sourcescope. The basedir is the base directory of the current project, for example ../apps/basics. The changed flag is true if this generator has itself been changed since it was last run. This pretty much means the generator should redo all it's work regardless of the status of the declarations.

Changed struct and node declarations are redocumented to enable project link traversal, and avoid misleading documentation. If you want documentation regenerated for other files, add the full file spec to the dirty files list.

Throws:

SandGeneratorException

cleanup

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

Delete generated files. The parameters are the same as for for the generate method.

Throws:

SandGeneratorException