Class Attribute

java.lang.Object
eu.maveniverse.domtrip.Attribute
public class Attribute extends Object
Represents an XML attribute with complete formatting preservation including quote styles, whitespace, and entity encoding.

The Attribute class encapsulates all information needed to preserve the exact formatting of XML attributes during round-trip processing. It maintains both the decoded attribute value and the original raw value with entities preserved, along with formatting details like quote style and whitespace.

Attribute Properties:

  • Quote Style Preservation - Maintains single vs double quotes
  • Whitespace Preservation - Preserves spacing before attributes
  • Entity Preservation - Maintains original entity encoding
  • Fluent Mutation - Mutable setters with method chaining, plus immutable-style withX() methods
  • Fluent API - Creation and modification with method chaining

Usage Examples:

// Create basic attribute
Attribute attr = new Attribute("class", "important");

// Create using factory methods
Attribute simple = Attribute.of("class", "important");
Attribute withQuotes = Attribute.of("id", "main", QuoteStyle.SINGLE);
Attribute complete = Attribute.of("data-value", "test & example", QuoteStyle.DOUBLE, "  ");

// Create and modify with fluent API
Attribute fluent = Attribute.of("class", "initial")
    .value("updated")
    .quoteStyle(QuoteStyle.SINGLE)
    .precedingWhitespace("  ");

// Create immutable variations
Attribute modified = attr.withValue("critical").withQuoteStyle(QuoteStyle.SINGLE);

Attribute Formatting:

Attributes are serialized with the following format:

[whitespace][name]=[quote][value][quote]

Example: class="important" or id='main'

Entity Handling:

The class automatically handles XML entity escaping for attribute values:

  • & → &
  • < → &lt;
  • > → &gt;
  • " → &quot; (when using double quotes)
  • ' → &apos; (when using single quotes)
See Also:

  • Constructor Details

  • Method Details

    • name

      public String name()

    • value

      public String value()

    • value

      public Attribute value(String value)

    • rawValue

      public String rawValue()

    • rawValue

      public Attribute rawValue(String rawValue)

    • quoteStyle

      public QuoteStyle quoteStyle()

    • quoteStyle

      public Attribute quoteStyle(QuoteStyle quoteStyle)

    • precedingWhitespace

      public String precedingWhitespace()

    • precedingWhitespace

      public Attribute precedingWhitespace(String precedingWhitespace)

    • getSerializationValue

      public String getSerializationValue(boolean useRaw)
      Provides the attribute value to use during XML serialization, preferring the original raw text when requested.
      Parameters:
      useRaw - if true, return the preserved raw attribute text when present; otherwise produce an escaped form
      Returns:
      `rawValue` if `useRaw` is true and a raw value exists, otherwise the escaped form of `value` using the active quote character

    • toXml

      public void toXml(StringBuilder sb, boolean useRaw)
      Serializes this attribute to XML

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • withValue

      public Attribute withValue(String newValue)
      Creates a new attribute with the specified value, preserving other properties.

    • withQuoteStyle

      public Attribute withQuoteStyle(QuoteStyle newQuoteStyle)
      Creates a new attribute with the specified quote style, preserving other properties.

    • withPrecedingWhitespace

      public Attribute withPrecedingWhitespace(String newWhitespace)
      Creates a new attribute with the specified preceding whitespace, preserving other properties.

    • copy

      public Attribute copy()
      Creates a deep copy of this attribute.
      Returns:
      a new attribute that is a copy of this attribute
      Since:
      1.1.0

    • clone

      @Deprecated public Attribute clone()
      Deprecated.
      Use copy() instead.
      Creates a deep copy of this attribute.
      Overrides:
      clone in class Object
      Returns:
      a new attribute that is a copy of this attribute

    • of

      public static Attribute of(String name, String value)
      Creates an attribute with the specified name and value.

      Factory method following modern Java naming conventions.

      Parameters:
      name - the attribute name
      value - the attribute value
      Returns:
      a new Attribute

    • of

      public static Attribute of(String name, String value, QuoteStyle quoteStyle)
      Creates an attribute with the specified name, value, and quote style.

      Factory method for creating attributes with specific formatting.

      Parameters:
      name - the attribute name
      value - the attribute value
      quoteStyle - the quote style to use
      Returns:
      a new Attribute

    • of

      public static Attribute of(QName qname, String value) throws DomTripException
      Creates an attribute from a QName and value.

      Creates an attribute using the QName's qualified name as the attribute name. This is useful for creating namespaced attributes.

      Parameters:
      qname - the QName for the attribute
      value - the attribute value
      Returns:
      a new Attribute
      Throws:
      DomTripException - if qname is null

    • of

      public static Attribute of(String name, String value, QuoteStyle quoteStyle, String precedingWhitespace)
      Creates an attribute with all formatting options.

      Factory method for creating attributes with complete control over formatting.

      Parameters:
      name - the attribute name
      value - the attribute value
      quoteStyle - the quote style to use
      precedingWhitespace - the whitespace before the attribute
      Returns:
      a new Attribute