Package io.jenkins.plugins.batchcontrol.ui

Class FormErrors

java.lang.Object
io.jenkins.plugins.batchcontrol.ui.FormErrors
@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public final class FormErrors extends Object
The refusal of a submitted form, rendered on the form itself (SPEC section 6 usability line, e2e-03 DEF-09): the message sits next to the field it is about and what the user typed is kept.

A do* endpoint that refuses its input builds one of these and calls render(org.kohsuke.stapler.StaplerRequest2, org.kohsuke.stapler.StaplerResponse2, java.lang.Object): the same request is forwarded to the screen's index.jelly with HTTP 400 (the status the plain Failure page answered before, so scripted callers see no change), and the view asks current(String) for the messages and the submitted values. Nothing here changes state; it runs after the endpoint's permission checks.

Submitted values are read back from the request only while an instance is attached to it, i.e. only on the POST that is being refused. A GET never gets a value from its query string into a field this way, and every value is rendered through Jelly's default escaping.

form names which form on a page failed, so a page with several forms (approve and reject both have a comment field) refills only the one that was submitted.

  • Constructor Details

    • FormErrors

      public FormErrors(String form)
      Parameters:
      form - the name of the form that was submitted (reject, create, ...)

  • Method Details

    • field

      public FormErrors field(String field, String text)
      Adds a message shown next to field; the first message for a field wins.

    • message

      public FormErrors message(String text)
      Sets the message shown above the form (one that is not about a single field).

    • fromService

      public FormErrors fromService(@CheckForNull String text, String... keywords)
      Files a service refusal next to the field its text is about, or above the form when no keyword matches. keywords alternates keyword and field name ("reason", "reason", "approver", "approvers"); the first keyword found in the message (case-insensitive) decides.

    • fromServiceStartingWith

      public FormErrors fromServiceStartingWith(@CheckForNull String text, String... prefixes)
      As fromService(java.lang.String, java.lang.String...), but a keyword counts only at the start of the message (case-insensitive). D-72b: for messages that may quote user data further on (parameter names, for one), so a word inside the quoted data cannot misfile the message.

    • attach

      public FormErrors attach(@CheckForNull Object data)
      Endpoint-side data the view needs to rebuild the form (for example parsed parameters).

    • withoutInput

      public FormErrors withoutInput()
      D-72: the submission is refused without its input being read (its body is over the size cap, and reading a field would parse it), so the form is shown empty: value(java.lang.String) and checked(java.lang.String, java.lang.String) return nothing and the view may use its defaults.

    • isEmpty

      public boolean isEmpty()
      Whether anything was refused.

    • isPresent

      public boolean isPresent()
      The inverse of isEmpty(), for Jelly.

    • isInputKept

      public boolean isInputKept()
      Whether the refused form is shown with the user's input (value(java.lang.String), checked(java.lang.String, java.lang.String)): something was refused and the input could be read (withoutInput()).

    • getForm

      public String getForm()

    • getMessage

      @CheckForNull public String getMessage()
      The message above the form, or null.

    • get

      @CheckForNull public String get(String field)
      The message next to field, or null.

    • getAttachment

      @CheckForNull public Object getAttachment()

    • value

      public String value(String field)
      What the user submitted in field; empty when nothing is being refused. D-72b: each character XML cannot hold is given back as U+FFFD (displayable(java.lang.String)). R4-03: on a multipart body the text is read as typed (RepeatedField.text(org.kohsuke.stapler.StaplerRequest2, java.lang.String): the json blob's value, else the part as UTF-8), not as Stapler's ISO-8859-1 reading of the part.

    • displayable

      public static String displayable(String text)
      D-72b: text with each character XML 1.0 cannot hold (U+0000, a lone surrogate, ...) replaced by U+FFFD, as a browser shows it. A refusal for such a character gives the input back this way, so the page never carries the character itself and the user sees where it was.

    • checked

      public boolean checked(String field, String value)
      Whether value was among the submitted values of the repeated field. D-37: on a multipart body Stapler keeps only the last part of the field, so the form's json blob is read instead when it holds values for the field (RepeatedField), and a refused form re-renders the same boxes checked that the service saw.

    • render

      public void render(org.kohsuke.stapler.StaplerRequest2 req, org.kohsuke.stapler.StaplerResponse2 rsp, Object it) throws IOException, jakarta.servlet.ServletException
      Forwards the current request to it's index.jelly with HTTP 400 and this refusal attached.
      Throws:
      IOException
      jakarta.servlet.ServletException

    • render

      public void render(org.kohsuke.stapler.StaplerRequest2 req, org.kohsuke.stapler.StaplerResponse2 rsp, Object it, String view) throws IOException, jakarta.servlet.ServletException
      As render(StaplerRequest2, StaplerResponse2, Object), to the view view of it: D-66, a form submitted from a dialog is answered with the dialog's own view, so core's dialog replaces its form with the refused one (messages shown, input kept).
      Throws:
      IOException
      jakarta.servlet.ServletException

    • render

      public void render(org.kohsuke.stapler.StaplerRequest2 req, org.kohsuke.stapler.StaplerResponse2 rsp, Object it, String view, int status) throws IOException, jakarta.servlet.ServletException
      As render(StaplerRequest2, StaplerResponse2, Object, String) with the HTTP status status (D-72: 413 for a body over the size cap).
      Throws:
      IOException
      jakarta.servlet.ServletException

    • current

      public static FormErrors current(String form)
      The refusal of form form on this request, or an empty one. Never null.

    • current

      public static FormErrors current()
      The refusal attached to this request, whatever form it is for, or an empty one.