org.azyva.dragom.model.plugin

Interface BuilderPlugin

All Superinterfaces:

ModulePlugin, NodePlugin

public interface BuilderPlugin
extends ModulePlugin

Allows building (the source code of) a Module.

The notion of build is broad. It is up to implementations of this plugin to define exactly what is a build or what happens during a build.

Specifically the build of a Module generally involves taking source files and generating other files from them (compiling, packaging, etc.). But it can also involve executing unit tests on the compiled code after building. This can even very from Module to Module for the same plugin implementation. These different facets of builds are not exposed by this plugin.

Generally builds generate files from source files and the concept of cleaning the build environment for a Module makes sense. When this is so the isCleanSupported() should return true and isSomethingToClean(java.nio.file.Path) and clean(java.nio.file.Path, java.io.Writer) should be be implemented.

Generally the build process generates a log. build(java.nio.file.Path, java.lang.String, java.io.Writer) accepts a Writer allowing the plugin implementation to provide this log if desired. Build tools are expected to provide this Writer and in turn provide the generated log to the user, often at the console. The log can also be generated by the build process within a log file within the Module workspace directory. It is up to the plugin implementation to decide about whether to provide the build log through the Writer or a file, or both.

UserInteractionCallbackPlugin must not be used during the build (or clean) process since the provided Writer will generally have been obtained from UserInteractionCallbackPlugin.provideInfoWithWriter(java.lang.String) and using UserInteractionCallbackPlugin directly would violate its contract.

Generally a build executes within a process of its own so that not to be dependent on the Dragom execution environnement.

Builds are expected to be non interactive, or at least not expect user input to be provided via some standard input stream to the build process. If user input is required during a build (and it is not possible to provide the information using input parameters to the build process), it is the responsibility of the plugin implementation to handle the situation typically by monitoring the output stream of the build process and providing the required information programmatically to its input stream. The infomration can be obtained from the user, but using facilities provided by the framework such as UserInteractionCallbackPlugin.

Author:

David Raymond

Method Summary

Modifier and Type	Method and Description
boolean	build(Path pathModuleWorkspace, String buildContext, Writer writerLog) Builds the Module, generating files from the source files.
boolean	clean(Path pathModuleWorkspace, Writer writerLog) Cleans the workspace directory of the Module by removing files that are generated by builds of the Module, was opposed to source files.
boolean	isCleanSupported()
boolean	isSomethingToBuild(Path pathModuleWorkspace) Indicates if the Module has source files that are more recent than files generated by the previous build, or if the build of the Module would generate new files.
boolean	isSomethingToClean(Path pathModuleWorkspace) Indicates if there is something (build-related) to clean in the workspace directory for the Module.

Methods inherited from interface org.azyva.dragom.model.plugin.ModulePlugin

getModule

Methods inherited from interface org.azyva.dragom.model.plugin.NodePlugin

getNode

Method Detail

isSomethingToBuild

boolean isSomethingToBuild(Path pathModuleWorkspace)

Indicates if the Module has source files that are more recent than files generated by the previous build, or if the build of the Module would generate new files.

Parameters:

pathModuleWorkspace - Path to the Module within the workspace.

Returns:

Indicates if there is something to build.

build

boolean build(Path pathModuleWorkspace,
              String buildContext,
              Writer writerLog)

Builds the Module, generating files from the source files.

The buildContext parameter allows callers to give some indication of the context in which the build is performed. Here are examples of possible build contexts:

• new-static-version: When the Module is built before creating a new static version using Release from dragom-core;
• build: When the Module is built by Build from dragom-core.

It is up to the plugin implementation whether and how to take the context into consideration. See MavenBuilderPluginImpl from dragom-core for an example.

Parameters:

pathModuleWorkspace - Path to the Module within the workspace.

buildContext - Build context. Can be null.

writerLog - Writer where the log of the build process can be written. Can be null if the caller is not interested in the log. The Writer must not be closed, giving the caller control over its lifecycle.

Returns:

Indicates if the build process was successful.

isCleanSupported

boolean isCleanSupported()

Returns:

Indicates if the Module supports the notion of cleaning, regardless of its workspace directory.

isSomethingToClean

boolean isSomethingToClean(Path pathModuleWorkspace)

Indicates if there is something (build-related) to clean in the workspace directory for the Module.

Parameters:

pathModuleWorkspace - Path to the Module within the workspace.

Returns:

Indicates if there is something to clean.

clean

boolean clean(Path pathModuleWorkspace,
              Writer writerLog)

Cleans the workspace directory of the Module by removing files that are generated by builds of the Module, was opposed to source files.

Parameters:

pathModuleWorkspace - Path to the Module within the workspace.

writerLog - Writer where the log of the clean process can be written. Can be null if the caller is not interested in the log. The Writer must not be closed, giving the caller control over its lifecycle.

Returns:

Indicates if the clean process was successful.