Package org.jenkinsci.plugins.workflow.steps

Class EnvironmentExpander

java.lang.Object

org.jenkinsci.plugins.workflow.steps.EnvironmentExpander

All Implemented Interfaces:

Serializable

public abstract class EnvironmentExpander
extends Object
implements Serializable

Interface destined for StepContext.get(java.lang.Class<T>) instead of raw EnvVars. Pass into BodyInvoker.withContext(java.lang.Object).

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor	Description
EnvironmentExpander()

Method Summary

Modifier and Type	Method	Description
static EnvironmentExpander	constant(Map<String,String> env)	Provides an expander for a constant map of string keys and string values.
abstract void	expand(EnvVars env)	May add environment variables to a context.
static EnvVars	getEffectiveEnvironment(EnvVars customEnvironment, EnvVars contextualEnvironment, EnvironmentExpander expander)	Deprecated. Use getEffectiveEnvironment(EnvVars, EnvVars, EnvironmentExpander, StepContext, TaskListener) to allow StepEnvironmentContributors to run.
static EnvVars	getEffectiveEnvironment(EnvVars customEnvironment, EnvVars contextualEnvironment, EnvironmentExpander expander, StepContext stepContext, TaskListener listener)	Computes an effective environment in a given context.
Set<String>	getSensitiveVariables()	Get the names of environment variables known to contain sensitive values, such as secrets, in the current context.
static EnvironmentExpander	merge(EnvironmentExpander original, EnvironmentExpander subsequent)	Merge together two expanders.

Methods inherited from class java.lang.Object

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

Constructor Detail

EnvironmentExpander

public EnvironmentExpander()

Method Detail

expand

public abstract void expand(@NonNull
                            EnvVars env)
                     throws IOException,
                            InterruptedException

May add environment variables to a context.

Parameters:

env - an original set of environment variables

Throws:

IOException

InterruptedException

getSensitiveVariables

@NonNull
public Set<String> getSensitiveVariables()

Get the names of environment variables known to contain sensitive values, such as secrets, in the current context. Should be overridden by subclasses that bind secret values to environment variables.

Returns:

a set of environment variables known to contain sensitive values

constant

public static EnvironmentExpander constant(@NonNull
                                           Map<String,String> env)

Provides an expander for a constant map of string keys and string values. Supports EnvVars.override(String, String) behavior, such as PATH+XYZ overrides.

Parameters:

env - A non-null map of string keys and string values.

Returns:

An expander which will provide the given map.

merge

public static EnvironmentExpander merge(@CheckForNull
                                        EnvironmentExpander original,
                                        @NonNull
                                        EnvironmentExpander subsequent)

Merge together two expanders.

Parameters:

original - an original one, such as one already found in a context

subsequent - what you are adding

Returns:

an expander which runs them both in that sequence (or, as a convenience, just subsequent in case original is null)

getEffectiveEnvironment

@Deprecated
@NonNull
public static EnvVars getEffectiveEnvironment(@NonNull
                                              EnvVars customEnvironment,
                                              @CheckForNull
                                              EnvVars contextualEnvironment,
                                              @CheckForNull
                                              EnvironmentExpander expander)
                                       throws IOException,
                                              InterruptedException

Deprecated.

Use getEffectiveEnvironment(EnvVars, EnvVars, EnvironmentExpander, StepContext, TaskListener) to allow StepEnvironmentContributors to run.

Throws:

IOException

InterruptedException

getEffectiveEnvironment

@NonNull
public static EnvVars getEffectiveEnvironment(@NonNull
                                              EnvVars customEnvironment,
                                              @CheckForNull
                                              EnvVars contextualEnvironment,
                                              @CheckForNull
                                              EnvironmentExpander expander,
                                              @CheckForNull
                                              StepContext stepContext,
                                              @NonNull
                                              TaskListener listener)
                                       throws IOException,
                                              InterruptedException

Computes an effective environment in a given context. Used from DefaultStepContext and EnvActionImpl. The precedence order is:

1. StepEnvironmentContributors (if any)
2. expander (if any)
3. customEnvironment
4. contextualEnvironment (if any)

Parameters:

customEnvironment - Run.getEnvironment(TaskListener), or EnvironmentAction#getEnvironment

contextualEnvironment - a possible override as per BodyInvoker.withContext(java.lang.Object) (such as from Computer.getEnvironment() called from PlaceholderExecutable)

expander - a possible expander

stepContext - the context of the step being executed

listener - Connected to the build console. Can be used to report errors.

Returns:

the effective environment

Throws:

IOException

InterruptedException