hudson

Class EnvVars

java.lang.Object

java.util.AbstractMap<K,V>

java.util.TreeMap<String,String>

hudson.EnvVars

All Implemented Interfaces:

Serializable, Cloneable, Map<String,String>, NavigableMap<String,String>, SortedMap<String,String>

public class EnvVars
extends TreeMap<String,String>

Environment variables.

While all the platforms I tested (Linux 2.6, Solaris, and Windows XP) have the case sensitive environment variable table, Windows batch script handles environment variable in the case preserving but case insensitive way (that is, cmd.exe can get both FOO and foo as environment variables when it's launched, and the "set" command will display it accordingly, but "echo %foo%" results in echoing the value of "FOO", not "foo" — this is presumably caused by the behavior of the underlying Win32 API GetEnvironmentVariable acting in case insensitive way.) Windows users are also used to write environment variable case-insensitively (like %Path% vs %PATH%), and you can see many documents on the web that claims Windows environment variables are case insensitive.

So for a consistent cross platform behavior, it creates the least confusion to make the table case insensitive but case preserving.

In Jenkins, often we need to build up "environment variable overrides" on the controller, then to execute the process on agents. This causes a problem when working with variables like PATH. So to make this work, we introduce a special convention PATH+FOO — all entries that starts with PATH+ are merged and prepended to the inherited PATH variable, on the process where a new process is executed.

Author:

Kohsuke Kawaguchi

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class java.util.AbstractMap

AbstractMap.SimpleEntry<K,V>, AbstractMap.SimpleImmutableEntry<K,V>

Field Summary

Fields

Modifier and Type	Field and Description
static Map<String,String>	masterEnvVars Environmental variables that we've inherited.

Constructor Summary

Constructors

Constructor and Description
EnvVars()
EnvVars(EnvVars m)
EnvVars(Map<String,String> m)
EnvVars(String... keyValuePairs) Builds an environment variables from an array of the form "key","value","key","value"...

Method Summary

Modifier and Type	Method and Description
void	addLine(String line) Takes a string that looks like "a=b" and adds that to this map.
static EnvVars	createCookie() Creates a magic cookie that can be used as the model environment variable when we later kill the processes.
String	expand(String s) Expands the variables in the given string by using environment variables represented in 'this'.
String	get(String key, String defaultValue) Convenience message
Platform	getPlatform() Gets the platform for which these env vars targeted.
static EnvVars	getRemote(hudson.remoting.VirtualChannel channel) Obtains the environment variables of a remote peer.
void	override(String key, String value) Overrides the current entry by the given entry.
EnvVars	overrideAll(Map<String,String> all) Overrides all values in the map by the given map.
EnvVars	overrideExpandingAll(Map<String,String> all) Overrides all values in the map by the given map.
String	put(String key, String value)
void	putAllNonNull(Map<String,String> map) Add entire map but filter null values out.
void	putIfNotNull(String key, String value) Add a key/value but only if the value is not-null.
static void	resolve(Map<String,String> env) Resolves environment variables against each other.
void	setPlatform(Platform platform) Sets the platform for which these env vars target.

Methods inherited from class java.util.TreeMap

ceilingEntry, ceilingKey, clear, clone, comparator, containsKey, containsValue, descendingKeySet, descendingMap, entrySet, firstEntry, firstKey, floorEntry, floorKey, forEach, get, headMap, headMap, higherEntry, higherKey, keySet, lastEntry, lastKey, lowerEntry, lowerKey, navigableKeySet, pollFirstEntry, pollLastEntry, putAll, remove, replace, replace, replaceAll, size, subMap, subMap, tailMap, tailMap, values

Methods inherited from class java.util.AbstractMap

equals, hashCode, isEmpty, toString

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Map

compute, computeIfAbsent, computeIfPresent, equals, getOrDefault, hashCode, isEmpty, merge, putIfAbsent, remove

Field Detail

masterEnvVars

public static final Map<String,String> masterEnvVars

Environmental variables that we've inherited.

Despite what the name might imply, this is the environment variable of the current JVM process. And therefore, it is the Jenkins controller's environment variables only when you access this from the controller.

If you access this field from agents, then this is the environment variable of the agent.

Constructor Detail

EnvVars

public EnvVars()

EnvVars

public EnvVars(@NonNull
               Map<String,String> m)

EnvVars

public EnvVars(@NonNull
               EnvVars m)

EnvVars

public EnvVars(String... keyValuePairs)

Builds an environment variables from an array of the form "key","value","key","value"...

Method Detail

getPlatform

@CheckForNull
public Platform getPlatform()

Gets the platform for which these env vars targeted.

Returns:

The platform.

Since:

2.144

setPlatform

public void setPlatform(@NonNull
                        Platform platform)

Sets the platform for which these env vars target.

Parameters:

platform - the platform to set.

Since:

2.144

override

public void override(String key,
                     String value)

Overrides the current entry by the given entry.

Handles PATH+XYZ notation.

overrideAll

public EnvVars overrideAll(Map<String,String> all)

Overrides all values in the map by the given map. See override(String, String).

Returns:

this

overrideExpandingAll

public EnvVars overrideExpandingAll(@NonNull
                                    Map<String,String> all)

Overrides all values in the map by the given map. Expressions in values will be expanded. See override(String, String).

Returns:

this

resolve

public static void resolve(Map<String,String> env)

Resolves environment variables against each other.

get

public String get(String key,
                  String defaultValue)

Convenience message

Since:

1.485

put

public String put(String key,
                  String value)

Specified by:

put in interface Map<String,String>

Overrides:

put in class TreeMap<String,String>

putIfNotNull

public void putIfNotNull(String key,
                         String value)

Add a key/value but only if the value is not-null. Otherwise no-op.

Since:

1.556

putAllNonNull

public void putAllNonNull(Map<String,String> map)

Add entire map but filter null values out.

Since:

2.214

addLine

public void addLine(String line)

Takes a string that looks like "a=b" and adds that to this map.

expand

public String expand(String s)

Expands the variables in the given string by using environment variables represented in 'this'.

createCookie

public static EnvVars createCookie()

Creates a magic cookie that can be used as the model environment variable when we later kill the processes.

getRemote

public static EnvVars getRemote(hudson.remoting.VirtualChannel channel)
                         throws IOException,
                                InterruptedException

Obtains the environment variables of a remote peer.

Parameters:

channel - Can be null, in which case the map indicating "N/A" will be returned.

Returns:

A fresh copy that can be owned and modified by the caller.

Throws:

IOException

InterruptedException