Package hudson.util

Class 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:
    Serialized Form

    • Method Detail

      • 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().

      • 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.

      • 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().

      • 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