Rudiments: cursordomnode Class Reference

Rudiments

Public Member Functions | List of all members
cursordomnode Class Reference

Inherits domnode.

## Public Member Functions
| cursordomnode (dom *dom, domnode *nullnode)
| cursordomnode (dom *dom, domnode *nullnode, const char *ns)
virtual | ~cursordomnode ()
virtual domnodetype | getType () const
virtual const char * | getName () const
virtual const char * | getValue () const
virtual domnode * | getParent () const
virtual uint64_t | getPosition () const
virtual domnode * | getPreviousSibling () const
virtual domnode * | getNextSibling () const
virtual uint64_t | getChildCount () const
virtual domnode * | getFirstChild () const
virtual uint64_t | getAttributeCount () const
virtual domnode * | getAttribute (const char *name) const
virtual domnode * | getAttributeIgnoringCase (const char *name) const
virtual domnode * | getAttribute (uint64_t position) const
virtual bool | isNullNode () const
Public Member Functions inherited from domnode
| domnode (dom *dom, domnode *nullnode)
| domnode (dom *dom, domnode *nullnode, domnodetype type, const char *name, const char *value)
| domnode (dom *dom, domnode *nullnode, domnodetype type, const char *ns, const char *name, const char *value)
virtual | ~domnode ()
void | cascadeOnDelete ()
void | dontCascadeOnDelete ()
virtual const char * | getNamespace () const
dom * | getTree () const
domnode * | getPreviousTagSibling () const
domnode * | getPreviousTagSibling (const char *name) const
domnode * | getPreviousTagSibling (const char *ns, const char *name) const
domnode * | getPreviousTagSiblingIgnoringCase (const char *name) const
domnode * | getPreviousTagSiblingIgnoringCase (const char *ns, const char *name) const
domnode * | getPreviousTagSibling (const char *name, const char *attributename, const char *attributevalue) const
domnode * | getPreviousTagSibling (const char *ns, const char *name, const char *attributename, const char *attributevalue) const
domnode * | getPreviousTagSiblingIgnoringCase (const char *name, const char *attributename, const char *attributevalue) const
domnode * | getPreviousTagSiblingIgnoringCase (const char *ns, const char *name, const char *attributename, const char *attributevalue) const
domnode * | getNextTagSibling () const
domnode * | getNextTagSibling (const char *name) const
domnode * | getNextTagSibling (const char *ns, const char *name) const
domnode * | getNextTagSiblingIgnoringCase (const char *name) const
domnode * | getNextTagSiblingIgnoringCase (const char *ns, const char *name) const
domnode * | getNextTagSibling (const char *name, const char *attributename, const char *attributevalue) const
domnode * | getNextTagSibling (const char *ns, const char *name, const char *attributename, const char *attributevalue) const
domnode * | getNextTagSiblingIgnoringCase (const char *name, const char *attributename, const char *attributevalue) const
domnode * | getNextTagSiblingIgnoringCase (const char *ns, const char *name, const char *attributename, const char *attributevalue) const
domnode * | getNextTagSiblingInSet (const char *const *set) const
domnode * | getNextTagSiblingInSet (const char *ns, const char *const *set) const
domnode * | getFirstChild (const char *name) const
domnode * | getFirstChild (const char *ns, const char *name) const
domnode * | getFirstChildIgnoringCase (const char *name) const
domnode * | getFirstChildIgnoringCase (const char *ns, const char *name) const
domnode * | getChild (uint64_t position) const
domnode * | getFirstChild (const char *name, const char *attributename, const char *attributevalue) const
domnode * | getFirstChild (const char *ns, const char *name, const char *attributename, const char *attributevalue) const
domnode * | getFirstChildIgnoringCase (const char *name, const char *attributename, const char *attributevalue) const
domnode * | getFirstChildIgnoringCase (const char *ns, const char *name, const char *attributename, const char *attributevalue) const
domnode * | getFirstTagChild () const
domnode * | getFirstTagChild (const char *name) const
domnode * | getFirstTagChild (const char *ns, const char *name) const
domnode * | getFirstTagChildIgnoringCase (const char *name) const
domnode * | getFirstTagChildIgnoringCase (const char *ns, const char *name) const
domnode * | getFirstTagChild (const char *name, const char *attributename, const char *attributevalue) const
domnode * | getFirstTagChild (const char *ns, const char *name, const char *attributename, const char *attributevalue) const
domnode * | getFirstTagChildIgnoringCase (const char *name, const char *attributename, const char *attributevalue) const
domnode * | getFirstTagChildIgnoringCase (const char *ns, const char *name, const char *attributename, const char *attributevalue) const
domnode * | getFirstTagChildInSet (const char *const *set) const
domnode * | getFirstTagChildInSet (const char *ns, const char *const *set) const
domnode * | getFirstTagDescendent (const char *name) const
domnode * | getFirstTagDescendent (const char *ns, const char *name) const
domnode * | getFirstTagDescendentIgnoringCase (const char *name) const
domnode * | getFirstTagDescendentIgnoringCase (const char *ns, const char *name) const
domnode * | getFirstTagDescendent (const char *name, const char *attributename, const char *attributevalue) const
domnode * | getFirstTagDescendent (const char *ns, const char *name, const char *attributename, const char *attributevalue) const
domnode * | getFirstTagDescendentIgnoringCase (const char *name, const char *attributename, const char *attributevalue) const
domnode * | getFirstTagDescendentIgnoringCase (const char *ns, const char *name, const char *attributename, const char *attributevalue) const
domnode * | getFirstTagDescendentInSet (const char *const *set) const
domnode * | getFirstTagDescendentInSet (const char *ns, const char *const *set) const
domnode * | getNextTag () const
domnode * | getNextTag (domnode *top) const
domnode * | getPreviousTag () const
domnode * | getPreviousTag (domnode *top) const
const char * | getAttributeValue (const char *name) const
const char * | getAttributeValue (uint64_t position) const
constnamevaluepairs * | getAttributes () const
void | setAttributeValue (const char *name, const char *value)
void | setAttributeValue (const char *name, int64_t value)
void | setAttributeValue (const char *name, uint64_t value)
domnode * | getNullNode () const
virtual void | setType (domnodetype type)
virtual void | setNamespace (const char *ns)
virtual void | setName (const char *name)
void | setName (const char *ns, const char *name)
virtual void | setValue (const char *value)
virtual void | setParent (domnode *parent)
virtual void | setPreviousSibling (domnode *previous)
virtual void | setNextSibling (domnode *next)
bool | insertChild (domnode *child, uint64_t position)
bool | appendChild (domnode *child)
domnode * | insertTag (const char *tag, uint64_t position)
domnode * | insertTag (const char *ns, const char *tag, uint64_t position)
domnode * | appendTag (const char *tag)
domnode * | appendTag (const char *ns, const char *tag)
bool | moveChild (domnode *child, domnode *parent, uint64_t position)
bool | deleteChild (uint64_t position)
bool | deleteChild (domnode *child)
bool | deleteFirstChild (const char *name)
bool | deleteFirstChild (const char *ns, const char *name)
bool | deleteFirstChildIgnoringCase (const char *name)
bool | deleteFirstChildIgnoringCase (const char *ns, const char *name)
bool | deleteFirstChild (const char *name, const char *attributename, const char *attributevalue)
bool | deleteFirstChild (const char *ns, const char *name, const char *attributename, const char *attributevalue)
bool | deleteFirstChildIgnoringCase (const char *name, const char *attributename, const char *attributevalue)
bool | deleteFirstChildIgnoringCase (const char *ns, const char *name, const char *attributename, const char *attributevalue)
bool | deleteChildren ()
bool | deleteChildren (const char *name)
bool | deleteChildren (const char *ns, const char *name)
bool | deleteChildrenIgnoringCase (const char *name)
bool | deleteChildrenIgnoringCase (const char *ns, const char *name)
bool | deleteChildren (const char *name, const char *attributename, const char *attributevalue)
bool | deleteChildren (const char *ns, const char *name, const char *attributename, const char *attributevalue)
bool | deleteChildrenIgnoringCase (const char *name, const char *attributename, const char *attributevalue)
bool | deleteChildrenIgnoringCase (const char *ns, const char *name, const char *attributename, const char *attributevalue)
bool | deleteDescendents (const char *name)
bool | deleteDescendents (const char *ns, const char *name)
bool | deleteDescendentsIgnoringCase (const char *name)
bool | deleteDescendentsIgnoringCase (const char *ns, const char *name)
bool | deleteDescendents (const char *name, const char *attributename, const char *attributevalue)
bool | deleteDescendents (const char *ns, const char *name, const char *attributename, const char *attributevalue)
bool | deleteDescendentsIgnoringCase (const char *name, const char *attributename, const char *attributevalue)
bool | deleteDescendentsIgnoringCase (const char *ns, const char *name, const char *attributename, const char *attributevalue)
bool | renameFirstChild (const char *oldname, const char *newname)
bool | renameFirstChild (const char *oldns, const char *oldname, const char *newns, const char *newname)
bool | renameFirstChildIgnoringCase (const char *oldname, const char *newname)
bool | renameFirstChildIgnoringCase (const char *oldns, const char *oldname, const char *newns, const char *newname)
bool | renameChildren (const char *oldname, const char *newname)
bool | renameChildren (const char *oldns, const char *oldname, const char *newns, const char *newname)
bool | renameChildrenIgnoringCase (const char *oldname, const char *newname)
bool | renameChildrenIgnoringCase (const char *oldns, const char *oldname, const char *newns, const char *newname)
bool | renameDescendents (const char *oldname, const char *newname)
bool | renameDescendents (const char *oldns, const char *oldname, const char *newns, const char *newname)
bool | renameDescendentsIgnoringCase (const char *oldname, const char *newname)
bool | renameDescendentsIgnoringCase (const char *oldns, const char *oldname, const char *newns, const char *newname)
bool | insertText (const char *value, uint64_t position)
bool | appendText (const char *value)
bool | insertAttribute (domnode *attribute, uint64_t position)
bool | appendAttribute (domnode *attribute)
bool | insertAttribute (const char *name, const char *value, uint64_t position)
bool | appendAttribute (const char *name, const char *value)
bool | deleteAttribute (uint64_t position)
bool | deleteAttribute (const char *name)
bool | deleteAttribute (domnode *attribute)
bool | unwrapChild (domnode *child)
bool | unwrapFirstChild (const char *name)
bool | unwrapFirstChild (const char *ns, const char *name)
bool | unwrapFirstChildIgnoringCase (const char *name)
bool | unwrapFirstChildIgnoringCase (const char *ns, const char *name)
bool | unwrapChildren (const char *name)
bool | unwrapChildren (const char *ns, const char *name)
bool | unwrapChildrenIgnoringCase (const char *name)
bool | unwrapChildrenIgnoringCase (const char *ns, const char *name)
bool | unwrapDescendents (const char *name)
bool | unwrapDescendents (const char *ns, const char *name)
bool | unwrapDescendentsIgnoringCase (const char *name)
bool | unwrapDescendentsIgnoringCase (const char *ns, const char *name)
domnode * | wrapChild (domnode *child, const char *name)
domnode * | wrapChild (domnode *child, const char *ns, const char *name)
domnode * | wrapChildren (domnode *startchild, domnode *endchild, const char *name)
domnode * | wrapChildren (domnode *startchild, domnode *endchild, const char *ns, const char *name)
domnode * | wrapChildren (const char *name)
domnode * | wrapChildren (const char *ns, const char *name)
virtual domnode * | clone ()
virtual domnode * | clone (dom *dom)
void | write (output *out) const
void | write (output *out, bool indent) const
stringbuffer * | getPath () const
domnode * | getChildByPath (const char *path) const
domnode * | getAttributeByPath (const char *path, uint64_t position) const
domnode * | getAttributeByPath (const char *path, const char *name) const
const char * | getAttributeValueByPath (const char *path, uint64_t position) const
const char * | getAttributeValueByPath (const char *path, const char *name) const
void | setData (void *data)
void * | getData ()

## Additional Inherited Members
Static Public Member Functions inherited from domnode
static domnode * | createNullNode (dom *dom)

## Detailed Description

The cursordomnode class provides a base class for a special kind of domnode which allows data from a backend data store to be embedded in a dom tree without having to actually copy the data into memory.

A normal domnode has child nodes, which can be accessed via methods like getFirstChild(), getFirstTagChild(), getChild(n), etc. Once you have accessed a child node, you can access its children in a similar manner, or step between its siblings using methods like getNextSibling(), getNextTagSibling(), getPreviousSibling(), getPreviousTagSibling(), etc. Each node returned by one of the above mentioned methods is distinct from the node that the method was called on.

A cursordomnode provides this same interface to an arbitrary backend data source, via a single domnode, by stepping a "cursor" through the data source.

For example, a sql result might have a structure similar to:

resultset { columns { column: "user_id" column: "name" column: "description" } rows { row { field: "0" field: "car" field: "A small vehicle for driving around." } row { field: "0" field: "truck" field: "A large vehicle for hauling cargo." } } }

A child class of cursordomnode that implements the cursordomnode interface for a sql result set would step a virtual "cursor" through the different parts of the result set and calls to other domnode methods would return the data at that location.

For example, the cursor would be initially positioned on "resultset".

-> resultset { columns { ... } rows { ... } }

Calling getFirstChild() would position the cursor on "columns".

resultset { -> columns { ... } rows { ... } }

Calling getNextSibling() would position the cursor on "rows".

resultset { columns { ... } -> rows { ... } }

Calling getParent() would position the cursor back on "resultset", and so on.

If the cursor is positioned on a "column" or "field" then getAttributeValue() might be implemented to return the column name or field value.

It is important to note that since this is all being implemented by a single domnode, which just steps a virtual cursor around a backend data store, that each of the getParent(), getNext/PreviousChild(), etc. calls all return the SAME domnode.

For example, in the code: domnode *node=...some cursordomnode...; ... domnode *child=node->getFirstChild(); domnode *next=child->getNextSibling(); domnode *prev=child->getPreviousSibling();

"node", "child", "next", and "prev" would all point to the same node. The calls just cause the domnode to move its cursor around the backend data store. As such, it isn't possible to access two parts of the data store simultaneously, without copying them out.

There are two caveats to this behavior, but they should be intiutive:

- If the cursor is positioned on the top-level virtual node, then calls to getParent(), getNextSibling(), getPreviousSibling(), etc. will return legitimate parent or sibling nodes.
- If the cursor is stepped off of the end or beginning of something (eg. if it is positioned on the last row and getNextSibling() is called) then the call will return the nullnode.

Since most of the data is provided by a backend data store, a possibly-unintuitive consequence is that the cursordomnode is generally read-only. The namespace can be set, but any attempt to set the type, name, or value, to set attribute values, or to insert, delete, or move nodes will fail.

So, how is this useful?

Dom trees are traditionally stored entirely in-memory. As mentioned above, the cursordomnode provides a framework for embedding data from a backend data store in a dom tree without having to actually copy the data into memory.

An example use case would be to embed an instance of a child of cursordomnode that represents a sql result set into a larger dom and then call dom->write(socketfd) to send the entire dom to a web browser across a socket. Without a cursordomnode, the entire result set would have to be copied into the dom (and this into memory) before it could be sent. With a cursordomnode, each value in the sql result set would be fetched and sent, on-demand, without having to copy anything in the dom.

Again, it is important to note that the cursordomnode class itself is just a base class. The default implementations of its members do nothing and are intended to be overriden in a data-source-specific manner by a child class.

## Constructor & Destructor Documentation

## ◆ cursordomnode() [1/2]

cursordomnode::cursordomnode | ( | dom * | dom,
|  | domnode * | nullnode
| ) |  |

Creates a new node and intializes its member variables to NULL.

## ◆ cursordomnode() [2/2]

cursordomnode::cursordomnode | ( | dom * | dom,
|  | domnode * | nullnode,
|  | const char * | ns
| ) |  |

Creates a new node and intializes its member variables to NULL.

## ◆ ~cursordomnode()

virtual cursordomnode::~cursordomnode | ( |  | ) |
| virtual

Deletes the node, all attribute nodes and optionally all child nodes, recursively.

## Member Function Documentation

## ◆ getAttribute() [1/2]

virtual domnode* cursordomnode::getAttribute | ( | const char * | name | ) | const
| virtual

Returns the attribute named "name" or the nullnode if not found.

Reimplemented from domnode.

## ◆ getAttribute() [2/2]

virtual domnode* cursordomnode::getAttribute | ( | uint64_t | position | ) | const
| virtual

Returns the attribute node at index "position" or the nullnode if not found.

Reimplemented from domnode.

## ◆ getAttributeCount()

virtual uint64_t cursordomnode::getAttributeCount | ( |  | ) | const
| virtual

Returns the number of attributes.

Reimplemented from domnode.

## ◆ getAttributeIgnoringCase()

virtual domnode* cursordomnode::getAttributeIgnoringCase | ( | const char * | name | ) | const
| virtual

Returns the attribute named "name" (ignoring case) or the nullnode if not found.

Reimplemented from domnode.

## ◆ getChildCount()

virtual uint64_t cursordomnode::getChildCount | ( |  | ) | const
| virtual

Returns the number of immediate child nodes.

Reimplemented from domnode.

## ◆ getFirstChild()

virtual domnode* cursordomnode::getFirstChild | ( |  | ) | const
| virtual

Returns the first child node or the nullnode if no children are found.

Reimplemented from domnode.

## ◆ getName()

virtual const char* cursordomnode::getName | ( |  | ) | const
| virtual

Returns the name of the node.

Reimplemented from domnode.

## ◆ getNextSibling()

virtual domnode* cursordomnode::getNextSibling | ( |  | ) | const
| virtual

Returns a pointer to the next sibling node or the nullnode if none exists.

Reimplemented from domnode.

## ◆ getParent()

virtual domnode* cursordomnode::getParent | ( |  | ) | const
| virtual

Returns a pointer to the parent node or the nullnode if none exists.

Reimplemented from domnode.

## ◆ getPosition()

virtual uint64_t cursordomnode::getPosition | ( |  | ) | const
| virtual

Returns the position of the node, relative to its siblings.

Reimplemented from domnode.

## ◆ getPreviousSibling()

virtual domnode* cursordomnode::getPreviousSibling | ( |  | ) | const
| virtual

Returns a pointer to the previous sibling node or the nullnode if none exists.

Reimplemented from domnode.

## ◆ getType()

virtual domnodetype cursordomnode::getType | ( |  | ) | const
| virtual

Returns the type of the node.

Reimplemented from domnode.

## ◆ getValue()

virtual const char* cursordomnode::getValue | ( |  | ) | const
| virtual

Returns the value of node.

Reimplemented from domnode.

## ◆ isNullNode()

virtual bool cursordomnode::isNullNode | ( |  | ) | const
| virtual

Returns true if this node is the special nullnode and false otherwise.

Reimplemented from domnode.