JDOM
2.0.5

org.jdom2
Class Attribute

java.lang.Object
  extended by org.jdom2.Attribute
All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable, NamespaceAware

public class Attribute
extends java.lang.Object
implements NamespaceAware, java.io.Serializable, java.lang.Cloneable

An XML attribute. Methods allow the user to obtain the value of the attribute as well as namespace and type information.

JDOM 1.x Compatibility Note:
The Attribute class in JDOM 1.x had a number of int Constants declared to represent different Attribute Types. JDOM2 has introduced an AttributeType enumeration instead. To facilitate compatibility and to simplify JDOM 1.x migrations, the replacement AttributeType enums are referenced still using the JDOM 1.x constant names. In JDOM 1.x these names referenced constant int values. In JDOM2 these names reference Enum constants.

Author:
Brett McLaughlin, Jason Hunter, Elliotte Rusty Harold, Wesley Biggs, Victor Toni, Rolf Lear
See Also:
Serialized Form

Field Summary
static AttributeType CDATA_TYPE
          JDOM 1.x compatible reference to AttributeType.CDATA
static AttributeType ENTITIES_TYPE
          JDOM 1.x compatible reference to AttributeType.ENTITIES
static AttributeType ENTITY_TYPE
          JDOM 1.x compatible reference to AttributeType.ENTITY
static AttributeType ENUMERATED_TYPE
          JDOM 1.x compatible reference to AttributeType.ENUMERATION
static AttributeType ID_TYPE
          JDOM 1.x compatible reference to AttributeType.ID
static AttributeType IDREF_TYPE
          JDOM 1.x compatible reference to AttributeType.IDREF
static AttributeType IDREFS_TYPE
          JDOM 1.x compatible reference to AttributeType.IDREFS
protected  java.lang.String name
          The local name of the Attribute
protected  Namespace namespace
          The Namespace of the Attribute
static AttributeType NMTOKEN_TYPE
          JDOM 1.x compatible reference to AttributeType.NMTOKEN
static AttributeType NMTOKENS_TYPE
          JDOM 1.x compatible reference to AttributeType.NMTOKENS
static AttributeType NOTATION_TYPE
          JDOM 1.x compatible reference to AttributeType.NOTATION
protected  Element parent
          The parent to which this Attribute belongs.
protected  boolean specified
          Specified attributes are part of the XML, unspecified attributes are 'defaulted' from a DTD.
protected  AttributeType type
          The type of the Attribute
static AttributeType UNDECLARED_TYPE
          JDOM 1.x compatible reference to AttributeType.UNDECLARED
protected  java.lang.String value
          The value of the Attribute
 
Constructor Summary
protected Attribute()
          Default, no-args constructor for implementations to use if needed.
  Attribute(java.lang.String name, java.lang.String value)
          This will create a new Attribute with the specified (local) name and value, and does not place the attribute in a Namespace.
  Attribute(java.lang.String name, java.lang.String value, AttributeType type)
          This will create a new Attribute with the specified (local) name, value and type, and does not place the attribute in a Namespace.
  Attribute(java.lang.String name, java.lang.String value, AttributeType type, Namespace namespace)
          This will create a new Attribute with the specified (local) name, value, and type, and in the provided Namespace.
  Attribute(java.lang.String name, java.lang.String value, int type)
          Deprecated. Use Attribute(String, String, AttributeType)
  Attribute(java.lang.String name, java.lang.String value, int type, Namespace namespace)
          Deprecated. Use Attribute(String, String, AttributeType, Namespace).
  Attribute(java.lang.String name, java.lang.String value, Namespace namespace)
          This will create a new Attribute with the specified (local) name and value, and in the provided Namespace.
 
Method Summary
 Attribute clone()
          Return a deep clone of this instance.
 Attribute detach()
          Detach this Attribute from its parent.
 AttributeType getAttributeType()
          This will return the declared type of this Attribute.
 boolean getBooleanValue()
          This gets the effective boolean value of the attribute, or throws a DataConversionException if a conversion can't be performed.
 Document getDocument()
          Get this Attribute's Document.
 double getDoubleValue()
          This gets the value of the attribute, in double form, and if no conversion can occur, throws a DataConversionException
 float getFloatValue()
          This gets the value of the attribute, in float form, and if no conversion can occur, throws a DataConversionException
 int getIntValue()
          This gets the value of the attribute, in int form, and if no conversion can occur, throws a DataConversionException
 long getLongValue()
          This gets the value of the attribute, in long form, and if no conversion can occur, throws a DataConversionException
 java.lang.String getName()
          This will retrieve the local name of the Attribute.
 Namespace getNamespace()
          This will return this Attribute's Namespace.
 java.lang.String getNamespacePrefix()
          This will retrieve the namespace prefix of the Attribute.
 java.util.List<Namespace> getNamespacesInherited()
          Obtain a list of all namespaces that are in scope for this content, but were not introduced by this content.
 java.util.List<Namespace> getNamespacesInScope()
          Get the namespaces that are in-scope on this Attribute.
 java.util.List<Namespace> getNamespacesIntroduced()
          Obtain a list of all namespaces that are introduced to the XML tree by this node.
 java.lang.String getNamespaceURI()
          This returns the URI mapped to this Attribute's prefix.
 Element getParent()
          This will return the parent of this Attribute.
 java.lang.String getQualifiedName()
          This will retrieve the qualified name of the Attribute.
 java.lang.String getValue()
          This will return the actual textual value of this Attribute.
 boolean isSpecified()
          Get the 'specified' flag.
 Attribute setAttributeType(AttributeType type)
          This will set the type of the Attribute.
 Attribute setAttributeType(int type)
          Deprecated. use setAttributeType(AttributeType)
 Attribute setName(java.lang.String name)
          This sets the local name of the Attribute.
 Attribute setNamespace(Namespace namespace)
          This sets this Attribute's Namespace.
protected  Attribute setParent(Element parent)
          Set this Attribute's parent.
 void setSpecified(boolean specified)
          Change the specified flag to the given value.
 Attribute setValue(java.lang.String value)
          This will set the value of the Attribute.
 java.lang.String toString()
          This returns a String representation of the Attribute, suitable for debugging.
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

UNDECLARED_TYPE

public static final AttributeType UNDECLARED_TYPE
JDOM 1.x compatible reference to AttributeType.UNDECLARED


CDATA_TYPE

public static final AttributeType CDATA_TYPE
JDOM 1.x compatible reference to AttributeType.CDATA


ID_TYPE

public static final AttributeType ID_TYPE
JDOM 1.x compatible reference to AttributeType.ID


IDREF_TYPE

public static final AttributeType IDREF_TYPE
JDOM 1.x compatible reference to AttributeType.IDREF


IDREFS_TYPE

public static final AttributeType IDREFS_TYPE
JDOM 1.x compatible reference to AttributeType.IDREFS


ENTITY_TYPE

public static final AttributeType ENTITY_TYPE
JDOM 1.x compatible reference to AttributeType.ENTITY


ENTITIES_TYPE

public static final AttributeType ENTITIES_TYPE
JDOM 1.x compatible reference to AttributeType.ENTITIES


NMTOKEN_TYPE

public static final AttributeType NMTOKEN_TYPE
JDOM 1.x compatible reference to AttributeType.NMTOKEN


NMTOKENS_TYPE

public static final AttributeType NMTOKENS_TYPE
JDOM 1.x compatible reference to AttributeType.NMTOKENS


NOTATION_TYPE

public static final AttributeType NOTATION_TYPE
JDOM 1.x compatible reference to AttributeType.NOTATION


ENUMERATED_TYPE

public static final AttributeType ENUMERATED_TYPE
JDOM 1.x compatible reference to AttributeType.ENUMERATION


name

protected java.lang.String name
The local name of the Attribute


namespace

protected Namespace namespace
The Namespace of the Attribute


value

protected java.lang.String value
The value of the Attribute


type

protected AttributeType type
The type of the Attribute


specified

protected boolean specified
Specified attributes are part of the XML, unspecified attributes are 'defaulted' from a DTD.


parent

protected transient Element parent
The parent to which this Attribute belongs. Change it with setParent(Element)

Constructor Detail

Attribute

protected Attribute()
Default, no-args constructor for implementations to use if needed.


Attribute

public Attribute(java.lang.String name,
                 java.lang.String value,
                 Namespace namespace)
This will create a new Attribute with the specified (local) name and value, and in the provided Namespace.

Parameters:
name - String name of Attribute.
value - String value for new attribute.
namespace - Namespace namespace for new attribute.
Throws:
IllegalNameException - if the given name is illegal as an attribute name or if if the new namespace is the default namespace. Attributes cannot be in a default namespace.
IllegalDataException - if the given attribute value is illegal character data (as determined by Verifier.checkCharacterData(java.lang.String)).

Attribute

@Deprecated
public Attribute(java.lang.String name,
                            java.lang.String value,
                            int type,
                            Namespace namespace)
Deprecated. Use Attribute(String, String, AttributeType, Namespace).

This will create a new Attribute with the specified (local) name, value, and type, and in the provided Namespace.

Parameters:
name - String name of Attribute.
value - String value for new attribute.
type - int type for new attribute.
namespace - Namespace namespace for new attribute.
Throws:
IllegalNameException - if the given name is illegal as an attribute name or if if the new namespace is the default namespace. Attributes cannot be in a default namespace.
IllegalDataException - if the given attribute value is illegal character data (as determined by Verifier.checkCharacterData(java.lang.String)) or if the given attribute type is not one of the supported types.

Attribute

public Attribute(java.lang.String name,
                 java.lang.String value,
                 AttributeType type,
                 Namespace namespace)
This will create a new Attribute with the specified (local) name, value, and type, and in the provided Namespace.

Parameters:
name - String name of Attribute.
value - String value for new attribute.
type - AttributeType for new attribute.
namespace - Namespace namespace for new attribute.
Throws:
IllegalNameException - if the given name is illegal as an attribute name or if if the new namespace is the default namespace. Attributes cannot be in a default namespace.
IllegalDataException - if the given attribute value is illegal character data (as determined by Verifier.checkCharacterData(java.lang.String)) or if the given attribute type is not one of the supported types.

Attribute

public Attribute(java.lang.String name,
                 java.lang.String value)
This will create a new Attribute with the specified (local) name and value, and does not place the attribute in a Namespace.

Note: This actually explicitly puts the Attribute in the "empty" Namespace (Namespace.NO_NAMESPACE).

Parameters:
name - String name of Attribute.
value - String value for new attribute.
Throws:
IllegalNameException - if the given name is illegal as an attribute name.
IllegalDataException - if the given attribute value is illegal character data (as determined by Verifier.checkCharacterData(java.lang.String)).

Attribute

public Attribute(java.lang.String name,
                 java.lang.String value,
                 AttributeType type)
This will create a new Attribute with the specified (local) name, value and type, and does not place the attribute in a Namespace.

Note: This actually explicitly puts the Attribute in the "empty" Namespace (Namespace.NO_NAMESPACE).

Parameters:
name - String name of Attribute.
value - String value for new attribute.
type - AttributeType for new attribute.
Throws:
IllegalNameException - if the given name is illegal as an attribute name.
IllegalDataException - if the given attribute value is illegal character data (as determined by Verifier.checkCharacterData(java.lang.String)) or if the given attribute type is not one of the supported types.

Attribute

@Deprecated
public Attribute(java.lang.String name,
                            java.lang.String value,
                            int type)
Deprecated. Use Attribute(String, String, AttributeType)

This will create a new Attribute with the specified (local) name, value and type, and does not place the attribute in a Namespace.

Note: This actually explicitly puts the Attribute in the "empty" Namespace (Namespace.NO_NAMESPACE).

Parameters:
name - String name of Attribute.
value - String value for new attribute.
type - int type for new attribute.
Throws:
IllegalNameException - if the given name is illegal as an attribute name.
IllegalDataException - if the given attribute value is illegal character data (as determined by Verifier.checkCharacterData(java.lang.String)) or if the given attribute type is not one of the supported types.
Method Detail

getParent

public Element getParent()
This will return the parent of this Attribute. If there is no parent, then this returns null. Use return-type covariance to override Content's getParent() method to return an Element, not just a Parent

Returns:
parent of this Attribute

getDocument

public Document getDocument()
Get this Attribute's Document.

Returns:
The document to which this Attribute is associated, may be null.

getName

public java.lang.String getName()
This will retrieve the local name of the Attribute. For any XML attribute which appears as [namespacePrefix]:[attributeName], the local name of the attribute would be [attributeName]. When the attribute has no namespace, the local name is simply the attribute name.

To obtain the namespace prefix for this attribute, the getNamespacePrefix() method should be used.

Returns:
String - name of this attribute, without any namespace prefix.

setName

public Attribute setName(java.lang.String name)
This sets the local name of the Attribute.

Parameters:
name - the new local name to set
Returns:
Attribute - the attribute modified.
Throws:
IllegalNameException - if the given name is illegal as an attribute name.

getQualifiedName

public java.lang.String getQualifiedName()
This will retrieve the qualified name of the Attribute. For any XML attribute whose name is [namespacePrefix]:[elementName], the qualified name of the attribute would be everything (both namespace prefix and element name). When the attribute has no namespace, the qualified name is simply the attribute's local name.

To obtain the local name of the attribute, the getName() method should be used.

To obtain the namespace prefix for this attribute, the getNamespacePrefix() method should be used.

Returns:
String - full name for this element.

getNamespacePrefix

public java.lang.String getNamespacePrefix()
This will retrieve the namespace prefix of the Attribute. For any XML attribute which appears as [namespacePrefix]:[attributeName], the namespace prefix of the attribute would be [namespacePrefix]. When the attribute has no namespace, an empty String is returned.

Returns:
String - namespace prefix of this attribute.

getNamespaceURI

public java.lang.String getNamespaceURI()
This returns the URI mapped to this Attribute's prefix. If no mapping is found, an empty String is returned.

Returns:
String - namespace URI for this Attribute.

getNamespace

public Namespace getNamespace()
This will return this Attribute's Namespace.

Returns:
Namespace - Namespace object for this Attribute

setNamespace

public Attribute setNamespace(Namespace namespace)
This sets this Attribute's Namespace. If the provided namespace is null, the attribute will have no namespace. The namespace must have a prefix.

Parameters:
namespace - the new namespace
Returns:
Element - the element modified.
Throws:
IllegalNameException - if the new namespace is the default namespace. Attributes cannot be in a default namespace.

getValue

public java.lang.String getValue()
This will return the actual textual value of this Attribute. This will include all text within the quotation marks.

Returns:
String - value for this attribute.

setValue

public Attribute setValue(java.lang.String value)
This will set the value of the Attribute.

Parameters:
value - String value for the attribute.
Returns:
Attribute - this Attribute modified.
Throws:
IllegalDataException - if the given attribute value is illegal character data (as determined by Verifier.checkCharacterData(java.lang.String)).

getAttributeType

public AttributeType getAttributeType()
This will return the declared type of this Attribute.

Returns:
AttributeType - type for this attribute.

setAttributeType

public Attribute setAttributeType(AttributeType type)
This will set the type of the Attribute.

Parameters:
type - int type for the attribute.
Returns:
Attribute - this Attribute modified.
Throws:
IllegalDataException - if the given attribute type is not one of the supported types.

setAttributeType

@Deprecated
public Attribute setAttributeType(int type)
Deprecated. use setAttributeType(AttributeType)

This will set the type of the Attribute.

Parameters:
type - int type for the attribute.
Returns:
Attribute - this Attribute modified.
Throws:
IllegalDataException - if the given attribute type is not one of the supported types.

isSpecified

public boolean isSpecified()
Get the 'specified' flag. True values indicate this attribute was part of an XML document, false indicates it was defaulted from a DTD.

Returns:
the specified flag.
Since:
JDOM2

setSpecified

public void setSpecified(boolean specified)
Change the specified flag to the given value.

Parameters:
specified - The value to set the specified flag to.
Since:
JDOM2

toString

public java.lang.String toString()
This returns a String representation of the Attribute, suitable for debugging.

Overrides:
toString in class java.lang.Object
Returns:
String - information about the Attribute

clone

public Attribute clone()
Return a deep clone of this instance. Even if this instance has a parent, the returned clone will not.

All JDOM core classes are Cloneable, and never throw CloneNotSupportedException. Additionally all Cloneable JDOM classes return the correct type of instance from this method and there is no need to cast the result (co-variant return vaue).

Subclasses of this should still call super.clone() in their clone method.


detach

public Attribute detach()
Detach this Attribute from its parent.

Returns:
this Attribute (detached).

setParent

protected Attribute setParent(Element parent)
Set this Attribute's parent. This is not public!

Parameters:
parent - The parent to set
Returns:
this Attribute (state may be indeterminate depending on whether this has been included in the Element's list yet).

getIntValue

public int getIntValue()
                throws DataConversionException
This gets the value of the attribute, in int form, and if no conversion can occur, throws a DataConversionException

Returns:
int value of attribute.
Throws:
DataConversionException - when conversion fails.

getLongValue

public long getLongValue()
                  throws DataConversionException
This gets the value of the attribute, in long form, and if no conversion can occur, throws a DataConversionException

Returns:
long value of attribute.
Throws:
DataConversionException - when conversion fails.

getFloatValue

public float getFloatValue()
                    throws DataConversionException
This gets the value of the attribute, in float form, and if no conversion can occur, throws a DataConversionException

Returns:
float value of attribute.
Throws:
DataConversionException - when conversion fails.

getDoubleValue

public double getDoubleValue()
                      throws DataConversionException
This gets the value of the attribute, in double form, and if no conversion can occur, throws a DataConversionException

Returns:
double value of attribute.
Throws:
DataConversionException - when conversion fails.

getBooleanValue

public boolean getBooleanValue()
                        throws DataConversionException
This gets the effective boolean value of the attribute, or throws a DataConversionException if a conversion can't be performed. True values are: "true", "on", "1", and "yes". False values are: "false", "off", "0", and "no". Values are trimmed before comparison. Values other than those listed here throw the exception.

Returns:
boolean value of attribute.
Throws:
DataConversionException - when conversion fails.

getNamespacesInScope

public java.util.List<Namespace> getNamespacesInScope()
Get the namespaces that are in-scope on this Attribute.

Attribute has peculiarities that affect the in-scope Namespaces because there are conditions in which the Attribute's scope is different to its parent Element's scope. Specifically, if the parent Element is in a 'default' Namespace that is not the empty Namespace (e.g. xmlns="someurl") and this Attribute is also in the default Namespace (has no prefix - but for Attributes that means the Namespace URL is ""), then this Attribute has a different namespace scope from it's parent Element because it does not include the 'someurl' Namespace.

In the above conditions (no-prefix Attribute in an Element with a non-empty no-prefix Namespace) this Attribute effectively re-binds the "" prefix to the "" URL, thus the Attribute 'introduces' the Namespace. It follows then that the getNamespacesIntroduced() will return a list with the single member Namespace.NO_NAMESPACE.

Note that the Attribute's Namespace will always be reported first.

Description copied from NamespaceAware.getNamespacesInScope():

Obtain a list of all namespaces that are in scope for the current content.

The contents of this list will always be the combination of getNamespacesIntroduced() and getNamespacesInherited().

See NamespaceAware documentation for details on what the order of the Namespaces will be in the returned list.

Specified by:
getNamespacesInScope in interface NamespaceAware
Returns:
a read-only list of Namespaces.

getNamespacesIntroduced

public java.util.List<Namespace> getNamespacesIntroduced()
Description copied from interface: NamespaceAware
Obtain a list of all namespaces that are introduced to the XML tree by this node. Only Elements and Attributes can introduce namespaces, so all other Content types will return an empty list.

The contents of this list will always be a subset (but in the same order) of getNamespacesInScope(), and will never intersect getNamspacesInherited()

Specified by:
getNamespacesIntroduced in interface NamespaceAware
Returns:
a read-only list of Namespaces.

getNamespacesInherited

public java.util.List<Namespace> getNamespacesInherited()
Description copied from interface: NamespaceAware
Obtain a list of all namespaces that are in scope for this content, but were not introduced by this content.

The contents of this list will always be a subset (but in the same order) of getNamespacesInScope(), and will never intersect getNamspacesIntroduced()

Specified by:
getNamespacesInherited in interface NamespaceAware
Returns:
a read-only list of Namespaces.

JDOM
2.0.5

Copyright 2013 Jason Hunter, Brett McLaughlin. All Rights Reserved.