Package Torello.HTML

Class InnerTags

java.lang.Object

Torello.HTML.InnerTags

public class InnerTags
extends java.lang.Object

"Inner-Tags", a synonym for "Attributes" allows a user to do some aggregrate searches for the types of attributes in Vectorized-HTML.

This class was derived from information that is printed on the web-site "W3Schools.com". At first glance it appears to be a rather detailed amount of information, although that is contained within the data-structures are lists of HTML Element Attributes (Inner-Tags).

These inner-tags are kept in an internal class for the primary reason that on occasion a user or programmer may wish to check if a web-page has any HTML Elements that have "non-standard" attributes. Many of the more modern web-sites on the internet contain HTML Elements that are proprietary and invented. This is not "against the rules" - and browsers will continue to parse and render a web-page that has non-standard HTML elements.

In fact, using many implementations of Java-Script libraries will allow script to update elements after being rendered by the browser.

Field Summary

Fields

Modifier and Type	Field
protected static TreeMap<String, String>	attributeDescriptions
protected static TreeSet<String>	attributes
protected static TreeMap<String, String>	eventAttributeDescriptions
protected static TreeMap<String, String>	eventAttributes

Method Summary

TagNode Diagnostics: Check TagNode(s) for Event-Attributes
Modifier and Type	Method
static String[]	eventAttributes(Properties tnAllAV)
static Ret2<TagNodeIndex[], String[][]>	eventAttributes(Vector<? super TagNode> html)
static Ret2<TagNodeIndex[], String[][]>	eventAttributes(Vector<? super TagNode> html, int sPos, int ePos)
TagNode Diagnostics: Check TagNode(s) for Unlisted-Attributes
Modifier and Type	Method
static String[]	nonStandardAttributes(Properties tnAllAV)
static Ret2<TagNodeIndex[], String[][]>	nonStandardAttributes(Vector<? super TagNode> html)
static Ret2<TagNodeIndex[], String[][]>	nonStandardAttributes(Vector<? super TagNode> html, int sPos, int ePos)
List-Accessors: Standard HTML-Attribute TreeSet Data-Structure
Modifier and Type	Method
static void	addAttributes(String... attributes)
static String	aDescription(String innerTag)
static Iterator<Map.Entry<String, String>>	attributeAndDescriptionsIterator()
static Iterator<String>	attributeIterator()
static boolean	hasAttribute(String innerTag)
int	removeAttributes(String... attributes)
List-Accessors: Event-Attributes TreeMap Data-Structure
Modifier and Type	Method
void	addEventAttributes(String... eventAttributes)
static String	eaDescription(String innerTag)
static Iterator<Map.Entry<String, String>>	eventAttributeAndCategoriesIterator()
static Iterator<Map.Entry<String, String>>	eventAttributeAndDescriptionsIterator()
static Iterator<String>	eventAttributeIterator()
static boolean	hasEventAttribute(String innerTag)
int	removeEventAttributes(String... eventAttributes)
List-Accessors: Both Data-Structures (Simultaneously)
Modifier and Type	Method
static String	description(String innerTag)
static boolean	has(String innerTag)
static void	printAll(Appendable a, boolean printDescriptions)
static void	printAllToTerminal(boolean printDescriptions)
Lazy-Loader for Descriptions Files
Modifier and Type	Method
static void	loadDescriptions()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

attributes

🡇 ⇈

protected static final java.util.TreeSet<java.lang.String> attributes

This is an internal data-structure that shall contain a list of all Attributes. This list was scraped from the site w3schools.com, and it isn't guaranteed to contain every possible proprietary, alternate, deprecated, or even invented Attributes. Instead, this is a "Best Efforts" approach, and this class offers a good API for modifying the list to accomodate any new ideas.

Java HTML JAR Data-File:
This particular internal TreeSet is loaded from the '.jar' immediately, when the ClassLoader loads this class. This data-structure's contents may be viewed by clicking below:

Standard HTML Attributes

Code:

Exact Field Declaration Expression:

 @SuppressWarnings("unchecked")
     protected static final TreeSet<String> attributes = (TreeSet<String>) d.elementAt(0);

eventAttributes

🡅 🡇 ⇈

protected static final java.util.TreeMap<java.lang.String,java.lang.String> eventAttributes

This is an internal data-structure that shall contain a list of all Event-Attributes. This list was scraped from the site w3schools.com, and it isn't guaranteed to contain every possible proprietary, alternate, deprecated, or even invented Event-Attributes. Instead, this is a "Best Efforts" approach, and this class offers a good API for modifying the list to accomodate any new ideas.

Java HTML JAR Data-File:
This particular internal TreeMap is loaded from the '.jar' immediately, when the ClassLoader loads this class. This data-structure's contents may be viewed by clicking below:

• Event Attributes
• Events with Categories

TreeMap<String, String> Issue:
This list is stored as a TreeMap, rather than a TreeSet, because associated with each & every Java-Script Listener-Attribute Names is a 'category' that indicates what type of 'listener' the specified attribute is.

Code:

Exact Field Declaration Expression:

 @SuppressWarnings("unchecked")
     protected static final TreeMap<String, String> eventAttributes =
         (TreeMap<String, String>) d.elementAt(1);

attributeDescriptions

🡅 🡇 ⇈

protected static final java.util.TreeMap<java.lang.String,java.lang.String> attributeDescriptions

This TreeMap contains a short, descriptive, Text-String describing each and every one of the Attributes stored / listed by this class.

Data-File Lazy-Loading:
Here, this particular TreeMap is not actually automatically loaded by the ClassLoader when it first loads this class. Until a user has specifically requested a Text-Description for an HTML-Attribute, the contents of this TreeMap shall remain on disk, in the '.jar' File.

Invoke the method loadDescriptions() to request that this class retrieve the data needed for this TreeMap out of the '.jar' from disk. This data-structure's contents may be viewed by clicking the link below:

Standard Attribute Descriptions

Code:

Exact Field Declaration Expression:

 protected static final TreeMap<String, String> attributeDescriptions = new TreeMap<>();

eventAttributeDescriptions

🡅 🡇 ⇈

protected static final java.util.TreeMap<java.lang.String,java.lang.String> eventAttributeDescriptions

This TreeMap contains a short, descriptive, Text-String describing each and every one of the Event-Attributes stored / listed by this class.

Data-File Lazy-Loading:
Here, this particular TreeMap is not actually automatically loaded by the ClassLoader when it first loads this class. Until a user has specifically requested a Text-Description for an HTML-Attribute, the contents of this TreeMap shall remain on disk, in the '.jar' File.

Invoke the method loadDescriptions() to request that this class retrieve the data needed for this TreeMap out of the '.jar' from disk. This data-structure's contents may be viewed by clicking the link below:

Event Attribute Descriptions

Code:

Exact Field Declaration Expression:

 protected static final TreeMap<String, String> eventAttributeDescriptions = new TreeMap<>();

Method Detail

addAttributes

🡅 🡇 ⇈

public static void addAttributes(java.lang.String... attributes)

Inserts new Attributes into the internally stored data-structure field 'attributes'

Var-Args Parameter:
This method will over-write the String's passed to the Var-Args parameter 'attributes' to ensure that all of the String's are, indeed, in lower-case format.

Java HTML JAR Data-File:
The Attributes Field / data-structure is loaded by the Class-Loader when this class itself is loaded from the '.jar' File. View the starting contents of the particular data-files that contain this list here, with the links below:

• Attributes
• Text Descriptions

Parameters:

attributes - This var-args String[]-Array parameter accepts a list of new HTML-Attributes.

Throws:

java.lang.IllegalArgumentException - If among the list of Attributes provided there are any duplicates, or if the internally stored 'attributes' (TreeSet) field already contains a listed Attribute, then this exception will throw

java.lang.NullPointerException - If any of the Attributes inside the Var-Args parameter are null.

See Also:

removeAttributes(String[]), attributeIterator(), attributes

Code:

Exact Method Body:

 // All attributes are stored in lower-case format
 for (int i=0; i < attributes.length; i++) attributes[i] = attributes[i].toLowerCase();

 // It is always better to test input for errors.  Here, check that the attributes provided
 // are not already members of the internal TreeMap<String, String>

 for (String a : attributes) if (InnerTags.attributes.contains(a))

     throw new IllegalArgumentException(
         "You are attempting to insert an attribute [" + a + "] which is already a " +
         "member of the attributes list."
     );

 // Insert the event-attribute.  Provide a standard "Event Type", and a "Blank" Description
 // (Zero-Length String)

 for (String a : attributes)

     if (InnerTags.attributes.add(a))

         throw new IllegalArgumentException(
             "Failed to insert an attribute: [" + a + "].  You have attempted to insert " +
             "the same inner-tag twice."
         );

     // Standard Description
     else InnerTags.attributeDescriptions.put(a, "User-Provided Attribute");

addEventAttributes

🡅 🡇 ⇈

public void addEventAttributes(java.lang.String... eventAttributes)

Inserts new Event-Attributes into the internally stored data-structure field 'eventAttributes'

Var-Args Parameter:
This method will over-write the String's passed to the Var-Args parameter 'eventAttributes' to ensure that all of the String's are, indeed, in lower-case format.

Java HTML JAR Data-File:
The Event-Attributes Field / data-structure is loaded by the Class-Loader when this class itself is loaded from the '.jar' File. View the starting contents of the particular data-files that contain this list here, with the links below:

• Event-Attributes
• Text Descriptions

Parameters:

eventAttributes - This Var-Args String[]-Array parameter accepts a list of new HTML Event-Attributes (listeners).

Throws:

java.lang.IllegalArgumentException - If among the list of Event-Attributes provided there are any duplicates, or if the internally stored 'eventAttributes' (TreeMap) field already contains an already listed Event-Attribute, then this exception will throw

java.lang.NullPointerException - If any of the Event-Attributes named by the Var-Args parameter are null.

See Also:

removeEventAttributes(String[]), eventAttributeIterator(), eventAttributes

Code:

Exact Method Body:

 // All attributes are stored in lower-case format
 for (int i=0; i < eventAttributes.length; i++)
 eventAttributes[i] = eventAttributes[i].toLowerCase();

 // It is always better to test input for errors.  Here, check that the attributes provided
 // are not already members of the internal TreeMap<String, String>

 for (String ea : eventAttributes) if (InnerTags.eventAttributes.containsKey(ea))

     throw new IllegalArgumentException(
         "You are attempting to insert an event-attribute [" + ea + "] which is already " +
         "a member of the event-attributes list."
     );

 // Insert the event-attribute.  Provide a standard "Event Type", and a "Blank" Description
 // (Zero-Length String)

 for (String ea : eventAttributes)

     if (InnerTags.eventAttributes.put(ea, "User-Added") != null)

         throw new IllegalArgumentException(
             "Failed to insert an event-attribute: [" + ea + "].  You have attempted to " +
             "insert the same inner-tag twice."
         );

     // Standard Description
     else InnerTags.eventAttributeDescriptions.put(ea, "User-Provided Event Attribute");

removeAttributes

🡅 🡇 ⇈

public int removeAttributes(java.lang.String... attributes)

Removes a Attributes from the internally stored data-structure field 'attributes'

Java HTML JAR Data-File:
The Attributes Field / data-structure is loaded by the Class-Loader when this class itself is loaded from the '.jar' File. View the starting-contents of the particular data-files that contain this list here, with the links below:

• Attributes
• Text Descriptions

Parameters:

attributes - This Var-Args String[]-Array parameter accepts a list of Standard HTML Attributes to be removed from the internal list.

Returns:

This simply returns a count of the number of HTML-Attributes that were successfully removed from the internal 'attributes' data-structures. (This is equal to the number of Standard-Attributes passed via parameter 'attributes' that were actually defined within the internal data-structures)

See Also:

addAttributes(String[]), attributeIterator(), attributes

Code:

Exact Method Body:

 int count = 0;

 // All attributes are stored in lower-case format
 for (int i=0; i < attributes.length; i++)
 {
     String attrib = attributes[i].toLowerCase();

     if (InnerTags.attributes.remove(attrib))
     {
         count++;
         InnerTags.attributeDescriptions.remove(attrib);
     }
 }
        
 return count;

removeEventAttributes

🡅 🡇 ⇈

public int removeEventAttributes(java.lang.String... eventAttributes)

Removes a Event-Attributes from the internally stored data-structure field 'eventAttributes'

Java HTML JAR Data-File:
The Event-Attributes Field / data-structure is loaded by the Class-Loader when this class itself is loaded from the '.jar' File. View the starting-contents of the particular data-files that contain this list here, with the links below:

• Event-Attributes
• Text Descriptions

Parameters:

eventAttributes - This Var-Args String[]-Array parameter accepts a list of HTML Event Attributes to be removed from the internal list.

Returns:

This simply returns a count of the number of Event-Attributes that were successfully removed from the internal 'eventAttributes' data-structures. (This is equal to the number of Event-Attributes passed via parameter 'eventAttributes' that were actually defined within the internal data-structures)

See Also:

addEventAttributes(String[]), eventAttributeIterator(), eventAttributes

Code:

Exact Method Body:

 int count = 0;

 // All attributes are stored in lower-case format
 for (int i=0; i < eventAttributes.length; i++)
 {
     String eventAttrib = eventAttributes[i].toLowerCase();

     if (InnerTags.eventAttributes.remove(eventAttrib) != null)
     {
         count++;
         InnerTags.eventAttributeDescriptions.remove(eventAttrib);
     }
 }
        
 return count;

printAllToTerminal

🡅 🡇 ⇈

public static void printAllToTerminal(boolean printDescriptions)

Convenience Method
Invokes: printAll(Appendable, boolean).
Catches: Appendable's Exception.

Code:

Exact Method Body:

 try { printAll(System.out, printDescriptions); } catch (IOException e) { }

printAll

🡅 🡇 ⇈

public static void printAll(java.lang.Appendable a,
                            boolean printDescriptions)
                     throws java.io.IOException

This simply prints all data that is stored in the JAR data-files to an instance of 'Appendable'

Parameters:

a - This is parameter may not be a null, or a NullPointerException will throw. This the target-receiver for the text-output of this method. This parameter expects an implementation of Java's java.lang.Appendable interface which allows for a wide range of options when logging intermediate messages.

Class or Interface Instance	Use & Purpose
'System.out'	Sends text to the standard-out terminal
Torello.Java.StorageWriter	Sends text to System.out, and saves it, internally.
FileWriter, PrintWriter, StringWriter	General purpose java text-output classes
FileOutputStream, PrintStream	More general-purpose java text-output classes

IMPORTANT: The Appendable interface requires that the Checked-Exception IOException be caught when using its append(...) methods.

printDescriptions - When this parameter is TRUE, then (first) this method will ensure that the JAR Descriptions-Data-File is been loaded into memory. If it has not, then the description-String's will be loaded from disk. These String's contain a one-sentence-long text-description of each attribute / inner-tag listed in this class. They are not normally loaded by the Class-Loader for this class, unless specifically requested.

If this parameter is passed FALSE, then the data-file will not be visited, and the attribute-descriptions will not be sent to the output stream.

Throws:

java.io.IOException - The general purpose interface 'java.lang.Appendable' throws an IOException when printing information. If the Appendable provided to this method fails, this exception shall propagate out.

See Also:

attributes, eventAttributes, attributeDescriptions, eventAttributeDescriptions

Code:

Exact Method Body:

 if (! printDescriptions)
 {
     a.append("NON-EVENT ATTRIBUTES: ");

     for (String attribute : attributes)
         a.append(attribute + ", ");

     a.append("\n\nEVENT ATTRIBUTES: ");

     for (String attribute : eventAttributes.keySet())
         a.append(attribute + " (" + eventAttributes.get(attribute) + "), ");
 }
    
 else
 {
     loadDescriptions();

     a.append("NON-EVENT ATTRIBUTES:\n");

     for (String attribute : attributes)

         a.append(
             String.format("%-" + 20 + "s", attribute) +
             attributeDescriptions.get(attribute) + "\n"
         );

     a.append("\nEVENT ATTRIBUTES:\n");

     for (String attribute : eventAttributes.keySet())

         a.append(
             String.format("%-" + 20 + "s", attribute) +
             "[" + String.format("%-" + 20 + "s", eventAttributes.get(attribute) + "] ") + 
             eventAttributeDescriptions.get(attribute) + "\n"
         );
 }

loadDescriptions

🡅 🡇 ⇈

public static void loadDescriptions()

This method will visit the (small) data-file's that are included in the JAR-file distribution of the Java-HTML library. The data-file will only be loaded if the two tree data-structures have not already been loaded into memory. These are "descriptive String definitions" for each of the attributes stored here. The descriptions themselves were all scraped from the URL's listed below. They were scraped on April 7th, 2020 - and the definitions have been word-for-word copied from these URL's.

 URL url1 = new URL("https://www.w3schools.com/tags/ref_attributes.asp");
 URL url2 = new URL("https://www.w3schools.com/tags/ref_eventattributes.asp");

See Also:

LFEC.readObjectFromFile_JAR(java.lang.Class<?>, java.lang.String, boolean, java.lang.Class<T>), attributeAndDescriptionsIterator(), eventAttributeAndDescriptionsIterator(), attributeDescriptions, eventAttributeDescriptions

Code:

Exact Method Body:

 if ((attributeDescriptions.size() == 0) || (eventAttributeDescriptions.size() == 0))
 {
     Vector<Object> d = (Vector<Object>) LFEC.readObjectFromFile_JAR
         (Torello.Data.DataFileLoader.class, "data13.vdat", true, Vector.class);

     attributeDescriptions.putAll((TreeMap<String, String>) d.elementAt(0));
     eventAttributeDescriptions.putAll((TreeMap<String, String>) d.elementAt(1));
 }

attributeIterator

🡅 🡇 ⇈

public static java.util.Iterator<java.lang.String> attributeIterator()

Internally, Attributes are stored in a Java java.util.TreeSet<String>. This method invokes the method TreeSet.iterator().

RemoveUnsupportedIterator:
To prevent a user from accidentally removing an Inner-Tag from the internal data-structure field, the Iterator returned is wrapped in an instance of RemoveUnsupportedIterator.

Data File Contents:
The contents of this Iterator are loaded from a (small) internal data-file stored in the JAR Distribution for this Java HTML Package. The contents of this data-file (a list of String's that are returned by the Iterator) may be viewed, here, by clicking the link below:

Standard HTML Attributes

Returns:

an Iterator that cycles through the list of Attribute-String's stored in this class.

See Also:

RemoveUnsupportedIterator, addAttributes(String[]), removeAttributes(String[]), attributes

Code:

Exact Method Body:

 return new RemoveUnsupportedIterator<String>(attributes.iterator());

eventAttributeIterator

🡅 🡇 ⇈

public static java.util.Iterator<java.lang.String> eventAttributeIterator()

Internally, Event-Attributes are stored in a Java java.util.TreeMap<String, String>. This method invokes the method TreeMap.iterator(). The TreeMap has a key-set that contains all event-attributes mapped to the category of events they are related to. To retrieve the "event-type" information related to any particular event-attribute returned from this Iterator, just invoke the whatEventType(String eventAttribute) method.

Java-Script Listeners:
Event-Attributes are also referred to as Listeners and sometimes / also Java-Script Listeners. They usually have names like 'onload', 'onclick', 'onmouseover' etc...

RemoveUnsupportedIterator:
To prevent a user from accidentally removing an Inner-Tag from the internal data-structure field, the Iterator returned is wrapped in an instance of RemoveUnsupportedIterator.

Data File Contents:
The contents of this Iterator are loaded from a (small) internal data-file stored in the JAR Distribution for this Java HTML Package. The contents of this data-file (a list of String's that are returned by the Iterator) may be viewed, here, by clicking the link below:

Event Attributes

Returns:

an Iterator that cycles through the list of Attribute-String's stored in this class.

See Also:

RemoveUnsupportedIterator, addEventAttributes(String[]), removeEventAttributes(String[]), eventAttributes

Code:

Exact Method Body:

 return new RemoveUnsupportedIterator<String>(eventAttributes.keySet().iterator());

attributeAndDescriptionsIterator

🡅 🡇 ⇈

public static java.util.Iterator<java.util.Map.Entry<java.lang.String,java.lang.String>> attributeAndDescriptionsIterator
            ()

Builds an iterate that returns Standard HTML Attributes and their Text-String descriptions out of the internal data-structure field attributeDescriptions.

Lazy-Load Descriptions Data-File:
This method will attempt to load a particular data-file from the '.jar' File off of disk, into memory. This file contains a set of one-sentence descriptions, (stored as String's). After loading, this data is placed in the attributeDescriptions data-structure field.

Under normal operation, this class will not load "description" Text-Array's, since they don't have any use outside of a user's request to print information about the Attributes.

RemoveUnsupportedIterator:
To prevent a user from accidentally removing a description from the internal data-structure field, the Iterator returned is wrapped in an instance of RemoveUnsupportedIterator.

Viewing the Descriptions Data-File:
Again, the returned Iterator is lazy-loaded from the '.jar' File on user request. The Iterator returns instances of java.util.Map.Entry, and its contents may be viewed by clicking the link below:

Attributes and Descriptions

Returns:

An Iterator that iterates the Attribute-Description key-value pairs as instances of "Map.Entry<String, String>"

See Also:

RemoveUnsupportedIterator, attributeDescriptions, loadDescriptions()

Code:

Exact Method Body:

 // Loads the descriptions map, ONLY IF they have not already been loaded into memory
 // from the JAR data-files

 loadDescriptions();

 return new RemoveUnsupportedIterator<Map.Entry<String, String>>
     (attributeDescriptions.entrySet().iterator());

eventAttributeAndDescriptionsIterator

🡅 🡇 ⇈

public static java.util.Iterator<java.util.Map.Entry<java.lang.String,java.lang.String>> eventAttributeAndDescriptionsIterator
            ()

Builds an iterate that returns HTML Event-Attributes and their Text-String descriptions out of the internal data-structure field eventAttributeDescriptions.

Lazy-Load Descriptions Data-File:
This method will attempt to load a particular data-file from the '.jar' File off of disk, into memory. This file contains a set of one-sentence descriptions, (stored as String's). After loading, this data is placed in the eventAttributeDescriptions data-structure field.

Under normal operation, this class will not load "description" Text-Array's, since they don't have any use outside of a user's request to print information about the Attributes.

RemoveUnsupportedIterator:
To prevent a user from accidentally removing a description from the internal data-structure field, the Iterator returned is wrapped in an instance of RemoveUnsupportedIterator.

Viewing the Descriptions Data-File:
Again, the returned Iterator is lazy-loaded from the '.jar' File on user request. The Iterator returns instances of java.util.Map.Entry, and its contents may be viewed by clicking the link below:

Event Attributes and Descriptions

Returns:

An Iterator that iterates the Event-Attribute / Description key-value pairs as instances of "Map.Entry<String, String>"

See Also:

RemoveUnsupportedIterator, loadDescriptions(), eventAttributeDescriptions

Code:

Exact Method Body:

 // Loads the descriptions map, ONLY IF they have not already been loaded into memory from
 // the JAR data-files

 loadDescriptions();

 return new RemoveUnsupportedIterator<Map.Entry<String, String>>
     (eventAttributeDescriptions.entrySet().iterator());

eventAttributeAndCategoriesIterator

🡅 🡇 ⇈

public static java.util.Iterator<java.util.Map.Entry<java.lang.String,java.lang.String>> eventAttributeAndCategoriesIterator
            ()

Will build an iterate that can return event-attributes and their categories.

RemoveUnsupportedIterator:
In order to prevent accidental removal of the attributes-descriptions via the Iterator's "Remove" Method, the 'Iterator<...>' class has been overloaded with a class that throws exceptions if remove() is invoked.

Returns:

An Iterator that iterates the Event-Attribute / Category key-value pairs as instances of "Map.Entry<String, String>"

Data File Contents: The contents of this Iterator are loaded from a (small) internal data-file stored in the JAR Distribution for this Java HTML Package. The contents of this data-file (and the list of Map.Entry's returned by the Iterator) may be viewed, here, by clicking the link below:

Event Attributes and Categories

See Also:

RemoveUnsupportedIterator, eventAttributes

Code:

Exact Method Body:

 return new RemoveUnsupportedIterator<Map.Entry<String, String>>
     (eventAttributes.entrySet().iterator());

hasAttribute

🡅 🡇 ⇈

public static boolean hasAttribute(java.lang.String innerTag)

Will report whether an attribute is listed as a well-defined attribute, according to HTML standards.

List Modification:
The list of HTML-Attributes may, in fact, be altered. To add a new HTML-Attribute to the internal lookup table of valid Attributes, use addAttributes(String[]). To remove an Attribute from the internal list, use removeAttributes(String[]).

Viewing the Data-File:
The Complete list of attributes that are stored in this class' internal data structure are listed in the link below:

Attributes

Parameters:

innerTag - Throughout this package, the keywords "Attribute" and "InnerTag" are used interchangeably as best as is possible. This method will ask the internally stored java.util.TreeSet<String> if there is a well-defined attribute named by this parameter present in its tree-structure.

Returns:

Will return TRUE if the internally stored TreeSet<String> contains this string. The comparison that's performed is case-insensitive, and internally all inner-tag String's are stored in lower-case format.

See Also:

attributes

Code:

Exact Method Body:

 return attributes.contains(innerTag.toLowerCase());

hasEventAttribute

🡅 🡇 ⇈

public static boolean hasEventAttribute(java.lang.String innerTag)

Will report whether an event-attribute is listed as a well-defined event-attribute, according to HTML standards.

List Modification:
The list of HTML Event-Attributes may, in fact, be altered. To add a new HTML Event-Attribute to the internal lookup table of valid Event-Attributes, use addEventAttributes(String[]). To remove an Event Attribute from the internal list, use removeEventAttributes(String[]).

Viewing the Data-File:
The Complete list of event attributes that are stored in this class' internal data structure are listed in the link below:

Event Attributes

Parameters:

innerTag - Throughout this package, the keywords "Attribute" and "InnerTag" are used interchangeably as best as is possible. This method will ask the internally stored java.util.TreeMap<String, String> if there is a well-defined event-attribute named by this parameter present in its tree-structure's key-set. The key each node in the tree corresponds to an event-attribute, and the value corresponds to the type-name of the event - for instance: 'window-event', 'mouse-event', keyboard-event', etc.... These are also known as "Java-Script Listeners".

Returns:

Will return TRUE if the internally stored TreeSet<String> contains this string. The comparison that's performed is case-insensitive, and internally all inner-tag String's are stored in lower-case format.

See Also:

eventAttributes

Code:

Exact Method Body:

 return eventAttributes.containsKey(innerTag.toLowerCase());

has

🡅 🡇 ⇈

public static boolean has(java.lang.String innerTag)

Will report whether an attribute is either a standard, well-defined, attribute or (also) if the inner-tag is a well-defined event-inner-tag.

The Complete list of attributes and event attributes stored in this class internal data structure are listed in the two links below:

• Attributes
• Event Attributes

Parameters:

innerTag - This will ask both the TreeSet<String> 'attributes' data-structure if the inner-tag is contained, and if not, it will ask if the TreeMap<String, String> 'eventAttributes' data-structure contains the inner-tag. Before the tests are performed, this string is converted to lower-case format. Internally, all inner-tag String's are stored in lower-case format

Returns:

Will return TRUE if either of the two tree data-structures contain this inner-tag.

See Also:

attributes, eventAttributes

Code:

Exact Method Body:

 innerTag = innerTag.toLowerCase();

 // NOTE: Short-Circuit Boolean-Evaluation is always in effect when two '||' are used
 // instead of one '|'

 return attributes.contains(innerTag) || eventAttributes.containsKey(innerTag);

description

🡅 🡇 ⇈

public static java.lang.String description(java.lang.String innerTag)

Provides the description stored in the JAR data-file for both standard inner-tags, and event-based inner-tags.

DATA-FILE LOAD: This method will attempt to load a particular data-file from the JAR-library into memory. This file contains a one-sentence description, stored as java.lang.String's for each of the attributes and event-attributes known to this class. Under normal operation, these text arrays remain on-disk, only.

Parameters:

innerTag - This is the attribute whose description is sought. This may be either an regular attribute, or an event-attribute. Both tree data-structures will be searched.

Returns:

The one-line text-description provided for this innerTag. The comparison that's performed is case-insensitive, and internally all inner-tag String's are stored in lower-case format.

See Also:

attributeDescriptions, eventAttributeDescriptions

Code:

Exact Method Body:

 // Loads the descriptions map, ONLY IF they have not already been loaded 
 // into memory from the JAR data-files

 loadDescriptions(); 

 innerTag = innerTag.toLowerCase();

 String desc;

 if ((desc = attributeDescriptions.get(innerTag)) != null) return desc;

 if ((desc = eventAttributeDescriptions.get(innerTag)) != null) return desc;

 return null;

aDescription

🡅 🡇 ⇈

public static java.lang.String aDescription(java.lang.String innerTag)

Provides the description stored in the JAR data-file for Standard HTML Inner-Tags. (Note that in theory the term "Inner Tags" is intended to be synonymous with "Attributes" in this package)

Lazy-Load Descriptions Data-File:
This method will attempt to load a particular data-file from the '.jar' File off of disk, into memory. This file contains a set of one-sentence descriptions, (stored as String's). After loading, this data is placed in the attributeDescriptions data-structure field.

Under normal operation, this text array remains on-disk, only.

Viewing the Descriptions Data-File:
Again, the returned Iterator is lazy-loaded from the '.jar' File on user request. The Iterator returns instances of java.util.Map.Entry, and its contents may be viewed by clicking the link below:

Attributes and Descriptions

Parameters:

innerTag - This is the attribute whose description is sought. This must be a regular attribute, not an event-attribute. Only the former tree data-structure will be searched.

Returns:

The one-line text-description provided for this innerTag. The comparison that's performed is case-insensitive, and internally all inner-tag String's are stored in lower-case format.

See Also:

attributeDescriptions, loadDescriptions()

Code:

Exact Method Body:

 // Loads the descriptions map, ONLY IF they have not already been loaded into memory from
 // the JAR data-files

 loadDescriptions(); 

 return attributeDescriptions.get(innerTag.toLowerCase());

eaDescription

🡅 🡇 ⇈

public static java.lang.String eaDescription(java.lang.String innerTag)

Provides the description stored in the JAR data-file for HTML Event Inner-Tags. (Note that in theory the term "Inner Tags" is intended to be synonymous with "Attributes" in this package)

Lazy-Load Descriptions Data-File:
This method will attempt to load a particular data-file from the '.jar' File off of disk, into memory. This file contains a set of one-sentence descriptions, (stored as String's). After loading, this data is placed in the eventAttributeDescriptions data-structure field.

Under normal operation, this text array remains on-disk, only.

Viewing the Descriptions Data-File:
Again, the returned Iterator is lazy-loaded from the '.jar' File on user request. The Iterator returns instances of java.util.Map.Entry, and its contents may be viewed by clicking the link below:

Event Attributes and Descriptions

Parameters:

innerTag - This is the attribute whose description is sought. This must be an event attribute, not an regular / standard attribute. Only the event-attribute tree data-structure will be searched. Event-attributes are usually also called Java-Script listeners.

Returns:

The one-line text-description provided for this innerTag. The comparison that's performed is case-insensitive, and internally all inner-tag String's are stored in lower-case format.

See Also:

eventAttributeDescriptions, loadDescriptions()

Code:

Exact Method Body:

 // Loads the descriptions map, ONLY IF they have not already been loaded into memory from
 // the JAR data-files

 loadDescriptions();

 return eventAttributeDescriptions.get(innerTag.toLowerCase());

eventAttributes

🡅 🡇 ⇈

public static java.lang.String[] eventAttributes
            (java.util.Properties tnAllAV)

Retrieves all event-attributes that are found within a TagNode java.util.Properties list of attributes.

Default List Contents:
The complete list of standard HTML Event-Attributes contained by the internal data-set may be viewed using the link below:

Event HTML Attributes

This internal data-structure may be modified at runtime using the following:

• addEventAttributes(String...)
• removeEventAttributes(String...)

Parameters:

tnAllAV - This should be an instance of java.util.Properties that is properly generated by an invocation of the method TagNode.allAV(). Because these properties objects are not stored internally to TagNode, they are re-computed on each and every call to the method 'allAV()', these calls can be expensive if included within a loop. For this reason, this method accepts an instance of java.util.Properties, rather than the TagNode itself.

Returns:

This will return a list of any and all HTML Element Attributes that are listed in the Event Attributes Tree data-structure. This should indicate that an attribute is a Java-Script Listener of some form.

NOTE ON NULL: This method shall never return 'null'. If none of the attributes identified are Event / Java-Script listeners, then this method shall return a zero-length String-Array.

See Also:

hasEventAttribute(String), TagNode.allAV()

Code:

Exact Method Body:

 TreeSet<String> ret = new TreeSet<>();

 // Parameter 'tnAllAV' is just the list of attributes returned by a call to
 // TagNode.allAV()  - If any of these properties are listed in the internal data structure
 // for "Event Attributes", then they should be returned in the return-String-array

 for (String property : tnAllAV.stringPropertyNames())
     if (hasEventAttribute(property))
         ret.add(property);

 // Convert the TreeSet<String> to a (sorted) String[], and return
 String[] sArr = new String[ret.size()];

 return ret.toArray(sArr);

nonStandardAttributes

🡅 🡇 ⇈

public static java.lang.String[] nonStandardAttributes
            (java.util.Properties tnAllAV)

Retrieves all NON-STANDARD attributes that are found within a TagNode java.util.Properties list of attributes. The definition of a non standard HTML attribute, for the purposes of this method, is simply an HTML attribute whose name is NIETHER found in the internal data-structure listing all event-attributes, NOR IS FOUND within the internal data-structure of all HTML attributes. These two data-structures (lists) may be viewed with the link below:

• Standard HTML Attributes
• Event HTML Attributes

Both of these internal data-structures may be modified at runtime using the following:

• addAttributes(String...)
• removeAttributes(String...)
• addEventAttributes(String...)
• removeEventAttributes(String...)

Parameters:

tnAllAV - This should be an instance of java.util.Properties that is properly generated by an invocation of the method TagNode.allAV(). Because these properties objects are not stored internally to TagNode, they are re-computed on each and every call to the method 'allAV()', these calls can be expensive if included within a loop. For this reason, this method accepts an instance of java.util.Properties, rather than the TagNode itself.

Returns:

This will return a list of any and all HTML Element Attributes that are not listed among the standard attributes in the attribute TreeSet internal data-structure.

NOTE ON NULL: This method shall never return 'null'. If all attributes are well-known standard inner-tags, or event-inner-tags, then this method shall return a zero-length String-Array.

See Also:

has(String), hasEventAttribute(String), TagNode.allAV(), StrCmpr.startsWithIgnoreCase(String, String)

Code:

Exact Method Body:

 TreeSet<String> ret = new TreeSet<>();

 // Parameter 'tnAllAV' is just the list of attributes returned by a call to
 // TagNode.allAV()  - If any of these properties are **NOT** listed in the internal data
 // structures for either "Event Attributes" or "(Regular) Attributes", then they should
 // be returned in the return-String-array

 for (String property : tnAllAV.stringPropertyNames())

     if (! StrCmpr.startsWithIgnoreCase(property, "data-"))
         if ((! has(property)) && (! hasEventAttribute(property)))
             ret.add(property);

 // Convert the TreeSet<String> to a (sorted) String[], and return
 String[] sArr = new String[ret.size()];

 return ret.toArray(sArr);

eventAttributes

🡅 🡇 ⇈

public static Ret2<TagNodeIndex[],java.lang.String[][]> eventAttributes
            (java.util.Vector<? super TagNode> html)

Convenience Method
Invokes: eventAttributes(Vector, int, int).

Code:

Exact Method Body:

 return eventAttributes(html, 0, -1);

eventAttributes

🡅 🡇 ⇈

public static Ret2<TagNodeIndex[],java.lang.String[][]> eventAttributes
            (java.util.Vector<? super TagNode> html,
             int sPos,
             int ePos)

This method is intended to identify all TagNode elements on an input page that possess "HTML Event Attributes." TagNode elements that do match this criteria will be wrapped in a TagNodeIndex and returned in a two part Ret2 return array. The inner-tag event names will also be returned, using the {code class 'Ret2'} return data-structure.

Default List Contents:
The complete list of standard HTML Event-Attributes contained by the internal data-set may be viewed using the link below:

Event HTML Attributes

Parameters:

html - This is any vectorized-html web-page, or sub-page.

sPos - This is the (integer) Vector-index that sets a limit for the left-most Vector-position to inspect/search inside the input Vector-parameter.

This value is considered 'inclusive' meaning that the HTMLNode at this Vector-index will be visited by this method.

NOTE: If this value is negative, or larger than the length of the input-Vector, an exception will be thrown.

ePos - This is the (integer) Vector-index that sets a limit for the right-most Vector-position to inspect/search inside the input Vector-parameter.

This value is considered 'exclusive' meaning that the 'HTMLNode' at this Vector-index will not be visited by this method.

NOTE: If this value is larger than the size of input the Vector-parameter, an exception will throw.

ALSO: Passing a negative value to this parameter, 'ePos', will cause its value to be reset to the size of the input Vector-parameter.

Returns:

Returns an instance of Ret2. The two elements of the Ret2 construct will contain parallel arrays. These parallel arrays will have the following:

• Ret2.a (TagNodeIndex[])
  
  This will have an array of TagNodeIndex elements. Each of these contain both the TagNode that matched, and also the index into original html Vector-parameter where that TagNode was found.
  
  
• Ret2.b (String[]][])
  
  This is another array. It is parallel to the array in Ret2.a, and its contents, itself, is a an array of all the attributes that were "Event Listener" attributes found in the TagNode.

NOTE: This method is guaranteed not return 'null' values for either of these two arrays. If no event-inner-tag matches are found, the Ret2 construct will return two zero-length arrays in field Ret2.a, and Ret2.b;

List Modification:
If the list of Event-Attributes being returned by this method is "leaving out" certain Event-Attributes, or on the contrary, the returned lists are including other Event-Attributes that should not be returned by this method ... The internal HTML Event-Attributes data structures can be modified by calling:

• addEventAttributes(String...)
• removeEventAttributes(String...)

Throws:

java.lang.IndexOutOfBoundsException - This exception shall be thrown if any of the following are true:

• If 'sPos' is negative, or if sPos is greater-than-or-equal-to the size of the Vector
• If 'ePos' is zero, or greater than the size of the Vector
• If the value of 'sPos' is a larger integer than 'ePos'. If 'ePos' was negative, it is first reset to Vector.size(), before this check is done.

java.lang.ClassCastException - If 'html' contains references that do not inherit HTMLNode.

See Also:

LV, eventAttributes(Properties), TagNode.tok, TagNode.isClosing, NodeIndex.n, NodeIndex.index, eventAttributes(Vector)

Code:

Exact Method Body:

 // Builds a Stream<TagNode>
 Stream.Builder<TagNodeIndex> tniBuilder = Stream.builder(); 

 // Builds a Stream<String[]>
 Stream.Builder<String[]> sArrSBuilder = Stream.builder();

 LV l = new LV(sPos, ePos, html);

 Object o;       TagNode tn;     String[] sArr;

 // Iterate through the entire Vector.  Find TagNode's with Attributes.  Check if they
 // have "Event Attributes".  If so, keep them in the list to be returned.

 for (int i=l.start; i < l.end; i++)

     if (    ((tn = ((HTMLNode) html.elementAt(i)).openTagPWA()) != null)
         &&  ((sArr = eventAttributes(tn.allAV())).length > 0)
     )
     {
         // Save TagNodeIndex: "TagNode" (tn) plus "index" (i)
         tniBuilder.add(new TagNodeIndex(i, tn));

         // Save String-Array
         sArrSBuilder.add(sArr);
     }

 // Build the two Stream.Builders to Stream... Convert Streams to Arrays... Return
 return new Ret2<TagNodeIndex[], String[][]>(

     // Build-Stream<TagNode>, Convert Stream to Array, put in Ret2.a
     tniBuilder.build().toArray(TagNodeIndex[]::new),

     // Build-Stream<String[]>, Convert Stream to Array, put in Ret2.b
     sArrSBuilder.build().toArray(String[][]::new)
 );

nonStandardAttributes

🡅 🡇 ⇈

public static Ret2<TagNodeIndex[],java.lang.String[][]> nonStandardAttributes
            (java.util.Vector<? super TagNode> html)

Convenience Method
Invokes: nonStandardAttributes(Vector, int, int)

Code:

Exact Method Body:

 return nonStandardAttributes(html, 0, -1);

nonStandardAttributes

🡅 ⇈

public static Ret2<TagNodeIndex[],java.lang.String[][]> nonStandardAttributes
            (java.util.Vector<? super TagNode> html,
             int sPos,
             int ePos)

This method is intended to identify all TagNode elements on an input page that possess "non-standard HTML Attributes." Any TagNode elements that do match this criteria will be wrapped in a TagNodeIndex and returned in a two part Ret2 return array. The inner-tag event names will also be returned, using the {code class 'Ret2'} return data-structure.

Default List Contents:
The list of Attributes contained by the standard internal HTML Attributes data-set and Event-Attributes data-set may be viewed using the links below:

• Standard HTML Attributes
• Event HTML Attributes

Parameters:

html - This is any vectorized-html web-page, or sub-page.

sPos - This is the (integer) Vector-index that sets a limit for the left-most Vector-position to inspect/search inside the input Vector-parameter.

This value is considered 'inclusive' meaning that the HTMLNode at this Vector-index will be visited by this method.

NOTE: If this value is negative, or larger than the length of the input-Vector, an exception will be thrown.

ePos - This is the (integer) Vector-index that sets a limit for the right-most Vector-position to inspect/search inside the input Vector-parameter.

This value is considered 'exclusive' meaning that the 'HTMLNode' at this Vector-index will not be visited by this method.

NOTE: If this value is larger than the size of input the Vector-parameter, an exception will throw.

ALSO: Passing a negative value to this parameter, 'ePos', will cause its value to be reset to the size of the input Vector-parameter.

Returns:

Returns an instance of Ret2. The two elements of the Ret2 construct will contain parallel arrays. These parallel arrays will have the following:

• Ret2.a (TagNodeIndex[])
  
  This will have an array of TagNodeIndex elements. Each of these contain both the TagNode that matched, and also the index into the original html Vector-parameter where that TagNode was found.
  
  
• Ret2.b String[][]
  
  This is another array. It is parallel to the array in Ret2.a, and its contents, itself, is an array of all the attributes that were identified in the TagNode as "Non-Standard Attributes". Such (non-standard) attributes were NIETHER FOUND in the event attributes internal data-structure, NOR WERE THEY FOUND in the attributes internal data-structure.

NOTE: This method is guaranteed not return 'null' values for either of these two arrays. If no non-standard inner-tag matches are found, the Ret2 construct will return two zero-length arrays in field Ret2.a, and Ret2.b;

List Modification:
If the list of Attributes being returned by this method are "leaving out" certain Attributes, or on the contrary, the returned lists are including other Attributes that should not be returned ... Then BOTH the internal Standard HTML Attribute and HTML Event-Attribute data-sets may be modified by invoking the following methods:

• addAttributes(String...)
• removeAttributes(String...)
• addEventAttributes(String...)
• removeEventAttributes(String...)

Throws:

java.lang.IndexOutOfBoundsException - This exception shall be thrown if any of the following are true:

• If 'sPos' is negative, or if sPos is greater-than-or-equal-to the size of the Vector
• If 'ePos' is zero, or greater than the size of the Vector
• If the value of 'sPos' is a larger integer than 'ePos'. If 'ePos' was negative, it is first reset to Vector.size(), before this check is done.

java.lang.ClassCastException - If 'html' contains references that do not inherit HTMLNode.

See Also:

LV, nonStandardAttributes(Properties), TagNode.tok, TagNode.isClosing, NodeIndex.n, NodeIndex.index, nonStandardAttributes(Vector)

Code:

Exact Method Body:

 // Builds a Stream<TagNode>
 Stream.Builder<TagNodeIndex> tniBuilder = Stream.builder();

 // Builds a Stream<String[]>
 Stream.Builder<String[]> sArrSBuilder = Stream.builder();

 // Loop Counter, and Exception Checker
 LV l = new LV(sPos, ePos, html);

 TagNode tn;     String[] sArr;

 // Iterate through the entire Vector.  Find TagNode's with Attributes.  Check if they
 // have any Attributes with are NIETHER "Event Attributes", nor "Regular Attributes"
 // ... keep them in the list to be returned.

 for (int i=l.start; i < l.end; i++)

     if (    ((tn = ((HTMLNode) html.elementAt(i)).openTagPWA()) != null)
         &&  ((sArr = nonStandardAttributes(tn.allAV())).length > 0)
     )
     {
         // Save TagNodeIndex: "TagNode" (tn) plus "index" (i)
         tniBuilder.add(new TagNodeIndex(i, tn));

         // Save String-Array
         sArrSBuilder.add(sArr);
     }

 // Build the two Stream.Builders to Stream... Convert Streams to Arrays... Return
 return new Ret2<TagNodeIndex[], String[][]>(

     // Build-Stream<TagNode>, Convert Stream to Array, put in Ret2.a
     tniBuilder.build().toArray(TagNodeIndex[]::new),

     // Build-Stream<String[]>, Convert Stream to Array, put in Ret2.b
     sArrSBuilder.build().toArray(String[][]::new)
 );