Attributes
Date: 2016-12-04

net.htmlparser.jericho

## Class Attributes

- java.lang.Object
- - net.htmlparser.jericho.Segment
  - - net.htmlparser.jericho.nodoc.SequentialListSegment<Attribute>
    - - net.htmlparser.jericho.Attributes

- All Implemented Interfaces:
    java.lang.CharSequence, java.lang.Comparable<Segment>, java.lang.Iterable<Attribute>, java.util.Collection<Attribute>, java.util.List<Attribute>

      public final class Attributes
      extends SequentialListSegment<Attribute>

  Represents the list of `Attribute` objects present within a particular `StartTag`.

  This segment starts at the end of the start tag's name and ends at the end of the last attribute.

  The attributes in this list are a representation of those found in the source document and are not modifiable. The `OutputDocument.replace(Attributes, Map)` and `OutputDocument.replace(Attributes, boolean convertNamesToLowerCase)` methods provide the means to add, delete or modify attributes and their values in an `OutputDocument`.

  Any server tags encountered inside the attributes area of a non-server tag do not interfere with the parsing of the attributes.

  If too many syntax errors are encountered while parsing a start tag's attributes, the parser rejects the entire start tag and generates a log entry. The threshold for the number of errors allowed can be set using the `setDefaultMaxErrorCount(int)` static method.

  Obtained using the `StartTag.getAttributes()` method, or explicitly using the `Source.parseAttributes(int pos, int maxEnd)` method.

  It is common for instances of this class to contain no attributes.

  See also the XML 1.0 specification for attributes.

  See Also:
    `StartTag`, `Attribute`

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static java.lang.String` | `generateHTML(java.util.Map<java.lang.String,java.lang.String> attributesMap)` Returns the contents of the specified attributes map as HTML attribute name/value pairs.
    `Attribute` | `get(java.lang.String name)` Returns the `Attribute` with the specified name (case insensitive).
    `int` | `getCount()` Returns the number of attributes.
    `java.lang.String` | `getDebugInfo()` Returns a string representation of this object useful for debugging purposes.
    `static int` | `getDefaultMaxErrorCount()` Returns the default maximum error count allowed when parsing attributes.
    `java.lang.String` | `getValue(java.lang.String name)` Returns the decoded value of the attribute with the specified name (case insensitive).
    `java.util.Iterator<Attribute>` | `iterator()` Returns an iterator over the `Attribute` objects in this list in order of appearance.
    `java.util.ListIterator<Attribute>` | `listIterator(int index)` Returns a list iterator of the `Attribute` objects in this list in order of appearance, starting at the specified position in the list.
    `java.util.Map<java.lang.String,java.lang.String>` | `populateMap(java.util.Map<java.lang.String,java.lang.String> attributesMap, boolean convertNamesToLowerCase)` Populates the specified `Map` with the name/value pairs from these attributes.
    `static void` | `setDefaultMaxErrorCount(int value)` Sets the default maximum error count allowed when parsing attributes.

    - ### Methods inherited from class net.htmlparser.jericho.nodoc.SequentialListSegment

      `add, add, addAll, addAll, clear, contains, containsAll, get, indexOf, isEmpty, lastIndexOf, listIterator, remove, remove, removeAll, retainAll, set, size, subList, toArray, toArray`

    - ### Methods inherited from class net.htmlparser.jericho.Segment

      `charAt, compareTo, encloses, encloses, equals, getAllCharacterReferences, getAllElements, getAllElements, getAllElements, getAllElements, getAllElements, getAllElementsByClass, getAllStartTags, getAllStartTags, getAllStartTags, getAllStartTags, getAllStartTags, getAllStartTagsByClass, getAllTags, getAllTags, getBegin, getChildElements, getEnd, getFirstElement, getFirstElement, getFirstElement, getFirstElement, getFirstElementByClass, getFirstStartTag, getFirstStartTag, getFirstStartTag, getFirstStartTag, getFirstStartTag, getFirstStartTagByClass, getFormControls, getFormFields, getMaxDepthIndicator, getNodeIterator, getRenderer, getRowColumnVector, getSource, getStyleURISegments, getTextExtractor, getURIAttributes, hashCode, ignoreWhenParsing, isWhiteSpace, isWhiteSpace, length, parseAttributes, subSequence, toString`

    - ### Methods inherited from class java.lang.Object

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

    - ### Methods inherited from interface java.util.List

      `equals, hashCode`

- - ### Method Detail

    - #### get

          public Attribute get(java.lang.String name)

      Returns the `Attribute` with the specified name (case insensitive).

      If more than one attribute exists with the specified name (which is illegal HTML), the first is returned.

      Parameters:
        `name` - the name of the attribute to get.
      Returns:
        the attribute with the specified name, or `null` if no attribute with the specified name exists.
      See Also:
        `getValue(String name)`

    - #### getValue

          public java.lang.String getValue(java.lang.String name)

      Returns the decoded value of the attribute with the specified name (case insensitive).

      Returns `null` if no attribute with the specified name exists or the attribute has no value.

      This is equivalent to `get(name)``.``getValue()`, except that it returns `null` if no attribute with the specified name exists instead of throwing a `NullPointerException`.

      Parameters:
        `name` - the name of the attribute to get.
      Returns:
        the decoded value of the attribute with the specified name, or `null` if the attribute does not exist or has no value.
      See Also:
        `Attribute.getValue()`

    - #### getCount

          public int getCount()

      Returns the number of attributes.

      This is equivalent to calling the `size()` method specified in the `List` interface.

      Specified by:
        `getCount` in class `SequentialListSegment<Attribute>`
      Returns:
        the number of attributes.

    - #### iterator

          public java.util.Iterator<Attribute> iterator()

      Returns an iterator over the `Attribute` objects in this list in order of appearance.
      Specified by:
        `iterator` in interface `java.lang.Iterable<Attribute>`
      Specified by:
        `iterator` in interface `java.util.Collection<Attribute>`
      Specified by:
        `iterator` in interface `java.util.List<Attribute>`
      Overrides:
        `iterator` in class `SequentialListSegment<Attribute>`
      Returns:
        an iterator over the `Attribute` objects in this list in order of appearance.

    - #### listIterator

          public java.util.ListIterator<Attribute> listIterator(int index)

      Returns a list iterator of the `Attribute` objects in this list in order of appearance, starting at the specified position in the list.

      The specified index indicates the first item that would be returned by an initial call to the `next()` method. An initial call to the `previous()` method would return the item with the specified index minus one.

      IMPLEMENTATION NOTE: For efficiency reasons this method does not return an immutable list iterator. Calling any of the `add(Object)`, `remove()` or `set(Object)` methods on the returned `ListIterator` does not throw an exception but could result in unexpected behaviour.

      Specified by:
        `listIterator` in interface `java.util.List<Attribute>`
      Specified by:
        `listIterator` in class `SequentialListSegment<Attribute>`
      Parameters:
        `index` - the index of the first item to be returned from the list iterator (by a call to the `next()` method).
      Returns:
        a list iterator of the items in this list (in proper sequence), starting at the specified position in the list.
      Throws:
        `java.lang.IndexOutOfBoundsException` - if the specified index is out of range (`index < 0 || index > size()`).

    - #### populateMap

          public java.util.Map<java.lang.String,java.lang.String> populateMap(java.util.Map<java.lang.String,java.lang.String> attributesMap,
                                                                     boolean convertNamesToLowerCase)

      Populates the specified `Map` with the name/value pairs from these attributes.

      Both names and values are stored as `String` objects.

      The entries are added in order of apprearance in the source document.

      An attribute with no value is represented by a map entry with a `null` value.

      Attribute values are automatically decoded before storage in the map.

      Parameters:
        `attributesMap` - the map to populate, must not be `null`.
        `convertNamesToLowerCase` - specifies whether all attribute names are converted to lower case in the map.
      Returns:
        the same map specified as the argument to the `attributesMap` parameter, populated with the name/value pairs from these attributes.
      See Also:
        `generateHTML(Map attributesMap)`

    - #### getDebugInfo

          public java.lang.String getDebugInfo()

      Returns a string representation of this object useful for debugging purposes.
      Overrides:
        `getDebugInfo` in class `Segment`
      Returns:
        a string representation of this object useful for debugging purposes.

    - #### getDefaultMaxErrorCount

          public static int getDefaultMaxErrorCount()

      Returns the default maximum error count allowed when parsing attributes.

      The system default value is 2.

      When searching for start tags, the parser can find the end of the start tag only by parsing the attributes, as it is valid HTML for attribute values to contain '>' characters (see the HTML 4.01 specification section 5.3.2).

      If the source text being parsed does not follow the syntax of an attribute list at all, the parser assumes that the text which was originally identified as the beginning of of a start tag is in fact some other text, such as an invalid '<' character in the middle of some text, or part of a script element. In this case the entire start tag is rejected.

      On the other hand, it is quite common for attributes to contain minor syntactical errors, such as an invalid character in an attribute name. For this reason the parser allows a certain number of minor errors to occur while parsing an attribute list before the entire start tag or attribute list is rejected. This property indicates the number of minor errors allowed.

      Major syntactical errors cause the start tag or attribute list to be rejected immediately, regardless of the maximum error count setting.

      Some errors are considered too minor to count at all (ignorable), such as missing white space between the end of a quoted attribute value and the start of the next attribute name.

      The classification of particular syntax errors in attribute lists into major, minor, and ignorable is not part of the specification and may change in future versions.

      Errors are logged as they occur.

      The value of this property is set using the `setDefaultMaxErrorCount(int)` method.

      Returns:
        the default maximum error count allowed when parsing attributes.
      See Also:
        `Source.parseAttributes(int pos, int maxEnd, int maxErrorCount)`

    - #### setDefaultMaxErrorCount

          public static void setDefaultMaxErrorCount(int value)

      Sets the default maximum error count allowed when parsing attributes.

      See the `getDefaultMaxErrorCount()` method for a full description of this property.

      Parameters:
        `value` - the default maximum error count allowed when parsing attributes.

    - #### generateHTML

          public static java.lang.String generateHTML(java.util.Map<java.lang.String,java.lang.String> attributesMap)

      Returns the contents of the specified attributes map as HTML attribute name/value pairs.

      Each attribute (including the first) is preceded by a single space, and all values are encoded and enclosed in double quotes.

      The map keys must be of type `String` and values must be objects that implement the `CharSequence` interface.

      A `null` value represents an attribute with no value.

      Parameters:
        `attributesMap` - a map containing attribute name/value pairs.
      Returns:
        the contents of the specified attributes map as HTML attribute name/value pairs.
      See Also:
        `StartTag.generateHTML(String tagName, Map attributesMap, boolean emptyElementTag)`