001package Torello.HTML;
002
003import java.util.Comparator;
004
005/**
006 * Represents document text, and is one of only three HTML Element Classes provided by the Java
007 * HTML Library Tool, and also oneof the three classes that can be generated by the HTML Parser.
008 * 
009 * <EMBED CLASS='external-html' DATA-FILE-ID=TEXT_NODE>
010 * 
011 * <EMBED CLASS='external-html' DATA-FILE-ID=HTML_NODE_SUB_IMG>
012 * 
013 * @see HTMLNode
014 * @see TagNode
015 * @see CommentNode
016 */
017@Torello.JavaDoc.JDHeaderBackgroundImg(EmbedTagFileID="HTML_NODE_SUBCLASS")
018public final class TextNode
019    extends HTMLNode
020    implements CharSequence, java.io.Serializable, Cloneable, Comparable<TextNode>
021{
022    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUID> */
023    public static final long serialVersionUID = 1;
024
025    /**
026     * Constructs a new {@code TextNode} with internal field {@code String str} equal to parameter
027     * {@code 's'}
028     * 
029     * @param s Any valid Java {@code String} may be passed here.
030     */
031    public TextNode(String s) { super(s); }
032
033    /**
034     * This method identifies that {@code 'this'} instance of (abstract parent-class)
035     * {@link HTMLNode} is, indeed, an instance of sub-class {@code TextNode}.
036     *
037     * <BR /><BR /><B CLASS=JDDescLabel>Final Method:</B>
038     * 
039     * <BR />This method is final, and cannot be modified by sub-classes.
040     * 
041     * @return This method shall always return {@code TRUE}  It overrides the parent-class
042     * {@code HTMLNode} method {@link #isTextNode()}, which always returns {@code FALSE}.
043     */
044    @Override
045    public final boolean isTextNode() { return true; }
046
047    /**
048     * This method identifies that {@code 'this'} instance of (abstract parent-class)
049     * {@link HTMLNode} is, indeed, an instance of sub-class {@code TextNode}.
050     * 
051     * <BR /><BR /><B CLASS=JDDescLabel>Final Method:</B>
052     * 
053     * <BR />This method is final, and cannot be modified by sub-classes.
054     * 
055     * @return {@code 'this'} reference.  This method can be used inside loops for improving
056     * the readability of loop-condition expressions.  See example below:
057     * 
058     * <DIV CLASS=EXAMPLE>{@code
059     * TextNode t;
060     * 
061     * for (HTMLNode n : myHTMLVector)
062     *     if ((t = n.ifTextNode()) != null) 
063     *         System.out.println("Text-Node Contains: " + t.str);
064     * }</div>
065     * 
066     * <BR /><BR />This method-version overrides the parent-class-version, which always returns
067     * null.  This method is <I>not overriden by other {@code HTMLNode} sub-classes.</I>
068     */
069    @Override
070    public final TextNode ifTextNode() { return this; }
071
072    /**
073     * Java's {@code interface Cloneable} requirements.  This instantiates a new {@code TextNode}
074     * with identical {@code String str} fields.
075     * 
076     * @return A new {@code TextNode} whose internal fields are identical to this one.
077     */
078    public TextNode clone() { return new TextNode(str); }
079
080    /**
081     * Java's {@code interface Comparable<T>} requirements.  This does a very simple comparison
082     * using the underlying field {@code final String str} that all Text's contain.
083     * 
084     * @param tn Any other {@code TextNode} to be compared to {@code 'this' TextNode}
085     * 
086     * @return An integer that fulfils Java's {@code interface Comparable<T> public boolean
087     * compareTo(T t)} method requirements.
088     */
089    public int compareTo(TextNode tn)
090    { return this.str.compareTo(tn.str); }
091
092    /**
093     * This is an "alternative Comparitor" that can be used for sorting instances of this class.
094     * It should work with the {@code Collections.sort(List, Comparator)} method in the standard
095     * JDK package {@code java.util.*;}
096     * 
097     * <BR /><BR /><B>NOTE:</B> This version utilizes the standard JDK
098     * {@code String.compareToIgnoreCase(String)} method.
099     * 
100     * @see HTMLNode#str
101     */
102    public static final Comparator<TextNode> comp2 =
103        (TextNode txn1, TextNode txn2) -> txn1.str.compareToIgnoreCase(txn2.str);
104}