Package org.jenkinsci.plugins.vsphere.tools

Class VSphereHostSelection

java.lang.Object

org.jenkinsci.plugins.vsphere.tools.VSphereHostSelection

public final class VSphereHostSelection
extends Object

Pure, yavijava-free logic for picking a "best" ESXi host out of a cluster's members, given per-host stats and an optional admin-supplied allow-list. Kept free of vSphere API types so it can be unit-tested without a live vCenter connection.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final class	VSphereHostSelection.HostCandidate	Describes one candidate host's name, availability and current load, as needed to decide whether/how favourably it can be used for a new clone.
static final class	VSphereHostSelection.ScoredHost	A candidate host with its availability score (0 worst ..

Field Summary

Fields

Modifier and Type	Field	Description
static final String	HOST_SELECTION_MODE_NONE	Explicit "no host selection" override for a template/build-step's hostSelectionMode, distinct from leaving it blank (which means "inherit the cloud-level default" - see resolveMode(java.lang.String, java.lang.String)).

Method Summary

Modifier and Type	Method	Description
static String	excludedBecause(VSphereHostSelection.HostCandidate candidate, Set<String> allowList)	Why filterCandidates(java.util.List<org.jenkinsci.plugins.vsphere.tools.VSphereHostSelection.HostCandidate>, java.util.Set<java.lang.String>) drops this host, or null if it keeps it.
static List<VSphereHostSelection.HostCandidate>	filterByVmSize(List<VSphereHostSelection.HostCandidate> candidates, boolean requireCores, Integer vmCpus, boolean requireMemory, Integer vmMemoryMB)	Optionally drops candidates that are physically too small for the VM about to be created: with requireCores, hosts with fewer physical CPU cores than vmCpus; with requireMemory, hosts with less total physical RAM than vmMemoryMB.
static List<VSphereHostSelection.HostCandidate>	filterCandidates(List<VSphereHostSelection.HostCandidate> candidates, Set<String> allowList)	Filters candidates down to ones that are usable (connected, not in maintenance mode) and, if the allow-list is non-empty, whose name is in it.
static List<VSphereHostSelection.HostCandidate>	listOf(VSphereHostSelection.HostCandidate... candidates)	Convenience: same as calling Arrays.asList(T...) for tests.
static Set<String>	parseAllowList(String hostSelectionCandidatesCsv)	Parses a comma-separated allow-list of host names, trimming whitespace and discarding empty entries.
static Set<String>	parseAllowListOrNull(String hostSelectionCandidatesCsv)	Like parseAllowList(java.lang.String), but preserves the "not set at all" case as null instead of collapsing it to an empty set - needed so a blank hostSelectionCandidatesAsString can mean "inherit the cloud-level default" (see resolveCandidates(java.util.Set<java.lang.String>, java.util.Set<java.lang.String>)) while a deliberately non-blank-but-hostless value (e.g.
static VSphereHostSelection.HostCandidate	pickBest(List<VSphereHostSelection.HostCandidate> candidates, HostWeights weights)	The most available candidate according to rank(java.util.List<org.jenkinsci.plugins.vsphere.tools.VSphereHostSelection.HostCandidate>, org.jenkinsci.plugins.vsphere.tools.HostWeights), or null if none has statistics.
static VSphereHostSelection.HostCandidate	pickLeastLoaded(List<VSphereHostSelection.HostCandidate> candidates)	Picks the candidate with the lowest load fraction, excluding any candidate whose stats are unavailable.
static List<VSphereHostSelection.ScoredHost>	rank(List<VSphereHostSelection.HostCandidate> candidates, HostWeights weights)	Ranks the candidates that have usage statistics, most available first (equally scored ones keep their incoming order).
static Set<String>	resolveCandidates(Set<String> cloudDefault, Set<String> override)	Resolves a template/build-step's hostSelectionCandidates against its cloud's default: null (never set at this level) defers to cloudDefault; any explicitly-set value - including an empty set, meaning "explicitly no restriction" - wins outright.
static String	resolveMode(String cloudDefault, String override)	Resolves a template/build-step's hostSelectionMode against its cloud's default: blank/null defers to cloudDefault; HOST_SELECTION_MODE_NONE explicitly disables host selection regardless of the cloud default; any other value (a real mode) wins outright.
static String	sizeShortfall(VSphereHostSelection.HostCandidate candidate, boolean requireCores, Integer vmCpus, boolean requireMemory, boolean requireAvailableMemory, Integer vmMemoryMB)	As above, and with requireAvailableMemory also drops hosts that do not have at least vmMemoryMB of memory free right now (so the new VM would not be swapped by the hypervisor), or whose memory usage is unknown.
static String	sizeShortfall(VSphereHostSelection.HostCandidate candidate, boolean requireCores, Integer vmCpus, boolean requireMemory, Integer vmMemoryMB)	Why filterByVmSize(java.util.List<org.jenkinsci.plugins.vsphere.tools.VSphereHostSelection.HostCandidate>, boolean, java.lang.Integer, boolean, java.lang.Integer) drops this host, or null if it keeps it.
static String	toAllowListString(Set<String> hosts)	The inverse of parseAllowListOrNull(java.lang.String): renders null as "" (inherit), an empty set as a single comma (a visible, non-blank marker for "explicitly no restriction" that round-trips back through parseAllowListOrNull(java.lang.String) to an empty - not null - set), and anything else as the plain comma-separated form.
static String	toCsv(Collection<String> hosts)	Joins a collection of host names back into the comma-separated form used by the classic config UI textbox.

Methods inherited from class java.lang.Object

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

Field Details

HOST_SELECTION_MODE_NONE

public static final String HOST_SELECTION_MODE_NONE

Explicit "no host selection" override for a template/build-step's hostSelectionMode, distinct from leaving it blank (which means "inherit the cloud-level default" - see resolveMode(java.lang.String, java.lang.String)).

See Also:

• Constant Field Values

Method Details

parseAllowList

public static Set<String> parseAllowList(String hostSelectionCandidatesCsv)

Parses a comma-separated allow-list of host names, trimming whitespace and discarding empty entries. Returns an empty (not null) set when the input is null/blank, meaning "no restriction".

toCsv

public static String toCsv(Collection<String> hosts)

Joins a collection of host names back into the comma-separated form used by the classic config UI textbox. Returns "" (not null) for a null/empty input, so this is safe to use directly as a form field's current value.

parseAllowListOrNull

public static Set<String> parseAllowListOrNull(String hostSelectionCandidatesCsv)

Like parseAllowList(java.lang.String), but preserves the "not set at all" case as null instead of collapsing it to an empty set - needed so a blank hostSelectionCandidatesAsString can mean "inherit the cloud-level default" (see resolveCandidates(java.util.Set<java.lang.String>, java.util.Set<java.lang.String>)) while a deliberately non-blank-but-hostless value (e.g. a lone comma) can still mean "explicitly override to no restriction". Blank/whitespace-only input (including a single space) is treated as "not set"; anything else is parsed normally, which may still yield an empty (non-null) set.

toAllowListString

public static String toAllowListString(Set<String> hosts)

The inverse of parseAllowListOrNull(java.lang.String): renders null as "" (inherit), an empty set as a single comma (a visible, non-blank marker for "explicitly no restriction" that round-trips back through parseAllowListOrNull(java.lang.String) to an empty - not null - set), and anything else as the plain comma-separated form.

resolveMode

public static String resolveMode(String cloudDefault,
 String override)

Resolves a template/build-step's hostSelectionMode against its cloud's default: blank/null defers to cloudDefault; HOST_SELECTION_MODE_NONE explicitly disables host selection regardless of the cloud default; any other value (a real mode) wins outright.

resolveCandidates

public static Set<String> resolveCandidates(Set<String> cloudDefault,
 Set<String> override)

Resolves a template/build-step's hostSelectionCandidates against its cloud's default: null (never set at this level) defers to cloudDefault; any explicitly-set value - including an empty set, meaning "explicitly no restriction" - wins outright.

filterCandidates

public static List<VSphereHostSelection.HostCandidate> filterCandidates(List<VSphereHostSelection.HostCandidate> candidates,
 Set<String> allowList)

Filters candidates down to ones that are usable (connected, not in maintenance mode) and, if the allow-list is non-empty, whose name is in it. An empty/null allow-list means "consider every usable host".

excludedBecause

public static String excludedBecause(VSphereHostSelection.HostCandidate candidate,
 Set<String> allowList)

Why filterCandidates(java.util.List<org.jenkinsci.plugins.vsphere.tools.VSphereHostSelection.HostCandidate>, java.util.Set<java.lang.String>) drops this host, or null if it keeps it. For logging the reasoning behind a placement.

filterByVmSize

public static List<VSphereHostSelection.HostCandidate> filterByVmSize(List<VSphereHostSelection.HostCandidate> candidates,
 boolean requireCores,
 Integer vmCpus,
 boolean requireMemory,
 Integer vmMemoryMB)

Optionally drops candidates that are physically too small for the VM about to be created: with requireCores, hosts with fewer physical CPU cores than vmCpus; with requireMemory, hosts with less total physical RAM than vmMemoryMB. Compares absolute capacity, not current free resources, so sites that oversubscribe (swap, hyperthreads, ...) can simply leave both off. A host whose relevant capacity is unknown (0) does not satisfy a requirement that is switched on, and a VM size that is unknown (null) disables the corresponding check.

sizeShortfall

public static String sizeShortfall(VSphereHostSelection.HostCandidate candidate,
 boolean requireCores,
 Integer vmCpus,
 boolean requireMemory,
 Integer vmMemoryMB)

Why filterByVmSize(java.util.List<org.jenkinsci.plugins.vsphere.tools.VSphereHostSelection.HostCandidate>, boolean, java.lang.Integer, boolean, java.lang.Integer) drops this host, or null if it keeps it. For logging the reasoning behind a placement.

sizeShortfall

public static String sizeShortfall(VSphereHostSelection.HostCandidate candidate,
 boolean requireCores,
 Integer vmCpus,
 boolean requireMemory,
 boolean requireAvailableMemory,
 Integer vmMemoryMB)

As above, and with requireAvailableMemory also drops hosts that do not have at least vmMemoryMB of memory free right now (so the new VM would not be swapped by the hypervisor), or whose memory usage is unknown. Unlike requireMemory, which compares the RAM installed, this looks at the host's current usage, which changes by the minute.

rank

public static List<VSphereHostSelection.ScoredHost> rank(List<VSphereHostSelection.HostCandidate> candidates,
 HostWeights weights)

Ranks the candidates that have usage statistics, most available first (equally scored ones keep their incoming order). Hosts without statistics are left out.

With default weights, a host scores 1 minus its load fraction, which reproduces pickLeastLoaded(java.util.List<org.jenkinsci.plugins.vsphere.tools.VSphereHostSelection.HostCandidate>). Otherwise the score is the weighted average of four measures, each between 0 and 1: free CPU and free memory as a share of the host's own capacity, and free CPU (MHz) and free memory (MB) relative to the best of the candidates being compared.

pickBest

public static VSphereHostSelection.HostCandidate pickBest(List<VSphereHostSelection.HostCandidate> candidates,
 HostWeights weights)

The most available candidate according to rank(java.util.List<org.jenkinsci.plugins.vsphere.tools.VSphereHostSelection.HostCandidate>, org.jenkinsci.plugins.vsphere.tools.HostWeights), or null if none has statistics.

pickLeastLoaded

public static VSphereHostSelection.HostCandidate pickLeastLoaded(List<VSphereHostSelection.HostCandidate> candidates)

Picks the candidate with the lowest load fraction, excluding any candidate whose stats are unavailable. Returns null if no candidate has usable stats.

listOf

public static List<VSphereHostSelection.HostCandidate> listOf(VSphereHostSelection.HostCandidate... candidates)

Convenience: same as calling Arrays.asList(T...) for tests.