CruiseControl Plugins
Introduction
It's tough to imagine all of the ways that CruiseControl can be used. Different tools and subtle nuances in team style make it difficult to code a "one-size-fits-all" solution. As a result, CruiseControl has been designed as a small core with a very high-level implementation of continuous integration, with most of the implementation details delegated to plugins. This makes it easy to create new functionality, modify existing functionality, or remove unwanted functionality. Plugins also create a shallower learning curve when digging in the codebase, as you can be assured that all of the cvs functionality, for example, exists in one place. Encapsulating all of the functionality into plugins also makes testing easier.
- Design overview
- Types
- Initialization
- Execution
- Registration
- Plugin XML Documentation
- Default Registry
Plugin Design Overview
Plugins are represented by beans. Plugin classes are mapped to element names in the XML config file thanks to a process known as registration. Plugins distributed with cruisecontrol are all registered by default.
The configuration will be initiated by the
ProjectXMLHelper class which handles the mapping of the registered
plugin and delegates the plugin initialization to the
PluginXMLHelper
class. Once configured, the plugin is validated, and
executed at the appropriate time in the build cycle. This
execution time will depend on the plugin type.
Plugin Types
There are currently six different types of plugins that CruiseControl supports. Each has a slightly different role, but all are designed similarly. While they all implement different interfaces and have slightly different method names, we will refer to them collectively as plugins when discussing their similarities. The plugin types are:
Bootstrapper: run before the buildSourceControl: poll a code repository and determine if anything has changedBuilder: perform the actual building and testing of your codeLabelIncrementer: handles incrementing the label for you to use to tag your sourcePublisher: publish the results of your build, via email for exampleListener: handles project events
Plugin Initialization
The PluginXMLHelper will use introspection to
configure the bean.
Plugin configuration
In the case of normal initialization, the PluginXMLHelper will call setter methods that correspond to
attributes on your xml tag in the config file.
For example, the method setTarget(String target) on the
AntBuilder class corresponds to the attribute
target on the <ant/> element in the
config file. The parser is case insensitive, so the case need not match
from your attributes to your method names, so the standard
capitalization rules should apply.
It is possible for you to declare nested elements within your
plugin's declaration in the config file. In this case, CruiseControl
will expect your plugin class to implement an add or
create method for each nested element, depending whether your
nested element is itself a plugin or not:
- for nested elements that are also plugins, the
PluginXMLHelperdoesn't know to which class the element should map and then asks theProjectXMLHelperto configure the element. - for simple (non plugins) nested elements, the plugin knows the
type that will map to the config element name. Returning to our example
AntBuilderclass, we will see acreateJVMArg()method. We'll also see thatAntBuilderhas a nested JVMArg class. This create method is responsible for creating an instance ofJVMArgand keeping a reference to that object forAntBuilderto use later. It returns a reference to the newly createdJVMArgobject, so thatPluginXMLHelpercan configure the nested element in the same way as the parent element. In theory, there is no limit to the depth of your nesting, as long as the appropriate create methods have been written.
Plugin Validation
Immediately after the parser has configured your plugin, we will
validate the plugin using it's own validate() method.
This will enable us to fail quickly if your plugin has been incorrectly
configured, saving you the time of waiting for your plugin to execute to
determine whether your CruiseControl installation has been
successful.
Plugin Execution
After we have configured and validated all of the plugins, we will
begin executing them according to their type. Each plugin has an
"action" method that is the one method that CruiseControl will call when
executing your plugin. Let's take the example of the bootstrappers. At
the beginning of the build cycle, the first thing that we need to do is
to run the bootstrappers. We've already initialized and validated each
of these, so now we will just call the bootstrap() method
as we iterate over the list of registered bootstrappers. It's fairly
similar for each of the other types of plugins.
Plugin Registration
The registration of plugins is a simple and straightforward task.
Directly under the <cruisecontrol> element, or
within a <project> element, simply add a
<plugin name="" classname=""/> element,
where the name corresponds to the name you wish to use within the config
file, and the classname corresponds to the actual plugin Java class.
Plugins specified directly under the root element will be available
to all your projects, plugins under a project element will be only
available within that project. This is useful to override a plugin
like the labelincrementer for a single project.
In the interest of keeping config file sizes to a minimum, all plugins that ship with CruiseControl will be automatically registered. Should you wish to use one of the registered plugin names with your own custom plugin class, you can just explicitly register the plugin name and that will override the default registration.
Plugin Preconfiguration
On registering plugins, you can also define default values for some of the properties and nested elements of the plugins. You can do this by simply using the same attributes and child nodes as you would when using the plugin itself.
Defaults can be overridden when you actually use the plugin within a project. Note: when nested elements have a multiple cardinality, overriding an already pre-configured child element might accumulate them.
If you want to preconfigure an already registered plugin (whether
default plugin, or plugin registered at the root of the config), you may
leave out the classname attribute of the plugin element.
An example: to define some default values for the htmlemail
publisher, you can specify something like this in your config file:
<plugin name="htmlemail"
mailhost="smtp.example.com"
returnaddress="buildmaster@example.com"
subjectprefix="[CC]"
xsldir="C:\java\cruisecontrol-2.2.1\report\jsp\webcontent\xsl"
css="C:\java\cruisecontrol-2.2.1\report\jsp\webcontent\css\cruisecontrol.css">
<always address="project-dev@domain.com"/>
<plugin/>
Combined with ant style properties this can greatly reduce the size of your config files. In the extreme case you can create a template project where all that needs to be supplied is the project name:
<cruisecontrol>
<plugin name="project">
<bootstrappers>
<cvsbootstrapper localworkingcopy="projects/${project.name}"/>
</bootstrappers>
...
</plugin>
<project name="foo" />
<project name="bar" />
...
</cruisecontrol>
More information and examples can be found on the wiki.
Plugin XML Documentation
The config reference is automatically generated from comments and tags contained in the plugins code.
Here's a simple self-commented example:
/**
* This will make it into the plugin description.
* <p>You can also have HTML code </p>
* @cc-plugin
* @see other javadoc tags are not taken into account.
*/
public class MyPlugin {
/** The default value is automatically identified whenever possible */
private String myField = "defaultValue";
/**
* A comment that will describe the entry in the parameter table for the plugin.
* @required "the comment that will make it into the required column"
* @defaultValue "forceDefaultValue"
*/
public void setMyField(String myField) {
this.myField = myField;
}
/**
* A comment that will describe the entry in the Child table for the plugin.
* @cardinality 0..*
*/
public void addObject(Object object) {
...
}
}
For more information look at the gendoc API (FIXME link).
Default Plugin Registry
The following tables outlines the default plugin registry:
Bootstrappers
Source Controls
Builders
Label Incrementers
| Plugin Name | Class Name |
|---|---|
| labelincrementer | net.sourceforge.cruisecontrol.labelincrementers.DefaultLabelIncrementer |