Class Attributes

  • All Implemented Interfaces:
    java.lang.Cloneable, java.lang.Iterable<Attribute>

    public class Attributes
    extends java.lang.Object
    implements java.lang.Iterable<Attribute>, java.lang.Cloneable
    The attributes of an Element.

    During parsing, attributes in with the same name in an element are deduplicated, according to the configured parser's attribute case-sensitive setting. It is possible to have duplicate attributes subsequently if add(String, String) vs put(String, String) is used.

    Attribute name and value comparisons are generally case sensitive. By default for HTML, attribute names are normalized to lower-case on parsing. That means you should use lower-case strings when referring to attributes by name.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      private static class  Attributes.Dataset  
    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected static java.lang.String dataPrefix  
      private static java.lang.String EmptyString  
      private static int GrowthFactor  
      private static int InitialCapacity  
      (package private) static char InternalPrefix  
      (package private) java.lang.String[] keys  
      (package private) static int NotFound  
      private int size  
      (package private) java.lang.Object[] vals  
    • Constructor Summary

      Constructors 
      Constructor Description
      Attributes()  
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      Attributes add​(java.lang.String key, java.lang.String value)
      Adds a new attribute.
      void addAll​(Attributes incoming)
      Add all the attributes from the incoming set to this set.
      private void addObject​(java.lang.String key, java.lang.Object value)  
      java.util.List<Attribute> asList()
      Get the attributes as a List, for iteration.
      Attribute attribute​(java.lang.String key)
      Get an Attribute by key.
      private void checkCapacity​(int minNewSize)  
      (package private) static java.lang.String checkNotNull​(java.lang.Object val)  
      Attributes clone()  
      private static java.lang.String dataKey​(java.lang.String key)  
      java.util.Map<java.lang.String,​java.lang.String> dataset()
      Retrieves a filtered view of attributes that are HTML5 custom data attributes; that is, attributes with keys starting with data-.
      int deduplicate​(ParseSettings settings)
      Internal method.
      boolean equals​(java.lang.Object o)
      Checks if these attributes are equal to another set of attributes, by comparing the two sets.
      java.lang.String get​(java.lang.String key)
      Get an attribute value by key.
      java.lang.String getIgnoreCase​(java.lang.String key)
      Get an attribute's value by case-insensitive key
      (package private) java.util.Map<java.lang.String,​Range.AttributeRange> getRanges()
      Get the Ranges, if tracking is enabled; null otherwise.
      boolean hasDeclaredValueForKey​(java.lang.String key)
      Check if these attributes contain an attribute with a value for this key.
      boolean hasDeclaredValueForKeyIgnoreCase​(java.lang.String key)
      Check if these attributes contain an attribute with a value for this key.
      int hashCode()
      Calculates the hashcode of these attributes, by iterating all attributes and summing their hashcodes.
      boolean hasKey​(java.lang.String key)
      Tests if these attributes contain an attribute with this key.
      boolean hasKeyIgnoreCase​(java.lang.String key)
      Tests if these attributes contain an attribute with this key.
      java.lang.String html()
      Get the HTML representation of these attributes.
      (package private) void html​(java.lang.Appendable accum, Document.OutputSettings out)  
      (package private) int indexOfKey​(java.lang.String key)  
      private int indexOfKeyIgnoreCase​(java.lang.String key)  
      (package private) static java.lang.String internalKey​(java.lang.String key)  
      boolean isEmpty()
      Test if this Attributes list is empty (size==0).
      (package private) static boolean isInternalKey​(java.lang.String key)  
      java.util.Iterator<Attribute> iterator()  
      void normalize()
      Internal method.
      Attributes put​(java.lang.String key, boolean value)
      Set a new boolean attribute.
      Attributes put​(java.lang.String key, java.lang.String value)
      Set a new attribute, or replace an existing one by key.
      Attributes put​(Attribute attribute)
      Set a new attribute, or replace an existing one by key.
      (package private) void putIgnoreCase​(java.lang.String key, java.lang.String value)  
      private void remove​(int index)  
      void remove​(java.lang.String key)
      Remove an attribute by key.
      void removeIgnoreCase​(java.lang.String key)
      Remove an attribute by key.
      int size()
      Get the number of attributes in this set, including any jsoup internal-only attributes.
      Range.AttributeRange sourceRange​(java.lang.String key)
      Get the source ranges (start to end position) in the original input source from which this attribute's name and value were parsed.
      java.lang.String toString()  
      (package private) java.util.Map<java.lang.String,​java.lang.Object> userData()
      Get the map holding any user-data associated with these Attributes.
      java.lang.Object userData​(java.lang.String key)
      Get an arbitrary user-data object by key.
      Attributes userData​(java.lang.String key, java.lang.Object value)
      Set an arbitrary user-data object by key.
      • Methods inherited from class java.lang.Object

        finalize, getClass, notify, notifyAll, wait, wait, wait
      • Methods inherited from interface java.lang.Iterable

        forEach, spliterator
    • Constructor Detail

      • Attributes

        public Attributes()
    • Method Detail

      • checkCapacity

        private void checkCapacity​(int minNewSize)
      • indexOfKey

        int indexOfKey​(java.lang.String key)
      • indexOfKeyIgnoreCase

        private int indexOfKeyIgnoreCase​(java.lang.String key)
      • checkNotNull

        static java.lang.String checkNotNull​(java.lang.Object val)
      • get

        public java.lang.String get​(java.lang.String key)
        Get an attribute value by key.
        Parameters:
        key - the (case-sensitive) attribute key
        Returns:
        the attribute value if set; or empty string if not set (or a boolean attribute).
        See Also:
        hasKey(String)
      • attribute

        public Attribute attribute​(java.lang.String key)
        Get an Attribute by key. The Attribute will remain connected to these Attributes, so changes made via Attribute.setKey(String), Attribute.setValue(String) etc will cascade back to these Attributes and their owning Element.
        Parameters:
        key - the (case-sensitive) attribute key
        Returns:
        the Attribute for this key, or null if not present.
        Since:
        1.17.2
      • getIgnoreCase

        public java.lang.String getIgnoreCase​(java.lang.String key)
        Get an attribute's value by case-insensitive key
        Parameters:
        key - the attribute name
        Returns:
        the first matching attribute value if set; or empty string if not set (ora boolean attribute).
      • add

        public Attributes add​(java.lang.String key,
                              java.lang.String value)
        Adds a new attribute. Will produce duplicates if the key already exists.
        See Also:
        put(String, String)
      • addObject

        private void addObject​(java.lang.String key,
                               java.lang.Object value)
      • put

        public Attributes put​(java.lang.String key,
                              java.lang.String value)
        Set a new attribute, or replace an existing one by key.
        Parameters:
        key - case sensitive attribute key (not null)
        value - attribute value (which can be null, to set a true boolean attribute)
        Returns:
        these attributes, for chaining
      • userData

        java.util.Map<java.lang.String,​java.lang.Object> userData()
        Get the map holding any user-data associated with these Attributes. Will be created empty on first use. Held as an internal attribute, not a field member, to reduce the memory footprint of Attributes when not used. Can hold arbitrary objects; use for source ranges, connecting W3C nodes to Elements, etc.
        Returns:
        the map holding user-data
      • userData

        public java.lang.Object userData​(java.lang.String key)
        Get an arbitrary user-data object by key.
        Parameters:
        key - case-sensitive key to the object.
        Returns:
        the object associated to this key, or null if not found.
        Since:
        1.17.1
        See Also:
        userData(String key, Object val)
      • userData

        public Attributes userData​(java.lang.String key,
                                   java.lang.Object value)
        Set an arbitrary user-data object by key. Will be treated as an internal attribute, so will not be emitted in HTML.
        Parameters:
        key - case-sensitive key
        value - object value
        Returns:
        these attributes
        Since:
        1.17.1
        See Also:
        userData(String key)
      • putIgnoreCase

        void putIgnoreCase​(java.lang.String key,
                           java.lang.String value)
      • put

        public Attributes put​(java.lang.String key,
                              boolean value)
        Set a new boolean attribute. Removes the attribute if the value is false.
        Parameters:
        key - case insensitive attribute key
        value - attribute value
        Returns:
        these attributes, for chaining
      • put

        public Attributes put​(Attribute attribute)
        Set a new attribute, or replace an existing one by key.
        Parameters:
        attribute - attribute with case-sensitive key
        Returns:
        these attributes, for chaining
      • remove

        private void remove​(int index)
      • remove

        public void remove​(java.lang.String key)
        Remove an attribute by key. Case sensitive.
        Parameters:
        key - attribute key to remove
      • removeIgnoreCase

        public void removeIgnoreCase​(java.lang.String key)
        Remove an attribute by key. Case insensitive.
        Parameters:
        key - attribute key to remove
      • hasKey

        public boolean hasKey​(java.lang.String key)
        Tests if these attributes contain an attribute with this key.
        Parameters:
        key - case-sensitive key to check for
        Returns:
        true if key exists, false otherwise
      • hasKeyIgnoreCase

        public boolean hasKeyIgnoreCase​(java.lang.String key)
        Tests if these attributes contain an attribute with this key.
        Parameters:
        key - key to check for
        Returns:
        true if key exists, false otherwise
      • hasDeclaredValueForKey

        public boolean hasDeclaredValueForKey​(java.lang.String key)
        Check if these attributes contain an attribute with a value for this key.
        Parameters:
        key - key to check for
        Returns:
        true if key exists, and it has a value
      • hasDeclaredValueForKeyIgnoreCase

        public boolean hasDeclaredValueForKeyIgnoreCase​(java.lang.String key)
        Check if these attributes contain an attribute with a value for this key.
        Parameters:
        key - case-insensitive key to check for
        Returns:
        true if key exists, and it has a value
      • size

        public int size()
        Get the number of attributes in this set, including any jsoup internal-only attributes. Internal attributes are excluded from the html(), asList(), and iterator() methods.
        Returns:
        size
      • isEmpty

        public boolean isEmpty()
        Test if this Attributes list is empty (size==0).
      • addAll

        public void addAll​(Attributes incoming)
        Add all the attributes from the incoming set to this set.
        Parameters:
        incoming - attributes to add to these attributes.
      • getRanges

        java.util.Map<java.lang.String,​Range.AttributeRange> getRanges()
        Get the Ranges, if tracking is enabled; null otherwise.
      • iterator

        public java.util.Iterator<Attribute> iterator()
        Specified by:
        iterator in interface java.lang.Iterable<Attribute>
      • asList

        public java.util.List<Attribute> asList()
        Get the attributes as a List, for iteration.
        Returns:
        a view of the attributes as an unmodifiable List.
      • dataset

        public java.util.Map<java.lang.String,​java.lang.String> dataset()
        Retrieves a filtered view of attributes that are HTML5 custom data attributes; that is, attributes with keys starting with data-.
        Returns:
        map of custom data attributes.
      • html

        public java.lang.String html()
        Get the HTML representation of these attributes.
        Returns:
        HTML
      • html

        final void html​(java.lang.Appendable accum,
                        Document.OutputSettings out)
                 throws java.io.IOException
        Throws:
        java.io.IOException
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
      • equals

        public boolean equals​(java.lang.Object o)
        Checks if these attributes are equal to another set of attributes, by comparing the two sets. Note that the order of the attributes does not impact this equality (as per the Map interface equals()).
        Overrides:
        equals in class java.lang.Object
        Parameters:
        o - attributes to compare with
        Returns:
        if both sets of attributes have the same content
      • hashCode

        public int hashCode()
        Calculates the hashcode of these attributes, by iterating all attributes and summing their hashcodes.
        Overrides:
        hashCode in class java.lang.Object
        Returns:
        calculated hashcode
      • clone

        public Attributes clone()
        Overrides:
        clone in class java.lang.Object
      • normalize

        public void normalize()
        Internal method. Lowercases all (non-internal) keys.
      • deduplicate

        public int deduplicate​(ParseSettings settings)
        Internal method. Removes duplicate attribute by name. Settings for case sensitivity of key names.
        Parameters:
        settings - case sensitivity
        Returns:
        number of removed dupes
      • dataKey

        private static java.lang.String dataKey​(java.lang.String key)
      • internalKey

        static java.lang.String internalKey​(java.lang.String key)
      • isInternalKey

        static boolean isInternalKey​(java.lang.String key)