Package hudson.model

Class Node

java.lang.Object
hudson.model.AbstractModelObject
hudson.model.Node
All Implemented Interfaces:
ExtensionPoint, Describable<Node>, ModelObject, PersistenceRoot, 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, PersistenceRoot
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:

  • Field Details

    • SKIP_BUILD_CHECK_ON_FLYWEIGHTS

      public static boolean SKIP_BUILD_CHECK_ON_FLYWEIGHTS
      See Also:

    • 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 Details

    • Node

      public Node()

  • Method Details

    • 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
      In most cases, you should not call this method directly, but Jenkins.updateNode(Node) instead.
      Specified by:
      save in interface Saveable
      Throws:
      IOException - if the persistence failed.
      Since:
      1.635.

    • getConfigFile

      protected XmlFile getConfigFile()

    • 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(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 AbstractCIBase.updateComputerList(boolean, Collection) 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:

    • onLoad

      public void onLoad(Nodes parent, String name)

    • getTemporaryOfflineCause

      public OfflineCause getTemporaryOfflineCause()
      Get the cause if temporary offline.
      Returns:
      null if not temporary offline or there was no cause given.
      Since:
      2.340

    • getLabelCloud

      public TagCloud<LabelAtom> getLabelCloud()
      Return the possibly empty tag cloud for the labels of this node.

    • getLabelAtomSet

      @NonNull @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) protected Set<LabelAtom> getLabelAtomSet()
      Returns:
      An immutable set of LabelAtom associated with the current node label.

    • 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. an agent connecting.

    • drainLabelsToTrim

      @NonNull @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public Set<LabelAtom> drainLabelsToTrim()
      Returns:
      the labels to be trimmed for this node.

    • 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(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

      @NonNull 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(@NonNull org.kohsuke.stapler.StaplerRequest2 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

    • reconfigure

      @Deprecated public Node reconfigure(@NonNull org.kohsuke.stapler.StaplerRequest req, net.sf.json.JSONObject form) throws Descriptor.FormException
      Deprecated.
      use reconfigure(StaplerRequest2, JSONObject)
      Specified by:
      reconfigure in interface ReconfigurableDescribable<Node>
      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.)

      By default looks for a nested class (conventionally named DescriptorImpl) implementing Descriptor and marked with Extension.

      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

    • getRootDir

      public File getRootDir()
      Description copied from interface: PersistenceRoot
      Gets the root directory on the file system that this Item can use freely for storing the configuration data.

      This parameter is given by the ItemGroup when Item is loaded from memory.

      Specified by:
      getRootDir in interface PersistenceRoot