package Torello.HTML;

import Torello.JavaDoc.JDHeaderBackgroundImg;

/**
 * This class is mostly a wrapper for class <CODE>java&#46;lang&#46;String</CODE>, and serves as
 * the abstract parent of the three types of HTML elements offered by the Java HTML Library.
 * 
 * <EMBED CLASS="external-html" DATA-FILE-ID=HTML_NODE>
 * 
 * @see TagNode
 * @see TextNode
 * @see CommentNode
 */
@JDHeaderBackgroundImg(EmbedTagFileID={"HTML_NODE_HEADER", "HTML_NODE_SUB_IMG"})
public abstract class HTMLNode implements CharSequence, java.io.Serializable, Cloneable
{
    /** <EMBED CLASS="external-html" DATA-FILE-ID="SVUID"> */
    public static final long serialVersionUID = 1;

    /**
     * This is an immutable field.  It stores the complete contents of an HTML node.  It can be 
     * either the <B>"textual contents"</B>
     * of an HTML {@code TagNode}, or the text (directly) of the text-inside of an HTML page!
     * 
     * <BR /><BR />
     * <B>FOR INSTANCE:</B>
     * 
     * <BR /><BR /><UL CLASS="JDUL">
     * <LI>A subclass of HTMLNode - <CODE>TagNode</CODE> - could contain the String
     * 		<SPAN STYLE="color: red;">&lt;SPAN STYLE="CSS INFO"&gt;"</SPAN>
     * 		<I>inside this <CODE><B>str field</CODE></B> here.</I>
     * </LI>
     * <LI> The other sub-class of HTML - <CODE>TextNode</CODE> - could contain the {@code String}
     * 		<SPAN STYLE="color: red;">"This is a news-page from www.Gov.CN Chinese Government
     *      Portal."</SPAN> <I>inside this <CODE><B>str field</CODE></B> here.</I>
     * </LI>
     * </UL>
     * 
     * <BR /><B>NOTE:</B> Because sub-classes of {@code HTMLNode} are all immutable, generally,
     * if you wish to change the contents of an HTML page, a programmer is required to create new
     * nodes, rather than changing these fields.
     */
    public final String str;

    /**
     * Constructor that builds a new {@code HTMLNode}
     * 
     * @param s A valid string of an HTML element.
     */
    protected HTMLNode(String s) { this.str = s; }

    /**
     * Java's hash-code requirement.
     * 
     * <BR /><BR /><B CLASS=JDRedLabel>Final Method:</B>
     * 
     * <BR />This method is final, and cannot be modified by sub-classes.
     * 
     * @return A hash-code that may be used when storing this node in a java sorted-collection.
     */
    public final int hashCode() { return this.str.hashCode(); }

    /**
     * Java's {@code public boolean equals(Object o)} requirements.
     * 
     * <BR /><BR /><B CLASS=JDRedLabel>Final Method:</B>
     * 
     * <BR />This method is final, and cannot be modified by sub-classes.
     * 
     * @param o This may be any Java Object, but only ones of {@code 'this'} type whose
     * internal-values are identical will cause this method to return <B>TRUE</B>.
     * 
     * @return <B>TRUE</B> If {@code 'this'} equals another object {@code HTMLNode.}
     */
    public final boolean equals(Object o)
    {
        if (o == null) return false;
        if (o == this) return true;

        if (! this.getClass().equals(o.getClass())) return false;

        return ((HTMLNode) o).str.equals(this.str);
    }

    /**
     * Sub-classes of {@code HTMLNode} must be {@code Cloneable.}
     * 
     * @return Must return an identical copy of {@code 'this'} node.  The object reference cannot
     * be {@code 'this'} reference.
     */
    public abstract HTMLNode clone();


    // **********************************************************************************************
    // CharSequence Methods
    // **********************************************************************************************

    /**
     * Java's {@code toString()} requirement.
     * 
     * <BR /><BR /><B CLASS=JDRedLabel>Final Method:</B>
     * 
     * <BR />This method is final, and cannot be modified by sub-classes.
     * 
     * @return A {@code String}-representation of this {@code HTMLNode.}
     */
    public final String toString() { return this.str; }

    /**
     * Returns the char value at the specified index of the field: {@code public final String str}.
     * An index ranges from {@code '0'} (zero) to {@code HTMLNode.str.length() - 1.} The first 
     * {@code char} value of the sequence is at index zero, the next at index one, and so on, as 
     * for array indexing.
     * 
     * <BR /><BR /><B>NOTE:</B> If the {@code char} value specified by the index is a surrogate, 
     * the surrogate value is returned.
     * 
     * <BR /><BR /><B CLASS=JDRedLabel>Final Method:</B>
     * 
     * <BR />This method is final, and cannot be modified by sub-classes.
     * 
     * @param index The index of the {@code char} value to be returned
     * 
     * @return The specified {@code char} value
     */
    public final char charAt(int index) { return str.charAt(index); }

    /**
     * Returns the length of the field {@code public final String str}. 
     * The length is the number of 16-bit chars in the sequence.
     * 
     * <BR /><BR /><B CLASS=JDRedLabel>Final Method:</B>
     * 
     * <BR />This method is final, and cannot be modified by sub-classes.
     * 
     * @return the number of {@code chars} in {@code this.str}
     */
    public final int length() { return str.length(); }

    /**
     * Returns a {@code CharSequence} that is a subsequence of the {@code public final String str}
     * field of {@code 'this' HTMLNode}.
     * The subsequence starts with the {@code char} value at the specified index and ends with the 
     * {@code char} value at index {@code end - 1.} The length (in chars) of the returned sequence
     * is {@code end - start},  so if {@code start == end} then an empty sequence is returned.
     * 
     * <BR /><BR /><B CLASS=JDRedLabel>Final Method:</B>
     * 
     * <BR />This method is final, and cannot be modified by sub-classes.
     * 
     * @param start The start index, inclusive
     * @param end The end index, exclusive
     * 
     * @return The specified subsequence
     */
    public final CharSequence subSequence(int start, int end)
    { return str.substring(start, end); }


    // ********************************************************************************************
    // ********************************************************************************************
    // 'is' Optimization Methods
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * This method will return <B>TRUE</B> for any instance of {@code 'CommentNode'}.
     *
     * <BR /><BR />The purpose of this method is to efficiently return <B>TRUE</B> whenever
     * an instance of {@code 'HTMLNode'} should be checked to see if it is actually an inherited
     * instance of {@code CommentNode}.  This is (marginally) more efficient than using the Java
     * {@code 'instanceof'} operator.
     *
     * @return This (top-level inheritance-tree) method always returns <B>FALSE</B>.  The 
     * {@code '.java'} file for {@code class CommentNode} overrides this method, and returns
     * <B>TRUE</B>.
     * 
     * @see CommentNode#isCommentNode()
     */
    public boolean isCommentNode()
    {
        // This method will *only* be over-ridden by subclass CommentNode, where it shall return
        // TRUE.  Neither class TextNode, nor class TagNode will over-ride this method.

        return false;
    }

    /**
     * This method will return <B>TRUE</B> for any instance of {@code 'TextNode'}.
     *
     * <BR /><BR />The purpose of this method is to efficiently return <B>TRUE</B> whenever
     * an instance of {@code 'HTMLNode'} should be checked to see if it is actually an inherited
     * instance of {@code TextNode}.  This is (marginally) more efficient than using the Java
     * {@code 'instanceof'} operator.
     *
     * @return This (top-level inheritance-tree) method always returns <B>FALSE</B>.  The 
     * {@code '.java'} file for {@code class TextNode} overrides this method, and returns
     * <B>TRUE</B>.
     * 
     * @see TextNode#isTextNode()
     */
    public boolean isTextNode()
    {
        // This method will *only* be over-ridden by subclass CommentNode, where it shall return
        // TRUE.  Neither class TextNode, nor class TagNode will over-ride this method.

        return false;
    }

    /**
     * This method will return <B>TRUE</B> for any instance of {@code 'TagNode'}.
     *
     * <BR /><BR />The purpose of this method is to efficiently return <B>TRUE</B> whenever
     * an instance of {@code 'HTMLNode'} should be checked to see if it is actually an inherited
     * instance of {@code TagNode}.  This is (marginally) more efficient than using the Java
     * {@code 'instanceof'} operator.
     *
     * @return This (top-level inheritance-tree) method always returns <B>FALSE</B>.  The 
     * {@code '.java'} file for {@code class TagNode} overrides this method, and returns
     * <B>TRUE</B>.
     * 
     * @see TagNode#isTagNode()
     */
    public boolean isTagNode()
    {
        // This method will *only* be over-ridden by subclass TagNode, where it shall return
        // TRUE.  Neither class TextNode, nor class CommentNode will over-ride this method.

        return false;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // TagNode Optimization Methods
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * <B STYLE='color:red;'>PWA: Open Tag, 'Possibly With Attributes'</B>
     * 
     * This method is offered as an <I><B>optimization tool for quickly finding</B></I> HTML Tag's
     * that have attributes inside of a search-loop.  Since this class, class {@code HTMLNode}, is
     * the abstract parent of all three HTML element-types, and since <B>{@link TagNode} is the
     * only one of those three that overrides this method</B>, the "optimization" acheived is that,
     * by default, most concrete-instances of this abstract-parent class {@code HTMLNode} <I>will
     * immediately return null</I> when queried by a search-loop - which makes the process of
     * finding {@code TagNode's} with a particular attribute much more efficient.
     *
     * <BR /><BR />The purpose of this method is to quickly return a node that has been cast to
     * an instance of {@code TagNode}, if it is, indeed, a {@code TagNode} <B><I>and if</I></B> it
     * has an internal-{@code String} long-enough to possibly contain attributes (inner-tags).
     * 
     * @return This method shall always return null, unless this method has been overridden by a
     * sub-class.  Only {@code TagNode} overrides this method, and if the particular instance of
     * {@code TagNode} being tested contains an internal {@code 'str'} field that's long-enough to
     * have attributes (and it's {@code 'isClosing'} field is {@code FALSE}), <B>then and only
     * then</B> shall this return a non-null value.
     * 
     * <BR /><BR />When the overridden {@code TagNode} sub-class returns a non-null result, that
     * value will <B>always be equal to {@code 'this'}</B>
     * 
     * <BR /><BR /><B STYLE='color: red'>AGAIN:</B> For overriding sub-class {@code TagNode},
     * when this method returns a non-null value (always {@code 'this'} instance), it will be
     * because the internal-{@code String} is actually long enough to be worthy of being tested for
     * attribute / inner-tag <B STYLE='color:red'>key-value</B> pairs.
     * 
     * @see TagNode#openTagPWA()
     */
    public TagNode openTagPWA()
    {
        // This method will *only* be over-ridden by subclass TagNode.
        // For instances of inheriting class TextNode and CommentNode, this always returns null.
        // In 'TagNode' this method returns true based on the 'isClosing' field from that class,
        // and the length of the 'str' field from this class.

        return null;
    }

    /**
     * This method is offered as an <I><B>optimization tool for quickly finding</B></I> HTML Tag's
     * that are Opening-Tags.  Since this class, class {@code HTMLNode}, is the abstract parent of
     * all three HTML element-types, and since <B>{@link TagNode} is the only one of those three
     * that overrides this method</B>, the "optimization" acheived is that, by default, most
     * concrete-instances of this abstract-parent class {@code HTMLNode} <I>will immediately return
     * null</I> when queried by a search-loop - which makes the process of finding opening
     * {@code TagNode's} more efficient.
     *
     * @return This method shall always return null, unless this method has been overridden by a
     * sub-class.  Only {@code TagNode} overrides this method, and if the particular instance of
     * {@code TagNode} being tested has a {@code FALSE} value assigned to its {@code 'isClosing'}
     * field <B>then and only then</B> shall this return a non-null value.
     * 
     * <BR /><BR />When the overridden {@code TagNode} sub-class returns a non-null result, that
     * value will <B>always be equal to {@code 'this'}</B>
     * 
     * @see TagNode#openTag()
     */
    public TagNode openTag()
    {
        // This method will *only* be over-ridden by subclass TagNode.
        // For instances of inheriting class TextNode and CommentNode, this always returns null.
        // In 'TagNode' this method returns true based on that class 'isClosing' field.

        return null;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // 'if' loop-optimizers
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * <B STYLE='color: red;'>Loop Optimization Method</B>
     * 
     * <BR /><BR />When this method is invoked on an instance of sub-class {@link TagNode},
     * this method produces {@code 'this'} instance.
     * 
     * @return This method is overriden by sub-class {@code TagNode}, and in that class, this
     * method simply returns {@code 'this'}.  The other sub-classes of this ({@code abstract})
     * class inherit this version of this method, and therefore return null.
     * 
     * @see TagNode#ifTagNode()
     */
    public TagNode ifTagNode()
    {
        // This method will *only* be over-ridden by subclass TagNode, where it shall return
        // 'this'.  Neither class TextNode, nor class CommentNode will over-ride this method.

        return null;
    }

    /**
     * <B STYLE='color: red;'>Loop Optimization Method</B>
     * 
     * <BR /><BR />When this method is invoked on an instance of sub-class {@link TextNode},
     * this method produces {@code 'this'} instance.
     * 
     * @return This method is overriden by sub-class {@code TextNode}, and in that class, this
     * method simply returns {@code 'this'}.  The other sub-classes of this ({@code abstract})
     * class inherit this version of this method, and therefore return null.
     * 
     * @see TextNode#ifTextNode()
     */
    public TextNode ifTextNode()
    {
        // This method will *only* be over-ridden by subclass TextNode, where it shall return
        // 'this'.  Neither class TagNode, nor class CommentNode will over-ride this method.

        return null;
    }

    /**
     * <B STYLE='color: red;'>Loop Optimization Method</B>
     * 
     * <BR /><BR />When this method is invoked on an instance of sub-class {@link CommentNode},
     * this method produces {@code 'this'} instance.
     * 
     * @return This method is overriden by sub-class {@code CommentNode}, and in that class, this
     * method simply returns {@code 'this'}.  The other sub-classes of this ({@code abstract})
     * class inherit this version of this method, and therefore return null.
     * 
     * @see CommentNode#ifCommentNode()
     */
    public CommentNode ifCommentNode()
    {
        // This method will *only* be over-ridden by subclass CommentNode, where it shall return
        // 'this'.  Neither class TagNode, nor class TextNode will over-ride this method.

        return null;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // 'is' loop-optimizers
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Compile-Time "Syntactic Sugar" for casting an {@code HTMLNode} to a {@code TagNode}.
     * 
     * <BR /><BR /><B CLASS=JDRedLabel>Final Method:</B>
     * 
     * <BR />This method is final, and cannot be modified by sub-classes.
     * 
     * @return Simply returns {@code 'this'} instance.  (Note that the method
     * {@code Class.cast(Object)} <I>doesn't actually do *anything*</I>, other than provide the
     * compile-time logic some 'proof' in its type-analysis)
     * 
     * @throws ClassCastException <B STYLE='color: red;'>IMPORTANT:</B> If the instance is a
     * {@link TextNode} or {@code CommentNode}, rather than a {@link TagNode}, then (naturally) the
     * JVM will immediately throw a casting exception.
     */
    public final TagNode asTagNode() { return TagNode.class.cast(this); }

    /**
     * Compile-Time "Syntactic Sugar" for casting an {@code HTMLNode} to a {@code TextNode}.
     * 
     * <BR /><BR /><B CLASS=JDRedLabel>Final Method:</B>
     * 
     * <BR />This method is final, and cannot be modified by sub-classes.
     * 
     * @return Simply returns {@code 'this'} instance.  (Note that the method
     * {@code Class.cast(Object)} <I>doesn't actually do *anything*</I>, other than provide the
     * compile-time logic some 'proof' in its type-analysis)
     * 
     * @throws ClassCastException <B STYLE='color: red;'>IMPORTANT:</B> If the instance is a
     * {@link TagNode} or {@code CommentNode}, rather than a {@link TextNode}, then (naturally) the
     * JVM will immediately throw a casting exception.
     */
    public final TextNode asTextNode() { return TextNode.class.cast(this); }

    /**
     * Compile-Time "Syntactic Sugar" for casting an {@code HTMLNode} to a {@code CommentNode}.
     * 
     * <BR /><BR /><B CLASS=JDRedLabel>Final Method:</B>
     * 
     * <BR />This method is final, and cannot be modified by sub-classes.
     * 
     * @return Simply returns {@code 'this'} instance.  (Note that the method
     * {@code Class.cast(Object)} <I>doesn't actually do *anything*</I>, other than provide the
     * compile-time logic some 'proof' in its type-analysis)
     * 
     * @throws ClassCastException <B STYLE='color: red;'>IMPORTANT:</B> If the instance is a
     * {@link TagNode} or {@code TextNode}, rather than a {@link CommentNode}, then (naturally) the
     * JVM will immediately throw a casting exception.
     */
    public final CommentNode asCommentNode() { return CommentNode.class.cast(this); }
}