Package Torello.Java

Class WritableDirectoryException

  • All Implemented Interfaces:
    java.io.Serializable
    public class WritableDirectoryException
extends java.lang.RuntimeException
    Used by methods that accept 'target directory' parameters to validate that the parameter's contents actually point to a both valid and writable location on disk.

    This Exception is used to check Directory Name parameters that are passed to classes in this library. It has a check(String dirName) method that will perform a series of tests to ensure that a directory exists on the File-System, and that contents may be written to that directory.

    When a check fails, a consistently worded Exception-Message is provided.
    See Also:
    Serialized Form


    • Constructor Summary

      Constructors 
      Constructor Description
      WritableDirectoryException()
      Constructs a WritableDirectoryException with no detail message.
      WritableDirectoryException​(String message)
      Constructs a WritableDirectoryException with the specified detail message.
      WritableDirectoryException​(String message, Throwable cause)
      Constructs a new exception with the specified detail message and cause.
      WritableDirectoryException​(Throwable cause)
      Constructs a new exception with the specified cause and a detail message of (cause==null ? null : cause.toString()) (which typically contains the class and detail message of cause).

    • Method Summary

       
      'static' Exception Check Methods
      Modifier and Type Method
      static void check​(File directory)
      static void check​(String directory)

      • 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

      • serialVersionUID

        🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final long serialVersionUID
        This fulfils the SerialVersion UID requirement for all classes that implement Java's interface java.io.Serializable. Using the Serializable Implementation offered by java is very easy, and can make saving program state when debugging a lot easier. It can also be used in place of more complicated systems like "hibernate" to store data as well.

        Note that Java's java.lang.Exception and java.lang.Error classes implement the Serializable interface, and a warning-free build expects this field be defined here.
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
         public static final long serialVersionUID = 1;

      • THROW_ON_ZERO_LENGTH_STRING

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static boolean THROW_ON_ZERO_LENGTH_STRING
        This boolean allows a user to decide whether the zero-length String should force an exception throw when passed to this class' check(String) method. When this boolean is set to TRUE, the class will check whether or not the directory named by the String returned by a call to System.getProperty("user.dir") is writable.

        An invocation to method System.getProperty("user.dir") returns a String that contains the current user's home directory. If this directory is writable, then no exception throw shall occur when testing and passing a zero-length String to the 'directory' parameter of the check(String) method.

        When this parameter is set to FALSE, and when a zero-length String is passed to the 'directory' parameter of the 'check(String)' method.

        DEFAULT: The default behavior of method check(String) is to throw an exception whenever the zero-length String is passed.

    • Constructor Detail

      • WritableDirectoryException

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public WritableDirectoryException​(java.lang.String message,
                                  java.lang.Throwable cause)
        Constructs a new exception with the specified detail message and cause.

        NOTE:

        The detail message associated with cause is not automatically incorporated into this exception's detail message.
        Parameters:
        message - The detail message (which is saved for later retrieval by the Throwable.getMessage() method).
        cause - the cause (which is saved for later retrieval by the Throwable.getCause() method). (A null value is permitted, and indicates that the cause is nonexistent or unknown.)

      • WritableDirectoryException

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public WritableDirectoryException​(java.lang.Throwable cause)
        Constructs a new exception with the specified cause and a detail message of (cause==null ? null : cause.toString()) (which typically contains the class and detail message of cause). This constructor is useful for exceptions that are little more than wrappers for other Throwable's.
        Parameters:
        cause - The cause (which is saved for later retrieval by the Throwable.getCause() method). (A null value is permitted, and indicates that the cause is nonexistent or unknown.)

    • Method Detail

      • check

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static void check​(java.lang.String directory)
        Checks that a directory-name is valid and ready for saving image files.
        Parameters:
        directory - This is the directory-name to be tested.
        Throws:
        WritableDirectoryException - Throws under any of the following circustances:

        • Parameter 'directory' has been passed null.

        • Parameter 'directory' is a zero length String, and the configurable public and static boolean THROW_ON_ZERO_LENGTH_STRING has been set to TRUE.

        • The directory specified by parameter 'directory' does not exist anywhere on the file-system.

        • The file specified by parameter 'directory' exists, but is a file, rather than a directory.

        • This method was unable to write a small, temporary file to that directory, and in the process of attempting to do so caused a Java IOException to be thrown.

          Note that in this case, the IOException that was thrown (and caught) will be assigned as the 'cause' exception, and may be retrieved by calling 'this' exception's getCause() method.
        Code:
        Exact Method Body:
         if (directory == null) throw new WritableDirectoryException
     ("Parameter 'directory' was passed null");

 if (directory == "")
 {
     if (THROW_ON_ZERO_LENGTH_STRING) throw new WritableDirectoryException(
         "You have passed the zero-length String to the class " +
         "WritableDirectoryException's 'check' method.  If this is the desired behavior, " +
         "there is a configurable, static, boolean named 'THROW_ON_ZERO_LENGTH_STRING' " + 
         "in this class that should be set to FALSE.  Currently, when the zero-length " +
         "String is passed here, an exception (this one) is thrown immediately.  If this " +
         "configuration-boolean were TRUE, the directory checked would be the one " +
         "returned by a call to System.getProperty(\"user.dir\")"
     );

     directory = System.getProperty("user.dir");
 }

 check(new File(directory));

      • check

        🡅  ⇈  ⮫ 🗕  🗗  🗖 
        public static void check​(java.io.File directory)
        Checks that a directory-name is valid and ready for saving image files.
        Parameters:
        directory - This is the directory-name to be tested.
        Throws:
        WritableDirectoryException - Throws under any of the following circustances:

        • Parameter 'directory' has been passed null.

        • The directory specified by parameter 'directory' does not exist anywhere on the file-system.

        • The file specified by parameter 'directory' exists, but is a file, rather than a directory.

        • This method was unable to write a small, temporary file to that directory, and in the process of attempting to do so caused a Java IOException to be thrown.

          Note that in this case, the IOException that was thrown (and caught) will be assigned as the 'cause' exception, and may be retrieved by calling 'this' exception's getCause() method.
        Code:
        Exact Method Body:
         if (directory == null) throw new WritableDirectoryException
     ("Parameter 'directory' was passed null");

 // Make sure that the directory name exists on the file-system.  If not throw exception
 if (! directory.exists()) throw new WritableDirectoryException(
     "The directory-name [" + directory.toString() + "], that you have passed does not " +
     "exist, or could not be found be the file-system."
 );

 // Make sure that the directory-named is actually a directory, not a file, link, etc...
 if (! directory.isDirectory()) throw new WritableDirectoryException(
     "The directory-name [" + directory.toString() + "], that you have passed was found, " +
     "but it is not a valid directory-name on the file-system."
 );

 // Make sure that the directory provided is writable, or throw an exception.
 try
 {
     File f = File.createTempFile("test", "tmp", directory);
     f.delete();
 }

 catch (IOException ioe)
 {
     throw new WritableDirectoryException(
         "There was a JavaIOException when attempting to write a file to the directory-name " +
         '[' + directory.toString() + "].  Please see this exception's getCause() " +
         "throwable for more details.",
         ioe
     );
 }