Package org.jenkinsci.plugins.workflow.cps

Class GlobalVariable

java.lang.Object

org.jenkinsci.plugins.workflow.cps.GlobalVariable

All Implemented Interfaces:

ExtensionPoint

Direct Known Subclasses:

EnvActionImpl.Binder, ParamsVariable, RunWrapperBinder

public abstract class GlobalVariable
extends Object
implements ExtensionPoint

Defines a provider of a global variable offered to flows. Within a given flow execution, the variable is assumed to be a singleton. It is created on demand if the script refers to it by name.

Note: This extension point was designed for a handful of variables defined by generic Pipeline plugins. If you find yourself implementing this in a domain-specific plugin, you are probably doing too much work and harming usability in the process. For example, there will be no Snippetizer integration except to list its name and help text. Variables will also not generally be compatible with Declarative Pipeline, and may not work at all in alternate FlowExecution implementations. It is also all too easy to introduce security vulnerabilities for variables implemented using Groovy code. Just because you can does not mean you should. If at all possible, limit your plugin to implementing plain Steps.

Should have a view named help offering usage.

See Also:

GlobalVariableSet

Nested Class Summary

Nested classes/interfaces inherited from interface hudson.ExtensionPoint

ExtensionPoint.LegacyInstancesAreScopedToHudson

Field Summary

Fields

Modifier and Type	Field	Description
static Iterable<GlobalVariable>	ALL	Deprecated. use forRun(hudson.model.Run<?, ?>) instead

Constructor Summary

Constructors

Constructor	Description
GlobalVariable()

Method Summary

Modifier and Type	Method	Description
static GlobalVariable	byName(String name, Run<?,?> run)	Finds a particular variable by name.
static Iterable<GlobalVariable>	forJob(Job<?,?> job)	Returns all the registered GlobalVariables for some context.
static Iterable<GlobalVariable>	forRun(Run<?,?> run)	Returns all the registered GlobalVariables for some context.
abstract String	getName()	Defines the name of the variable.
abstract Object	getValue(CpsScript script)	Gets or creates the singleton value of the variable.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ALL

@Deprecated
public static final Iterable<GlobalVariable> ALL

Deprecated.

use forRun(hudson.model.Run<?, ?>) instead

Constructor Detail

GlobalVariable

public GlobalVariable()

Method Detail

getName

@NonNull
public abstract String getName()

Defines the name of the variable.

Returns:

a Java identifier

getValue

@NonNull
public abstract Object getValue(@NonNull
                                CpsScript script)
                         throws Exception

Gets or creates the singleton value of the variable. If the object is stateful, and the state should not be managed externally (such as with a RunAction2), then the implementation is responsible for saving it in the Script.getBinding().

Parameters:

script - the script we are running

Returns:

a POJO or GroovyObject

Throws:

Exception - if there was any problem creating it (will be thrown up to the script)

See Also:

CpsScript.getProperty(java.lang.String)

forRun

@NonNull
public static Iterable<GlobalVariable> forRun(@CheckForNull
                                              Run<?,?> run)

Returns all the registered GlobalVariables for some context.

Parameters:

run - see GlobalVariableSet.forRun(hudson.model.Run<?, ?>)

Returns:

a possibly empty list

forJob

@NonNull
public static Iterable<GlobalVariable> forJob(@CheckForNull
                                              Job<?,?> job)

Returns all the registered GlobalVariables for some context.

Parameters:

job - see GlobalVariableSet.forJob(hudson.model.Job<?, ?>)

Returns:

a possibly empty list

byName

@CheckForNull
public static GlobalVariable byName(@NonNull
                                    String name,
                                    @CheckForNull
                                    Run<?,?> run)

Finds a particular variable by name.

Parameters:

name - see getName()

run - see GlobalVariableSet.forRun(hudson.model.Run<?, ?>)

Returns:

the first matching variable, or null if there is none