https://github.com/jenkinsci/structs-plugin
Library plugin for DSL plugins that need concise names for Jenkins extensions
https://github.com/jenkinsci/structs-plugin
jenkins-api-plugin
Last synced: 11 months ago
JSON representation
Library plugin for DSL plugins that need concise names for Jenkins extensions
- Host: GitHub
- URL: https://github.com/jenkinsci/structs-plugin
- Owner: jenkinsci
- Created: 2015-12-20T21:18:38.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2025-05-30T19:41:32.000Z (about 1 year ago)
- Last Synced: 2025-05-31T04:44:55.396Z (about 1 year ago)
- Topics: jenkins-api-plugin
- Language: Java
- Homepage: https://plugins.jenkins.io/structs/
- Size: 504 KB
- Stars: 11
- Watchers: 99
- Forks: 35
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# Structs plugin
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](https://plugins.jenkins.io/job-dsl) 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.
``` java
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:
``` xml
org.jenkins-ci.plugins
structs
1.2
```
## Usage for DSL plugin developers
Look up an extension by its symbol:
``` java
@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](https://wiki.jenkins.io/display/JENKINS/Structured+Form+Submission) does it via `@DataBoundConstructor`:
``` java
new DescribableModel(Mailer.class).instantiate(
Collections.singletonMap("recipients", "kk@kohsuke.org"))
```
## Version history
Please refer to the [Changelog](CHANGELOG.md)