Package org.jenkins.plugins.lockableresources

Class LockableResourcesManager

java.lang.Object
hudson.model.Descriptor<GlobalConfiguration>
jenkins.model.GlobalConfiguration
org.jenkins.plugins.lockableresources.LockableResourcesManager
All Implemented Interfaces:
ExtensionPoint, Describable<GlobalConfiguration>, Saveable, Loadable, OnMaster
@Extension @Symbol("lockableResourcesManager") public class LockableResourcesManager extends GlobalConfiguration

  • Field Details

    • syncResources

      public static final Object syncResources
      Object to synchronized operations over LRM

  • Constructor Details

    • LockableResourcesManager

      public LockableResourcesManager()
      C-tor

  • Method Details

    • setAllowEmptyOrNullValues

      @DataBoundSetter public void setAllowEmptyOrNullValues(boolean allowEmptyOrNullValues)

    • isAllowEmptyOrNullValues

      public boolean isAllowEmptyOrNullValues()

    • setAllowEphemeralResources

      @DataBoundSetter public void setAllowEphemeralResources(boolean allowEphemeralResources)
      Sets whether ephemeral resources can be created automatically.
      Parameters:
      allowEphemeralResources - true to allow automatic creation of ephemeral resources

    • isAllowEphemeralResources

      public boolean isAllowEphemeralResources()
      Returns whether ephemeral resources are allowed.
      Returns:
      true if ephemeral resources can be created automatically

    • setRemoteApiEnabled

      @DataBoundSetter public void setRemoteApiEnabled(boolean remoteApiEnabled)

    • isRemoteApiEnabled

      public boolean isRemoteApiEnabled()

    • setExposeLabel

      @DataBoundSetter public void setExposeLabel(String exposeLabel)

    • getExposeLabel

      public String getExposeLabel()

    • getExposeLabels

      @NonNull @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public Set<String> getExposeLabels()
      The configured exposeLabel(s) as a set. exposeLabel is a whitespace-separated list of labels (same convention as LockableResource.getLabelsAsList()); a resource is exposed to remote clients if it carries any of them (OR). An empty/blank value exposes nothing (opt-in). A single label is simply a one-element set, so existing single-label configurations behave unchanged.

    • setClientId

      @DataBoundSetter public void setClientId(String clientId)

    • getClientId

      public String getClientId()

    • setForcedServerId

      @DataBoundSetter public void setForcedServerId(String forcedServerId)

    • getForcedServerId

      public String getForcedServerId()

    • doCheckForcedServerId

      @POST public FormValidation doCheckForcedServerId(@QueryParameter String value)
      Form validation for forcedServerId: warns when the value does not match any configured remote connection (delegated mode would fail at lock() time).

    • getEffectiveClientId

      @CheckForNull public String getEffectiveClientId()
      Returns the effective client identifier to send to remote servers. Uses the configured clientId if non-empty; otherwise falls back to Jenkins.getRootUrl() (which may be null if not configured).

    • getResources

      public List<LockableResource> getResources()
      Get all resources Includes declared, ephemeral and node resources

    • getRemotes

      public List<RemoteConnection> getRemotes()
      Returns a defensive copy of configured remote connections.

    • getRemotesAsMap

      public Map<String,RemoteConnection> getRemotesAsMap()
      Returns remote connections as a map keyed by serverId.

      Duplicate serverIds are resolved as last-entry-wins to match form submission order.

    • setRemotes

      @DataBoundSetter public void setRemotes(List<RemoteConnection> remotes)
      Set all remote connections.

    • getReadOnlyResources

      @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public List<LockableResource> getReadOnlyResources()
      Get all resources - read only The same as getResources() but unmodifiable list. The getResources() is unsafe to use because of possible concurrent modification exception.

    • getDeclaredResources

      @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public List<LockableResource> getDeclaredResources()
      Get declared resources, means only defined in config file (xml or JCaC yaml).

    • setDeclaredResources

      @DataBoundSetter public void setDeclaredResources(List<LockableResource> declaredResources)
      Set all declared resources (do not include ephemeral and node resources).

    • getResourcesFromProject

      @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public List<LockableResource> getResourcesFromProject(String fullName)
      Get all resources used by project.

    • isValidLabel

      @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public Boolean isValidLabel(@Nullable String label)
      Check if the label is valid. Valid in this context means, if is configured on someone resource.

    • getAllLabels

      @NonNull @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public Set<String> getAllLabels()
      Returns all configured labels.

    • getFreeResourceAmount

      @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) @Deprecated public int getFreeResourceAmount(String label)
      Deprecated.
      Get amount of free resources contained given *label* This method is deprecated (no where used) and is not tested.

    • getResourcesWithLabel

      @Deprecated @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public List<LockableResource> getResourcesWithLabel(String label, Map<String,Object> params)
      Deprecated.
      Use getResourcesWithLabel(String label) Note: The param *params* is not used (has no effect)

    • getResourcesWithLabel

      @NonNull @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public List<LockableResource> getResourcesWithLabel(String label)
      Returns resources matching by given *label*.

    • getResourcesMatchingScript

      @NonNull @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public List<LockableResource> getResourcesMatchingScript(@NonNull org.jenkinsci.plugins.scriptsecurity.sandbox.groovy.SecureGroovyScript script, @CheckForNull Map<String,Object> params) throws ExecutionException
      Returns a list of resources matching by given *script*.
      Parameters:
      script - Script
      params - Additional parameters
      Returns:
      List of the matching resources
      Throws:
      ExecutionException - Script execution failed for one of the resources. It is considered as a fatal failure since the requirement list may be incomplete
      Since:
      2.0

    • fromName

      @CheckForNull @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public LockableResource fromName(@CheckForNull String resourceName)
      Returns resource matched by name. Returns null in case, the resource does not exist.

    • fromNames

      @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public List<LockableResource> fromNames(@Nullable List<String> names)

    • fromNames

      @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public List<LockableResource> fromNames(List<String> names, boolean createResource)

    • resourceExist

      @NonNull @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public Boolean resourceExist(@CheckForNull String resourceName)
      Checks if given resource exist.

    • queue

      public boolean queue(List<LockableResource> resources, long queueItemId, String queueProjectName)

    • queue

      @Deprecated @CheckForNull @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public List<LockableResource> queue(LockableResourcesStruct requiredResources, long queueItemId, String queueItemProject, int number, Map<String,Object> params, Logger log)
      Deprecated.
      Use tryQueue(org.jenkins.plugins.lockableresources.queue.LockableResourcesStruct, long, java.lang.String, int, java.util.Map, java.util.logging.Logger)

    • uncacheIfFreeing

      public boolean uncacheIfFreeing(LockableResource candidate, boolean unlocking, boolean unreserving)
      If the lockable resource availability was evaluated before and cached to avoid frequent re-evaluations under queued pressure when there are no resources to give, we should state that a resource is again instantly available for re-evaluation when we know it was busy and right now is being freed. Note that a resource may be (both or separately) locked by a build and/or reserved by a user (or stolen from build to user) so we only un-cache it here if it becomes completely available. Called as a helper from methods that unlock/unreserve/reset (or indirectly - recycle) stuff.

      NOTE for people using LR or LRM methods directly to add some abilities in their pipelines that are not provided by plugin: the `cachedCandidates` is an LRM concept, so if you tell a resource (LR instance) directly to unlock/unreserve, it has no idea to clean itself from this cache, and may be considered busy in queuing for some time afterward.

    • tryQueue

      @CheckForNull @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public List<LockableResource> tryQueue(LockableResourcesStruct requiredResources, long queueItemId, String queueItemProject, int number, Map<String,Object> params, Logger log) throws ExecutionException
      Try to acquire the resources required by the task.
      Parameters:
      number - Number of resources to acquire. 0 means all
      Returns:
      List of the locked resources if the task has been accepted. null if the item is still waiting for the resources
      Throws:
      ExecutionException - Cannot queue the resource due to the execution failure. Carries info in the cause
      Since:
      2.0

    • lock

      @Deprecated public boolean lock(List<LockableResource> resources, Run<?,?> build, @Nullable org.jenkinsci.plugins.workflow.steps.StepContext context)
      Deprecated.

    • lock

      @Deprecated public boolean lock(List<LockableResource> resources, Run<?,?> build, @Nullable org.jenkinsci.plugins.workflow.steps.StepContext context, @Nullable String logmessage, String variable, boolean inversePrecedence)
      Deprecated.

    • lock

      public boolean lock(List<LockableResource> resourcesToLock, Run<?,?> build)
      Try to lock the resource and return true if locked.

    • lock

      public boolean lock(List<LockableResource> resourcesToLock, Run<?,?> build, @Nullable String reason)
      Try to lock the resource and return true if locked.
      Parameters:
      resourcesToLock - The resources to lock.
      build - The build that is locking the resources.
      reason - The reason why the resources are being locked (displayed in UI).
      Returns:
      true if locked successfully.

    • unlockBuild

      public void unlockBuild(@Nullable Run<?,?> build)

    • unlockNames

      public void unlockNames(@Nullable List<String> resourceNamesToUnLock, Run<?,?> build)

    • unlockResources

      public void unlockResources(List<LockableResource> resourcesToUnLock)

    • unlockResources

      public void unlockResources(List<LockableResource> resourcesToUnLock, Run<?,?> build)

    • getResourcesNames

      @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public static List<String> getResourcesNames(List<LockableResource> resources)
      Returns names (IDs) of given *resources*.

    • getAllResourcesNames

      @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public List<String> getAllResourcesNames()
      Returns names (IDs) off all existing resources (inclusive ephemeral)

    • getCurrentQueuedContext

      @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public List<QueuedContextStruct> getCurrentQueuedContext()
      Returns current queue

    • createResource

      public boolean createResource(@CheckForNull String name)
      Creates the resource if it does not exist and ephemeral resources are allowed.
      Parameters:
      name - the resource name
      Returns:
      true if resource was created, false if it already exists or ephemeral resources are disabled

    • createResourceWithLabel

      public boolean createResourceWithLabel(@CheckForNull String name, @CheckForNull String label)

    • createResourceWithLabelAndProperties

      public boolean createResourceWithLabelAndProperties(@CheckForNull String name, @CheckForNull String label, Map<String,String> properties)

    • addResource

      @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public boolean addResource(@Nullable LockableResource resource)

    • addResource

      @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public boolean addResource(@Nullable LockableResource resource, boolean doSave)

    • reserve

      public boolean reserve(List<LockableResource> resources, String userName)
      Reserves an available resource for the userName indefinitely (until that person, or some explicit scripted action, decides to release the resource).

    • reserve

      public boolean reserve(List<LockableResource> resources, String userName, String reason)
      Reserves an available resource for the userName indefinitely (until that person, or some explicit scripted action, decides to release the resource).
      Parameters:
      resources - list of resources to reserve
      userName - the user reserving the resources
      reason - the reason for reserving (optional)
      Returns:
      true if all resources were successfully reserved, false if any was not free

    • steal

      public boolean steal(List<LockableResource> resources, String userName)
      Reserves a resource that may be or not be locked by some job (or reserved by some user) already, giving it away to the userName indefinitely (until that person, or some explicit scripted action, later decides to release the resource).

    • steal

      public boolean steal(List<LockableResource> resources, String userName, String reason)
      Reserves a resource that may be or not be locked by some job (or reserved by some user) already, giving it away to the userName indefinitely (until that person, or some explicit scripted action, later decides to release the resource).
      Parameters:
      resources - list of resources to steal
      userName - the user stealing the resources
      reason - the reason for stealing (optional)
      Returns:
      true if stolen successfully

    • reassign

      public void reassign(List<LockableResource> resources, String userName)
      Reserves a resource that may be or not be reserved by some person already, giving it away to the userName indefinitely (until that person, or some explicit scripted action, decides to release the resource).

    • unreserve

      public void unreserve(List<LockableResource> resources)

    • getDisplayName

      @NonNull public String getDisplayName()
      Overrides:
      getDisplayName in class Descriptor<GlobalConfiguration>

    • reset

      public void reset(List<LockableResource> resources)

    • recycle

      public void recycle(List<LockableResource> resources)
      Make the lockable resource reusable and notify the queue(s), if any WARNING: Do not use this from inside the lock step closure which originally locked this resource, to avoid nasty surprises! Namely, this *might* let a second consumer use the resource quickly, but when the original closure ends and unlocks again that resource, a third consumer might then effectively hijack it from the second one.

    • changeQueueOrder

      @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public void changeQueueOrder(String queueId, int newPosition) throws IOException
      Change the order (position) of the given item in the queue
      Throws:
      IOException

    • configure

      public boolean configure(org.kohsuke.stapler.StaplerRequest2 req, net.sf.json.JSONObject json)
      Overrides:
      configure in class GlobalConfiguration

    • getAvailableResources

      public List<LockableResource> getAvailableResources(List<LockableResourcesStruct> requiredResourcesList)

    • removeResources

      public void removeResources(List<LockableResource> toBeRemoved)
      Function removes all given resources

    • getAvailableResources

      public List<LockableResource> getAvailableResources(List<LockableResourcesStruct> requiredResourcesList, @Nullable PrintStream logger, @Nullable ResourceSelectStrategy selectStrategy)
      Checks if there are enough resources available to satisfy the requirements specified within requiredResources and returns the necessary available resources. If not enough resources are available, returns null.

    • getAvailableResources

      public List<LockableResource> getAvailableResources(List<LockableResourcesStruct> requiredResourcesList, @Nullable PrintStream logger, @Nullable ResourceSelectStrategy selectStrategy, @NonNull Predicate<LockableResource> candidateFilter)
      As getAvailableResources(List, PrintStream, ResourceSelectStrategy) but restricts the candidate pool to resources accepted by candidateFilter. This is the seam the remote bridge uses to apply its exposeLabel visibility filter; local callers pass "accept all". The filter is a plain predicate (it knows nothing about exposeLabel), so the canonical resolver stays generic. It is applied to the candidate pool before count-based selection, so a label request with amount<=0 ("all") means "all visible matching".

    • printLogs

      public static void printLogs(String msg, Level level, Logger L, @Nullable PrintStream logger)

    • queueContext

      @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public void queueContext(org.jenkinsci.plugins.workflow.steps.StepContext context, List<LockableResourcesStruct> requiredResources, String resourceDescription, String variableName, boolean inversePrecedence, int priority)

    • queueContext

      @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public void queueContext(org.jenkinsci.plugins.workflow.steps.StepContext context, List<LockableResourcesStruct> requiredResources, String resourceDescription, String variableName, boolean inversePrecedence, int priority, String reason, long timeoutForAllocateResource, String timeoutUnit)

    • unqueueContext

      public boolean unqueueContext(org.jenkinsci.plugins.workflow.steps.StepContext context)

    • getCurrentRemoteQueueEntries

      @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public List<RemoteQueueEntry> getCurrentRemoteQueueEntries()
      Returns a read-only snapshot of current remote queue entries. Used by the management UI to show remote API waiters alongside local queue entries.

    • queueRemote

      @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public void queueRemote(@NonNull RemoteQueueEntry entry)
      Adds a remote queue entry in priority-descending order (highest priority at front, matching local pipeline queue ordering). Must be called under syncResources.

    • unqueueRemote

      @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public void unqueueRemote(@NonNull String lockId)
      Removes a remote queue entry by lockId (called when the client cancels a QUEUED request or when a release is received for a QUEUED record). Idempotent. Must be called under syncResources.

    • lockForRemote

      @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public boolean lockForRemote(@NonNull List<LockableResource> resources, @NonNull String lockId)
      Marks resources as remotely locked by lockId. Equivalent to lock(List, Run, String) but uses setRemoteLockedBy() instead of setBuild() so that resources do not require an active Jenkins build.
      Returns:
      false if any resource is not free (defensive; caller should have pre-checked)

    • unlockRemoteResources

      @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public void unlockRemoteResources(@NonNull List<String> resourceNames, @NonNull String lockId)
      Frees remotely locked resources and wakes any waiters (local or remote). Equivalent to unlockResources(List, Run) but for remote locks.

    • get

      public static LockableResourcesManager get()

    • scheduleQueueMaintenance

      public static void scheduleQueueMaintenance()
      Trigger an immediate Queue re-evaluation so items waiting for lockable resources are dispatched as soon as resources become available, instead of waiting for the next 5-second timer tick.

      Must be called outside synchronized(syncResources) to avoid holding the plugin lock while Jenkins acquires the Queue lock.

    • refreshQueue

      public void refreshQueue()
      Refresh the queue to allow waiting jobs to re-evaluate available resources.

      This method should be called after modifying labels on existing resources, as label changes do not automatically trigger queue re-evaluation.

      It performs the following actions:

      1. Invalidates the cached resource candidates
      2. Processes waiting pipeline job contexts
      3. Triggers Jenkins queue maintenance for freestyle jobs

    • checkTimeouts

      @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public void checkTimeouts()
      Checks for timed-out entries in the pipeline lock queue and fails them. Called by LockWaitTimeoutPeriodicWork as a safety net.

    • save

      public void save()
      Specified by:
      save in interface Saveable
      Overrides:
      save in class Descriptor<GlobalConfiguration>

    • flushPendingSave

      @Terminator public static void flushPendingSave()
      Flush any pending async save during Jenkins shutdown so that lock state is never lost on an orderly restart.

    • getFirst

      @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public LockableResource getFirst()
      For testing purpose.