org.cdmckay.coffeedom
Class Attribute

java.lang.Object
  org.cdmckay.coffeedom.Attribute

All Implemented Interfaces:

Serializable, Cloneable

public class Attribute
extends Object
implements Serializable, Cloneable

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

Author:

Brett McLaughlin, Jason Hunter, Elliotte Rusty Harold, Wesley Biggs, Victor Toni, Cameron McKay

See Also:

Serialized Form

Nested Class Summary

static class

Attribute.Type

Field Summary

protected String	name The local name of the Attribute
protected Namespace	namespace The Namespace of the Attribute
protected Element	parent Parent element, or null if none
protected Attribute.Type	type The type of the Attribute
protected String	value The value of the Attribute

Constructor Summary

protected	Attribute() Default, no-args constructor for implementations to use if needed.
	Attribute(String name, 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(String name, String value, Attribute.Type 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(String name, String value, Attribute.Type type, Namespace namespace) This will create a new Attribute with the specified (local) name, value, and type, and in the provided Namespace.
	Attribute(String name, 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() This will return a clone of this Attribute.
Attribute	detach() This detaches the Attribute from its parent, or does nothing if the Attribute has no parent.
boolean	equals(Object ob) This tests for equality of this Attribute to the supplied Object.
Attribute.Type	getAttributeType() This will return the actual 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() This retrieves the owning Document for this Attribute, or null if not a currently a member of a 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
String	getName() This will retrieve the local name of the Attribute.
Namespace	getNamespace() This will return this Attribute's Namespace.
String	getNamespacePrefix() This will retrieve the namespace prefix of the Attribute.
String	getNamespaceURI() This returns the URI mapped to this Attribute's prefix.
Element	getParent() This will return the parent of this Attribute.
String	getQualifiedName() This will retrieve the qualified name of the Attribute.
String	getValue() This will return the actual textual value of this Attribute.
int	hashCode() This returns the hash code for this Attribute.
Attribute	setAttributeType(Attribute.Type type) This will set the type of the Attribute.
Attribute	setName(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) This will set the parent of this Attribute.
Attribute	setValue(String value) This will set the value of the Attribute.
String	toString() This returns a String representation of the Attribute, suitable for debugging.

Methods inherited from class java.lang.Object

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

Field Detail

name

protected String name

The local name of the Attribute

namespace

protected transient Namespace namespace

The Namespace of the Attribute

value

protected String value

The value of the Attribute

type

protected Attribute.Type type

The type of the Attribute

parent

protected Element parent

Parent element, or null if none

Constructor Detail

Attribute

protected Attribute()

Default, no-args constructor for implementations to use if needed.

Attribute

public Attribute(String name,
                 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(String)).

Attribute

public Attribute(String name,
                 String value,
                 Attribute.Type 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 - 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(String)) or if the given attribute type is not one of the supported types.

Attribute

public Attribute(String name,
                 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(String)).

Attribute

public Attribute(String name,
                 String value,
                 Attribute.Type 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 - name of Attribute.

value - value for new attribute.

type - 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(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.

Returns:

parent of this Attribute

getDocument

public Document getDocument()

This retrieves the owning Document for this Attribute, or null if not a currently a member of a Document.

Returns:

Document owning this Attribute, or null.

setParent

protected Attribute setParent(Element parent)

This will set the parent of this Attribute.

Parameters:

parent - Element to be new parent.

Returns:

this Attribute modified.

detach

public Attribute detach()

This detaches the Attribute from its parent, or does nothing if the Attribute has no parent.

Returns:

Attribute - this Attribute modified.

getName

public 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(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 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 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 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 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(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(String)).

getAttributeType

public Attribute.Type getAttributeType()

This will return the actual declared type of this Attribute.

Returns:

type for this attribute.

setAttributeType

public Attribute setAttributeType(Attribute.Type type)

This will set the type of the Attribute.

Parameters:

type - type for the attribute.

Returns:

Attribute - this Attribute modified.

Throws:

IllegalDataException - if the given attribute type is not one of the supported types.

toString

public String toString()

This returns a String representation of the Attribute, suitable for debugging.

Overrides:

toString in class Object

Returns:

String - information about the Attribute

equals

public final boolean equals(Object ob)

This tests for equality of this Attribute to the supplied Object.

Overrides:

equals in class Object

Parameters:

ob - Object to compare to.

Returns:

boolean - whether the Attribute is equal to the supplied Object.

hashCode

public final int hashCode()

This returns the hash code for this Attribute.

Overrides:

hashCode in class Object

Returns:

int - hash code.

clone

public Attribute clone()

This will return a clone of this Attribute.

Overrides:

clone in class Object

Returns:

Attribute - clone of this Attribute.

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.