Package hudson.tools

Class ToolInstallation

java.lang.Object

hudson.model.AbstractDescribableImpl<ToolInstallation>

hudson.tools.ToolInstallation

All Implemented Interfaces:

ExtensionPoint, Describable<ToolInstallation>, Serializable

Direct Known Subclasses:

JDK, Maven.MavenInstallation

public abstract class ToolInstallation
extends AbstractDescribableImpl<ToolInstallation>
implements Serializable, ExtensionPoint

Formalization of a tool installed in nodes used for builds. (Examples include things like JDKs, Ants, Mavens, and Groovys.)

You can define such a concept in your plugin entirely on your own, without extending from this class, but choosing this class as a base class has several benefits:

• Hudson allows admins to specify different locations for tools on some agents. For example, JDK on the controller might be on /usr/local/java but on a Windows agent it could be at c:\Program Files\Java
• Hudson can verify the existence of tools and provide warnings and diagnostics for admins. (TBD)
• Hudson can perform automatic installations for users. (TBD)

Implementations of this class are strongly encouraged to also implement NodeSpecific (by using translateFor(Node, TaskListener)) and EnvironmentSpecific (by using EnvVars.expand(String).) Callers such as build steps can then use translate(AbstractBuild,TaskListener) and cast to the desired ToolInstallation subtype, or just call NodeSpecific.forNode(hudson.model.Node, hudson.model.TaskListener) and EnvironmentSpecific.forEnvironment(hudson.EnvVars) directly.

To contribute an extension point, put Extension on your ToolDescriptor class.

Since:

1.286

Author:

huybrechts

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
protected static class	ToolInstallation.ToolConverter	Subclasses can extend this for data migration from old field storing home directory.

Nested classes/interfaces inherited from interface hudson.ExtensionPoint

ExtensionPoint.LegacyInstancesAreScopedToHudson

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	ToolInstallation(String name, String home)	Deprecated. as of 1.302.
protected	ToolInstallation(String name, String home, List<? extends ToolProperty<?>> properties)

Method Summary

Modifier and Type	Method	Description
static DescriptorExtensionList<ToolInstallation,ToolDescriptor<?>>	all()	Returns all the registered ToolDescriptors.
void	buildEnvVars(EnvVars env)	Expose any environment variables that this tool installation wants the build to see.
String	getHome()	Gets the home directory of this tool.
String	getName()	Gets the human readable name that identifies this tool among other ToolInstallations of the same kind.
DescribableList<ToolProperty<?>,ToolPropertyDescriptor>	getProperties()
protected Object	readResolve()	Invoked by XStream when this object is read into memory.
String	toString()
ToolInstallation	translate(AbstractBuild<?,?> buildInProgress, TaskListener listener)	Convenient version of translate(Node, EnvVars, TaskListener) that just takes a build object in progress.
ToolInstallation	translate(Node node, EnvVars envs, TaskListener listener)	Performs a necessary variable/environment/context expansion.
protected String	translateFor(Node node, TaskListener log)	Finds a tool on a node.
protected Object	writeReplace()

Methods inherited from class hudson.model.AbstractDescribableImpl

getDescriptor

Methods inherited from class java.lang.Object

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

Constructor Detail

ToolInstallation

@Deprecated
protected ToolInstallation(String name,
                           String home)

Deprecated.

as of 1.302. Use ToolInstallation(String, String, List)

ToolInstallation

protected ToolInstallation(String name,
                           String home,
                           List<? extends ToolProperty<?>> properties)

Method Detail

getName

public String getName()

Gets the human readable name that identifies this tool among other ToolInstallations of the same kind.

getHome

@CheckForNull
public String getHome()

Gets the home directory of this tool. The path can be in Unix format as well as in Windows format. Must be absolute.

Returns:

the home directory location, if defined (may only be defined on the result of translate(Node, EnvVars, TaskListener), e.g. if unavailable on controller)

buildEnvVars

public void buildEnvVars(EnvVars env)

Expose any environment variables that this tool installation wants the build to see.

To add entry to PATH, do envVars.put("PATH+XYZ",path) where 'XYZ' is something unique. Variable names of the form 'A+B' is interpreted as adding the value to the existing PATH.

Since:

1.460

getProperties

public DescribableList<ToolProperty<?>,ToolPropertyDescriptor> getProperties()

translate

public ToolInstallation translate(@NonNull
                                  Node node,
                                  EnvVars envs,
                                  TaskListener listener)
                           throws IOException,
                                  InterruptedException

Performs a necessary variable/environment/context expansion.

Parameters:

node - Node that this tool is used in.

envs - Set of environment variables to expand any references.

listener - Any lengthy operation (such as auto-installation) will report its progress here.

Returns:

ToolInstallation object that is fully specialized.

Throws:

IOException

InterruptedException

Since:

1.460

See Also:

NodeSpecific, EnvironmentSpecific

translate

public ToolInstallation translate(AbstractBuild<?,?> buildInProgress,
                                  TaskListener listener)
                           throws IOException,
                                  InterruptedException

Convenient version of translate(Node, EnvVars, TaskListener) that just takes a build object in progress.

Throws:

IOException

InterruptedException

Since:

1.460

translateFor

protected String translateFor(Node node,
                              TaskListener log)
                       throws IOException,
                              InterruptedException

Finds a tool on a node. Checks if the location of the tool is overridden for the given node, and if so, return the node-specific home directory. Also checks available ToolLocationTranslators. Otherwise returns installation.getHome().

This is the core logic behind NodeSpecific.forNode(Node, TaskListener) for ToolInstallation, and meant to be used by the forNode implementations.

Returns:

never null.

Throws:

IOException

InterruptedException

readResolve

protected Object readResolve()

Invoked by XStream when this object is read into memory.

writeReplace

protected Object writeReplace()
                       throws Exception

Throws:

Exception

toString

public String toString()

Overrides:

toString in class Object

all

public static DescriptorExtensionList<ToolInstallation,ToolDescriptor<?>> all()

Returns all the registered ToolDescriptors.