nu.xom

## Class Attribute

- Object
- - nu.xom.Node
  - - nu.xom.Attribute

-     public class Attribute
      extends Node

  This class represents an attribute such as `type="empty"` or `xlink:href="http://www.example.com"`.

  Attributes that declare namespaces such as `xmlns="http://www.w3.org/TR/1999/xhtml"` or `xmlns:xlink="http://www.w3.org/TR/1999/xlink"` are stored separately on the elements where they appear. They are never represented as `Attribute` objects.

  Version:
    1.3.0
  Author:
    Elliotte Rusty Harold

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `Attribute.Type` Uses the type-safe enumeration design pattern to represent attribute types, as specified by XML DTDs.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Attribute(Attribute attribute)` Creates a copy of the specified attribute.
    `Attribute(String localName, String value)` Creates a new attribute in no namespace with the specified name and value and undeclared type.
    `Attribute(String localName, String value, Attribute.Type type)` Creates a new attribute in no namespace with the specified name, value, and type.
    `Attribute(String name, String URI, String value)` Creates a new attribute in the specified namespace with the specified name and value and undeclared type.
    `Attribute(String name, String URI, String value, Attribute.Type type)` Creates a new attribute in the specified namespace with the specified name, value, and type.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `Attribute` | `copy()` Creates a deep copy of this attribute that is not attached to an element.
    `Node` | `getChild(int position)` Throws `IndexOutOfBoundsException` because attributes do not have children.
    `int` | `getChildCount()` Returns 0 because attributes do not have children.
    `String` | `getLocalName()` Returns the local name of this attribute, not including the prefix.
    `String` | `getNamespacePrefix()` Returns the prefix of this attribute, or the empty string if this attribute is not in a namespace.
    `String` | `getNamespaceURI()` Returns the namespace URI of this attribute, or the empty string if this attribute is not in a namespace.
    `String` | `getQualifiedName()` Returns the qualified name of this attribute, including the prefix if this attribute is in a namespace.
    `Attribute.Type` | `getType()` Returns the DTD type of this attribute.
    `String` | `getValue()` Returns the attribute value.
    `void` | `setLocalName(String localName)` Sets the local name of the attribute.
    `void` | `setNamespace(String prefix, String URI)` Sets the attribute's namespace prefix and URI.
    `void` | `setType(Attribute.Type type)` Sets the type of this attribute to one of the ten DTD types or `Type.UNDECLARED`.
    `void` | `setValue(String value)` Sets the attribute's value to the specified string, replacing any previous value.
    `String` | `toString()` Returns a string representation of the attribute suitable for debugging and diagnosis.
    `String` | `toXML()` Returns a string representation of the attribute that is a well-formed XML attribute.

    - ### Methods inherited from class nu.xom.Node

      `detach, equals, getBaseURI, getDocument, getParent, hashCode, query, query`

    - ### Methods inherited from class Object

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

- - ### Constructor Detail

    - #### Attribute

          public Attribute(String localName,
                           String value)

      Creates a new attribute in no namespace with the specified name and value and undeclared type.

      Parameters:
        `localName` - the unprefixed attribute name
        `value` - the attribute value
      Throws:
        `IllegalNameException` - if the local name is not a namespace well-formed, non-colonized name
        `IllegalDataException` - if the value contains characters which are not legal in XML such as vertical tab or a null. Characters such as " and & are legal, but will be automatically escaped when the attribute is serialized.

    - #### Attribute

          public Attribute(String localName,
                           String value,
                           Attribute.Type type)

      Creates a new attribute in no namespace with the specified name, value, and type.

      Parameters:
        `localName` - the unprefixed attribute name
        `value` - the attribute value
        `type` - the attribute type
      Throws:
        `IllegalNameException` - if the local name is not a namespace well-formed non-colonized name
        `IllegalDataException` - if the value contains characters which are not legal in XML such as vertical tab or a null. Note that characters such as " and & are legal, but will be automatically escaped when the attribute is serialized.

    - #### Attribute

          public Attribute(String name,
                           String URI,
                           String value)

      Creates a new attribute in the specified namespace with the specified name and value and undeclared type.

      Parameters:
        `name` - the prefixed attribute name
        `URI` - the namespace URI
        `value` - the attribute value
      Throws:
        `IllegalNameException` - if the name is not a namespace well-formed name
        `IllegalDataException` - if the value contains characters which are not legal in XML such as vertical tab or a null. Note that characters such as " and & are legal, but will be automatically escaped when the attribute is serialized.
        `MalformedURIException` - if `URI` is not an RFC 3986 URI reference
        `NamespaceConflictException` - if there's no prefix, but the URI is not the empty string, or the prefix is `xml` and the URI is not http://www.w3.org/XML/1998/namespace

    - #### Attribute

          public Attribute(String name,
                           String URI,
                           String value,
                           Attribute.Type type)

      Creates a new attribute in the specified namespace with the specified name, value, and type.

      Parameters:
        `name` - the prefixed attribute name
        `URI` - the namespace URI
        `value` - the attribute value
        `type` - the attribute type
      Throws:
        `IllegalNameException` - if the name is not a namespace well-formed prefixed name
        `IllegalDataException` - if the value contains characters which are not legal in XML such as vertical tab or a null. Note that characters such as " and & are legal, but will be automatically escaped when the attribute is serialized.
        `MalformedURIException` - if `URI` is not an RFC 3986 absolute URI reference

    - #### Attribute

          public Attribute(Attribute attribute)

      Creates a copy of the specified attribute.

      Parameters:
        `attribute` - the attribute to copy

  - ### Method Detail

    - #### getType

          public final Attribute.Type getType()

      Returns the DTD type of this attribute. If this attribute does not have a type, then `Type.UNDECLARED` is returned.

      Returns:
        the DTD type of this attribute

    - #### setType

          public void setType(Attribute.Type type)

      Sets the type of this attribute to one of the ten DTD types or `Type.UNDECLARED`.

      Parameters:
        `type` - the DTD type of this attribute
      Throws:
        `NullPointerException` - if `type` is null
        `IllegalDataException` - if this is an `xml:id` attribute and the `type` is not ID

    - #### getValue

          public final String getValue()

      Returns the attribute value. If the attribute was originally created by a parser, it will have been normalized according to its type. However, attributes created in memory are not normalized.

      Specified by:
        `getValue` in class `Node`
      Returns:
        the value of the attribute

    - #### setValue

          public void setValue(String value)

      Sets the attribute's value to the specified string, replacing any previous value. The value is not normalized automatically.

      Parameters:
        `value` - the value assigned to the attribute
      Throws:
        `IllegalDataException` - if the value contains characters which are not legal in XML such as vertical tab or a null. Characters such as " and & are legal, but will be automatically escaped when the attribute is serialized.

    - #### getLocalName

          public final String getLocalName()

      Returns the local name of this attribute, not including the prefix.

      Returns:
        the attribute's local name

    - #### setLocalName

          public void setLocalName(String localName)

      Sets the local name of the attribute.

      Parameters:
        `localName` - the new local name
      Throws:
        `IllegalNameException` - if `localName` is not a namespace well-formed, non-colonized name

    - #### getQualifiedName

          public final String getQualifiedName()

      Returns the qualified name of this attribute, including the prefix if this attribute is in a namespace.

      Returns:
        the attribute's qualified name

    - #### getNamespaceURI

          public final String getNamespaceURI()

      Returns the namespace URI of this attribute, or the empty string if this attribute is not in a namespace.

      Returns:
        the attribute's namespace URI

    - #### getNamespacePrefix

          public final String getNamespacePrefix()

      Returns the prefix of this attribute, or the empty string if this attribute is not in a namespace.

      Returns:
        the attribute's prefix

    - #### setNamespace

          public void setNamespace(String prefix,
                                   String URI)

      Sets the attribute's namespace prefix and URI. Because attributes must be prefixed in order to have a namespace URI (and vice versa) this must be done simultaneously.

      Parameters:
        `prefix` - the new namespace prefix
        `URI` - the new namespace URI
      Throws:
        `MalformedURIException` - if `URI` is not an RFC 3986 URI reference
        `IllegalNameException` - if
        - The prefix is `xmlns`.
        - The prefix is null or the empty string.
        - The URI is null or the empty string.
        `NamespaceConflictException` - if
        - The prefix is `xml` and the namespace URI is not `http://www.w3.org/XML/1998/namespace`.
        - The prefix conflicts with an existing declaration on the attribute's parent element.

    - #### getChild

          public final Node getChild(int position)

      Throws `IndexOutOfBoundsException` because attributes do not have children.

      Specified by:
        `getChild` in class `Node`
      Parameters:
        `position` - the child to return
      Returns:
        nothing. This method always throws an exception.
      Throws:
        `IndexOutOfBoundsException` - because attributes do not have children

    - #### getChildCount

          public final int getChildCount()

      Returns 0 because attributes do not have children.

      Specified by:
        `getChildCount` in class `Node`
      Returns:
        zero

    - #### copy

          public Attribute copy()

      Creates a deep copy of this attribute that is not attached to an element.

      Specified by:
        `copy` in class `Node`
      Returns:
        a copy of this attribute

    - #### toXML

          public final String toXML()

      Returns a string representation of the attribute that is a well-formed XML attribute.

      Specified by:
        `toXML` in class `Node`
      Returns:
        a string containing the XML form of this attribute

    - #### toString

          public final String toString()

      Returns a string representation of the attribute suitable for debugging and diagnosis. However, this is not necessarily a well-formed XML attribute.

      Overrides:
        `toString` in class `Object`
      Returns:
        a non-XML string representation of this attribute
      See Also:
        `Object.toString()`

Copyright 2002-2020 Elliotte Rusty Harold
elharo@ibiblio.org