Child pages
  • Manage global settings and tools installations

Due to some maintenance issues, this service has been switched in read-only mode, you can find more information about the why

and how to migrate your plugin documentation in this blogpost

Skip to end of metadata
Go to start of metadata

This is the 2nd part of the Plugin Developer tutorial.

Our plugin introduced a new build step to be configured on FreeStyle jobs. We will now add global, system-wide configuration (i.e. Jenkins > Manage Jenkins > Configure)

Global configuration

Do you know GRaveN can run your builds on the Cloud ? We will let user enable this option as a global setting. In our hudson.plugins.graven.GravenBuilder resource package we add a global.jelly view file. As the name suggest, such file will be used to configure global settings for the plugin component, that are managed by the Descriptor. This one then acts as a metadata container.

<?jelly escape-by-default='true'?>
<j:jelly xmlns:j="jelly:core" xmlns:f="/lib/form">

  <f:section title="${%GRaveN}" name="graven">
      <f:entry title="${%Send builds to the Cloud}" field="enableCloud">
        <f:checkbox/>
      </f:entry>
  </f:section>

</j:jelly>

Noticed in this global view that the section is set with a name="graven". As our form fields may collide with other plugin, especially if we use common names like name or path, we use a dedicated namespace to isolate plugin attributes form other plugins. The effect is that all form elements will be packaged in a dedicated graven JSON structure when sent back to the server, so we can easily filter the form data that match our component. 

As for config.jelly, we can define help tooltips as companion html files and support i18n with a bundle.

The Descriptor will get populated by this view if we override the configure method to retrieve data from the global configuration form submission

    @Extension
    public static class Descriptor extends BuildStepDescriptor<Builder> {

        private boolean enableCloud;

        public Descriptor() {
            load();
        }

        @Override
        public boolean configure(StaplerRequest req, JSONObject json) throws FormException {
            json = json.getJSONObject("graven");
            enableCloud = json.getBoolean("enableCloud");
            save();
            return true;
        }

        public boolean isEnableCloud() {
            return enableCloud;
        }
(...)

We can also use DataBinding, as we did with DataBoundConstructors, to avoid picking all form fields using a json.getXXX call, but for this to happen we have to either create setter method for the enableCloud attribute or declare it as public :

        @Override
        public boolean configure(StaplerRequest req, JSONObject json) throws FormException {
            req.bindJSON(this, json.getJSONObject("graven"));
            save();
            return true;
        }

        public void setEnableCloud(boolean enableCloud) {...}

Persist configuration

Just after binding the form submission to Descriptor attributes, we call the save method so that Jenkins will store the data in a dedicated XML file hudson.plugins.graven.GravenBuilder.xml in JENKINS_HOME. XStream is used to serialize data to configuration files, compared to other Java to XML binding solution, it has the benefits to be very flexible, so that we can easily support legacy configuration file when some attribute name have been refactored. To retrieve the saved data on Jenkins startup, we call the load method from the default constructor.

For GravenBuilder instances to access metadata in a simple way, we will use Java 5 covariant return type and override getDescriptor so that we can simply access our Descriptor singleton :

    public boolean isEnableCloud() {
        return getDescriptor().isEnableCloud();
    }

    @Override
    public Descriptor getDescriptor() {
        return (Descriptor) super.getDescriptor();
    }

Tools Installation

We could use this global configuration to manage GRaveN installation, so that user can choose the GRaveN version they want to build project with. This is such a common case in Jenkins, that there is already a pre-define canvas to support configuring installation and even auotmatic installation from a downloadable package.

We create a new Jenkins component to support GRaveN installation, with the adequate Descriptor :

/**
 * @author <a href="mailto:nicolas.deloof@cloudbees.com">Nicolas De loof</a>
 */
public class GravenInstallation extends ToolInstallation {

    @DataBoundConstructor
    public GravenInstallation(String name, String home, List<? extends ToolProperty<?>> properties) {
        super(name, home, properties);
    }

    @Extension
    public static final class Descriptor extends ToolDescriptor<GravenInstallation> {

        public Descriptor() {
            setInstallations();
            load();
        }

        @Override
        public String getDisplayName() {
            return "GRaveN";
        }

        @Override
        public GravenInstallation newInstance(StaplerRequest req, JSONObject formData) throws FormException {
            return (GravenInstallation) super.newInstance(req, formData.getJSONObject("gravenInstallation"));
        }
    }
}

Notice the call to setInstallation on Descriptor constructor to initialize a default empty installation set for new Jenkins instance, followed by a call to load to retrieve persisted configuration.

The newInstance method - that would by default search for a DataBoundConstructor to match the JSON form data - is overridden to extract the subset that matches our global configuration namespace for tool installation.

QUESTION : is there a way to only declare the namespace ? maybe this could be a valuable improvement to only override some JSONObject getJsonDataRoot(formData) or even just return the "namespace"

The associated view for this component is a config.jelly file. You may wonder this is not a global.jelly one, but note our Descriptor inherit from ToolDescriptor; Stapler view inherit from their parent view, and our descriptor will automatically be integrated in the ToolInstallation canvas that handles multiple ("repeatable") entries, additional properties, and more...

<j:jelly xmlns:j="jelly:core" xmlns:f="/lib/form">

  <f:entry title="${%Name}" field="name">
    <f:textbox/>
  </f:entry>

  <f:entry title="${%Home directory}" field="home">
      <f:textbox />
  </f:entry>

</j:jelly>


Do you notice the "install automatically" link ? This is a benefit from reusing ToolInstallation : as much tools can be installed from a downloadable zip and/or using some scripting, this configuration is provided by default, with extension point to provide your own ToolInstaller strategy when required. You can for example extend DownloadFromURLInstaller so that the tool will be downloaded from it's distribution site and installed on demand.

Path on slave

How to configure our tool installation if we distribute builds on slave executors ? They may use distinct location for tools or maybe even distinct Operatin Systems. As described in ToolInstallation javadoc, you are encouraged (but not required) to implement NodeSpecific and EnvironmentSpecific to help Jenkins translate the configured path to match the node/environment where the build will be executed. Let's do :

public class GravenInstallation extends ToolInstallation
       implements NodeSpecific<GravenInstallation>, EnvironmentSpecific<GravenInstallation> {

    public GravenInstallation forEnvironment(EnvVars environment) {
        return new GravenInstallation(getName(), environment.expand(getHome()), getProperties().toList());
    }

    public GravenInstallation forNode(Node node, TaskListener log) throws IOException, InterruptedException {
        return new GravenInstallation(getName(), translateFor(node, log), getProperties().toList());
    }
(...)

Those two methods allow to use environment variable and let Jenkins "expand" them at runtime to get execution path, as well as to translate path for a node, using node specific properties. This will aslo be used by automatic ToolInstaller to install the tools on node where it is not yet available.

  • No labels