001package Torello.JavaDoc;
002
003import Torello.HTML.*;
004import Torello.HTML.NodeSearch.*;
005import Torello.Java.FileRW;
006
007import java.util.*;
008
009/**
010 * Exception that may be thrown when building an <B>{@link Upgrade}</B> class instance.
011 * 
012 * <BR /><BR />If there are any exceptions when building or running the {@link Upgrade} class,
013 * this exception will throw.  This is sometimes used as a wrapper-exception.
014 */
015public class UpgradeException extends IllegalArgumentException
016{
017    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUIDEX>  */
018    public static final long serialVersionUID = 1;
019
020    /** Constructs an <CODE>UpgradeException</CODE> with no detail message. */
021    public UpgradeException()
022    { super(); }
023
024    /**
025     * Constructs an <CODE>UpgradeException</CODE> with the specified detail message.
026     * @param message the detail message.
027     */
028    public UpgradeException(String message)
029    { super(message); }
030
031    /**
032     * Constructs a new exception with the specified detail message and cause.
033     * 
034     * <BR /><BR /><B CLASS=JDDescLabel>NOTE:</B>
035     * 
036     * <BR /><BR />The detail message associated with cause is not automatically incorporated into
037     * this exception's detail message.
038     * 
039     * @param message The detail message (which is saved for later retrieval by the
040     * {@code Throwable.getMessage()} method).
041     * 
042     * @param cause the cause (which is saved for later retrieval by the
043     * {@code Throwable.getCause()} method). (A null value is permitted, and indicates that the
044     * cause is nonexistent or unknown.)
045     */
046    public UpgradeException(String message, Throwable cause)
047    { super(message, cause); }
048
049    /**
050     * Constructs a new exception with the specified cause and a detail message of
051     * {@code (cause==null ? null : cause.toString())} (which typically contains the class and
052     * detail message of cause).
053     * 
054     * <BR /><BR />This constructor is useful for exceptions that are little more than wrappers for
055     * other throwables.
056     * 
057     * @param cause The cause (which is saved for later retrieval by the
058     * {@code Throwable.getCause()} method). (A null value is permitted, and indicates that the
059     * cause is nonexistent or unknown.)
060     */
061    public UpgradeException(Throwable cause)
062    { super(cause); }
063
064    /**
065     * Simple error checking to ensure that a file exists, and that it is accessible.
066     * 
067     * @param fileOrDirectoryName This is the file (or directory) to be checked for existence and
068     * security
069     * privileges.
070     * 
071     * @param fileOrDirectoryTypeMessage This message will be used in error or exception messages
072     * if the check fails.
073     * 
074     * @throws UpgradeException If there are any problems loading the file, or reading from it,
075     * then this exception will throw.
076     * 
077     * @throws JavaDocError This will throw if Java throws a serious error.  This is unlikely, but
078     * given that file-system problems should be dealt with immediately, if they occur, catching
079     * Java Error's is taken seriously here.
080     */
081    public static void checkFileExistsAndCanAccess
082        (String fileOrDirectoryName, String fileOrDirectoryTypeMessage)
083    {
084        try
085        {
086            if (! ((new java.io.File(fileOrDirectoryName)).exists()))
087
088                throw new UpgradeException(
089                    fileOrDirectoryTypeMessage + " does not exist, or is not found:\n" +
090                    "[" + fileOrDirectoryName + "]"
091                );
092        } 
093
094        catch (UpgradeException ue) { throw ue; }
095
096        catch (Exception e)
097        {
098            throw new UpgradeException(
099                "There was an Error attempting to access" + fileOrDirectoryTypeMessage + '\n' +
100                "[" + fileOrDirectoryName + "]\n"+
101                "due to a(n) [" + e.getClass().getSimpleName() + "] throw.\n" +
102                "Please see Throwable.getCause() for Details.", e
103            );
104        }
105    }
106
107    /**
108     * Simple error checking to ensure that write access is available to a file-name.
109     * 
110     * @param fileName This is the file to be checked for write-access privileges.
111     * 
112     * @param fileTypeMessage This message will be used in error or exception messages if the
113     * check fails.
114     * 
115     * @param initStr This is the initialization string to write to the file.  This parameter may
116     * be null, and if it is an empty string will be written.
117     * 
118     * @throws UpgradeException If there are any problems writing to the file, then
119     * this exception will throw.
120     */
121    public static void checkFileIsWriteable
122        (String fileName, String fileTypeMessage, String initStr)
123    {
124        try
125            { FileRW.writeFile((initStr != null) ? initStr : "", fileName); }
126
127        catch (Exception e)
128        {
129            throw new UpgradeException(
130                "Unable to write " + fileTypeMessage + ":\n" + fileName + '\n' +
131                "due to a(n) [" + e.getClass().getSimpleName() + "] throw.\n" +
132                "Please see Throwable.getCause() for Details.", e
133            );
134        } 
135    }
136}