Package org.kiwiproject.validation

Annotation Interface DirectoryPath

@Documented @Constraint(validatedBy={}) @Target({METHOD,FIELD,ANNOTATION_TYPE,CONSTRUCTOR,PARAMETER,TYPE_USE}) @Retention(RUNTIME) public @interface DirectoryPath
The annotated element must point to an existing directory. Please read the implementation note regarding intended usage of this annotation with respect to the potential for Path Traversal attacks.

By default, does not permit null values. If the element being validated allows null values, you can set allowNull() to true.

You can also use ensureReadable() and ensureWritable() to verify that the directory is readable or writable by the current process.

Finally, the mkdirs() option provides a way to actually create the specified directory if it does not exist. Please read the documentation for this option.

Examples: 

 @DirectoryPath
  private String tempDir;
 
 @DirectoryPath(allowNull = true)
  public String getTempDir() { return this.tempDir; }
 
 @DirectoryPath(ensureReadable = true, ensureWritable = true, mkdirs = true)
  private String tempDir;
Implementation Note:
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.

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    boolean
    allowNull
    Whether to consider null as valid.
    boolean
    ensureReadable
    Whether to verify that the specified directory can be read by the current process.
    boolean
    ensureWritable
    Whether to verify that the specified directory can be read by the current process.
    Class<?>[]
    groups
     
    String
    message
     
    boolean
    mkdirs
    Whether this validator will attempt to create the directory if it does not exist.
    Class<? extends jakarta.validation.Payload>[]
    payload
     

  • Element Details

    • message

      String message
      Default:
      "{org.kiwiproject.validation.DirectoryPath.message}"

    • groups

      Class<?>[] groups
      Default:
      {}

    • payload

      Class<? extends jakarta.validation.Payload>[] payload
      Default:
      {}

    • allowNull

      boolean allowNull
      Whether to consider null as valid. The default is false.
      Returns:
      true to consider null as valid
      Default:
      false

    • ensureReadable

      boolean ensureReadable
      Whether to verify that the specified directory can be read by the current process. The default is false (no verification is performed).
      Returns:
      true to validate the directory is readable; if false does not verify
      Default:
      false

    • ensureWritable

      boolean ensureWritable
      Whether to verify that the specified directory can be read by the current process. The default is false (no verification is performed).
      Returns:
      true to validate the directory is writable; if false does not verify
      Default:
      false

    • mkdirs

      boolean mkdirs
      Whether this validator will attempt to create the directory if it does not exist.

      IMPORTANT: This is generally unexpected behavior (to have any side-effects during validation).

      However, based on the use cases we have encountered, this is a pragmatic way to ensure directories are present, and we have found the alternatives to be clumsy at best, overly complicated at worst. One common example is to ensure a temporary or working directory exists for an application to use.

      Regardless, please be sure you understand the side-effecting behavior if you set this to true.

      Returns:
      true to create any missing directories; if false directories are not created
      Default:
      false