57 lines
3.0 KiB
Markdown
57 lines
3.0 KiB
Markdown
# Developer documentation
|
|
|
|
This document describes the JCasC API and design for plugin developers who are interested in
|
|
extending JCasC by implementing custom Configurators or re-using the configuration mechanism
|
|
in another context.
|
|
|
|
Also see the plugin's [Javadoc](https://javadoc.jenkins.io/plugin/configuration-as-code/) for more information about classes and methods referenced on this page.
|
|
|
|
## Using Configuration as Code
|
|
|
|
### Configurators
|
|
|
|
Third party code to rely on JCasC has to create a key:value hierarchical representation of the target
|
|
component and its sub-components. This representation is defined by the `io.jenkins.plugins.casc.model` package,
|
|
and does not force use on any specific file format, despite we focus on YAML.
|
|
|
|
The main API is the `Configurator` which encapsulates access to the target component data model and how to create/configure it.
|
|
Such a data model is exposed to external usage as a set of `Attribute`s via the `Configurator.describe()` method.
|
|
Each key in the key:value representation used as configuration input, has to match an `Attribute`.
|
|
|
|
### ConfigurationContext
|
|
|
|
The configuration process only relies on `ConfigurationContext` to convert the key:value representation into a live
|
|
component instance. Third party components to use this mechanism can provide a custom context, while
|
|
JCasC relies on registered Jenkins components.
|
|
|
|
`ConfigurationContext` provides:
|
|
|
|
- tweaks support for deprecated and restricted attributes, as well as unknown input elements
|
|
- defines registry to retrieve Configurator for various component and classes to be configured
|
|
- offers option to register `Listener`s to get notified about the configuration process and react on errors
|
|
|
|
### YAML support
|
|
|
|
`io.jenkins.plugins.casc.yaml` package defines the implementation for loading the configuration from YAML sources.
|
|
`YamlUtils.loadFrom` encapsulates the YAML parsing and merge process from a set of YAML documents, while `YamlSource`
|
|
abstracts the way we load documents from files, URLs, or any other sources.
|
|
|
|
## Extending Configuration as Code
|
|
|
|
`Configurator` and `Attribute` are the core abstraction of Configuration as Code to offer implementation flexibility.
|
|
JCasC offers an implementation based on introspecting Java classes, relying on web UI data-binding
|
|
mechanisms for `DataBound` component, and on JavaBean conventions for others (Descriptors, Extensions).
|
|
|
|
To implement Configurator for some component which doesn't fit into this model, or to control the exposed data
|
|
model without relying on introspection, one can extend `BaseConfigurator` and override the `describe()` method to
|
|
control the exposed data model.
|
|
|
|
`Attribute`s exposed by this data model only have to define how to set value on target component and how to retrieve
|
|
current value from a live instance (used by `export` feature). Here again JCasC offers as default
|
|
implementation a JavaBean compliant implementation, but one could override get and/or set operation with custom
|
|
code to support alternate mechanisms.
|
|
|
|
## Useful links
|
|
|
|
* [Javadoc](https://javadoc.jenkins.io/plugin/configuration-as-code/)
|