001package Torello.HTML;
002
003/**
004 * This class is not used internally, but is intended to be used to check for invalid 
005 * attribute-<B STYLE="color: red;">values</B> inside HTML Tags.  
006 * 
007 * <BR /><BR />One variant of such a check is look for the presence of new-line ({@code '\n'})
008 * characters in those <B STYLE='color:red'>values</B>.  (The HTML 5.0 Specification certainly does
009 * not disallow new-lines, though).  Since attribute <B STYLE="color: red;">values</B> may contain
010 * just about anything.
011 * 
012 * <BR /><BR />Since this package was initially written for foreign-language news translations, 
013 * higher-level {@code UTF-8} characters occur inside HTML element inner-tag
014 * <B STYLE="color: red;">values</B> all the time.  
015 */
016public class InnerTagValueException extends IllegalArgumentException
017{
018    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUIDEX> */
019    public static final long serialVersionUID = 1;
020
021    /** Constructs an {@code InnerTagValueException} with no detail message. */
022    public InnerTagValueException()
023    { super(); }
024
025    /**
026     * Constructs an {@code InnerTagValueException} with the specified detail message.
027     * @param message the detail message.
028     */
029    public InnerTagValueException(String message)
030    { super(message); }
031
032    /**
033     * Constructs a new exception with the specified detail message and cause.
034     * 
035     * <BR /><BR /><B CLASS=JDDescLabel>NOTE:</B>
036     * 
037     * <BR /><BR />The detail message associated with cause is not automatically incorporated into
038     * this exception's detail message.
039     * 
040     * @param message The detail message (which is saved for later retrieval by the
041     * {@code Throwable.getMessage()} method).
042     * 
043     * @param cause the cause (which is saved for later retrieval by the
044     * {@code Throwable.getCause()} method).  (A null value is permitted, and indicates that the
045     * cause is nonexistent or unknown).
046     */
047    public InnerTagValueException(String message, Throwable cause)
048    { super(message, cause); }
049
050    /**
051     * Constructs a new exception with the specified cause and a detail message of
052     * {@code (cause==null ? null : cause.toString())} (which typically contains the class and
053     * detail message of cause).
054     * 
055     * This constructor is useful for exceptions that are little more than wrappers for other
056     * throwables.
057     * 
058     * @param cause The cause (which is saved for later retrieval by the
059     * {@code Throwable.getCause()} method).  (A null value is permitted, and indicates that the
060     * cause is nonexistent or unknown).
061     */
062    public InnerTagValueException(Throwable cause)
063    { super(cause); }
064
065    /**
066     * This merely performs a "new-line {@code ('\n')}" test.  If a new-line character is found, an
067     * exception is thrown.
068     * 
069     * @param value Any Java-{@code String}, but this <B STYLE="color: red;">value</B> is intended
070     * to be used in an HTML-Element Attribute-<B STYLE="color: red;">Value</B> Pair as the
071     * attribute-<B STYLE="color: red;">value</B> (not the
072     * attribute-<B STYLE="color: red;">key</B>).
073     * 
074     * @throws InnerTagValueException If this new-line test fails, this exception is thrown.
075     */
076    public static void check(String value)
077    {
078        if (value.indexOf("\n") != -1) throw new InnerTagValueException(
079            "The following inner-tag attribute-value contains the newline-character:\n" +
080            value.replace("\n", "[\\n]") + "\n"
081        );
082    }
083
084    /**
085     * This performs the identical test as the other method by this same name, but allows for the
086     * attribute-<B STYLE="color: red;">key</B> to be included in the Exception's "Error Message"
087     * (for reporting purposes only)
088     * 
089     * @param value Any Java-{@code String}, but this <B STYLE="color: red;">value</B> is intended
090     * to be used in an HTML-Element Attribute-<B STYLE="color: red;">Value</B> Pair as the
091     * attribute-<B STYLE="color: red;">value</B> (not the
092     * attribute-<B STYLE="color: red;">key</B>).
093     * 
094     * @param key This is the key associated with this value.  It is included for "error-reporting'
095     * (the exception's Message {@code String}) only!
096     * 
097     * @see #check(String)
098     * @throws InnerTagValueException If this new-line test fails, this exception is thrown.
099     */
100    public static void check(String value, String key)
101    {
102        if (value.indexOf("\n") != -1) throw new InnerTagValueException(
103            "The following inner-tag attribute-value contains the newline-character:\n" +
104            "key:\t" + key + "\n" +
105            "value:\t" + value.replace("\n", "[\\n]") + "\n"
106        );
107    }
108}