1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
package Torello.HTML;

/**
 * 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.
 * 
 * <BR /><BR /><EMBED CLASS="external-html" DATA-FILE-ID="N">
 * <EMBED CLASS="external-html" DATA-FILE-ID="HTMLNODESUB">
 */
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><SPAN STYLE="color: red;">FINAL METHOD:</B></SPAN> 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><SPAN STYLE="color: red;">FINAL METHOD:</B></SPAN> 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)
    {
        return      (this == o)
                || (    (o != null)
                    &&  (this.getClass().equals(o.getClass()))
                    &&  (((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><SPAN STYLE="color: red;">FINAL METHOD:</B></SPAN> 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><SPAN STYLE="color: red;">FINAL METHOD:</B></SPAN> 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><SPAN STYLE="color: red;">FINAL METHOD:</B></SPAN> 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><SPAN STYLE="color: red;">FINAL METHOD:</B></SPAN> 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}.
     * 
     * @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 TagNode asTagNode() { return TagNode.class.cast(this); }

    /**
     * Compile-Time "Syntactic Sugar" for casting an {@code HTMLNode} to a {@code TextNode}.
     * 
     * @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 TextNode asTextNode() { return TextNode.class.cast(this); }

    /**
     * Compile-Time "Syntactic Sugar" for casting an {@code HTMLNode} to a {@code CommentNode}.
     * 
     * @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 CommentNode asCommentNode() { return CommentNode.class.cast(this); }

}