org.kiwiproject.validation.FilePath Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of kiwi Show documentation

Kiwi is a utility library. We really like Google's Guava, and also use Apache Commons. But if they don't have something we need, and we think it is useful, this is where we put it.

There is a newer version: 4.5.2

Show newest version

package org.kiwiproject.validation;

import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
import static java.lang.annotation.ElementType.CONSTRUCTOR;
import static java.lang.annotation.ElementType.FIELD;
import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.ElementType.PARAMETER;
import static java.lang.annotation.ElementType.TYPE_USE;
import static java.lang.annotation.RetentionPolicy.RUNTIME;

import jakarta.validation.Constraint;
import jakarta.validation.Payload;

import java.lang.annotation.Documented;
import java.lang.annotation.Retention;
import java.lang.annotation.Target;

/**
 * The annotated element must point to an existing file. Please read the implementation note regarding
 * intended usage of this annotation with respect to the potential for
 * Path Traversal attacks.
 * 
 * By default, this does not permit null values. If the element being validated allows {@code null} values, you can
 * set {@link #allowNull()} to {@code true}.
 * 

 * Examples:
 * 
 * {@literal @}FilePath
 *  private String location;
 * 
 *  * {@literal @}FilePath(allowNull = true)
 *  public String getLocation() { return this.location; }
 * 
 *
 * @implNote This annotation is not intended to validate user input from client-side applications, because of the
 * possibility of Path Traversal attacks. Instead,
 * the intended usage is to validate application configuration parameters, e.g., an application reads a local
 * configuration file at startup. Even this is not 100% safe, since the configuration could come from a remote
 * location such as a configuration service, so users should understand the usage risks and mitigate when possible.
 */
@Documented
@Constraint(validatedBy = {})
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
@Retention(RUNTIME)
public @interface FilePath {

    String message() default "{org.kiwiproject.validation.FilePath.message}";

    Class[] groups() default {};

    Class[] payload() default {};

    /**
     * Whether to consider null as valid. The default is false.
     *
     * @return true to consider null as valid
     */
    boolean allowNull() default false;
}