package Torello.JavaDoc;

import Torello.HTML.*;
import Torello.HTML.NodeSearch.*;
import Torello.Java.FileRW;

import java.util.*;

/**
 * Exception that may be thrown when building an <B>{@link Upgrade}</B> class instance.
 * 
 * <BR /><BR />If there are any exceptions when building or running the {@link Upgrade} class,
 * this exception will throw.  This is sometimes used as a wrapper-exception.
 */
public class UpgradeException extends IllegalArgumentException
{
    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUIDEX>  */
    public static final long serialVersionUID = 1;

    /** Constructs an <CODE>UpgradeException</CODE> with no detail message. */
    public UpgradeException()
    { super(); }

    /**
     * Constructs an <CODE>UpgradeException</CODE> with the specified detail message.
     * @param message the detail message.
     */
    public UpgradeException(String message)
    { super(message); }

    /**
     * Constructs a new exception with the specified detail message and cause.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>NOTE:</B>
     * 
     * <BR /><BR />The detail message associated with cause is not automatically incorporated into
     * this exception's detail message.
     * 
     * @param message The detail message (which is saved for later retrieval by the
     * {@code Throwable.getMessage()} method).
     * 
     * @param cause the cause (which is saved for later retrieval by the
     * {@code Throwable.getCause()} method). (A null value is permitted, and indicates that the
     * cause is nonexistent or unknown.)
     */
    public UpgradeException(String message, Throwable cause)
    { super(message, cause); }

    /**
     * Constructs a new exception with the specified cause and a detail message of
     * {@code (cause==null ? null : cause.toString())} (which typically contains the class and
     * detail message of cause).
     * 
     * <BR /><BR />This constructor is useful for exceptions that are little more than wrappers for
     * other throwables.
     * 
     * @param cause The cause (which is saved for later retrieval by the
     * {@code Throwable.getCause()} method). (A null value is permitted, and indicates that the
     * cause is nonexistent or unknown.)
     */
    public UpgradeException(Throwable cause)
    { super(cause); }

    /**
     * Simple error checking to ensure that a file exists, and that it is accessible.
     * 
     * @param fileOrDirectoryName This is the file (or directory) to be checked for existence and
     * security
     * privileges.
     * 
     * @param fileOrDirectoryTypeMessage This message will be used in error or exception messages
     * if the check fails.
     * 
     * @throws UpgradeException If there are any problems loading the file, or reading from it,
     * then this exception will throw.
     * 
     * @throws JavaDocError This will throw if Java throws a serious error.  This is unlikely, but
     * given that file-system problems should be dealt with immediately, if they occur, catching
     * Java Error's is taken seriously here.
     */
    public static void checkFileExistsAndCanAccess
        (String fileOrDirectoryName, String fileOrDirectoryTypeMessage)
    {
        try
        {
            if (! ((new java.io.File(fileOrDirectoryName)).exists()))

                throw new UpgradeException(
                    fileOrDirectoryTypeMessage + " does not exist, or is not found:\n" +
                    "[" + fileOrDirectoryName + "]"
                );
        } 

        catch (UpgradeException ue) { throw ue; }

        catch (Exception e)
        {
            throw new UpgradeException(
                "There was an Error attempting to access" + fileOrDirectoryTypeMessage + '\n' +
                "[" + fileOrDirectoryName + "]\n"+
                "due to a(n) [" + e.getClass().getSimpleName() + "] throw.\n" +
                "Please see Throwable.getCause() for Details.", e
            );
        }
    }

    /**
     * Simple error checking to ensure that write access is available to a file-name.
     * 
     * @param fileName This is the file to be checked for write-access privileges.
     * 
     * @param fileTypeMessage This message will be used in error or exception messages if the
     * check fails.
     * 
     * @param initStr This is the initialization string to write to the file.  This parameter may
     * be null, and if it is an empty string will be written.
     * 
     * @throws UpgradeException If there are any problems writing to the file, then
     * this exception will throw.
     */
    public static void checkFileIsWriteable
        (String fileName, String fileTypeMessage, String initStr)
    {
        try
            { FileRW.writeFile((initStr != null) ? initStr : "", fileName); }

        catch (Exception e)
        {
            throw new UpgradeException(
                "Unable to write " + fileTypeMessage + ":\n" + fileName + '\n' +
                "due to a(n) [" + e.getClass().getSimpleName() + "] throw.\n" +
                "Please see Throwable.getCause() for Details.", e
            );
        } 
    }
}