Package eu.maveniverse.domtrip

Class Attribute

java.lang.Object

eu.maveniverse.domtrip.Attribute

public class Attribute
extends java.lang.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:

• & → &
• < → <
• > → >
• " → " (when using double quotes)
• ' → ' (when using single quotes)

See Also:

Element, QuoteStyle

Constructor Summary

Constructors

Constructor	Description
Attribute(java.lang.String name, java.lang.String value)
Attribute(java.lang.String name, java.lang.String value, char quoteChar, java.lang.String precedingWhitespace)
Attribute(java.lang.String name, java.lang.String value, char quoteChar, java.lang.String precedingWhitespace, java.lang.String rawValue)
Attribute(java.lang.String name, java.lang.String value, QuoteStyle quoteStyle, java.lang.String precedingWhitespace)
Attribute(java.lang.String name, java.lang.String value, QuoteStyle quoteStyle, java.lang.String precedingWhitespace, java.lang.String rawValue)

Method Summary

Modifier and Type	Method	Description
Attribute	clone()	Deprecated. Use copy() instead.
Attribute	copy()	Creates a deep copy of this attribute.
boolean	equals(java.lang.Object obj)
java.lang.String	getSerializationValue(boolean useRaw)	Provides the attribute value to use during XML serialization, preferring the original raw text when requested.
int	hashCode()
java.lang.String	name()
static Attribute	of(QName qname, java.lang.String value)	Creates an attribute from a QName and value.
static Attribute	of(java.lang.String name, java.lang.String value)	Creates an attribute with the specified name and value.
static Attribute	of(java.lang.String name, java.lang.String value, QuoteStyle quoteStyle)	Creates an attribute with the specified name, value, and quote style.
static Attribute	of(java.lang.String name, java.lang.String value, QuoteStyle quoteStyle, java.lang.String precedingWhitespace)	Creates an attribute with all formatting options.
java.lang.String	precedingWhitespace()
Attribute	precedingWhitespace(java.lang.String precedingWhitespace)
QuoteStyle	quoteStyle()
Attribute	quoteStyle(QuoteStyle quoteStyle)
java.lang.String	rawValue()
Attribute	rawValue(java.lang.String rawValue)
java.lang.String	toString()
void	toXml(java.lang.StringBuilder sb, boolean useRaw)	Serializes this attribute to XML
java.lang.String	value()
Attribute	value(java.lang.String value)
Attribute	withPrecedingWhitespace(java.lang.String newWhitespace)	Creates a new attribute with the specified preceding whitespace, preserving other properties.
Attribute	withQuoteStyle(QuoteStyle newQuoteStyle)	Creates a new attribute with the specified quote style, preserving other properties.
Attribute	withValue(java.lang.String newValue)	Creates a new attribute with the specified value, preserving other properties.

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Attribute

public Attribute(java.lang.String name,
                 java.lang.String value)

Attribute

public Attribute(java.lang.String name,
                 java.lang.String value,
                 QuoteStyle quoteStyle,
                 java.lang.String precedingWhitespace)

Attribute

public Attribute(java.lang.String name,
                 java.lang.String value,
                 QuoteStyle quoteStyle,
                 java.lang.String precedingWhitespace,
                 java.lang.String rawValue)

Attribute

public Attribute(java.lang.String name,
                 java.lang.String value,
                 char quoteChar,
                 java.lang.String precedingWhitespace)
          throws DomTripException

Throws:

DomTripException

Attribute

public Attribute(java.lang.String name,
                 java.lang.String value,
                 char quoteChar,
                 java.lang.String precedingWhitespace,
                 java.lang.String rawValue)
          throws DomTripException

Throws:

DomTripException

Method Detail

name

public java.lang.String name()

value

public java.lang.String value()

value

public Attribute value(java.lang.String value)

rawValue

public java.lang.String rawValue()

rawValue

public Attribute rawValue(java.lang.String rawValue)

quoteStyle

public QuoteStyle quoteStyle()

quoteStyle

public Attribute quoteStyle(QuoteStyle quoteStyle)

precedingWhitespace

public java.lang.String precedingWhitespace()

precedingWhitespace

public Attribute precedingWhitespace(java.lang.String precedingWhitespace)

getSerializationValue

public java.lang.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(java.lang.StringBuilder sb,
                  boolean useRaw)

Serializes this attribute to XML

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

equals

public boolean equals(java.lang.Object obj)

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

withValue

public Attribute withValue(java.lang.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(java.lang.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 java.lang.Object

Returns:

a new attribute that is a copy of this attribute

of

public static Attribute of(java.lang.String name,
                           java.lang.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(java.lang.String name,
                           java.lang.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,
                           java.lang.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(java.lang.String name,
                           java.lang.String value,
                           QuoteStyle quoteStyle,
                           java.lang.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