VTD-XML: The Future of XML Processing

SourceForge.net Logo

Sourceforge Home

Mailing Lists





4.Classes/Interfaces and Methods

Important Classes/Interfaces

Essential Classes

  • VTD Generator: VTDGen is the class that encapsulates the main parsing, index loading and index reading functions

  • VTD Navigator: VTDNav is the class that (1) encapsulates XML, VTD, and hierarchical info (2) contains various navigation functions (3) performs various comparison and VTD to string or numerical data conversion functions

  • Autopilot: A class containing functions that perform node-level iteration and XPath.

  • XMLModifier: A class that takes advantage of VTD-XML's incremental update capability

Other Classes/Interfaces

  • ILongBuffer: This is the interface for VTD record container.

  • FastLongBuffer: This class implements ILongBuffer interface. Under the hood, it is a chunk-based buffer that will grow automatically.

  • NodeRecorder: Save the node location.

  • BookMark: A hashable, comparable way of saving a single copy of cursor position.

  • TextIterator: This class allows one to access text nodes in a mix-content document.

  • ParseException: The root class for any exception conditions during parse

  • NavException: The root class for any exceptions during navigation

  • XPathEvalException: Thrown when there is something during XPath evaluation

  • XPathParseException: Thrown when an error occurred during the construction of XPathExpr

  • XMLModiferException: Thrown when there is an exception condition during the modification of XML document

Member methods of VTDNav

In this sub-section, we categorize and selectively annotate member methods of VTDNav.

  1. Methods designed for hierarchical view of VTD

    • Navigate the cursor
      * boolean toElement(int direction);
      * boolean toElement(int direction, String elementName);
      * boolean toElementNS(int direction, String URL, String local_name);

    • About the element at the cursor position
      * int getCurrentIndex()                    // return the VTD index of the current element
      * int getCurrentDepth()                    // return depth of current element
      * boolean matchElement(String s);    // match the element name (of the cursor) against a string value
      * boolean matchElementNS(String s); // match the element name (name space aware)

    * boolean matchTokens(int i1,VTDNav vn1, int i2); // match the element name (name space aware)

    • Attributes, Text, and CDATA
      * int getAttrVal(String attrName);
      * int getAttrValNS(String URL, String localName);
      * boolean hasAttr(String attrName);
      * boolean hasAttrNs(String URL, String localName);
      * int getText()            // return the index value of the text value (character data or CDATA), -1 if none found

    • Helper function
      * void push();
      * boolean pop();

    • Address an element fragment
      * long getElementFragment(); // get the length and offset of the element fragment;
                                                  // upper 32 bits length lower 32 bits offset

  2. Methods for individual VTD records

    • Comparison
      * boolean matchRawTokenString(int, String); // Match the token against a string, entities and char
                                        // references are not resolved
      * boolean matchTokenString(int, String); // match the token against a string, entities and char
                                     // references are resolved
      * boolean matchTokens(int i1, VTDNav vn2,int i2) // match two VTD tokens

      * int compareRawTokenString(int, String); //lexically compare a VTD token with a string, returns
      // 1, 0 or -1
      * int compareTokenString(int, String); //lexically compare a VTD token with a string, returns
      // 1, 0 or -1
      * int compareTokens(int, VTDNav vn2, int); // lexically compare two VTD tokens


    • Query token parameters
      * int getTokenDepth(int index);
      * int getTokenLength(int index);
      * int getTokenOffset(int index);
      * int getTokenType(int index);

    • Token to String conversion
      * String toRawString(int index);            // entities and char references not resolved
      * String toString(int index);                  // entities and char reference resolved
      * String toNormalizedString(int index);  // Normalized

    • Tokens to numerical data conversion
      * int parseInt(int index);
      * long parseLong(int index);
      * float parseFloat(int index);
      * double parseDouble(int index);

    • Properties of XML and VTD
      * int getRootIndex();                   // Return the VTD index for the root element
      * IByteBuffer getXML();                // Get the document buffer
      * int getTokenCount();                 // Get the total number of VTD tokens


  3. Methods for writing/loading index

    • Index writing

    *void writeIndex(OutputStream os);
    *void writeIndex(String FileName);

    • Index loading

    *VTDNav loadIndex(InputStream is);
    loadIndex(String FileName);
    loadIndex(byte[] ba);

  4. Methods of AutoPilot for Doing Node Iteration

    • Select Elements
      * void selectElement(String elementName); // select element name before iterating
      * void selectElementNS(String URL, String elementName);       // the namespace aware version

    • Iterate the nodes
      * boolean iterate();


  5. Methods of AutoPilot for XPath

    • Select XPath
      * void declareXPathNameSpace(String attrName);
      * void selectXPath(String XPathExpr);    // compile the XPath string

    • Evaluate XPath

    * int evalXPath();  // evaluate XPath and moves the cursor to various locations of the document
    * double evalXPathToNumber(); // evaluate XPath to a double
    * String evalXPathToString();  //evaluate XPath to a string
    * boolean evalXPathToBoolean(); // evaluate XPath to a boolean

    • Other Methods
      * void resetXPath();      // call this function will reset the internal state of XPath for reuse
      * void bind(VTDNav vn); //bind  VTDNav to an autoPilot


  6. Methods for XMLModifier

  • Remove

    *void remove()
    *void removeAttribute(String attrName)
    *void removeToken(int i)

  • Insert

    *void insertAfterElement(String s)
    *void insertAfterElement(byte[] ba)
    *void insertBeforeElement(String s)
    *void insertBeforeElement(byte[] ba)
    *void insertAttribute(String s);
    *void insertAttribute(byte[] ba);


  • Update

*void updateToken(byte[] b);
*void updateToken(String s);

  • Other Methods

*output(OutputStream os);

VTD in 30 seconds

VTD+XML Format

User's Guide

  0. Introduction

  1. Goals and Features   

  2. How to Process XML

  3. Navigate VTD

  4. Classes/Interfaces and Methods

  5. Comparison with DOM,  SAX, and Pull

  6. Table for Token Types

 7. The C version VTD-XML

Developer's Guide

VTD: A Technical Perspective

Code Samples


Getting Involved

Articles and Presentations