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     * <EMBED CLASS='external-html' DATA-FILE-ID=EXPF_PARAM>
032     * 
033     * @throws ExceptionCheckError If parameter {@code 'fn'} is passed null
034     * 
035     * @see #fn
036     */
037    public FileExpectedException(String message, FileNode fn)
038    {
039        super(message);
040        this.fn = fn;
041
042        if (this.fn == null) throw new ExceptionCheckError
043            ("FileExpectedException constructor parameter 'fn' was passed null");
044    }
045
046    /**
047     * Constructs a new exception with the specified detail message, cause-chain 
048     * {@code Throwable}, and one {@code public, final} parameter: {@code fn}.
049     * 
050     * <BR /><BR /><DIV CLASS=JDHint>
051     * <B STYLE='color:red;'>Note:</B> The detail message associated with cause is not
052     * automatically incorporated into this exception's detail message.
053     * </DIV>
054     * 
055     * @param message This is any message informing the user what has occurred.
056     * 
057     * @param cause This parameter may be used when generating "multiple-exceptions" that are 
058     * modified as they are thrown.
059     * 
060     * @param fn This is the instance of {@code class FileNode} that was involved in the mistake.
061     * <EMBED CLASS='external-html' DATA-FILE-ID=EXPF_PARAM>
062     * 
063     * @throws ExceptionCheckError If parameter {@code 'fn'} is passed null
064     * 
065     * @see #fn
066     */
067    public FileExpectedException(String message, Throwable cause, FileNode fn)
068    {
069        super(message, cause);
070        this.fn = fn;
071
072        if (this.fn == null) throw new ExceptionCheckError
073            ("FileExpectedException constructor parameter 'fn' was passed null");
074    }
075
076    /**
077     * Checks whether or not the {@code FileNode} parameter passed is actually one representing a
078     * file, not a directory.
079     * 
080     * @param fn This may be any instance of {@code FileNode} however if it is not one that is
081     * meaning to represent an operating-system file, then this method will automatically throw an
082     * exception.
083     * 
084     * @throws FileExpectedException If parameter {@code 'fn'} is a file, not a directory.
085     */
086    public static void check(FileNode fn)
087    {
088        if (fn.isDirectory) throw new FileExpectedException(
089            "The invocation of the previous method on a FileNode that is, itself, a directory " +
090            "and not a file instead cannot proceed.",
091            fn
092        );
093    }
094}