Hosted By:
SourceForge
 

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.

  1. Design overview
  2. Types
  3. Initialization
  4. Execution
  5. Registration
  6. Plugin XML Documentation
  7. 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:

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:

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

Plugin Name Class Name
accurevbootstrapper net.sourceforge.cruisecontrol.bootstrappers.AccurevBootstrapper
alienbrainbootstrapper net.sourceforge.cruisecontrol.bootstrappers.AlienBrainBootstrapper
antbootstrapper net.sourceforge.cruisecontrol.bootstrappers.AntBootstrapper
clearcasebootstrapper net.sourceforge.cruisecontrol.bootstrappers.ClearCaseBootstrapper
clearcaseviewstrapper net.sourceforge.cruisecontrol.bootstrappers.ClearCaseViewstrapper
cmsynergybootstrapper net.sourceforge.cruisecontrol.bootstrappers.CMSynergyBootstrapper
cvsbootstrapper net.sourceforge.cruisecontrol.bootstrappers.CVSBootstrapper
execbootstrapper net.sourceforge.cruisecontrol.bootstrappers.ExecBootstrapper
gitbootstrapper net.sourceforge.cruisecontrol.bootstrappers.GitBootstrapper
harvestbootstrapper net.sourceforge.cruisecontrol.bootstrappers.AllFusionHarvestBootstrapper
lockfilebootstrapper net.sourceforge.cruisecontrol.bootstrappers.LockFileBootstrapper
mercurialbootstrapper net.sourceforge.cruisecontrol.bootstrappers.MercurialBootstrapper
p4bootstrapper net.sourceforge.cruisecontrol.bootstrappers.P4Bootstrapper
plasticscmbootstrapper net.sourceforge.cruisecontrol.bootstrappers.PlasticSCMBootstrapper
snapshotcmbootstrapper net.sourceforge.cruisecontrol.bootstrappers.SnapshotCMBootstrapper
starteambootstrapper net.sourceforge.cruisecontrol.bootstrappers.StarTeamBootstrapper
surroundbootstrapper net.sourceforge.cruisecontrol.bootstrappers.SSCMBootstrapper
svnbootstrapper net.sourceforge.cruisecontrol.bootstrappers.SVNBootstrapper
tfsbootstrapper net.sourceforge.cruisecontrol.bootstrappers.TFSBootstrapper
vssbootstrapper net.sourceforge.cruisecontrol.bootstrappers.VssBootstrapper

Source Controls

Plugin Name Class Name
accurev net.sourceforge.cruisecontrol.sourcecontrols.Accurev
alienbrain net.sourceforge.cruisecontrol.sourcecontrols.AlienBrain
alwaysbuild net.sourceforge.cruisecontrol.sourcecontrols.AlwaysBuild
buildstatus net.sourceforge.cruisecontrol.sourcecontrols.BuildStatus
clearcase net.sourceforge.cruisecontrol.sourcecontrols.ClearCase
cmsynergy net.sourceforge.cruisecontrol.sourcecontrols.CMSynergy
compound net.sourceforge.cruisecontrol.sourcecontrols.Compound
cvs net.sourceforge.cruisecontrol.sourcecontrols.ConcurrentVersionsSystem
darcs net.sourceforge.cruisecontrol.sourcecontrols.Darcs
filesystem net.sourceforge.cruisecontrol.sourcecontrols.FileSystem
forceonly net.sourceforge.cruisecontrol.sourcecontrols.ForceOnly
git net.sourceforge.cruisecontrol.sourcecontrols.Git
harvest net.sourceforge.cruisecontrol.sourcecontrols.AllFusionHarvest
httpfile net.sourceforge.cruisecontrol.sourcecontrols.HttpFile
mavensnapshotdependency net.sourceforge.cruisecontrol.sourcecontrols.MavenSnapshotDependency
maven2snapshotdependency net.sourceforge.cruisecontrol.sourcecontrols.Maven2SnapshotDependency
mks net.sourceforge.cruisecontrol.sourcecontrols.MKS
p4 net.sourceforge.cruisecontrol.sourcecontrols.P4
plasticscm net.sourceforge.cruisecontrol.sourcecontrols.PlasticSCM
pvcs net.sourceforge.cruisecontrol.sourcecontrols.PVCS
snapshotcm net.sourceforge.cruisecontrol.sourcecontrols.SnapshotCM
starteam net.sourceforge.cruisecontrol.sourcecontrols.StarTeam
store net.sourceforge.cruisecontrol.sourcecontrols.Store
surround net.sourceforge.cruisecontrol.sourcecontrols.SSCM
svn net.sourceforge.cruisecontrol.sourcecontrols.SVN
tfs net.sourceforge.cruisecontrol.sourcecontrols.TeamFoundationServer
timebuild net.sourceforge.cruisecontrol.sourcecontrols.TimeBuild
ucm net.sourceforge.cruisecontrol.sourcecontrols.UCM
veto net.sourceforge.cruisecontrol.sourcecontrols.Veto
vss net.sourceforge.cruisecontrol.sourcecontrols.Vss
vssjournal net.sourceforge.cruisecontrol.sourcecontrols.VssJournal

Builders

Plugin Name Class Name
ant net.sourceforge.cruisecontrol.builders.AntBuilder
composite net.sourceforge.cruisecontrol.builders.CompositeBuilder
exec net.sourceforge.cruisecontrol.builders.ExecBuilder
maven net.sourceforge.cruisecontrol.builders.MavenBuilder
maven2 net.sourceforge.cruisecontrol.builders.Maven2Builder
nant net.sourceforge.cruisecontrol.builders.NantBuilder
pause net.sourceforge.cruisecontrol.PauseBuilder
phing net.sourceforge.cruisecontrol.PhingBuilder
rake net.sourceforge.cruisecontrol.RakeBuilder

Label Incrementers

Plugin Name Class Name
labelincrementer net.sourceforge.cruisecontrol.labelincrementers.DefaultLabelIncrementer

Publishers

Plugin Name Class Name
antpublisher net.sourceforge.cruisecontrol.publishers.AntPublisher
artifactspublisher net.sourceforge.cruisecontrol.publishers.ArtifactsPublisher
clearcasebaselinepublisher net.sourceforge.cruisecontrol.publishers.ClearCaseBaselinePublisher
cmsynergybaselinepublisher net.sourceforge.cruisecontrol.publishers.CMSynergyBaselinePublisher
cmsynergytaskpublisher net.sourceforge.cruisecontrol.publishers.CMSynergyTaskPublisher
compoundpublisher net.sourceforge.cruisecontrol.publishers.CompoundPublisher
email net.sourceforge.cruisecontrol.publishers.LinkEmailPublisher
execute net.sourceforge.cruisecontrol.publishers.ExecutePublisher
ftppublisher net.sourceforge.cruisecontrol.publishers.FTPPublisher
htmlemail net.sourceforge.cruisecontrol.publishers.HTMLEmailPublisher
http net.sourceforge.cruisecontrol.publishers.HTTPPublisher
jabber net.sourceforge.cruisecontrol.publishers.LinkJabberPublisher
onfailure net.sourceforge.cruisecontrol.publishers.OnFailurePublisher
onsuccess net.sourceforge.cruisecontrol.publishers.OnSuccessPublisher
origo net.sourceforge.cruisecontrol.publishers.OrigoPublisher
rss net.sourceforge.cruisecontrol.publishers.RSSPublisher
sametimeannouncement net.sourceforge.cruisecontrol.publishers.SametimeAnnouncementPublisher
scp net.sourceforge.cruisecontrol.publishers.SCPPublisher
sfeefrs net.sourceforge.cruisecontrol.publishers.sfee.SfeeFrsPublisher
sfeetracker net.sourceforge.cruisecontrol.publishers.sfee.SfeeTrackerPublisher
sfeedocman net.sourceforge.cruisecontrol.publishers.sfee.SfeeDocumentManagerPublisher
socket net.sourceforge.cruisecontrol.publishers.SocketPublisher
weblog net.sourceforge.cruisecontrol.publishers.WeblogPublisher
x10 net.sourceforge.cruisecontrol.publishers.X10Publisher
xsltlogpublisher net.sourceforge.cruisecontrol.publishers.XSLTLogPublisher
yahoopublisher net.sourceforge.cruisecontrol.publishers.YahooPublisher

Listeners

Plugin Name Class Name
lockfilelistener net.sourceforge.cruisecontrol.listeners.LockFileListener
cmsynergysessionmonitor net.sourceforge.cruisecontrol.listeners.CMSynergySessionMonitor
currentbuildstatuslistener net.sourceforge.cruisecontrol.listeners.CurrentBuildStatusListener
currentbuildstatusftplistener net.sourceforge.cruisecontrol.listeners.CurrentBuildStatusFTPListener
currentbuildstatuspagelistener net.sourceforge.cruisecontrol.listeners.CurrentBuildStatusPageListener