XmlNodeReader
Class XmlNodeReader

The XmlNodeReader class is meant to be an easy interface for getting data out of XML. Internally it uses a NotesDomParser to process the XML and steps through the DOM tree to read nodes and attributes.

Please see the lsdoc_description sub for usage details and examples, or better yet, download LotusScript.doc from http://www.lsdoc.org and generate some documentation!

Property Summary
Boolean isEmpty (Get)
     Returns True if this object does not contain a base node reference or if the base node's isNull property is True, or False otherwise.
NotesDOMNode thisNode (Get)
     Returns the NotesDomNode that this object uses as its base node.
String thisNodeName (Get)
     Returns the name of the node used as this object's base node.
Methods Summary
Public New()
     Creates a new, empty XmlNodeReader.
Functions Summary
NotesDOMNode findChildNode(node As NotesDOMNode, childName As String, count As Integer)
     Returns the nth child node with a specific name, that is directly beneath the given node.
NotesDOMNode findFirstChildNode(node As NotesDOMNode, childName As String)
     Returns the first child node with a specific name, that is directly beneath the given node.
Public String get(nodePath As String)
     Returns the text of the FIRST node or attribute that matches this node path, if any.
Public Variant getAll(nodePath As String)
     Returns a string array containing the text of ALL nodes or attributes that match this node path, if any.
Public Variant getAttributeNames(nodePath As String)
     Returns a string array containing the name of all attributes for the node that matches this node path, if any.
String getAttributeText(node As NotesDOMNode, attrName As String)
     Returns the text of the given attribute.
Public String getLastError()
     Returns the last error string that was generated internal to this class.
Public NotesDOMNode getNode(nodePath As String)
     Returns the FIRST node that matches this node path as a NotesDomNode.
XmlNodeReader getNodeReader(nodePath As String)
     Returns the FIRST node that matches this node path as an XmlNodeReader.
Variant getNodeReaders(nodePath As String)
     Returns ALL nodes that match this node path as an array of XmlNodeReader.
Public Variant getNodes(nodePath As String)
     Returns ALL nodes that match this node path as an array of NotesDomNode.
String getNodeText(node As NotesDOMNode)
     Returns the text of the given node.
Public Variant getSubNodeNames(nodePath As String)
     Returns a string array containing the name of all child nodes (only direct children, not grandchildren or great-grandchildren or below) of the node that matches this node path, if any.
Private NotesDOMNode GetNodeFromPathArray(parent As NotesDOMNode, nparr As Variant)
     Internal function to get the node described by a node path array, based on the given parent node.
Public XmlNodeReader ReadFile(fileName As String)
     Reads a text file of XML data in to this object for parsing.
Public XmlNodeReader ReadNode(n As NotesDOMNode)
     Reads a NotesDomNode in to this object for parsing.
Public XmlNodeReader ReadStream(s As NotesStream)
     Reads a NotesStream of XML data in to this object for parsing.
Public XmlNodeReader ReadText(txt As String)
     Reads a string of XML data in to this object for parsing.
Private String setLastError(msg As String, error_num As Integer)
     Internal method used to set the private lastError string.

Method Detail

New

Public New()
Creates a new, empty XmlNodeReader. Note that you can still call get(), getNode(), etc. on an empty XmlNodeReader and not generate LotusScript runtime errors -- method calls will simply return empty strings or empty references.

Function Detail

findChildNode

Function findChildNode(node As NotesDOMNode, childName As String, count As Integer) As NotesDOMNode
Returns the nth child node with a specific name, that is directly beneath the given node. For example, if a "bookshelf" node has 5 "book" nodes beneath it, you would use a count parameter of 1 to get the first book, 2 to get the second book, etc. This will NOT find child nodes that are more than one level beneath the given node. Also, the node name being searched for is NOT case-sensitive, to prevent silly errors.

findFirstChildNode

Function findFirstChildNode(node As NotesDOMNode, childName As String) As NotesDOMNode
Returns the first child node with a specific name, that is directly beneath the given node. This will NOT find child nodes that are more than one level beneath the given node. Also, the node name being searched for is NOT case-sensitive, to prevent silly errors.

get

Public Function get(nodePath As String) As String
Returns the text of the FIRST node or attribute that matches this node path, if any. An empty string is returned if the node or attribute is not found.

getAll

Public Function getAll(nodePath As String) As Variant
Returns a string array containing the text of ALL nodes or attributes that match this node path, if any. An array containing a single empty string is returned if the node or attribute is not found.

getAttributeNames

Public Function getAttributeNames(nodePath As String) As Variant
Returns a string array containing the name of all attributes for the node that matches this node path, if any. An array containing a single empty string is returned if the node is not found, or if there are no attributes.

getAttributeText

Function getAttributeText(node As NotesDOMNode, attrName As String) As String
Returns the text of the given attribute. If the node is not valid or the attribute is not found, an empty string is returned. The attribute name is NOT case-sensitive, to prevent silly errors.

getLastError

Public Function getLastError() As String
Returns the last error string that was generated internal to this class. If a parsing error occurred when the initial Read operation was performed, this will always return the parsing error. Note that error strings other than the parse error are cleared at the start of each Get-type method call, so if an error happens at one Get and then a second Get is successful then the last error string will be empty.

getNode

Public Function getNode(nodePath As String) As NotesDOMNode
Returns the FIRST node that matches this node path as a NotesDomNode. An uninitialized node is returned if the node is not found, so check for "node Is Nothing" on the return value.

getNodeReader

Function getNodeReader(nodePath As String) As XmlNodeReader
Returns the FIRST node that matches this node path as an XmlNodeReader. An empty XmlNodeReader is returned if the node is not found, so check for "reader.IsEmpty" on the return value.

getNodeReaders

Function getNodeReaders(nodePath As String) As Variant
Returns ALL nodes that match this node path as an array of XmlNodeReader. An array containing a single empty XmlNodeReader is returned if the node is not found.

getNodes

Public Function getNodes(nodePath As String) As Variant
Returns ALL nodes that match this node path as an array of NotesDomNode. An array containing a single uninitialized node is returned if the node is not found.

getNodeText

Function getNodeText(node As NotesDOMNode) As String
Returns the text of the given node. If the node is not valid, an empty string is returned. If there are subnodes and whitespace in the formatting of the XML between subnodes, the concatenated whitespace will be returned as well. However, only the text directly beneath the node will be returned, not the text beneath any subnodes.

getSubNodeNames

Public Function getSubNodeNames(nodePath As String) As Variant
Returns a string array containing the name of all child nodes (only direct children, not grandchildren or great-grandchildren or below) of the node that matches this node path, if any. An array containing a single empty string is returned if the node is not found, or there are no child nodes.

GetNodeFromPathArray

Private Function GetNodeFromPathArray(parent As NotesDOMNode, nparr As Variant) As NotesDOMNode
Internal function to get the node described by a node path array, based on the given parent node. Normally the parent node will be the internal mynode reference, but it might be useful later if we add a method like getSubnodeArray("feed.entry", "author") to get all subnodes of a set of all nodes that match a path.

ReadFile

Public Function ReadFile(fileName As String) As XmlNodeReader
Reads a text file of XML data in to this object for parsing. Note that if there is ANY leading whitespace at the beginning of the file, parsing will probably fail.

ReadNode

Public Function ReadNode(n As NotesDOMNode) As XmlNodeReader
Reads a NotesDomNode in to this object for parsing.

ReadStream

Public Function ReadStream(s As NotesStream) As XmlNodeReader
Reads a NotesStream of XML data in to this object for parsing. Note that if there is ANY leading whitespace at the beginning of the stream, parsing will probably fail.

ReadText

Public Function ReadText(txt As String) As XmlNodeReader
Reads a string of XML data in to this object for parsing.

setLastError

Private Function setLastError(msg As String, error_num As Integer) As String
Internal method used to set the private lastError string. By default, errors that occur inside of this class are handled and discarded silently. If you want to add error logging or notification, or if you'd rather throw runtime errors instead of ignoring them, you should modify this method (or, a better way is to create a subclass of this class and override the method).