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:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	FormValidation.CheckMethod Builds up the check URL for the client-side JavaScript to call back.
static class	FormValidation.FileValidator Performs an application-specific validation on the given file.
static class	FormValidation.Kind Indicates the kind of result.
static class	FormValidation.URLCheck Convenient base class for checking the validity of URLs.

Field Summary

Fields

Modifier and Type	Field and Description
FormValidation.Kind	kind

Method Summary

Modifier and Type	Method and Description
static FormValidation	aggregate(Collection<FormValidation> validations) Aggregate multiple validations into one.
static FormValidation	error(String message) Sends out a string error message that indicates an error.
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[])
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.
static FormValidation	error(Throwable e, String format, Object... args)
static FormValidation	errorWithMarkup(String message) Sends out an HTML fragment that indicates an error.
void	generateResponse(org.kohsuke.stapler.StaplerRequest req, org.kohsuke.stapler.StaplerResponse rsp, Object node)
static FormValidation	ok()
static FormValidation	ok(String message)
static FormValidation	ok(String format, Object... args)
static FormValidation	okWithMarkup(String message)
abstract String	renderHtml()
static FormValidation	respond(FormValidation.Kind kind, String html) Sends out an arbitrary HTML fragment as the output.
protected void	respond(org.kohsuke.stapler.StaplerResponse rsp, String html) Sends out an arbitrary HTML fragment as the output.
static FormValidation	validateBase64(String value, boolean allowWhitespace, boolean allowEmpty, String errorMessage) Makes sure that the given string is a base64 encoded text.
static FormValidation	validateExecutable(String exe) Makes sure that the given string points to an executable file.
static FormValidation	validateExecutable(String exe, FormValidation.FileValidator exeValidator) Makes sure that the given string points to an executable file.
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)
static FormValidation	validateNonNegativeInteger(String value) Makes sure that the given string is a non-negative integer.
static FormValidation	validatePositiveInteger(String value) Makes sure that the given string is a positive integer.
static FormValidation	validateRequired(String value) Makes sure that the given string is not null or empty.
static FormValidation	warning(String message)
static FormValidation	warning(String format, Object... args)
static FormValidation	warning(Throwable e, String message)
static FormValidation	warning(Throwable e, String format, Object... args)
static FormValidation	warningWithMarkup(String message)

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

Field Detail

kind

public final FormValidation.Kind kind

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

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