Plugin Information
View Structs on the plugin site for more information.

Library plugin for DSL plugins that need concise names for Jenkins extensions

Overview

Jenkins has many DSL like plugins that require having short concise names for implementations of the extension points and other Jenkins objects. For example, Job DSL Plugin refers to each SCM extension by its short name. The same goes for pipeline plugin.

It benefits users that these DSL plugins use consistent names. This plugin, together with the @Symbol annotation, allow plugin developers to name their extension and have all the DSL plugins recognize them.

Usage for developers creating any plugins

To allow all the DSL plugins to refer to your extensions by the same name, put @Symbol annotation along side your @Extension. The symbol name must be a valid Java identifier, and it should be short and concise. To keep the symbol name short, it needs to be only unique within the extension point. For example, GitSCM and GitToolInstaller should both have a symbol name git, because they are from different extension points. For compatibility reasons with DSL plugins that predates the structs plugin, some extensions may have legacy names that do not follow this convention.

public class GitSCM {
   ...

   @Extension @Symbol("git")
   public static class DescriptorImpl extends SCMDescriptor {
      ...
   }
}

If you are targeting 1.x version of Jenkins, you must also add the following dependency to your plugin POM:

    <dependency>
        <groupId>org.jenkins-ci.plugins</groupId>
        <artifactId>structs</artifactId>
        <version>1.2</version>
    </dependency>

Usage for DSL plugin developers

Look up an extension by its symbol:

@Extension @Symbol("foo")
public class FooGlobalConfiguration extends GlobalConfiguration {
   ...
}

// this yields the FooGlobalConfiguration instance
SymbolLookup.get().find(GlobalConfiguration.class,"foo")

Construct a Describable object from a key/value pairs, much like how Structured Form Submission does it via @DataBoundConstructor:

new DescribableModel(Mailer.class).instantiate(Collections.singletonMap("recipients","kk@kohsuke.org"))

Changelog

Version 1.20 (Jul 29, 2019)

JENKINS-33217 - DescribableHelper does not detect stray parameters Resolved Log a warning when additional parameters are passed into `DescribableModel` objects, such as Pipeline steps, since these parameters are currently being ignored.
Internal - Update parent pom (PR-46) and fix unit tests (PR-50)

Version 1.19 (?)

TODO

Version 1.18 (Apr 25, 2019)

JENKINS-44892 - Ability to override reflective metadata in DescribableModel Resolved Add new CustomDescribableModel API to allow custom instantiation and uninstantiation for DescribableModel for advanced use cases.

Version 1.17 (Oct 05, 2018)

JENKINS-53917 - choice parameter no longer supports choices in pipeline Resolved Reverting change in 1.16.

Version 1.16 (Oct 04, 2018)

Analysis problems with ChoiceParameterDefinition.

Version 1.15 (Sept 25, 2018)

Automatically coerce String to a number or boolean when a parameter expects a number or boolean.

Version 1.14 (Feb 14, 2018)

Parameter handling (dependency for JENKINS-37215)

Version 1.13 (Feb 1, 2018)

Hotfix for sigh Groovy-related madness, partially reverting memory optimizations from 1.12
Minor correction to DescribableModel caching lookup
- Eliminates any risk looking up DescribableModels if different plugins somehow define identical but incompatible Describable classes in the same package and class

Version 1.12 (Feb 1, 2018)

Major Optimizations:
- Cache negative-hits in Symbol lookup (i.e. "no match"), eliminating needless classloading and iteration over classes.
- Cache DescribableModels, eliminating classloading associated with creation.
- Net result: huge reduction in disk reads, lock contention (classloading), CPU use, and memory garbage generated.
Minor optimization: reduce memory use and garbage generation (collection pre-sizing and use of Singleton collections)
JENKINS-46122 Report base class name when symbol couldn't be resolved

Version 1.10 (Aug 03, 2017)

Javadoc improvements.
Adjusting annotation-indexer version to match current core baseline, avoiding POM warnings in plugins depending on this one.

Version 1.9 (Jun 26, 2017)

JENKINS-45130 When uninstantiating, qualify otherwise ambiguous class names for array and list properties.

Version 1.8 (Jun 15, 2107)

JENKINS-44864 When uninstantiating, suppress values from @Deprecated setters where the values have no effect on the resulting object.

Version 1.7 (May 25, 2017)

JENKINS-43337 Snippet generation should qualify otherwise ambiguous class names.
JENKINS-34464 Allow binding of parameters of type Result, for example in the upstream trigger.
JENKINS-31967 Handle remaining primitive types for parameters, for example double in junit configuration.

Version 1.6 (Feb 13, 2017)

JENKINS-38157 Better diagnostics.
Allow Groovy GString to be used in more places.
API to check deprecation status of a type.

Version 1.5 (Aug 30, 2016)

JENKINS-37820 Stack overflow in 1.4 under certain conditions.

Version 1.4 (Aug 26, 2016)

JENKINS-37403 API for getting @Symbol off an Object.

Version 1.3 (Jul 28, 2016)

JENKINS-29922 Support for @Symbol in DescribableModel.

Version 1.2.0 (Jun 17, 2016)

Added method to query deprecated methods (PR #5)
Improve diagnostics for mismatched types (JENKINS-34070)
Prevent recursions in the DescribableModel.toString() method (PR #3, related to JENKINS-32925)

Version 1.1.1 (Jun 16, 2016)

Fix URL to the plugin's Wiki page in order to get it listed in Jenkins Update Center again (JENKINS-JENKINS-35918)

Version 1.1 (Mar 22, 2016)

Many small commits made by Unknown User (kohsuke)

Version 1.0 (Mar 18, 2016)

initial version

Jenkins : Structs plugin