Package io.jenkins.plugins.batchcontrol.ui

Class ApprovalRequiredFailure

java.lang.Object

java.lang.Throwable

java.lang.Exception

java.lang.RuntimeException

hudson.model.Failure

io.jenkins.plugins.batchcontrol.ui.ApprovalRequiredFailure

All Implemented Interfaces:

Serializable, org.kohsuke.stapler.HttpResponse

@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
public class ApprovalRequiredFailure
extends Failure

The refusal of a user-originated manual run of an approval-required job (SPEC item 6, e2e-03 DEF-02), thrown by the queue gate in place of a plain Failure.

Throwable.getMessage() is the gate's plain-text guidance, unchanged for the CLI and for any caller that only reads the message. In a browser (the parameterized build form posts to core's build and gets this page back) generateResponse(org.kohsuke.stapler.StaplerRequest2, org.kohsuke.stapler.StaplerResponse2, java.lang.Object, java.lang.Throwable) renders index.jelly instead of core's generic error page, which printed the request URL as text: the page links the request form only for a BatchControl/Request holder, the only user for whom that URL is not a 404 (JobRequestAction#getUrlName()), and tells anyone else whom to ask. It answers HTTP 400 like the Failure it replaces and never changes state.

Only the job's full name is kept (the exception is Serializable); the job is looked up again for the page as the viewing user, so a job the viewer cannot read is simply not linked.

D-60: a refused parameterized build leads to the Request Run form

When a person's submission to the build or buildWithParameters endpoint of a parameterized job is refused and the viewer may request runs (isCanRequest()), the answer is a 303 redirect to the job's Request Run form with the submitted values carried as p.<name> query parameters (RequestRunPrefill; sensitive values never). This covers the classic build form, buildWithParameters from a browser and the parameters dialog of the new job page: that dialog submits with fetch and, given a page without a form, re-opened the response URL with GET — core's classic parameters form, which asked for the values a second time. A followed redirect is opened as it is, so the dialog now leads to the request form. Nothing is queued or stored by the redirect. Re-runs (Rebuild, Retry, Replay) post elsewhere and keep the page below.

Any other viewer gets this page. Its content sits inside a <form> with no action and no controls, never submitted, only so that the new job page's dialog shows the refusal in place (it renders the first form of a response) instead of re-opening the classic form.

R4-02: a script gets the plain message, never the redirect

A script (isScriptCaller(org.kohsuke.stapler.StaplerRequest2)) that posts to buildWithParameters or build with an API token must see the refusal as a failure: curl -fL followed the 303 to the HTML form, got 200 and exited 0 although nothing was queued. A script therefore gets HTTP 400 with Throwable.getMessage() as text/plain, before any redirect or page; the message is the gate's existing wording. Browsers keep the D-60 redirect and the page above.

See Also:

• Serialized Form

Constructor Summary

Constructors

Constructor	Description
ApprovalRequiredFailure(Job<?,?> job, String message)
ApprovalRequiredFailure(Job<?,?> job, String message, List<ParameterValue> submitted)

Method Summary

Modifier and Type	Method	Description
void	generateResponse(org.kohsuke.stapler.StaplerRequest2 req, org.kohsuke.stapler.StaplerResponse2 rsp, Object node)
void	generateResponse(org.kohsuke.stapler.StaplerRequest2 req, org.kohsuke.stapler.StaplerResponse2 rsp, Object node, Throwable throwable)
Job<?,?>	getJob()	The refused job as the viewer sees it, or null when the viewer cannot read it.
String	getJobFullName()
boolean	isCanRequest()	Whether the page links the request form: the viewer may submit a run request for the job (BatchControl/Request, without which <job>/batch-control/ answers 404, and Item/Read; Item/Build is not required, D-38a).

Methods inherited from class java.lang.Throwable

addSuppressed, fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, getSuppressed, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.kohsuke.stapler.HttpResponse

generateResponse

Constructor Details

ApprovalRequiredFailure

public ApprovalRequiredFailure(Job<?,?> job,
 String message)

Parameters:

job - the approval-required job whose run was refused

message - the plain-text guidance returned by Throwable.getMessage()

ApprovalRequiredFailure

public ApprovalRequiredFailure(Job<?,?> job,
 String message,
 @CheckForNull
 List<ParameterValue> submitted)

Parameters:

job - the approval-required job whose run was refused

message - the plain-text guidance returned by Throwable.getMessage()

submitted - the parameter values of the refused submission (its ParametersAction), or null; only those RequestRunPrefill.carriedValues(hudson.model.Job<?, ?>, java.util.List<hudson.model.ParameterValue>) allows are kept

Method Details

getJobFullName

public String getJobFullName()

getJob

@CheckForNull
public Job<?,?> getJob()

The refused job as the viewer sees it, or null when the viewer cannot read it.

isCanRequest

public boolean isCanRequest()

Whether the page links the request form: the viewer may submit a run request for the job (BatchControl/Request, without which <job>/batch-control/ answers 404, and Item/Read; Item/Build is not required, D-38a).

generateResponse

public void generateResponse(org.kohsuke.stapler.StaplerRequest2 req,
 org.kohsuke.stapler.StaplerResponse2 rsp,
 Object node,
 @CheckForNull
 Throwable throwable)
                      throws IOException,
jakarta.servlet.ServletException

Overrides:

generateResponse in class Failure

Throws:

IOException

jakarta.servlet.ServletException

generateResponse

public void generateResponse(org.kohsuke.stapler.StaplerRequest2 req,
 org.kohsuke.stapler.StaplerResponse2 rsp,
 Object node)
                      throws IOException,
jakarta.servlet.ServletException

Specified by:

generateResponse in interface org.kohsuke.stapler.HttpResponse

Overrides:

generateResponse in class Failure

Throws:

IOException

jakarta.servlet.ServletException