Element Class Reference

#include <elm/xom/Element.h>

Inheritance diagram for Element:

Public Member Functions
	Element (String name)
	Element (String name, String uri)
	Element (const Element *element)
virtual void	addAttribute (Attribute *attribute)
virtual void	addNamespaceDeclaration (String prefix, String uri)
virtual void	appendChild (String text)
virtual void	appendChild (Node *node)
virtual Node *	copy (void)
virtual Attribute *	getAttribute (int index)
virtual Attribute *	getAttribute (String name)
virtual Attribute *	getAttribute (String localName, String ns)
virtual int	getAttributeCount (void)
virtual Option< String >	getAttributeValue (String name)
virtual Option< String >	getAttributeValue (String localName, String ns)
virtual Elements *	getChildElements (void)
virtual Elements *	getChildElements (String name)
virtual Elements *	getChildElements (String localName, String ns)
virtual Element *	getFirstChildElement (String name)
virtual Element *	getFirstChildElement (String localName, String ns)
virtual String	getLocalName (void)
virtual int	getNamespaceDeclarationCount (void)
virtual String	getNamespacePrefix (void)
virtual String	getNamespacePrefix (int index)
virtual String	getNamespaceURI (void)
virtual String	getNamespaceURI (String prefix)
virtual String	getQualifiedName (void)
virtual String	getValue (void)
virtual void	insertChild (String text, int position)
virtual void	insertChild (Node *node, int position)
virtual Attribute *	removeAttribute (Attribute *attribute)
virtual Nodes *	removeChildren (void)
virtual void	removeNamespaceDeclaration (String prefix)
virtual void	setBaseURI (String uri)
virtual void	setLocalName (String local_name)
virtual void	setNamespacePrefix (String prefix)
virtual void	setNamespaceURI (String uri)
virtual String	toString (void)
virtual String	toXML (void)
Public Member Functions inherited from ParentNode
virtual int	indexOf (Node *child)
virtual Node *	removeChild (int position)
virtual Node *	removeChild (Node *child)
virtual void	replaceChild (Node *old_child, Node *new_child)
virtual Node *	getChild (int index)
virtual int	getChildCount (void)
Public Member Functions inherited from Node
virtual	~Node (void)
void *	getNode (void) const
kind_t	kind (void) const
void	detach (void)
bool	equals (const Node *node) const
virtual String	getBaseURI (void)
virtual Document *	getDocument (void)
virtual ParentNode *	getParent (void)
virtual Nodes *	query (const String &xpath)
virtual Nodes *	query (const String &xpath, XPathContext *context)
int	line (void) const

Protected Member Functions
	Element (void *node)
virtual Element *	shallowCopy (void)
Protected Member Functions inherited from ParentNode
	ParentNode (void *node)
void	internSetBaseURI (String URI)
Protected Member Functions inherited from Node
	Node (void *_node)
void	setNode (void *_node)
Node *	make (void *node)
Node *	get (void *node)
Node *	internCopy (void)
Node *	internGetChild (int index)
int	internGetChildCount (void)
String	internGetValue (void)
String	internToXML (void)

Static Protected Member Functions
static void *	makeNS (String name, String uri)
Static Protected Member Functions inherited from Node
static void	freeNode (void *node)

Additional Inherited Members
Public Types inherited from Node
enum	kind_t {   NONE = 0, ELEMENT, DOCUMENT, TEXT,   COMMENT, ATTRIBUTE, PROCESSING_INSTRUCTION, DOCTYPE,   NAMESPACE }
typedef enum elm::xom::Node::kind_t	kind_t
Protected Attributes inherited from Node
void *	node

Detailed Description

Represents an XML element.

Constructor & Destructor Documentation

Element() [1/4]

Element ( void *  node )

protected

Build an element from the parser representation.

Parameters

node	Node in the parser representation.

References Node::node.

Referenced by Element::shallowCopy().

Element() [2/4]

Element

(

String

name

)

Creates a new element in no namespace.

Parameters

name	the name of the element

Exceptions

IllegalNameException

if name is not a legal XML 1.0 non-colonized name.

Element() [3/4]

Element	(	String	name,
		String	uri
	)

Creates a new element in a namespace.

Parameters

name	the qualified name of the element
uri	the namespace URI of the element

Exceptions

IllegalNameException	if name is not a legal XML 1.0 name
NamespaceConflictException	if name's prefix cannot be used with uri
MalformedURIException	if uri is not an RFC 3986 absolute URI reference

Element() [4/4]

Element

(

const Element *

element

)

Creates a deep copy of an element. The copy is disconnected from the tree, and does not have a parent.

Parameters

element

the element to copy

References Node::getNode(), and Node::node.

Member Function Documentation

addAttribute()

void addAttribute ( Attribute *  attribute )

virtual

Adds an attribute to this element, replacing any existing attribute with the same local name and namespace URI.

Parameters

attribute

the attribute to add

Exceptions

MultipleParentException	if the attribute is already attached to an element
NamespaceConflictException	- if the attribute's prefix is mapped to a different namespace URI than the same prefix is mapped to by this element, another attribute of this element, or an additional namespace declaration of this element.

References Attribute::getLocalName(), Node::getNode(), Attribute::getValue(), Node::node, and Node::setNode().

addNamespaceDeclaration()

void addNamespaceDeclaration ( String  prefix, String  uri  )

virtual

Declares a namespace prefix. This is only necessary when prefixes are used in element content and attribute values, as in XSLT and the W3C XML Schema Language. Do not use this method to declare prefixes for element and attribute names.

If you do redeclare a prefix that is already used by an element or attribute name, the additional namespace is added if and only if the URI is the same. Conflicting namespace declarations will throw an exception.

Parameters

prefix	the prefix to declare.
uri	the absolute URI reference to map the prefix to.
MalformedURIException	if URI is not an RFC 3986 URI reference
IllegalNameException	if prefix is not a legal XML non-colonized name
NamespaceConflictException	if the mapping conflicts with an existing element, attribute, or additional namespace declaration

References Node::node.

appendChild() [1/2]

void appendChild ( Node *  child )

virtual

Appends a node to the children of this node.

Parameters

child

node to append to this node

Note

Fails if (1) if this node cannot have children of this type, (2) if child already has a parent.

Reimplemented from ParentNode.

References ParentNode::appendChild(), and Node::node.

appendChild() [2/2]

void appendChild ( String  text )

virtual

Converts a string to a text node and appends that node to the children of this node.

Parameters

text	String to add to this node.

Exceptions

IllegalAddException

if this node cannot have children of this type.

References Node::node.

copy()

Node * copy ( void  )

virtual

Implements Node.

getAttribute() [1/3]

Attribute * getAttribute ( int  index )

virtual

Selects an attribute by index. The index is purely for convenience and has no particular meaning. In particular, it is not necessarily the position of this attribute in the original document from which this Element object was read. As with most lists in Java, attributes are numbered from 0 to one less than the length of the list.

In general, you should not add attributes to or remove attributes from the list while iterating across it. Doing so will change the indexes of the other attributes in the list. it is, however, safe to remove an attribute from either end of the list (0 or getAttributeCount()-1) until there are no attributes left.

Parameters

index

the attribute to return.

Returns

the indexth attribute of this element

References Node::get(), and Node::node.

Referenced by Serializer::writeAttributes().

getAttribute() [2/3]

Attribute * getAttribute ( String  localName, String  ns  )

virtual

Returns the attribute with the specified name and namespace URI, or null if this element does not have an attribute with that name in that namespace.

Parameters

localName	the local name of the attribute.
namespaceURI	the namespace of the attribute.

Returns

the attribute of this element with the specified name and namespace.

References Node::get(), and Node::node.

getAttribute() [3/3]

Attribute * getAttribute ( String  name )

virtual

Returns the attribute with the specified name in no namespace, or null if this element does not have an attribute with that name in no namespace.

Parameters

name	the name of the attribute .

Returns

the attribute of this element with the specified name.

References Node::get(), and Node::node.

getAttributeCount()

int getAttributeCount ( void  )

virtual

Returns the number of attributes of this Element, not counting namespace declarations. This is always a non-negative number.

Returns

the number of attributes in the container.

References Node::node.

Referenced by Serializer::writeAttributes().

getAttributeValue() [1/2]

Option< String > getAttributeValue ( String  localName, String  ns  )

virtual

Returns the value of the attribute with the specified name and namespace URI, or null if this element does not have such an attribute.

Parameters

localName	the name of the attribute.
namespaceURI	the namespace of the attribute.

Returns

the value of the attribute of this element with the specified name and namespace.

References Node::node, elm::none, and elm::some().

getAttributeValue() [2/2]

Option< String > getAttributeValue ( String  name )

virtual

Returns the value of the attribute with the specified name in no namespace, or none if this element does not have an attribute with that name.

Parameters

name	the name of the attribute.

Returns

the value of the attribute of this element with the specified name.

References Node::node, elm::none, and elm::some().

Referenced by XOMUnserializer::flush().

getChildElements() [1/3]

Elements * getChildElements ( String  localName, String  ns  )

virtual

Returns a list of the immediate child elements of this element with the specified local name and namespace URI. Passing the empty string or null as the local name returns all elements in the specified namespace. Passing null or the empty string as the namespace URI returns elements with the specified name in no namespace. The elements returned are in document order.

Parameters

localName	The name of the elements included in the list.
namespaceURI	The namespace URI of the elements included in the list.

Returns

A comatose list containing the child elements of this element with the specified name in the specified namespace.

References Node::Elements, Node::make(), and Node::node.

getChildElements() [2/3]

Elements * getChildElements ( String  name )

virtual

Returns a list of the child elements of this element with the specified name in no namespace. The elements returned are in document order.

Parameters

name	The name of the elements included in the list .

Returns

A comatose list containing the child elements of this element with the specified name.

References Node::Elements, Node::make(), and Node::node.

getChildElements() [3/3]

Elements * getChildElements ( void  )

virtual

Returns a list of all the child elements of this element in document order.

Returns

a comatose list containing all child elements of this element.

References Node::Elements, Node::make(), and Node::node.

getFirstChildElement() [1/2]

Element * getFirstChildElement ( String  localName, String  ns  )

virtual

Returns the first child element with the specified local name and namespace URI. If there is no such element, it returns null.

Parameters

localName	The local name of the element to return.
namespaceURI	The namespace URI of the element to return.

Returns

The first child with the specified local name in the specified namespace, or null if there is no such element.

References Node::make(), and Node::node.

getFirstChildElement() [2/2]

Element * getFirstChildElement ( String  name )

virtual

Returns the first child element with the specified name in no namespace. If there is no such element, it returns null.

Parameters

name	The name of the element to return.

Returns

The first child element with the specified local name in no namespace or null if there is no such element.

References Node::make(), and Node::node.

getLocalName()

String getLocalName ( void  )

virtual

Returns the local name of this element, not including the namespace prefix or colon.

Returns

The local name of this element.

References Node::node.

Referenced by Element::parse(), and Serializer::writeEmptyElementTag().

getNamespaceDeclarationCount()

int getNamespaceDeclarationCount ( void  )

virtual

Returns the number of namespace declarations on this element. This counts the namespace of the element itself (which may be the empty string), the namespace of each attribute, and each namespace added by addNamespaceDeclaration. However, prefixes used multiple times are only counted once; and the xml prefix used for xml:base, xml:lang, and xml:space is not counted even if one of these attributes is present on the element.

The return value is almost always positive. It can be zero if and only if the element itself has the prefix xml; e.g. <xml:space />. This is not endorsed by the XML specification. The prefix xml is reserved for use by the W3C, which has only used it for attributes to date. You really shouldn't do this. Nonetheless, this is not malformed so XOM allows it.

Returns

The number of namespaces declared by this element.

References Node::node.

Referenced by Serializer::writeStartTag().

getNamespacePrefix() [1/2]

String getNamespacePrefix ( int  index )

virtual

Returns the indexth namespace prefix declared on this element. Namespaces inherited from ancestors are not included. The index is purely for convenience, and has no meaning in itself. This includes the namespaces of the element name and of all attributes' names (except for those with the prefix xml such as xml:space) as well as additional declarations made for attribute values and element content. However, prefixes used multiple times (e.g. on several attribute values) are only reported once. The default namespace is reported with an empty string prefix if present. Like most lists in Java, the first prefix is at index 0.

If the namespaces on the element change for any reason (adding or removing an attribute in a namespace, adding or removing a namespace declaration, changing the prefix of an element, etc.) then then this method may skip or repeat prefixes. Don't change the prefixes of an element while iterating across them.

Parameters

index

The prefix to return.

Returns

The prefix.

References Node::node.

getNamespacePrefix() [2/2]

String getNamespacePrefix ( void  )

virtual

Returns the prefix of this element, or the empty string if this element does not have a prefix.

Returns

The prefix of this element.

References Node::node.

Referenced by Serializer::writeStartTag().

getNamespaceURI() [1/2]

String getNamespaceURI ( String  prefix )

virtual

Returns the namespace URI mapped to the specified prefix within this element. Returns null if this prefix is not associated with a URI.

Parameters

prefix

The namespace prefix whose URI is desired.

Returns

The namespace URI mapped to prefix.

References Node::node.

getNamespaceURI() [2/2]

String getNamespaceURI ( void  )

virtual

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

Returns

The namespace URI of this element.

References Node::node.

Referenced by Serializer::writeStartTag().

getQualifiedName()

String getQualifiedName ( void  )

virtual

Returns the complete name of this element, including the namespace prefix if this element has one.

Returns

The qualified name of this element.

Warning

The string allocated by this call must be fried !

References Node::node.

Referenced by Serializer::writeEndTag(), and Serializer::writeStartTag().

getValue()

String getValue ( void  )

virtual

Get the node as a string with markup removed.

Returns

Text value of the node. The returned string must be fried by the caller.

Implements Node.

References Node::internGetValue().

insertChild() [1/2]

void insertChild ( Node *  node, int  position  )

virtual

Insert a node at the given position.

Parameters

position	Where to insert the child.
node	Node to insert.

Reimplemented from ParentNode.

References ParentNode::insertChild(), and Node::node.

insertChild() [2/2]

void insertChild ( String  text, int  position  )

virtual

Converts a string to a text node and inserts that node at the specified position.

Parameters

position	Where to insert the child.
text	The string to convert to a text node and insert.

References ParentNode::insertChild().

makeNS()

void * makeNS ( String  name, String  uri  )

staticprotected

Build an element with a namespace.

Parameters

name	Qualified element name.
uri	URI of the namespace.

References CString::chars(), and Node::node.

removeAttribute()

Attribute * removeAttribute ( Attribute *  attribute )

virtual

Removes an attribute from this element.

Parameters

attribute

The attribute to remove.

Returns

The attribute that was removed.

Exceptions

NoSuchAttributeException

If this element is not the parent of attribute.

removeChildren()

Nodes * removeChildren ( void  )

virtual

removeNamespaceDeclaration()

void removeNamespaceDeclaration ( String  prefix )

virtual

setBaseURI()

void setBaseURI ( String  uri )

virtual

Implements ParentNode.

setLocalName()

void setLocalName ( String  local_name )

virtual

setNamespacePrefix()

void setNamespacePrefix ( String  prefix )

virtual

setNamespaceURI()

void setNamespaceURI ( String  uri )

virtual

shallowCopy()

Element * shallowCopy ( void  )

protectedvirtual

Creates a very shallow copy of the element with the same name and namespace URI, but no children, attributes, base URI, or namespace declaration. This method is invoked as necessary by the copy method and the copy constructor.

Subclasses should override this method so that it returns an instance of the subclass so that types are preserved when copying. This method should not add any attributes, namespace declarations, or children to the shallow copy. Any such items will be overwritten.

Returns

an empty element with the same name and namespace as this element

References Element::Element().

toString()

String toString ( void  )

virtual

toXML()

String toXML ( void  )

virtual

Implements Node.

---

The documentation for this class was generated from the following files:

• include/elm/xom/Element.h
• src/xom_Element.cpp