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=JDDescLabel>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=JDDescLabel>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 {@code TRUE}.
     * 
     * @return {@code TRUE} 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=JDDescLabel>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=JDDescLabel>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=JDDescLabel>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=JDDescLabel>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 {@code TRUE} for any instance of {@code 'CommentNode'}.
     *
     * <BR /><BR />The purpose of this method is to efficiently return {@code TRUE} 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 {@code FALSE}.  The 
     * {@code '.java'} file for {@code class CommentNode} overrides this method, and returns
     * {@code TRUE}.
     * 
     * @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 {@code TRUE} for any instance of {@code 'TextNode'}.
     *
     * <BR /><BR />The purpose of this method is to efficiently return {@code TRUE} 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 {@code FALSE}.  The 
     * {@code '.java'} file for {@code class TextNode} overrides this method, and returns
     * {@code TRUE}.
     * 
     * @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 {@code TRUE} for any instance of {@code 'TagNode'}.
     *
     * <BR /><BR />The purpose of this method is to efficiently return {@code TRUE} 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 {@code FALSE}.  The 
     * {@code '.java'} file for {@code class TagNode} overrides this method, and returns
     * {@code TRUE}.
     * 
     * @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
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * <EMBED CLASS='external-html' DATA-RET=null DATA-FILE-ID=OPEN_TAG_PWA_DESC>
     * 
     * <BR /><BR />This makes the process of finding {@code TagNode's} having 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 this method will return
     * {@code 'this'} instance, if and only if the following conditions hold:
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=OPEN_TAG_PWA_RET>
     * 
     * @see TagNode#openTagPWA()
     * @see isOpenTagPWA()
     */
    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;
    }

    /**
     * <EMBED CLASS='external-html' DATA-RET=null DATA-FILE-ID=OPEN_TAG_DESC>
     *
     * @return This method shall always return null, unless this method has been overridden by a
     * sub-class.  Only {@code TagNode} overrides this method, and this method will return
     * {@code 'this'} instance, if and only if the following conditions hold:
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=OPEN_TAG_PWA_RET>
     * 
     * <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;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // TagNode Optimization Methods, Part II - Same as above, but returns boolean
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * <EMBED CLASS='external-html' DATA-RET=false DATA-FILE-ID=OPEN_TAG_PWA_DESC>
     * <EMBED CLASS='external-html' DATA-RET=false DATA-FILE-ID=IS_OPEN_TAG_PWA_EX>
     * 
     * @return This method shall always return {@code FALSE}, unless it has been overriden by a
     * subclass.  Subclass {@link TagNode} overrides this, and will return {@code TRUE} if and only
     * if the following conditions hold:
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=OPEN_TAG_PWA_RET>
     * 
     * @see TagNode#isOpenTagPWA()
     * @see #openTagPWA()
     */
    public boolean isOpenTagPWA()
    {
        // This method will *only* be over-ridden by subclass TagNode.
        // For instances of inheriting class TextNode and CommentNode, this always returns false.
        // 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 false;
    }

    /**
     * <EMBED CLASS='external-html' DATA-RET=false DATA-FILE-ID=OPEN_TAG_DESC>
     *
     * <BR /><BR />This method will function almost identically to {@link #openTag()}, with the
     * subtle difference being that it returns a {@code TRUE / FALSE} boolean, instead of an
     * instance-reference.
     * 
     * @return This method shall always return {@code FALSE}, unless it has been overriden by a
     * subclass.  Subclass {@link TagNode} overrides this, and will return {@code TRUE} if and only
     * if the following conditions hold:
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=OPEN_TAG_RET>
     * 
     * @see TagNode#isOpenTag()
     * @see #openTag()
     */
    public boolean isOpenTag()
    {
        // This method will *only* be over-ridden by subclass TagNode.
        // For instances of inheriting class TextNode and CommentNode, this always returns FALSE.
        // In 'TagNode' this method returns TRUE based on that class 'isClosing' field.

        return false;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // '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=JDDescLabel>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=JDDescLabel>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=JDDescLabel>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); }
}