hudson.model

Class Node

java.lang.Object

hudson.model.AbstractModelObject

hudson.model.Node

All Implemented Interfaces:

ExtensionPoint, Describable<Node>, ModelObject, ReconfigurableDescribable<Node>, Saveable, SearchableModelObject, SearchItem, AccessControlled, OnMaster

Direct Known Subclasses:

AbstractCIBase, Slave

@ExportedBean
public abstract class Node
extends AbstractModelObject
implements ReconfigurableDescribable<Node>, ExtensionPoint, AccessControlled, OnMaster, Saveable

Base type of Jenkins agents (although in practice, you probably extend Slave to define a new agent type).

As a special case, Jenkins extends from here.

Nodes are persisted objects that capture user configurations, and instances get thrown away and recreated whenever the configuration changes. Running state of nodes are captured by Computers.

There is no URL binding for Node. Computer and TransientComputerActionFactory must be used to associate new Actions to agents.

Author:

Kohsuke Kawaguchi

See Also:

NodeDescriptor, Computer

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Node.InternalComputerListener Let Nodes be aware of the lifecycle of their own Computer.
static class	Node.Mode Constants that control how Hudson allocates jobs to agents.

Nested classes/interfaces inherited from interface hudson.ExtensionPoint

ExtensionPoint.LegacyInstancesAreScopedToHudson

Field Summary

Fields

Modifier and Type	Field and Description
protected boolean	holdOffLaunchUntilSave Newly copied agents get this flag set, so that Jenkins doesn't try to start/remove this node until its configuration is saved once.
static boolean	SKIP_BUILD_CHECK_ON_FLYWEIGHTS

Fields inherited from interface hudson.model.Saveable

NOOP

Constructor Summary

Constructors

Constructor and Description
Node()

Method Summary

Modifier and Type	Method and Description
CauseOfBlockage	canTake(Queue.BuildableItem item) Called by the Queue to determine whether or not this node can take the given task.
CauseOfBlockage	canTake(Queue.Task task) Deprecated. as of 1.413 Use canTake(Queue.BuildableItem)
protected abstract Computer	createComputer() Creates a new Computer object that acts as the UI peer of this Node.
abstract Launcher	createLauncher(TaskListener listener) Returns a Launcher for executing programs on this node.
FilePath	createPath(String absolutePath) Gets the FilePath on this node.
ACL	getACL() Obtains the ACL associated with this object.
Set<LabelAtom>	getAssignedLabels() Returns the possibly empty set of labels that are assigned to this node, including the automatic self label, manually assigned labels and dynamically assigned labels via the LabelFinder extension point.
hudson.remoting.VirtualChannel	getChannel() Gets the current channel, if the node is connected and online, or null.
ClockDifference	getClockDifference() Estimates the clock difference with this agent.
abstract hudson.remoting.Callable<ClockDifference,IOException>	getClockDifferenceCallable() Returns a Callable that when run on the channel, estimates the clock difference.
abstract NodeDescriptor	getDescriptor() Gets the descriptor for this instance.
String	getDisplayName()
FileSystemProvisioner	getFileSystemProvisioner() Deprecated.
TagCloud<LabelAtom>	getLabelCloud() Return the possibly empty tag cloud for the labels of this node.
abstract String	getLabelString() Returns the manually configured label for a node.
abstract Node.Mode	getMode() Returns Node.Mode.EXCLUSIVE if this node is only available for those jobs that exclusively specifies this node as the assigned node.
abstract String	getNodeDescription() Human-readable description of this node.
abstract String	getNodeName() Name of this node.
abstract DescribableList<NodeProperty<?>,NodePropertyDescriptor>	getNodeProperties() Gets the NodeProperty instances configured for this Node.
<T extends NodeProperty> T	getNodeProperty(Class<T> clazz) Gets the specified property or null if the property is not configured for this Node.
NodeProperty	getNodeProperty(String className) Gets the property from the given classname or null if the property is not configured for this Node.
List<NodePropertyDescriptor>	getNodePropertyDescriptors()
abstract int	getNumExecutors() Returns the number of Executors.
abstract FilePath	getRootPath() Gets the root directory of this node.
String	getSearchUrl() Returns the URL of this item relative to the parent SearchItem.
LabelAtom	getSelfLabel() Gets the special label that represents this node itself.
abstract FilePath	getWorkspaceFor(TopLevelItem item) Returns a "workspace" directory for the given TopLevelItem.
boolean	isAcceptingTasks() Returns true if the node is accepting tasks.
boolean	isHoldOffLaunchUntilSave()
Node	reconfigure(org.kohsuke.stapler.StaplerRequest req, net.sf.json.JSONObject form) When a parent/owner object of a Describable gets a config form submission and instances are recreated, this method is invoked on the existing instance (meaning the 'this' reference points to the existing instance) to create a new instance to be added to the parent/owner object.
void	save() Persists the state of this object into XML.
void	setLabelString(String labelString) Sets the label string for a node.
abstract void	setNodeName(String name) Deprecated. to indicate that this method isn't really meant to be called by random code.
Computer	toComputer() Gets the corresponding Computer object.

Methods inherited from class hudson.model.AbstractModelObject

getSearch, getSearchIndex, getSearchName, makeSearchIndex, requirePOST, sendError, sendError, sendError, sendError, sendError

Methods inherited from class java.lang.Object

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

Methods inherited from interface hudson.security.AccessControlled

checkAnyPermission, checkPermission, hasAnyPermission, hasPermission, hasPermission, hasPermission2

Field Detail

SKIP_BUILD_CHECK_ON_FLYWEIGHTS

public static boolean SKIP_BUILD_CHECK_ON_FLYWEIGHTS

See Also:

JENKINS-46652

holdOffLaunchUntilSave

protected transient volatile boolean holdOffLaunchUntilSave

Newly copied agents get this flag set, so that Jenkins doesn't try to start/remove this node until its configuration is saved once.

Constructor Detail

Node

public Node()

Method Detail

getDisplayName

public String getDisplayName()

Specified by:

getDisplayName in interface ModelObject

getSearchUrl

public String getSearchUrl()

Description copied from interface: SearchItem

Returns the URL of this item relative to the parent SearchItem.

Specified by:

getSearchUrl in interface SearchItem

Returns:

URL like "foo" or "foo/bar". The path can end with '/'. The path that starts with '/' will be interpreted as the absolute path (within the context path of Jenkins.)

isHoldOffLaunchUntilSave

public boolean isHoldOffLaunchUntilSave()

save

public void save()
          throws IOException

Description copied from interface: Saveable

Persists the state of this object into XML.

For making a bulk change efficiently, see BulkChange.

To support listeners monitoring changes to this object, call SaveableListener.fireOnChange(hudson.model.Saveable, hudson.XmlFile)

Specified by:

save in interface Saveable

Throws:

IOException - if the persistence failed.

Since:

1.635.

getNodeName

@Exported(visibility=999)
 @NonNull
public abstract String getNodeName()

Name of this node.

Returns:

"" if this is master

setNodeName

@Deprecated
public abstract void setNodeName(String name)

Deprecated. to indicate that this method isn't really meant to be called by random code.

When the user clones a Node, Hudson uses this method to change the node name right after the cloned Node object is instantiated.

This method is never used for any other purpose, and as such for all practical intents and purposes, the node name should be treated like immutable.

getNodeDescription

@Exported
public abstract String getNodeDescription()

Human-readable description of this node.

createLauncher

public abstract Launcher createLauncher(TaskListener listener)

Returns a Launcher for executing programs on this node.

The callee must call Launcher.decorateFor(Node) before returning to complete the decoration.

getNumExecutors

@Exported
public abstract int getNumExecutors()

Returns the number of Executors. This may be different from getExecutors().size() because it takes time to adjust the number of executors.

getMode

@Exported
public abstract Node.Mode getMode()

Returns Node.Mode.EXCLUSIVE if this node is only available for those jobs that exclusively specifies this node as the assigned node.

toComputer

@CheckForNull
public final Computer toComputer()

Gets the corresponding Computer object.

Returns:

this method can return null if there's no Computer object for this node, such as when this node has no executors at all.

getChannel

@CheckForNull
public final hudson.remoting.VirtualChannel getChannel()

Gets the current channel, if the node is connected and online, or null. This is just a convenience method for Computer.getChannel() with null check.

createComputer

@CheckForNull
 @Restricted(value=org.kohsuke.accmod.restrictions.ProtectedExternally.class)
protected abstract Computer createComputer()

Creates a new Computer object that acts as the UI peer of this Node. Nobody but Jenkins.updateComputerList() should call this method.

Returns:

Created instance of the computer. Can be null if the Node implementation does not support it (e.g. Cloud agent).

isAcceptingTasks

public boolean isAcceptingTasks()

Returns true if the node is accepting tasks. Needed to allow agents programmatic suspension of task scheduling that does not overlap with being offline. Called by Computer.isAcceptingTasks(). This method is distinct from Computer.isAcceptingTasks() as sometimes the Node concrete class may not have control over the Computer concrete class associated with it.

Returns:

true if the node is accepting tasks.

Since:

1.586

See Also:

Computer.isAcceptingTasks()

getLabelCloud

public TagCloud<LabelAtom> getLabelCloud()

Return the possibly empty tag cloud for the labels of this node.

getAssignedLabels

@Exported
public Set<LabelAtom> getAssignedLabels()

Returns the possibly empty set of labels that are assigned to this node, including the automatic self label, manually assigned labels and dynamically assigned labels via the LabelFinder extension point. This method has a side effect of updating the hudson-wide set of labels and should be called after events that will change that - e.g. a agent connecting.

getLabelString

public abstract String getLabelString()

Returns the manually configured label for a node. The list of assigned and dynamically determined labels is available via getAssignedLabels() and includes all labels that have been manually configured. Mainly for form binding.

setLabelString

public void setLabelString(String labelString)
                    throws IOException

Sets the label string for a node. This value will be returned by getLabelString().

Parameters:

labelString - The new label string to use.

Throws:

IOException

Since:

1.477

getSelfLabel

@NonNull
 @WithBridgeMethods(value=Label.class)
public LabelAtom getSelfLabel()

Gets the special label that represents this node itself.

canTake

@Deprecated
public CauseOfBlockage canTake(Queue.Task task)

Deprecated. as of 1.413 Use canTake(Queue.BuildableItem)

Called by the Queue to determine whether or not this node can take the given task. The default checks include whether or not this node is part of the task's assigned label, whether this node is in Node.Mode.EXCLUSIVE mode if it is not in the task's assigned label, and whether or not any of this node's NodePropertys say that the task cannot be run.

Since:

1.360

canTake

public CauseOfBlockage canTake(Queue.BuildableItem item)

Called by the Queue to determine whether or not this node can take the given task. The default checks include whether or not this node is part of the task's assigned label, whether this node is in Node.Mode.EXCLUSIVE mode if it is not in the task's assigned label, and whether or not any of this node's NodePropertys say that the task cannot be run.

Since:

1.413

getWorkspaceFor

@CheckForNull
public abstract FilePath getWorkspaceFor(TopLevelItem item)

Returns a "workspace" directory for the given TopLevelItem.

Workspace directory is usually used for keeping out the checked out source code, but it can be used for anything.

Returns:

null if this node is not connected hence the path is not available

getRootPath

@CheckForNull
public abstract FilePath getRootPath()

Gets the root directory of this node.

Hudson always owns a directory on every node. This method returns that.

Returns:

null if the node is offline and hence the FilePath object is not available.

createPath

@CheckForNull
public FilePath createPath(String absolutePath)

Gets the FilePath on this node.

getFileSystemProvisioner

@Deprecated
public FileSystemProvisioner getFileSystemProvisioner()

Deprecated.

getNodeProperties

@NonNull
public abstract DescribableList<NodeProperty<?>,NodePropertyDescriptor> getNodeProperties()

Gets the NodeProperty instances configured for this Node.

getNodeProperty

@CheckForNull
public <T extends NodeProperty> T getNodeProperty(Class<T> clazz)

Gets the specified property or null if the property is not configured for this Node.

Parameters:

clazz - the type of the property

Returns:

null if the property is not configured

Since:

2.37

getNodeProperty

@CheckForNull
public NodeProperty getNodeProperty(String className)

Gets the property from the given classname or null if the property is not configured for this Node.

Parameters:

className - The classname of the property

Returns:

null if the property is not configured

Since:

2.37

getNodePropertyDescriptors

public List<NodePropertyDescriptor> getNodePropertyDescriptors()

getACL

public ACL getACL()

Description copied from interface: AccessControlled

Obtains the ACL associated with this object.

Specified by:

getACL in interface AccessControlled

Returns:

never null.

reconfigure

public Node reconfigure(org.kohsuke.stapler.StaplerRequest req,
                        net.sf.json.JSONObject form)
                 throws Descriptor.FormException

Description copied from interface: ReconfigurableDescribable

When a parent/owner object of a Describable gets a config form submission and instances are recreated, this method is invoked on the existing instance (meaning the 'this' reference points to the existing instance) to create a new instance to be added to the parent/owner object.

The default implementation of this should be the following:

 return form==null ? null : getDescriptor().newInstance(req, form);
 

Specified by:

reconfigure in interface ReconfigurableDescribable<Node>

Parameters:

req - The current HTTP request being processed.

form - JSON fragment that corresponds to this describable object. If the newly submitted form doesn't include a fragment for this describable (meaning the user has de-selected your descriptor), then this argument is null.

Returns:

The new instance. To not to create an instance of a describable, return null.

Throws:

Descriptor.FormException

getDescriptor

public abstract NodeDescriptor getDescriptor()

Description copied from interface: Describable

Gets the descriptor for this instance.

Descriptor is a singleton for every concrete Describable implementation, so if a.getClass() == b.getClass() then by default a.getDescriptor() == b.getDescriptor() as well. (In rare cases a single implementation class may be used for instances with distinct descriptors.)

Specified by:

getDescriptor in interface Describable<Node>

getClockDifference

public ClockDifference getClockDifference()
                                   throws IOException,
                                          InterruptedException

Estimates the clock difference with this agent.

Returns:

always non-null.

Throws:

InterruptedException - if the operation is aborted.

IOException

getClockDifferenceCallable

public abstract hudson.remoting.Callable<ClockDifference,IOException> getClockDifferenceCallable()

Returns a Callable that when run on the channel, estimates the clock difference.

Returns:

always non-null.

Since:

1.522