001package Torello.Java;
002
003/**
004 * Thrown when a <CODE>FileNode</CODE> operation has been invoked on an instance that represents
005 * an Operating-System <B><CODE>Directory</CODE></B>, but that invoked-method may only be applied
006 * to Operating-System <B><CODE>File</CODE></B> instances.  This is a {@code RuntimeException},
007 * not a checked-exception.
008 *
009 * <BR /><BR /><EMBED CLASS="external-html" DATA-FILE-ID="EXPM">
010 */
011public class FileExpectedException extends RuntimeException
012{
013    /** <EMBED CLASS="external-html" DATA-FILE-ID="SVUIDEX">  */
014    public static final long serialVersionUID = 1;
015
016    /**
017     * <EMBED CLASS="external-html" DATA-FILE-ID="EXPF">
018     * 
019     * <BR /><BR />This public final field contains the {@code FileNode} that caused an exception
020     * to throw.
021     */
022    public final FileNode fn;
023
024    /**
025     * Constructs a new exception with the specified detail message, and one {@code public, final} 
026     * parameter: {@code fn}.
027     * 
028     * @param message This is any message informing the user what has occurred.
029     * 
030     * @param fn This is the instance of {@code class FileNode} that was involved in the mistake.
031     * <B><I>This parameter should not be left null.</I></B>  If it were accidentally left null,
032     * this could force exception-handling code to to throw exceptions while checking exceptions!
033     * 
034     * @see #fn
035     */
036    public FileExpectedException(String message, FileNode fn)
037    { super(message); this.fn = fn; }
038
039    /**
040     * Constructs a new exception with the specified detail message, cause-chain 
041     * {@code Throwable}, and one {@code public, final} parameter: {@code fn}.
042     * 
043     * @param message This is any message informing the user what has occurred.
044     * 
045     * @param fn This is the instance of {@code class FileNode} that was involved in the mistake.
046     * <B><I>This parameter should not be left null.</I></B>  If it were accidentally left null,
047     * this could force exception-handling code to to throw exceptions while checking exceptions!
048     * 
049     * @param cause This parameter may be used when generating "multiple-exceptions" that are 
050     * modified as they are thrown.
051     * 
052     * @see #fn
053     */
054    public FileExpectedException(String message, Throwable cause, FileNode fn)
055    { super(message, cause); this.fn = fn; }
056
057
058    /**
059     * Checks whether or not the {@code FileNode} parameter passed is actually one representing a
060     * file, not a directory.
061     * 
062     * @param fn This may be any instance of {@code FileNode} however if it is not one that is
063     * meaning to represent an operating-system file, then this method will automatically throw an
064     * exception.
065     * 
066     * @throws FileExpectedException If parameter {@code 'fn'} is a file, not a directory.
067     */
068    public static void check(FileNode fn)
069    {
070        if (fn.isDirectory) throw new FileExpectedException(
071            "The invocation of the previous method on a FileNode that is, itself, a directory " +
072            "and not a file instead cannot proceed.",
073            fn
074        );
075    }
076}