SCM plugin architecture

This section describes the basic architecture of an SCM plugin.

Disclaimer: Out of Date

This page is out of date! The pollChanges API has been deprecated in favor of a new API that can track multiple changes coming in while a build is waiting in the quiet period. You can find some info in the SCM javadoc hudson.scm.SCM and see Subversion Plugin for a sample implementation http://fisheye.hudson-ci.org/browse/Hudson/trunk/hudson/plugins/subversion. Hopefully this page will get updated someday too.. The SCM class

All SCM plugins are subclasses of hudson.scm.SCM. This class has four abstract methods that an SCM implementation must implement:

   public boolean checkout(AbstractBuild build, Launcher launcher, FilePath workspace, BuildListener listener, File changelogFile) throws IOException, InterruptedException;
   public boolean pollChanges(AbstractProject project, Launcher launcher, FilePath workspace, TaskListener listener) throws IOException, InterruptedException;
   public ChangeLogParser createChangeLogParser();
   public SCMDescriptor<?> getDescriptor();

The basic means of interaction between the plugin and the rest of hudson are the pollChanges and checkout methods, which are used, respectively, to poll the SCM for changes and to check out updated files. The createChangeLogParser method is supposed to return something that can parse an XML file with change set information, and getDescriptor to return a descriptor capable of creating instances of the actual SCM class.

Create the configuration options as normal fields, by adding fields to the SCM class they will be persisted when Hudson is stopped and started. If you have a field that should not be persisted to XML it should be marked as transient.

public class TeamFoundationServerScm extends SCM {

   private boolean cleanCopy;
   private String server;
   private String project;
   private String workspaceName;

   private String username;
   private String password;
   private String domain;
   ...

}

Methods

The following sections describe the methods in more detail. constructor

Create a constructor that takes non-transient fields, and add the annotation @DataBoundConstructor to it. Using the annotation helps the Stapler class to find which constructor that should be used when automatically copying values from a web form to a class.

@DataBoundConstructor public TeamFoundationServerScm(String server, String project, boolean cleanCopy,

         String username, String password, String domain, String workspaceName) {
   // Copying arguments to fields

}

checkout

The checkout method is expected to check out modified files into the project workspace. See below section for more information. pollChanges

The pollChanges method is expected to return if there has been any changes on the SCM repository or not. See below section for more information. createChangeLogParser

The checkout method should, besides checking out the modified files, write a changelog.xml file that contains the changes for a certain build. The changelog.xml file is specific for each SCM implementation, and the createChangeLogParser returns a parser that can parse the file and return a ChangeLogSet. See below section for more information. getDescriptor

Returns the ScmDescriptor<?> for the SCM object. The ScmDescriptor is used to create new instances of the SCM. For more information see next section.

@Override public SCMDescriptor<TeamFoundationServerScm> getDescriptor() {

   return PluginImpl.TFS_DESCRIPTOR;

}

The Descriptor class

The relationship of Descriptor and SCM (the describable) is akin to class and object. What this means is that the descriptor is used to create instances of the describable. Usually the Descriptor is an internal class in the SCM class named DescriptorImpl. The Descriptor should also contain the global configuration options as fields, just like the SCM class contains the configurations options for a job.

public class TeamFoundationServerScm extends SCM {

   ...

   public static class DescriptorImpl extends SCMDescriptor {
       private String tfExecutable;

       protected DescriptorImpl() {
           super(TeamFoundationServerScm.class, null);
           load();
       }
       ...
   }

}

Methods

Methods that will be overriden

   public String getDisplayName()
   public boolean configure(StaplerRequest req) throws FormException

getDisplayName

Returns the name of the SCM, this is the name that will show up next to CVS and Subversion when configuring a job.

@Override public String getDisplayName() {

   return "Team Foundation Server";

}

configure

The method is invoked when the global configuration page is submitted. In the method the data in the web form should be copied to the Descriptor's fields. To persist the fields to the global configuration XML file, the save() method must be called. Data is defined in the global.jelly page.

@Override public boolean configure(StaplerRequest req) throws FormException {

   tfExecutable = Util.fixEmpty(req.getParameter("tfs.tfExecutable").trim());
   save();
   return true;

}

The PluginImpl class

All plugins must have a class that extends the Plugin class and registers the SCMDescriptor's (and other descriptors) with Hudson (actually, Hudson now allows you to omit this class and use the @Extension annotation to register the descriptor).

public class PluginImpl extends Plugin {

   public static final TeamFoundationServerScm.DescriptorImpl TFS_DESCRIPTOR = new TeamFoundationServerScm.DescriptorImpl();

   /**
    * Registers SCMDescriptors with Hudson.
    */
   @Override
   public void start() throws Exception {
       SCMS.SCMS.add(TFS_DESCRIPTOR);
       super.start();
   }

}

Jelly files

The jelly files for the Descriptor go into the src/main/resources/hudson/plugins/$plugin-name/$PluginScm/ folder where $plugin-name is the name of your plugin and $PluginScm is the plugin's SCM class implementation. For the Team Foundation Server plugin this path is /src/main/resources/hudson/plugins/tfs/TfsScm. The jelly files are the configuration view for the SCM class. global.jelly

Contains global configuration that is displayed in system configuration page. Typical configuration parameters that is going to be used by all Hudson jobs, for example the path to the SCM tool.

<j:jelly xmlns:j="jelly:core" xmlns:st="jelly:stapler" xmlns:d="jelly:define"

        xmlns:l="/lib/layout" xmlns:t="/lib/hudson" xmlns:f="/lib/form">
 <f:section title="Team Foundation Server">
   <f:entry title="TF command line executable"  help="/plugin/tfs/tfExecutable.html">
     <f:textbox name="tfs.tfExecutable" value="${descriptor.tfExecutable}"
                checkUrl="'${rootURL}/scm/TeamFoundationServerScm/executableCheck?value='+escape(this.value)"/>
   </f:entry>
 </f:section>

</j:jelly>

The field tfs.tfExecutable will be populated with the string from DescriptorImpl.getTfExecutable(). The method should return "tfs" by default.

public String getTfExecutable() {

   if (tfExecutable == null) {
       return "tfs";
   } else {
       return tfExecutable;
   }

}

The field tfs.tfsExecutable will also validate the entered tool path through checkUrl. When the user has entered a path (and moves the focus away from field) Hudson will call DescriptorImpl.doExectuableCheck to validate that the path can be found.

public FormValidation doExecutableCheck(@QueryParameter String value) {

   return FormValidation.validateExecutable(value);

}

config.jelly

Contains configuration for one Hudson job. Typical configuration parameters that used in a job, such as server URL, etc. The fields in the jelly file should correspond to the fields in the SCM class.

<j:jelly xmlns:j="jelly:core" xmlns:st="jelly:stapler" xmlns:d="jelly:define"

        xmlns:l="/lib/layout" xmlns:t="/lib/hudson" xmlns:f="/lib/form">
   <f:entry title="Server URL" help="/plugin/tfs/server.html">
       <f:textbox name="tfs.server" value="${scm.server}"/>
   </f:entry>

   <f:entry title="Name of project" help="/plugin/tfs/project.html">
       <f:textbox name="tfs.project" value="${scm.project}"
            checkUrl="'/fieldCheck?errorText=${h.jsStringEscape(h.encode('%Project is mandatory.'))}&value='+encode(this.value)"/>
   </f:entry>

   <f:advanced>

       <f:entry title="Clean copy">
           <f:checkbox name="tfs.cleanCopy" checked="${scm.cleanCopy}"/>
               If checked, Hudson will delete the directory and all its contents before downloading the files
               from the repository for every build.
       </f:entry>

       <f:entry title="Workspace name" help="/plugin/tfs/workspacename.html">
           <f:textbox name="tfs.workspaceName" value="${scm.workspaceName}"/>
       </f:entry>

   </f:advanced>

</j:jelly>

As with the Descriptor the web form fields are populate from the SCM object through properties, the value for "tfs.server" is retrieved from the TeamFoundationServerScm.getServer() method.

public String getServer() {

   return server;

}

public boolean isCleanCopy() {

   return cleanCopy;

} ....

The tfs.project field is mandatory and will display an error text below it if the field is empty. The error text is defined by the checkUrl attribute, and can be also used to validate numbers. The checkUrl can be used for more advanced validating such as testing the server if it exists and needs credentials. HTML Help files

For each entry in a jelly file that has a help attribute Hudson will display a help icon to the right. When the icon is clicked the named HTML page will be inlined just below the entry field. The HTML page must reside in the src/main/webapp folder. server.html

The name or URL of the team foundation server. If the server has been registered on the machine then it is only necessary to enter the name.