001package Torello.CSS;
002
003import java.util.function.Predicate;
004import java.util.regex.Pattern;
005import java.util.Objects;
006
007/**
008 * An exception for using with a Validity-Check of a CSS Class-Name.
009 * 
010 * <BR /><BR /><B CLASS=JDDescLabel2>Regular-Expression:</B>
011 * 
012 * <BR />The following is considered the validator for this exception's
013 * {@link #check(String) Validity-Checker} method.
014 * 
015 * <DIV CLASS=REGEX>{@code
016 * ^-?[_a-zA-Z]+[_a-zA-Z0-9-]*$
017 * }</DIV>
018 * 
019 * <EMBED CLASS='external-html' DATA-FILE-ID=CLASS_NAME_CHaRT>
020 * @see #VALID_CSS_CLASS_NAME
021 * @see #VALID_CSS_CLASS_NAME_PRED
022 */
023public class ClassNameCSSException extends RuntimeException
024{
025    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUIDEX> */
026    public static final long serialVersionUID = 1;
027
028    /**
029     * This is a validator regular-expression.  It is intended to check whether or not a
030     * CSS Class-Name is valid or not.
031     * 
032     * @see VALID_CSS_CLASS_NAME_PRED
033     */
034    public static final Pattern VALID_CSS_CLASS_NAME =
035        // Pattern.compile("^([_a-zA-Z]|-[_a-zA-Z])[_\\-a-zA-Z0-9]*$");
036        Pattern.compile("^-?[_a-zA-Z]+[_a-zA-Z0-9-]*$");
037
038    /**
039     * This is the validator {@link #VALID_CSS_CLASS_NAME Reg-Ex} after having been converted into
040     * a {@code java.util.function.Predicate<String>}.
041     * 
042     * @see VALID_CSS_CLASS_NAME
043     */
044    public static final Predicate<String> VALID_CSS_CLASS_NAME_PRED =
045        VALID_CSS_CLASS_NAME.asPredicate();
046
047    /** Constructs a {@code ClassNameCSSException} with no detail message. */
048    public ClassNameCSSException()
049    { super(); }
050
051    /**
052     * Constructs a {@code ClassNameCSSException} with the specified detail message.
053     * @param message the detail message.
054     */
055    public ClassNameCSSException(String message)
056    { super(message); }
057
058    /**
059     * Constructs a new exception with the specified detail message and cause.
060     * 
061     * <BR /><BR /><B CLASS=JDDescLabel>NOTE:</B>
062     * 
063     * <BR /><BR />The detail message associated with cause is not automatically incorporated into
064     * this exception's detail message.
065     * 
066     * @param message The detail message (which is saved for later retrieval by the
067     * {@code Throwable.getMessage()} method).
068     * 
069     * @param cause the cause (which is saved for later retrieval by the
070     * {@code Throwable.getCause()} method).  (A null value is permitted, and indicates that the
071     * cause is non-existent or unknown.)
072     */
073    public ClassNameCSSException(String message, Throwable cause)
074    { super(message, cause); }
075
076    /**
077     * Constructs a new exception with the specified cause and a detail message of
078     * {@code (cause==null ? null : cause.toString())} (which typically contains the class and
079     * detail message of cause).  This constructor is useful for exceptions that are little more
080     * than wrappers for other throwables.
081     * 
082     * @param cause The cause (which is saved for later retrieval by the
083     * {@code Throwable.getCause()} method).  (A null value is permitted, and indicates that the
084     * cause is non-existent or unknown.)
085     */
086    public ClassNameCSSException(Throwable cause)
087    { super(cause); }
088
089    /**
090     * Checks if a the provided {@code cssClassName} is a valid name according the CSS
091     * Regular-Expression that's incorporated into this class.
092     * 
093     * @param cssClassName Any Java-{@code String}, but only a valid CSS Class-Name can prevent
094     * this method from throwing this class' exception.
095     * 
096     * @throws ClassNameCSSException if the provided {@code cssClassName} isn't a proper CSS
097     * Class-Name, according to the Regular-Expression Predicate {@link #VALID_CSS_CLASS_NAME_PRED}
098     * 
099     * @throws NullPointerException if {@code cssClassName} is null, then NPE throws.
100     * 
101     * @see #VALID_CSS_CLASS_NAME
102     * @see #VALID_CSS_CLASS_NAME_PRED
103     */
104    public static void check(String cssClassName)
105    {
106        Objects.requireNonNull(cssClassName, "The CSS Class-Name which was passed is null");
107
108        if (! VALID_CSS_CLASS_NAME_PRED.test(cssClassName)) throw new ClassNameCSSException(
109            "The CSS Class-Name that was passed: " + '[' + cssClassName + "], " +
110            "is not a valid CSS Class-Name.\n" +
111            "It did not match the Reg-Ex: " +
112            VALID_CSS_CLASS_NAME.pattern()
113        );
114    }
115}