BufferNode Struct Reference

Represents a buffer node. More...

#include <buffernode.h>

Collaboration diagram for BufferNode:

[legend]

List of all members.

Public Member Functions
	BufferNode (const char *_data, BufferNode *_parent)
	Constructor.
	BufferNode (TAG _tag, BufferNode *_parent)
	Constructor.
	BufferNode (const char *_data, BufferNode *_parent, vector< unsigned > *_cumulative_roles, vector< unsigned > *_non_cumulative_roles)
	Constructor.
	BufferNode (TAG _tag, BufferNode *_parent, vector< unsigned > *_cumulative_roles, vector< unsigned > *_non_cumulative_roles)
	Constructor.
virtual	~BufferNode ()
void	addChild (BufferNode *child)
	Adds a child node for this BufferNode object.
void	appendRoles (vector< unsigned > *_cumulative_roles, vector< unsigned > *_non_cumulative_roles)
	Appends the specified roles to the buffer node.
void	print (OutputStream &eos)
	Prints the subtree defined by the BufferNode object.
void	printNoSubnodes (OutputStream &dos)
	Debug prints the BufferNode without its child nodes.
void	debugPrint (OutputStream &dos)
	Debug prints the subtree defined by the BufferNode object.
void	debugPrintCompleteBuffer (OutputStream &dos)
	Debug prints the complete buffer (i.e. starting with the root).
const char *	getPCDataRepresentation ()
	Returns the PCDATA representation of the buffer node.
void	getPCDataRepresentation (std::ostringstream &s)
	Collects the character child nodes in the passed input stream.
void	close ()
	Marks the associated buffer TagNode object as closed.
bool	isClosed ()
	Returns true if the associated buffer TagNode is marked as closed, false otherwise.
void	lock ()
	Locks the BufferNode object.
void	unlock ()
	Unlocks the BufferNode object and triggers garbage collection (if possible).
bool	isLocked ()
	Returns true if the buffer node is locked, false otherwise.
bool	isRoot ()
	Returns true if the buffer node is the document root, false otherwise.
bool	isMarked ()
	Returns true if the BufferNode object carries cumulative or non-cumulative roles.
bool	isCumulativeMarked ()
	Returns true if the BufferNode object carries a cumulativ role.
bool	hasCumulativeMarkedAncestor ()
	Returns true if the BufferNode object has an ancestor with a cumulative role.
bool	hasNoMarkedAndNoLockedDos ()
	Returns true if the BufferNode object has any marked or locked descendants or is marked/locked itself.
void	removeRoleFromNode (Role *role)
	Removes the specified role from the BufferNode object.
void	clear ()
	Triggers garbage collection, starting at this BufferNode object.
void	clearSubtreeIfPossible ()
	This garbage collection method tries to garbage collect the whole subtre of the node.
Public Attributes
bool	type
	The type of the buffer node.
BufferNode *	parent
	The parent of the buffer node object.
BufferNode *	r_sibling
	The right sibling of the buffer node object.
IntMultiSet *	cumulative_roles
	The set of cumulative roles.
IntMultiSet *	non_cumulative_roles
	The set of non-cumulative roles.
void *	node
	The content carried by the BufferNode object.
bool	is_locked
	A flag that can be used to lock the BufferNode.

---

Detailed Description

Represents a buffer node.

A buffer node represents a buffer node in the DOM tree, thus containing additional information like parent and right-sibling pointer. Additionally it contains fields for storing roles that are assigned to the buffer nodes, as well as methods for removing such roles. Each buffer node is either a TagNode or a CharNode. The specific information is stored in the void* node-member, which must be casted on demand. We chose this compact representation to keep the buffer representation minimal (recall that the goal of our project was to minimize main memory consumption, hence a small DOM buffer representation is crucial).

Author:

Michael Schmidt

Gunnar Jehl

Version:

2.1

License:

Software License Agreement (BSD License)

Definition at line 78 of file buffernode.h.

---

Constructor & Destructor Documentation

BufferNode::BufferNode	(	const char *	_data,
		BufferNode *	_parent
	)

Constructor.

Constructor - creating object for a fresh character buffer child node for the given parent.

Parameters:

[in]	_data	The PCDATA content carried by the character node.
[in]	_parent	The parent of the newly created node.

Definition at line 40 of file buffernode.cpp.

BufferNode::BufferNode	(	TAG	_tag,
		BufferNode *	_parent
	)

Constructor.

Constructor - creating object for a fresh tag buffer child node for the given parent.

Parameters:

[in]	_tag	The tag id carried by the tag node.
[in]	_parent	The parent of the newly created node.

Definition at line 56 of file buffernode.cpp.

BufferNode::BufferNode	(	const char *	_data,
		BufferNode *	_parent,
		vector< unsigned > *	_cumulative_roles,
		vector< unsigned > *	_non_cumulative_roles
	)

Constructor.

Constructor - creating object for a fresh character buffer child node for the given parent and appends the specified roles to the node.

Parameters:

[in]	_data	The PCDATA content carried by the character node.
[in]	_parent	The parent of the newly created node.
[in]	_cumulative_roles	Pointer to a set of cumulative roles.
[in]	_non_cumulative_roles	Pointer to a set of non-cumulative roles.

Definition at line 70 of file buffernode.cpp.

References appendRoles().

BufferNode::BufferNode	(	TAG	_tag,
		BufferNode *	_parent,
		vector< unsigned > *	_cumulative_roles,
		vector< unsigned > *	_non_cumulative_roles
	)

Constructor.

Constructor - creating object for a fresh tag buffer child node for the given parent and appends the specified roles to the node.

Parameters:

[in]	_tag	The tag id carried by the tag node.
[in]	_parent	The parent of the newly created node.
[in]	_cumulative_roles	Pointer to a set of cumulative roles.
[in]	_non_cumulative_roles	Pointer to a set of non-cumulative roles.

Definition at line 89 of file buffernode.cpp.

References appendRoles().

BufferNode::~BufferNode

(

)

[virtual]

Destructor.

Definition at line 108 of file buffernode.cpp.

References cumulative_roles, node, non_cumulative_roles, type, TYPE_PCDATA, and TYPE_TAG.

---

Member Function Documentation

void BufferNode::addChild

(

BufferNode *

child

)

Adds a child node for this BufferNode object.

The child is added at the rightmost position, thus following document order.

Parameters:

[in]

child

The child node to be added.

Returns:

void

Definition at line 122 of file buffernode.cpp.

References TagNode::children, node, and BufferNodeList::push_back().

Referenced by Buffer::appendPCData(), and Buffer::appendTag().

void BufferNode::appendRoles	(	vector< unsigned > *	_cumulative_roles,
		vector< unsigned > *	_non_cumulative_roles
	)

Appends the specified roles to the buffer node.

The method is intended to be called only once, i.e. previous role information is overwritten.

Parameters:

[in]	_cumulative_roles	Pointer to a set of cumulative roles.
[in]	_non_cumulative_roles	Pointer to a set of non-cumulative roles.

Return values:

void

Definition at line 128 of file buffernode.cpp.

References cumulative_roles, and non_cumulative_roles.

Referenced by Buffer::appendRoles(), and BufferNode().

void BufferNode::clear

(

)

Triggers garbage collection, starting at this BufferNode object.

Garbage collection is propagated downwards and upwards, if possible.

Return values:

void

Definition at line 284 of file buffernode.cpp.

References clear(), clearSubtreeIfPossible(), is_locked, isRoot(), node, parent, type, TYPE_PCDATA, and TYPE_TAG.

Referenced by clear(), Executor::evalQuery(), BufferIterator::getNext(), and removeRoleFromNode().

void BufferNode::clearSubtreeIfPossible

(

)

This garbage collection method tries to garbage collect the whole subtre of the node.

Implements downward propagation of garbage collection.

Return values:

void

Definition at line 305 of file buffernode.cpp.

References TagNode::children, BufferNodeList::getFront(), hasCumulativeMarkedAncestor(), isCumulativeMarked(), node, BufferNodeList::removeElem(), type, and TYPE_TAG.

Referenced by clear().

void BufferNode::close

(

)

[inline]

Marks the associated buffer TagNode object as closed.

This method applies only to tag buffer nodes, i.e. requires that the member variable type is set to TYPE_TAG. The caller must assert that this condition holds, otherwise the method is likely to crash.

Returns:

void

Definition at line 203 of file buffernode.h.

References node.

Referenced by Buffer::closeTag().

void BufferNode::debugPrint

(

OutputStream &

dos

)

Debug prints the subtree defined by the BufferNode object.

The output also contains role information, so this method is suited for debug purpose only.

Parameters:

[in]

dos

Reference to the (debug) OutputStream.

Return values:

void

Definition at line 171 of file buffernode.cpp.

References cumulative_roles, TagMap::getInstance(), TagMap::getTag(), is_locked, NEWLINE, node, non_cumulative_roles, IntMultiSet::print(), type, TYPE_PCDATA, and TYPE_TAG.

Referenced by BufferIterator::debugPrint(), Buffer::debugPrint(), and debugPrintCompleteBuffer().

void BufferNode::debugPrintCompleteBuffer

(

OutputStream &

dos

)

Debug prints the complete buffer (i.e. starting with the root).

The output will also contain role information, so this method is suited for debug purpose only. This method is realized by climbing up to the buffer root node and then calling debugPrint().

Parameters:

[in]

dos

Reference to the (debug) OutputStream.

Return values:

void

Definition at line 206 of file buffernode.cpp.

References debugPrint(), debugPrintCompleteBuffer(), and parent.

Referenced by debugPrintCompleteBuffer().

void BufferNode::getPCDataRepresentation

(

std::ostringstream &

s

)

Collects the character child nodes in the passed input stream.

This is a help method of getPCDataRepresentation()

Parameters:

[in]

s

A std::ostringstream where the PCDATA representation is appended to.

Return values:

void

Definition at line 219 of file buffernode.cpp.

References TagNode::children, BufferNodeList::getFront(), node, r_sibling, type, and TYPE_PCDATA.

const char * BufferNode::getPCDataRepresentation

(

)

Returns the PCDATA representation of the buffer node.

This is done by appending the PCDATA content of the child nodes.

Note:

The caller is responsible to free() the return value.

Return values:

const

char* The PCDATA representation of the node.

Definition at line 211 of file buffernode.cpp.

Referenced by VarStepExpression::getNextValue(), and VarExpression::getNextValue().

bool BufferNode::hasCumulativeMarkedAncestor

(

)

Returns true if the BufferNode object has an ancestor with a cumulative role.

In particular, ancestors with non-cumulative roles are ignored.

Return values:

bool

Returns true if at least one ancestor BufferNode carries one or more cumulative roles.

Definition at line 248 of file buffernode.cpp.

References hasCumulativeMarkedAncestor(), isCumulativeMarked(), isRoot(), and parent.

Referenced by clearSubtreeIfPossible(), and hasCumulativeMarkedAncestor().

bool BufferNode::hasNoMarkedAndNoLockedDos

(

)

Returns true if the BufferNode object has any marked or locked descendants or is marked/locked itself.

The type of the marking (cumulative vs. non-cumulative) roles does not play a role.

Return values:

Returns

true if the BufferNode object has any marked or locked descendants or is marked/locked itself.

Definition at line 253 of file buffernode.cpp.

References TagNode::children, BufferNodeList::getFront(), is_locked, isMarked(), node, r_sibling, type, and TYPE_PCDATA.

bool BufferNode::isClosed

(

)

[inline]

Returns true if the associated buffer TagNode is marked as closed, false otherwise.

This method applies only to tag buffer nodes, i.e. requires that the member variable type is set to TYPE_TAG. The caller must assert that this condition holds, otherwise the method is likely to crash (after all, checking for a CharNode to be closed makes no sense).

Returns:

void

Definition at line 214 of file buffernode.h.

Referenced by BufferIterator::getNext(), and BufferIterator::isSatisfyingPath().

bool BufferNode::isCumulativeMarked

(

)

Returns true if the BufferNode object carries a cumulativ role.

The method does not take into consideration cumulative roles of ancestors.

Return values:

bool

Returns true if the BufferNode object carries one or more cumulative roles, false otherwise.

Definition at line 240 of file buffernode.cpp.

References cumulative_roles, and IntMultiSet::isEmpty().

Referenced by clearSubtreeIfPossible(), and hasCumulativeMarkedAncestor().

bool BufferNode::isLocked

(

)

[inline]

Returns true if the buffer node is locked, false otherwise.

This is a simple check for the value of the member variable is_locked.

Return values:

bool

Returns true if the buffer node is locked, false otherwise.

Definition at line 242 of file buffernode.h.

References is_locked.

Referenced by BufferIterator::getNext().

bool BufferNode::isMarked

(

)

Returns true if the BufferNode object carries cumulative or non-cumulative roles.

The method does not take into consideration cumulative roles of ancestors.

Return values:

bool

Returns true if the BufferNode object directly carries cumulative or non-cumulative roles, false otherwise.

Definition at line 231 of file buffernode.cpp.

References cumulative_roles, IntMultiSet::isEmpty(), and non_cumulative_roles.

Referenced by hasNoMarkedAndNoLockedDos().

bool BufferNode::isRoot

(

)

[inline]

Returns true if the buffer node is the document root, false otherwise.

Returns true if the buffer node is the (virtual) XML document root node, i.e. the topmost node in the buffer, false otherwise.

Returns:

bool Returns true if this node is the virtual document root, false otherwise.

Definition at line 252 of file buffernode.h.

References node, TAGID_ROOT, type, and TYPE_TAG.

Referenced by clear(), BufferIterator::debugPrint(), hasCumulativeMarkedAncestor(), and BufferIterator::isSatisfyingPath().

void BufferNode::lock

(

)

[inline]

Locks the BufferNode object.

Locks the BufferNode object by setting the member is_locked to true.

Return values:

void

Definition at line 223 of file buffernode.h.

References is_locked.

Referenced by BufferIterator::getNext().

void BufferNode::print

(

OutputStream &

eos

)

Prints the subtree defined by the BufferNode object.

The output contains no role information. This method can be used for output during regular query evaluation.

Parameters:

[in]

eos

Reference to the (evaluation) OutputStream.

Return values:

void

Definition at line 139 of file buffernode.cpp.

References TagMap::getInstance(), TagMap::getTag(), node, parent, type, TYPE_PCDATA, and TYPE_TAG.

Referenced by VarExpression::eval(), Buffer::print(), and Buffer::printCurrent().

void BufferNode::printNoSubnodes

(

OutputStream &

dos

)

Debug prints the BufferNode without its child nodes.

The output also contains role information, so this method is suited for debug purpose only.

Parameters:

[in]

dos

Reference to the (debug) OutputStream.

Return values:

void

Definition at line 161 of file buffernode.cpp.

References TagMap::getInstance(), TagMap::getTag(), node, type, TYPE_PCDATA, and TYPE_TAG.

Referenced by BufferIterator::debugPrint().

void BufferNode::removeRoleFromNode

(

Role *

role

)

Removes the specified role from the BufferNode object.

Removes the specified role from the BufferNode object and triggers garbage collection, if possible.

Parameters:

[in]

role

Pointer to the Role that is to be removed.

Return values:

void

Definition at line 272 of file buffernode.cpp.

References clear(), cumulative_roles, Role::getId(), Role::isDosRole(), non_cumulative_roles, and IntMultiSet::removeElem().

void BufferNode::unlock

(

)

[inline]

Unlocks the BufferNode object and triggers garbage collection (if possible).

Unlocks the BufferNode object by releasing the member variable is_locked to true. In addition, active garbage collection is triggered.

Return values:

void

Definition at line 233 of file buffernode.h.

References is_locked.

Referenced by BufferIterator::getNext().

---

Member Data Documentation

IntMultiSet * BufferNode::cumulative_roles

The set of cumulative roles.

The IntMultiSet specifying all cumulative roles associated with this buffer node.

Note:

This member variable is used if GCX is compiled with -DROLE_REFCOUNT turned off, which is useful for debugging purpose.

Definition at line 349 of file buffernode.h.

Referenced by appendRoles(), debugPrint(), isCumulativeMarked(), isMarked(), removeRoleFromNode(), and ~BufferNode().

bool BufferNode::is_locked

A flag that can be used to lock the BufferNode.

Locking prevents the BufferNode from being deleted. It is necessary to ensure that nodes referenced by buffer iterators will not be deleted too early, which might cause undefined pointers.

Definition at line 385 of file buffernode.h.

Referenced by clear(), debugPrint(), hasNoMarkedAndNoLockedDos(), isLocked(), lock(), and unlock().

void * BufferNode::node

The content carried by the BufferNode object.

This variable is either of type TagNode* or of type CharNode*, i.e. represents either the character or tag node data. The member variable type serves as a switch and can be queries to cast the node accordingly.

Definition at line 377 of file buffernode.h.

Referenced by addChild(), clear(), clearSubtreeIfPossible(), close(), debugPrint(), BufferIterator::getNext(), getPCDataRepresentation(), hasNoMarkedAndNoLockedDos(), BufferIterator::isMatchingNodeTestAndPredicates(), isRoot(), BufferIterator::isSatisfyingPath(), print(), printNoSubnodes(), and ~BufferNode().

IntMultiSet * BufferNode::non_cumulative_roles

The set of non-cumulative roles.

The IntMultiSet specifying all non-cumulative roles associated with this buffer node.

Note:

This member variable is used if GCX is compiled with -DROLE_REFCOUNT turned off, which is useful for debugging purpose.

Definition at line 368 of file buffernode.h.

Referenced by appendRoles(), debugPrint(), isMarked(), removeRoleFromNode(), and ~BufferNode().

BufferNode * BufferNode::parent

The parent of the buffer node object.

Set to NULL for the document root.

Definition at line 325 of file buffernode.h.

Referenced by clear(), Buffer::closeTag(), debugPrintCompleteBuffer(), BufferIterator::getNext(), hasCumulativeMarkedAncestor(), BufferIterator::isSatisfyingPath(), and print().

BufferNode * BufferNode::r_sibling

The right sibling of the buffer node object.

Set to NULL if no right sibling exists.

Definition at line 331 of file buffernode.h.

Referenced by BufferIterator::getNext(), getPCDataRepresentation(), hasNoMarkedAndNoLockedDos(), BufferIterator::isSatisfyingPath(), BufferNodeList::operator[](), BufferNodeList::print(), BufferNodeList::push_back(), BufferNodeList::removeElem(), and BufferNodeList::~BufferNodeList().

bool BufferNode::type

The type of the buffer node.

The type is either TYPE_TAG or TYPE_PCDATA and serves as a switch for casting the void* node member, either to a TagNode* or CharNode* object.

Definition at line 319 of file buffernode.h.

Referenced by BufferIterator::BufferIterator(), clear(), clearSubtreeIfPossible(), debugPrint(), BufferIterator::debugPrint(), BufferIterator::getNext(), getPCDataRepresentation(), hasNoMarkedAndNoLockedDos(), BufferIterator::init(), BufferIterator::isMatchingNodeTestAndPredicates(), isRoot(), BufferIterator::isSatisfyingPath(), print(), printNoSubnodes(), BufferIterator::reset(), and ~BufferNode().