This section describes the basic architecture of an SCM plugin.
All SCM plugins are subclasses of hudson.scm.SCM. This class has four abstract methods that an SCM implementation must implement:
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.
The following sections describe the methods in more detail.
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.
The checkout method is expected to check out modified files into the project workspace. See below section for more information.
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.
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.
Returns the ScmDescriptor<?> for the SCM object. The ScmDescriptor is used to create new instances of the SCM. For more information see next section.
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.
Methods that will be overriden
Returns the name of the SCM, this is the name that will show up next to CVS and Subversion when configuring a job.
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.
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).
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.
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.
The field tfs.tfExecutable will be populated with the string from DescriptorImpl.getTfExecutable(). The method should return "tfs" by default.
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.
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.
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.
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.
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.
Skip to end of metadata Go to start of metadata