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