Improving directory handling exceptions

Current Situation

• YADE performs the following directory operations:
  • Source
    • Check whether the source directory exists and can be read.
    • Delete the source directory if the source post-processing built-in command REMOVE_DIRECTORY() is used.
  • Target
    • Check whether the target directory exists and can be written to.
    • Create the target directories if DisableMakeDirectories=false (default).
    • Delete the target directory if the target post-processing built-in command REMOVE_DIRECTORY() is used.
• If an error occurs during directory handling, the exception is properly thrown, including the original exception from the underlying provider.
• However, generic YADEEngine exceptions are currently used, and the exception message formats are not standardized across all providers.
• For example, if a source directory does not exist on an SFTP server:

  com.sos.yade.engine.exceptions.YADEEngineSourceFilesSelectorException: com.sos.commons.vfs.exceptions.ProviderException: [Source][my_source_dir][selectFiles]net.schmizz.sshj.sftp.SFTPException: No such file
  

  Instead of a dedicated SourceDirectoryNotFoundException, the exception chain above requires additional analysis to determine what actually happened.

Desired Behavior

• Introduce dedicated directory-related exceptions to make directory handling errors:
  • immediately understandable from the exception type
  • consistent across all providers
  • and ensure that the original underlying provider exception remains available as the cause of the dedicated exception
• The YADE-specific return codes introduced with YADE-656 should be extended with directory-specific return codes.

Maintainer Note

• Provider Exceptions API (YADE-independent):
  • ProviderDirectoryException - generic directory operation error, e.g. read/write.
  • ProviderDirectoryCreationException
  • ProviderDirectoryNotFoundException
    • Limitation for the FTP/FTPS provider
      • A generic ProviderDirectoryException exception will be thrown instead of ProviderDirectoryNotFoundException
      • FTP/FTPS does not provide a dedicated reply code for directory not found.
      • The generic 550 reply code can have different meanings, including not found and access denied.
      • Therefore, 550 cannot be reliably mapped to ProviderDirectoryNotFoundException.
      • See https://www.rfc-editor.org/info/rfc959/
    • Limitation for the HTTP/HTTPS provider
      • YADE throws a ProviderUnsupportedOperationException: selecting specific files from an <provider> directory is not supported
• YADE Exceptions
  • YADEEngineSourceDirectoryException
  • YADEEngineSourceDirectoryNotFoundException
  • YADEEngineTargetDirectoryException
  • YADEEngineTargetDirectoryCreationException
  • YADEEngineTargetDirectoryNotFoundException
• Directory-specific return codes (JS7 2.9.1) - full list of available return codes: see YADE-656.
  • 35 - The source directory was not found.
  • 38 - Generic source directory error (e.g. read/delete/access denied) and fallback for all other unclassified source directory related errors.
  • 45 - DisableMakeDirectories=true and the target directory was not found.
  • 46 - DisableMakeDirectories=false and target directories could not be created.
  • 48 - Generic target directory error (e.g. read/write/delete/access denied) and fallback for all other unclassified target directory related errors.