#include <DbXml.hpp>

class DbXml::XmlDebugListener {
public:
    virtual ~XmlDebugListener()
    virtual void start(const XmlStackFrame *stack)
    virtual void end(const XmlStackFrame *stack)
    virtual void enter(const XmlStackFrame *stack)
    virtual void exit(const XmlStackFrame *stack)
    virtual void error(const XmlException &error, 
                       const XmlStackFrame *stack)
}; 

The XmlDebugListener class allows the user to track the progress of a query as it executes. The XmlStackFrame argument to the methods of this class gives access to the point in the query plan corresponding to the current execution state, as well as the execution stack trace and parts of the dynamic context for that stack frame.

During evaluation of a query, BDB XML will evaluate the sub-expressions of the query. The XmlDebugListener::start() method is called when evaluation of a sub-expression starts and the XmlDebugListener::end() method is called when it ends. This can occur more than once for the same sub-expression if the expression is in a loop or in a function that is called more than once.

When evaluating a sub-expression BDB XML calls into that sub-expression a number of times to retrieve parts of its result. For eager evaluation, this will happen only once, but for lazy evalution this will happen once per item in the result. The XmlDebugListener::enter() method is called when BDB XML requests results from a sub-expression and the XmlDebugListener::exit() method is called when the results requested have been calculated.