hudson.model

Interface Queue.Task

All Superinterfaces:

ModelObject, ResourceActivity, SubTask

All Known Subinterfaces:

BuildableItem, BuildableItemWithBuildWrappers, ParameterizedJobMixIn.ParameterizedJob<JobT,RunT>, Queue.FlyweightTask, Queue.NonBlockingTask, Queue.TransientTask, SCMedItem

All Known Implementing Classes:

AbstractProject, AbstractQueueTask, FreeStyleProject, Project, QueueTaskFilter

Enclosing class:

Queue

public static interface Queue.Task
extends ModelObject, SubTask

Task whose execution is controlled by the queue.

Value equality of Queue.Tasks is used to collapse two tasks into one. This is used to avoid infinite queue backlog.

Pending Queue.Tasks are persisted when Hudson shuts down, so it needs to be persistable via XStream. To create a non-persisted transient Task, extend Queue.TransientTask marker interface.

Plugins are encouraged to extend from AbstractQueueTask instead of implementing this interface directly, to maintain compatibility with future changes to this interface.

Plugins are encouraged to implement AccessControlled otherwise the tasks will be hidden from display in the queue.

For historical reasons, Queue.Task object by itself also represents the "primary" sub-task (and as implied by this design, a Queue.Task must have at least one sub-task.) Most of the time, the primary subtask is the only sub task.

Method Summary

Modifier and Type	Method and Description
void	checkAbortPermission() Checks the permission to see if the current user can abort this executable.
default String	getAffinityKey() Returns task-specific key which is used by the LoadBalancer to choose one particular executor amongst all the free executors on all possibly suitable nodes.
default CauseOfBlockage	getCauseOfBlockage() If the execution of this task should be blocked for temporary reasons, this method returns a non-null object explaining why.
default org.acegisecurity.Authentication	getDefaultAuthentication() This method allows the task to provide the default fallback authentication object to be used when QueueItemAuthenticator fails to authenticate the build.
default org.acegisecurity.Authentication	getDefaultAuthentication(Queue.Item item) This method allows the task to provide the default fallback authentication object to be used when QueueItemAuthenticator fails to authenticate the build.
String	getFullDisplayName()
String	getName() Unique name of this task.
default Collection<? extends SubTask>	getSubTasks() Obtains the SubTasks that constitute this task.
String	getUrl() Returns the URL of this task relative to the context root of the application.
default String	getWhyBlocked() Deprecated. as of 1.330 Use CauseOfBlockage.getShortDescription() instead.
boolean	hasAbortPermission() Works just like checkAbortPermission() except it indicates the status by a return value, instead of exception.
default boolean	isBuildBlocked() Deprecated. Use getCauseOfBlockage() != null
default boolean	isConcurrentBuild() True if the task allows concurrent builds, where the same Queue.Task is executed by multiple executors concurrently on the same or different nodes.

Methods inherited from interface hudson.model.ModelObject

getDisplayName

Methods inherited from interface hudson.model.queue.SubTask

createExecutable, getAssignedLabel, getEstimatedDuration, getLastBuiltOn, getOwnerTask, getSameNodeConstraint

Methods inherited from interface hudson.model.ResourceActivity

getDisplayName, getResourceList

Method Detail

isBuildBlocked

@Deprecated
default boolean isBuildBlocked()

Deprecated. Use getCauseOfBlockage() != null

Returns true if the execution should be blocked for temporary reasons.

getWhyBlocked

@Deprecated
default String getWhyBlocked()

Deprecated. as of 1.330 Use CauseOfBlockage.getShortDescription() instead.

getCauseOfBlockage

@CheckForNull
default CauseOfBlockage getCauseOfBlockage()

If the execution of this task should be blocked for temporary reasons, this method returns a non-null object explaining why.

Otherwise this method returns null, indicating that the build can proceed right away.

This can be used to define mutual exclusion that goes beyond ResourceActivity.getResourceList().

Returns:

by default, null

getName

String getName()

Unique name of this task.

This method is no longer used, left here for compatibility. Just return ModelObject.getDisplayName().

getFullDisplayName

String getFullDisplayName()

See Also:

Item.getFullDisplayName()

getAffinityKey

default String getAffinityKey()

Returns task-specific key which is used by the LoadBalancer to choose one particular executor amongst all the free executors on all possibly suitable nodes. NOTE: To be able to re-use the same node during the next run this key should not change from one run to another. You probably want to compute that key based on the job's name.

Returns:

by default: getFullDisplayName()

See Also:

LoadBalancer

checkAbortPermission

void checkAbortPermission()

Checks the permission to see if the current user can abort this executable. Returns normally from this method if it's OK.

NOTE: If you have implemented AccessControlled this should just be checkPermission(hudson.model.Item.CANCEL);

Throws:

org.acegisecurity.AccessDeniedException - if the permission is not granted.

hasAbortPermission

boolean hasAbortPermission()

Works just like checkAbortPermission() except it indicates the status by a return value, instead of exception. Also used by default for Queue.Item.hasCancelPermission().

NOTE: If you have implemented AccessControlled this should just be return hasPermission(hudson.model.Item.CANCEL);

Returns:

false if the user doesn't have the permission.

getUrl

String getUrl()

Returns the URL of this task relative to the context root of the application.

When the user clicks an item in the queue, this is the page where the user is taken to. Hudson expects the current instance to be bound to the URL returned by this method.

Returns:

URL that ends with '/'.

isConcurrentBuild

default boolean isConcurrentBuild()

True if the task allows concurrent builds, where the same Queue.Task is executed by multiple executors concurrently on the same or different nodes.

Returns:

by default, false

Since:

1.338

getSubTasks

default Collection<? extends SubTask> getSubTasks()

Obtains the SubTasks that constitute this task.

The collection returned by this method must also contain the primary SubTask represented by this Queue.Task object itself as the first element. The returned value is read-only.

At least size 1.

Returns:

by default, this

Since:

1.377

getDefaultAuthentication

@NonNull
default org.acegisecurity.Authentication getDefaultAuthentication()

This method allows the task to provide the default fallback authentication object to be used when QueueItemAuthenticator fails to authenticate the build.

When the task execution touches other objects inside Jenkins, the access control is performed based on whether this Authentication is allowed to use them.

Returns:

by default, ACL.SYSTEM

Since:

1.520

See Also:

QueueItemAuthenticator, Tasks.getDefaultAuthenticationOf(Queue.Task)

getDefaultAuthentication

@NonNull
default org.acegisecurity.Authentication getDefaultAuthentication(Queue.Item item)

This method allows the task to provide the default fallback authentication object to be used when QueueItemAuthenticator fails to authenticate the build.

When the task execution touches other objects inside Jenkins, the access control is performed based on whether this Authentication is allowed to use them.

This method was added to an interface after it was created, so plugins built against older versions of Jenkins may not have this method implemented. Called private method _getDefaultAuthenticationOf(Task) on Tasks to avoid AbstractMethodError.

Since:

1.592

See Also:

QueueItemAuthenticator, Tasks.getDefaultAuthenticationOf(Queue.Task, Queue.Item)