UAPNode Class Reference

A UAPNode is the basic building block for constructing a UAP model. More...

#include <UAPNode.hpp>

Collaboration diagram for UAPNode:

List of all members.

Public Member Functions

UAPNode ()

Creates an empty UAP node.

UAPNode (enum UAPNode_type _type, const Str &_name)

Creates a UAPNode initialized with the specified type and name.

UAPNode (const Str &_name)

Creates a UAPNode initialized with the specified name.

UAPNode (const UAPNode &node)

Creates a copy of a UAPNode and copies of all its sub-nodes.

Str getName () const

Returns the local-name of this node.

void setName (const Str &_name)

Sets the local-name of this node.

void getPath (IntArray &path) const

Returns the path to this node.

enum UAPNode_type getType () const

Returns the type of this node.

void setType (enum UAPNode_type _type)

Sets the type of this node.

UAPNode * getParent () const

Returns the parent of this node.

void setParent (UAPNode *_parent)

Sets the parent of this node to the specified node.

UAPNode * getTwin () const

Returns the twin of this node.

void setTwin (UAPNode *_twin)

Sets the twin of this node to the specified node.

UAPNode * getConnect () const

Returns the connect of this node.

void setConnect (UAPNode *_connect)

Sets the connect of this node to the specified node.

UAPNode * detachNode ()

Detaches the node from the tree it is in.

void deleteNode ()

Deletes the node as well as the entire sub-tree.

NodeVec & getChildren ()

Returns a list of children of this node.

NodeVecIter getChildIter (const UAPNode *child)

Returns an iterator pointing to the child node.

UAPNode * addChild (const Str &_name, enum UAPNode_type _type, UAPNode *old_child=NULL)

Inserts a child just before old_child in the list of children of this node.

UAPNode * addChild (UAPNode *node, const UAPNode *old_child=NULL)

Adds the specified node just before the old_child node in the list of children of this node and returns a pointer to the child node.

UAPNode * addChildCopy (const UAPNode *node, const UAPNode *old_child=NULL)

Adds a copy of the specified node (along with its entire subtree) just before the old_child node in the list of children of this node and returns a pointer to the child.

AttributeVec & getAttributes ()

Returns a list of attributes of this a node.

UAPAttribute * getAttribute (const Str &_name)

Returns the attribute in this node with the specified name.

UAPNode * addAttribute (const Str &_name, const Str &_value, bool allow_repeats=false)

Appends an attribute to the end of the list of attributes in this node.

Str getAttributeString (const Str &_name)

Returns the string value associated with the specified attribute.

bool removeAttribute (const Str &_name)

Removes the attribute with name _name from the list of attributes in this node.

NodeVec getChildrenByName (const Str &_name)

Returns a list of the descendent children of a given name on this node.

UAPNode * getChildByName (const Str &_name, bool create=false)

Returns a child node of a given name.

NodeVec getSubNodesByName (const Str &_name)

Returns a list of sub-nodes of the current node with the specified name.

void getSubNodesByName (const Str &_name, NodeVec &nodeList)

See getSubNodesByName(const Str&).

int getChildIndexNumber () const

Gets the child index number for a node.

UAPNode * add (UAPNode_list list_name, UAPNode *new_ele, UAPNode *old_ele=NULL)

Adds a reference to a UAPNode to the slave, master, or controller list.

UAPNode * add (UAPNode_list list_name, UAPNode *new_ele, NodeVecIter insert_pt)

Adds a reference to a UAPNode to the slave, master, or controller list.

NodeVec & getList (UAPNode_list list_name)

Returns a slave, master, or controller list of this node.

Str toString (int indent=0, bool encode_all=true, const Str &prefix="") const

Returns a string representing this node.

Str toStringTree (int indent=0) const

Returns a string representing the UAP tree rooted at this node.

Str toXMLTree (int indent=0) const

Returns an XML representation of the UAPNode and of all subnodes.

void checkTree ()

Makes consistancy checks on the node tree.

Str getXMLURI () const

Returns the Universal Resource Identifier of this node.

void setXMLURI (const Str &uri)

Sets the Universal Resource Identifier of this node.

Str getXMLPrefix () const

Returns the XML prefix used for the Universal Resource Identifier of this node.

void setXMLPrefix (const Str &prefix)

Sets the XML prefix of this node.

Str getQName () const

Get the XML qualified name for this node.

Str getUniversalName () const

Get the universal name for this node.

void addXMLNSAttributes (bool close_to_root=true)

Adds "xmlns" attributes to create a conforming xml tree.

Friends

std::ostream & operator<< (std::ostream &os, const UAPNode &node)

Overrides the default output stream operator.

Detailed Description

A UAPNode is the basic building block for constructing a UAP model.

A UAP model is essentially a tree of UAPNodes. This is similar to an XML tree except a UAP node also contains pointers to slaves, etc.

Each UAPNode has:

A name.
An xml_prefix.
An xml_uri.
A type. Generally this is ELEMENT_NODE.
A pointer to its parent node.
A pointer to its twin node.
Pointers to its children nodes.
A list of attributes.
See also:
UAPAttribute
Pointers to its masters.
Pointers to its controllers.
Pointers to its slaves.

Note: For a node that is part of a tree, an "elder" of the node can be the parent, the parent of the parent, all the way up to the root node.

Consider the XML node:

     <car:parts xmlns:car = "http://www.cars.com/xml" />

When this is translated to a UAPNode the result is:

     .name = "parts"
     .xml_prefix = "car"
     .xml_uri = "http://www.cars.com/xml"

In this example:

     local-name     = "parts"
     qualified-name = "car:parts"
     universal-name = "{http://www.cars.com/xml}parts"
     full-name      = "{http://www.cars.com/xml}car:parts"

Note: The qualified-name is also called the "qname".

Local, qualified, universal, and full-names are used in UAPnode creation. Some eamples of such names and how they are parsed:

   Name              Type                URI          Prefix
   ----------        ----------          -----        ----------
   "parts"           local-name          Undefined    Undefined
   ":parts"          qualified-name      Undefined    ""
   "pre:parts"       qualified-name      Undefined    "pre"
   "{uri}parts"      universal-name      "uri"        Undefined
   "{}parts"         universal-name   Blank ("") URIs not permitted on input!
   "{uri}:parts"     full-name           "uri"        ""
   "{uri}pre:parts"  full-name           "uri"        "pre"
   "{}pre:parts"     full-name        Blank ("") URIs not permitted on input!

Note: While prefixes may be undefined on input, URIs are never undefined.

Definition at line 128 of file UAPNode.hpp.

Constructor & Destructor Documentation

UAPNode::UAPNode ( )

Creates an empty UAP node.

UAPNode::UAPNode	(	enum UAPNode_type	_type,
		const Str &	_name
	)

Creates a UAPNode initialized with the specified type and name.

Undefined xml_prefix or xml_uri values will be set to blank ("").

Parameters:

	_type	The node's type.
	_name	A local/qualified/universal/or full name. See UAPNode.

Definition at line 8 of file UAPNode.cpp.

UAPNode::UAPNode ( const Str & _name )

Creates a UAPNode initialized with the specified name.

The node type will be ELEMENT_NODE. Undefined xml_prefix or xml_uri values will be set to blank ("").

Parameters:

_name

A local/qualified/universal/or full name. See UAPNode.

Definition at line 21 of file UAPNode.cpp.

UAPNode::UAPNode ( const UAPNode & node )

Creates a copy of a UAPNode and copies of all its sub-nodes.

This method overrides the default copy constructor.

Definition at line 34 of file UAPNode.cpp.

Member Function Documentation

UAPNode * UAPNode::add	(	UAPNode_list	list_name,
		UAPNode *	new_ele,
		NodeVecIter	insert_pt
	)

Adds a reference to a UAPNode to the slave, master, or controller list.

This reference will be put just before the reference to old_ele.

Parameters:

	list_name	Name of the list.
	new_ele	Node to point to.
	insert_pt	Iterator to an element in the list. The new_ele will be put just before this.

Returns:: Pointer to the inserted element.

Definition at line 398 of file UAPNode.cpp.

UAPNode * UAPNode::add	(	UAPNode_list	list_name,
		UAPNode *	new_ele,
		UAPNode *	old_ele = `NULL`
	)

Adds a reference to a UAPNode to the slave, master, or controller list.

This reference will be put just before the reference to old_ele.

Parameters:

	list_name	Name of the list.
	new_ele	Node to point to
	old_ele	new_ele will be put just before old_ele. If old_ele = NULL (the default) then new_ele will be appended at the end of the list.

Definition at line 381 of file UAPNode.cpp.

UAPNode * UAPNode::addAttribute	(	const Str &	_name,
		const Str &	_value,
		bool	allow_repeats = `false`
	)

Appends an attribute to the end of the list of attributes in this node.

This methods creates a new UAPAttribute from the specified name and value and adds it to the end of the list of attributes in this node. Exception: When the argument allow_repeats = false, and an attribute with _name already exists, no new attribute is created and the matching attribute has its value replaced by _value.

Parameters:

	_name	The name of the attribute.
	_value	The value of the attribute.
	allow_repeats	True to allow duplicate attributes. False if attributes must be unique. Default: False.

Returns:: "this" node.

Definition at line 319 of file UAPNode.cpp.

UAPNode * UAPNode::addChild	(	UAPNode *	node,
		const UAPNode *	old_child = `NULL`
	)

Adds the specified node just before the old_child node in the list of children of this node and returns a pointer to the child node.

Parameters:

	node	The node to be added.
	old_child	The new child is put just before this existing child. Default is at the end of the children list.

Returns:: Pointer to the node that was added.

Definition at line 260 of file UAPNode.cpp.

UAPNode * UAPNode::addChild	(	const Str &	_name,
		enum UAPNode_type	_type,
		UAPNode *	old_child = `NULL`
	)

Inserts a child just before old_child in the list of children of this node.

This method creates a new UAPNode and initializes it to the specified type and name for the child. The child is inserted just before old_child in the list of children and a pointer to the child is returned.

If _name is a local-name: xml_prefix will be blank. xml_uri will be blank unless there is an elder node with a blank xml_prefix. In this case, xml_uri will inherit the xml_uri of the nearest such elder.

If _name is a qualified-name, the xml_uri will be taken from the nearest elder that has the same xml_prefix value.

If _name is a universal-name, the xml_prefix will be taken from the nearest elder that has the same xml_uri. If no such error exists, an exception is thrown.

Parameters:

	_name	A local/qualified/universal/or full name. See UAPNode.
	_type	The type of the child.
	old_child	The new child is put just before this existing child. If old_child = NULL then the new child is put at the end of the children list.

Returns:: The child node. Returns NULL if there is an error

Definition at line 246 of file UAPNode.cpp.

UAPNode * UAPNode::addChildCopy	(	const UAPNode *	node,
		const UAPNode *	old_child = `NULL`
	)

Adds a copy of the specified node (along with its entire subtree) just before the old_child node in the list of children of this node and returns a pointer to the child.

Parameters:

	node	The node to be added.
	old_child	The new child is put just before this existing child. Default is at the end of the children list.

Returns:: Pointer to the new child.

Definition at line 252 of file UAPNode.cpp.

void UAPNode::addXMLNSAttributes ( bool close_to_root = true )

Adds "xmlns" attributes to create a conforming xml tree.

In a UAPNode tree, namespace URI information is stored as a component of the individual nodes. When the tree is printed or saved to a file, this information is lost. To preserve this information, appropriate "xmlns" attributes must be present. This method adds to the tree such attributes as needed. There are many possibilities in the placement of "xmlns" attribues. If close_to_root is True then this method will place the attributes as close to the root node as possible. If False, this method will try to palace the attributes close to where they are used. In both cases, this method tries to minimize the number of attributes created.

Parameters:

close_to_root

Strategy for placing the "xmlns" attributes.

Definition at line 671 of file UAPNode.cpp.

void UAPNode::checkTree ( )

Makes consistancy checks on the node tree.

1) Checks that all pairent pointers in the tree are indeed pointing to the parent. 2) Checks that ix_child is correct.

Definition at line 600 of file UAPNode.cpp.

void UAPNode::deleteNode ( )

Deletes the node as well as the entire sub-tree.

Also see detachNode.

Definition at line 420 of file UAPNode.cpp.

UAPNode * UAPNode::detachNode ( )

Detaches the node from the tree it is in.

If the node is the root node or the node is not in a tree, nothing is done. Also see deleteNode.

Returns:: The detached node.

Definition at line 146 of file UAPNode.cpp.

UAPAttribute * UAPNode::getAttribute ( const Str & _name )

Returns the attribute in this node with the specified name.

Parameters:

_name

The attribute name

Returns:: NULL if the attribute does not exist. Otherwise, the attribute in this node with the specified name.

Definition at line 288 of file UAPNode.cpp.

AttributeVec & UAPNode::getAttributes ( )

Returns a list of attributes of this a node.

This method returns a list of UAPAttribute objects.

Returns:: a list of attributes of this node.

See also:: AttributeVec

Definition at line 282 of file UAPNode.cpp.

string UAPNode::getAttributeString ( const Str & _name )

Returns the string value associated with the specified attribute.

This method stores the value of the specified attribute in the

Parameters:

_name

The attribute name

Returns:: The string value of the attribute. Blank "" if it does not exist.

Definition at line 298 of file UAPNode.cpp.

UAPNode * UAPNode::getChildByName	(	const Str &	_name,
		bool	create = `false`
	)

Returns a child node of a given name.

Parameters:

	_name	The universal-name of the child
	create	If true then create the child if it does not exist. If created then the node type will be ELEMENT_NODE.

Returns:: A child node with the given name. NULL if not found or if parent does not exist.

Definition at line 357 of file UAPNode.cpp.

int UAPNode::getChildIndexNumber ( ) const

Gets the child index number for a node.

Returns:: The child index number.

Definition at line 595 of file UAPNode.cpp.

NodeVecIter UAPNode::getChildIter ( const UAPNode * child )

Returns an iterator pointing to the child node.

Parameters:

child

The child node.

Returns:: An iterator pointing to the node. If the child node is not found then returns this.children.end().

Definition at line 138 of file UAPNode.cpp.

NodeVec & UAPNode::getChildren ( )

Returns a list of children of this node.

This method returns a list of UAPNode objects.

Returns:: a list of children of this node.

Definition at line 132 of file UAPNode.cpp.

NodeVec UAPNode::getChildrenByName ( const Str & _name )

Returns a list of the descendent children of a given name on this node.

If _name is a qname, match by xml_prefix instead of xml_uri.

Parameters:

_name

The name of the children

Returns:: A list of the descendent children of a given name on this node.

Definition at line 338 of file UAPNode.cpp.

UAPNode * UAPNode::getConnect ( ) const

Returns the connect of this node.

Returns:: the connect of this node.

Definition at line 120 of file UAPNode.cpp.

NodeVec & UAPNode::getList ( UAPNode_list list_name )

Returns a slave, master, or controller list of this node.

This method returns a list of UAPNode objects.

Parameters:

list_name

Name of the list: "SLAVE", "MASTER", or "CONTROLLER".

Returns:: A list of nodes.

Definition at line 406 of file UAPNode.cpp.

string UAPNode::getName ( ) const

Returns the local-name of this node.

Returns:: The local-name of this node.

Definition at line 72 of file UAPNode.cpp.

UAPNode * UAPNode::getParent ( ) const

Returns the parent of this node.

Returns:: The parent of this node.

Definition at line 96 of file UAPNode.cpp.

void UAPNode::getPath ( IntArray & path ) const

Returns the path to this node.

The path is a list of ix_child numbers starting from the root.

Returns:: the path to this node.

Definition at line 53 of file UAPNode.cpp.

string UAPNode::getQName ( ) const

Get the XML qualified name for this node.

the qualified name is of the form "xml_prefix:local_name"

Returns:: XML qualified name.

Definition at line 660 of file UAPNode.cpp.

void UAPNode::getSubNodesByName	(	const Str &	_name,
		NodeVec &	nodeList
	)

See getSubNodesByName(const Str&).

Definition at line 573 of file UAPNode.cpp.

NodeVec UAPNode::getSubNodesByName ( const Str & _name )

Returns a list of sub-nodes of the current node with the specified name.

All sub-nodes (children and sub-children) are searched.

See also:: NodeVec

Parameters:

_name

The universal-name of the node.

Returns:: A list of sub-nodes of the current node with the specified name.

Definition at line 553 of file UAPNode.cpp.

UAPNode * UAPNode::getTwin ( ) const

Returns the twin of this node.

Returns:: the twin of this node.

Definition at line 108 of file UAPNode.cpp.

enum UAPNode_type UAPNode::getType ( ) const

Returns the type of this node.

Returns:: the type of this node.

Definition at line 84 of file UAPNode.cpp.

string UAPNode::getUniversalName ( ) const

Get the universal name for this node.

the Universal name is of the form "{uri}local_name"

Returns:: Universal name

Definition at line 649 of file UAPNode.cpp.

string UAPNode::getXMLPrefix ( ) const

Returns the XML prefix used for the Universal Resource Identifier of this node.

Returns:: The URI prefix.

Definition at line 637 of file UAPNode.cpp.

string UAPNode::getXMLURI ( ) const

Returns the Universal Resource Identifier of this node.

Returns:: The Universal Resource Identifier of this node.

Definition at line 625 of file UAPNode.cpp.

bool UAPNode::removeAttribute ( const Str & _name )

Removes the attribute with name _name from the list of attributes in this node.

Parameters:

_name

The name of the attribute to remove

Returns:: true if the attribute existed. false otherwise.

Definition at line 307 of file UAPNode.cpp.

void UAPNode::setConnect ( UAPNode * _connect )

Sets the connect of this node to the specified node.

Parameters:

_connect

the node

Definition at line 126 of file UAPNode.cpp.

void UAPNode::setName ( const Str & _name )

Sets the local-name of this node.

Parameters:

_name

The name

Definition at line 78 of file UAPNode.cpp.

void UAPNode::setParent ( UAPNode * _parent )

Sets the parent of this node to the specified node.

Parameters:

_parent

the node

Definition at line 102 of file UAPNode.cpp.

void UAPNode::setTwin ( UAPNode * _twin )

Sets the twin of this node to the specified node.

Parameters:

_twin

the node

Definition at line 114 of file UAPNode.cpp.

void UAPNode::setType ( enum UAPNode_type _type )

Sets the type of this node.

Parameters:

_type

The type

Definition at line 90 of file UAPNode.cpp.

void UAPNode::setXMLPrefix ( const Str & prefix )

Sets the XML prefix of this node.

Parameters:

preifx

The name of the prefix

Definition at line 643 of file UAPNode.cpp.

void UAPNode::setXMLURI ( const Str & uri )

Sets the Universal Resource Identifier of this node.

Parameters:

uri

The name of the URI

Definition at line 631 of file UAPNode.cpp.

string UAPNode::toString	(	int	indent = `0`,
		bool	encode_all = `true`,
		const Str &	prefix = `""`
	)			const

Returns a string representing this node.

The attributes of this node are printed in brackets.

Parameters:

	indent	Number of spaces to indent.
	encode_all	If true (default) then encode information on any twin, master, and slave data.
	prefix	Prefix string to be prepended to output.

Returns:: A string representation of this node.

See also:: toStringTree

Definition at line 436 of file UAPNode.cpp.

string UAPNode::toStringTree ( int indent = 0 ) const

Returns a string representing the UAP tree rooted at this node.

The argument depth is a specifier for the depth of the tree so far and defaults to 0.

This method recursively prints a textual representation of the tree rooted at this node.

Parameters:

indent

Number of spaces to indent.

Returns:: A textual representation of the UAP tree rooted at this node.

See also:: toString

Definition at line 491 of file UAPNode.cpp.

string UAPNode::toXMLTree ( int indent = 0 ) const

Returns an XML representation of the UAPNode and of all subnodes.

Note that all information on twins, slaves, controllers, etc. is lost.

Parameters:

indent

Number of spaces to indent.

Returns:: An XML representation of the UAP tree rooted at this node.

Definition at line 517 of file UAPNode.cpp.

Friends And Related Function Documentation

std::ostream& operator<<	(	std::ostream &	os,
		const UAPNode &	node
	)			`[friend]`

Overrides the default output stream operator.

See also:: toString

Definition at line 795 of file UAPNode.cpp.


Public Member Functions
	UAPNode ()
	Creates an empty UAP node.
	UAPNode (enum UAPNode_type _type, const Str &_name)
	Creates a UAPNode initialized with the specified type and name.
	UAPNode (const Str &_name)
	Creates a UAPNode initialized with the specified name.
	UAPNode (const UAPNode &node)
	Creates a copy of a UAPNode and copies of all its sub-nodes.
Str	getName () const
	Returns the local-name of this node.
void	setName (const Str &_name)
	Sets the local-name of this node.
void	getPath (IntArray &path) const
	Returns the path to this node.
enum UAPNode_type	getType () const
	Returns the type of this node.
void	setType (enum UAPNode_type _type)
	Sets the type of this node.
UAPNode *	getParent () const
	Returns the parent of this node.
void	setParent (UAPNode *_parent)
	Sets the parent of this node to the specified node.
UAPNode *	getTwin () const
	Returns the twin of this node.
void	setTwin (UAPNode *_twin)
	Sets the twin of this node to the specified node.
UAPNode *	getConnect () const
	Returns the connect of this node.
void	setConnect (UAPNode *_connect)
	Sets the connect of this node to the specified node.
UAPNode *	detachNode ()
	Detaches the node from the tree it is in.
void	deleteNode ()
	Deletes the node as well as the entire sub-tree.
NodeVec &	getChildren ()
	Returns a list of children of this node.
NodeVecIter	getChildIter (const UAPNode *child)
	Returns an iterator pointing to the `child` node.
UAPNode *	addChild (const Str &_name, enum UAPNode_type _type, UAPNode *old_child=NULL)
	Inserts a child just before old_child in the list of children of this node.
UAPNode *	addChild (UAPNode node, const UAPNode old_child=NULL)
	Adds the specified node just before the `old_child` node in the list of children of this node and returns a pointer to the child node.
UAPNode *	addChildCopy (const UAPNode node, const UAPNode old_child=NULL)
	Adds a copy of the specified node (along with its entire subtree) just before the `old_child` node in the list of children of this node and returns a pointer to the child.
AttributeVec &	getAttributes ()
	Returns a list of attributes of this a node.
UAPAttribute *	getAttribute (const Str &_name)
	Returns the attribute in this node with the specified name.
UAPNode *	addAttribute (const Str &_name, const Str &_value, bool allow_repeats=false)
	Appends an attribute to the end of the list of attributes in this node.
Str	getAttributeString (const Str &_name)
	Returns the string value associated with the specified attribute.
bool	removeAttribute (const Str &_name)
	Removes the attribute with name `_name` from the list of attributes in this node.
NodeVec	getChildrenByName (const Str &_name)
	Returns a list of the descendent children of a given name on this node.
UAPNode *	getChildByName (const Str &_name, bool create=false)
	Returns a child node of a given name.
NodeVec	getSubNodesByName (const Str &_name)
	Returns a list of sub-nodes of the current node with the specified name.
void	getSubNodesByName (const Str &_name, NodeVec &nodeList)
	See getSubNodesByName(const Str&).
int	getChildIndexNumber () const
	Gets the child index number for a node.
UAPNode *	add (UAPNode_list list_name, UAPNode new_ele, UAPNode old_ele=NULL)
	Adds a reference to a UAPNode to the slave, master, or controller list.
UAPNode *	add (UAPNode_list list_name, UAPNode *new_ele, NodeVecIter insert_pt)
	Adds a reference to a UAPNode to the slave, master, or controller list.
NodeVec &	getList (UAPNode_list list_name)
	Returns a slave, master, or controller list of this node.
Str	toString (int indent=0, bool encode_all=true, const Str &prefix="") const
	Returns a string representing this node.
Str	toStringTree (int indent=0) const
	Returns a string representing the UAP tree rooted at this node.
Str	toXMLTree (int indent=0) const
	Returns an XML representation of the UAPNode and of all subnodes.
void	checkTree ()
	Makes consistancy checks on the node tree.
Str	getXMLURI () const
	Returns the Universal Resource Identifier of this node.
void	setXMLURI (const Str &uri)
	Sets the Universal Resource Identifier of this node.
Str	getXMLPrefix () const
	Returns the XML prefix used for the Universal Resource Identifier of this node.
void	setXMLPrefix (const Str &prefix)
	Sets the XML prefix of this node.
Str	getQName () const
	Get the XML qualified name for this node.
Str	getUniversalName () const
	Get the universal name for this node.
void	addXMLNSAttributes (bool close_to_root=true)
	Adds "xmlns" attributes to create a conforming xml tree.
Friends
std::ostream &	operator<< (std::ostream &os, const UAPNode &node)
	Overrides the default output stream operator.