Package hudson.util

Class FormValidation

java.lang.Object
java.lang.Throwable
java.lang.Exception
java.io.IOException
hudson.util.FormValidation
All Implemented Interfaces:
Serializable, org.kohsuke.stapler.HttpResponse
public abstract class FormValidation extends IOException implements org.kohsuke.stapler.HttpResponse
Represents the result of the form field validation.

Use one of the factory methods to create an instance, then return it from your doCheckXyz method. (Via HttpResponse, the returned object will render the result into StaplerResponse.) This way of designing form field validation allows you to reuse doCheckXyz() methods programmatically as well (by using kind.

For typical validation needs, this class offers a number of validateXXX(...) methods, such as validateExecutable(String). FilePath also has a number of validateXXX(...) methods that you may be able to reuse.

Also see doCheckCvsRoot in CVSSCM as an example.

This class extends IOException so that it can be thrown from a method. This allows one to reuse the checking logic as a part of the real computation, such as: 

 String getAntVersion(File antHome) throws FormValidation {
    if (!antHome.isDirectory())
        throw FormValidation.error(antHome+" doesn't look like a home directory");
    ...
    return IOUtils.toString(new File(antHome,"version"));
 }

 ...

 public FormValidation doCheckAntVersion(@QueryParameter String f) {
     try {
         return ok(getAntVersion(new File(f)));
     } catch (FormValidation f) {
         return f;
     }
 }

 ...

 public void perform(...) {
     String version = getAntVersion(antHome);
     ...
 }
Since:
1.294
Author:
Kohsuke Kawaguchi
See Also:

  • Field Details

  • Method Details

    • error

      public static FormValidation error(String message)
      Sends out a string error message that indicates an error.
      Parameters:
      message - Human readable message to be sent. error(null) can be used as ok().

    • warning

      public static FormValidation warning(String message)

    • ok

      public static FormValidation ok(String message)

    • ok

      public static FormValidation ok()

    • error

      public static FormValidation error(String format, Object... args)
      Sends out a string error message that indicates an error, by formatting it with String.format(String, Object[])

    • warning

      public static FormValidation warning(String format, Object... args)

    • ok

      public static FormValidation ok(String format, Object... args)

    • error

      public static FormValidation error(Throwable e, String message)
      Sends out a string error message, with optional "show details" link that expands to the full stack trace.

      Use this with caution, so that anonymous users do not gain too much insights into the state of the system, as error stack trace often reveals a lot of information. Consider if a check operation needs to be exposed to everyone or just those who have higher access to job/hudson/etc.

    • warning

      public static FormValidation warning(Throwable e, String message)

    • error

      public static FormValidation error(Throwable e, String format, Object... args)

    • warning

      public static FormValidation warning(Throwable e, String format, Object... args)

    • aggregate

      @NonNull public static FormValidation aggregate(@NonNull Collection<FormValidation> validations)
      Aggregate multiple validations into one.
      Returns:
      Validation of the least successful kind aggregating all child messages.
      Since:
      1.590

    • errorWithMarkup

      public static FormValidation errorWithMarkup(String message)
      Sends out an HTML fragment that indicates an error.

      This method must be used with care to avoid cross-site scripting attack.

      Parameters:
      message - Human readable message to be sent. error(null) can be used as ok().

    • warningWithMarkup

      public static FormValidation warningWithMarkup(String message)

    • okWithMarkup

      public static FormValidation okWithMarkup(String message)

    • respond

      public static FormValidation respond(FormValidation.Kind kind, String html)
      Sends out an arbitrary HTML fragment as the output.

    • validateExecutable

      public static FormValidation validateExecutable(String exe)
      Makes sure that the given string points to an executable file.

    • validateExecutable

      public static FormValidation validateExecutable(String exe, FormValidation.FileValidator exeValidator)
      Makes sure that the given string points to an executable file.
      Parameters:
      exeValidator - If the validation process discovers a valid executable program on the given path, the specified FormValidation.FileValidator can perform additional checks (such as making sure that it has the right version, etc.)

    • validateNonNegativeInteger

      public static FormValidation validateNonNegativeInteger(String value)
      Makes sure that the given string is a non-negative integer.

    • validateIntegerInRange

      public static FormValidation validateIntegerInRange(String value, int lower, int upper)
      Make sure that the given string is an integer in the range specified by the lower and upper bounds (both inclusive)
      Parameters:
      value - the value to check
      lower - the lower bound (inclusive)
      upper - the upper bound (inclusive)
      Since:
      2.104

    • validatePositiveInteger

      public static FormValidation validatePositiveInteger(String value)
      Makes sure that the given string is a positive integer.

    • validateRequired

      public static FormValidation validateRequired(String value)
      Makes sure that the given string is not null or empty.

    • validateBase64

      public static FormValidation validateBase64(String value, boolean allowWhitespace, boolean allowEmpty, String errorMessage)
      Makes sure that the given string is a base64 encoded text.
      Parameters:
      allowWhitespace - if you allow whitespace (CR,LF,etc) in base64 encoding
      allowEmpty - Is empty string allowed?
      errorMessage - Error message.
      Since:
      1.305

    • generateResponse

      public void generateResponse(org.kohsuke.stapler.StaplerRequest req, org.kohsuke.stapler.StaplerResponse rsp, Object node) throws IOException, javax.servlet.ServletException
      Specified by:
      generateResponse in interface org.kohsuke.stapler.HttpResponse
      Throws:
      IOException
      javax.servlet.ServletException

    • renderHtml

      public abstract String renderHtml()

    • respond

      protected void respond(org.kohsuke.stapler.StaplerResponse rsp, String html) throws IOException, javax.servlet.ServletException
      Sends out an arbitrary HTML fragment as the output.
      Throws:
      IOException
      javax.servlet.ServletException