com.ximpleware
Class VTDNav

java.lang.Object
  extended by com.ximpleware.VTDNav

public class VTDNav
extends java.lang.Object

The VTD Navigator allows one to navigate XML document represented in VTD records and Location caches. There is one and only one cursor that you can navigate to any part of the tree. If a method operating on a node doesn't accept the node as input, by default it refers to the cursor element. The hierarchy consists entirely of elements.


Nested Class Summary
 class VTDNav.helper
           
 
Field Summary
static int FC
           
static int FIRST_CHILD
           
static int FORMAT_ASCII
           
static int FORMAT_ISO_8859_1
           
static int FORMAT_ISO_8859_10
           
static int FORMAT_ISO_8859_11
           
static int FORMAT_ISO_8859_12
           
static int FORMAT_ISO_8859_13
           
static int FORMAT_ISO_8859_14
           
static int FORMAT_ISO_8859_15
           
static int FORMAT_ISO_8859_16
           
static int FORMAT_ISO_8859_2
           
static int FORMAT_ISO_8859_3
           
static int FORMAT_ISO_8859_4
           
static int FORMAT_ISO_8859_5
           
static int FORMAT_ISO_8859_6
           
static int FORMAT_ISO_8859_7
           
static int FORMAT_ISO_8859_8
           
static int FORMAT_ISO_8859_9
           
static int FORMAT_UTF_16BE
           
static int FORMAT_UTF_16LE
           
static int FORMAT_UTF8
           
static int FORMAT_WIN_1250
           
static int FORMAT_WIN_1251
           
static int FORMAT_WIN_1252
           
static int FORMAT_WIN_1253
           
static int FORMAT_WIN_1254
           
static int FORMAT_WIN_1255
           
static int FORMAT_WIN_1256
           
static int FORMAT_WIN_1257
           
static int FORMAT_WIN_1258
           
static int LAST_CHILD
           
static int LC
           
static int NEXT_SIBLING
           
static int NS
           
static int P
           
static int PARENT
           
static int PREV_SIBLING
           
static int PS
           
static int R
           
static int ROOT
           
static int STRING_NORMALIZED
           
static int STRING_RAW
           
static int STRING_REGULAR
           
static int TOKEN_ATTR_NAME
           
static int TOKEN_ATTR_NS
           
static int TOKEN_ATTR_VAL
           
static int TOKEN_CDATA_VAL
           
static int TOKEN_CHARACTER_DATA
           
static int TOKEN_COMMENT
           
static int TOKEN_DEC_ATTR_NAME
           
static int TOKEN_DEC_ATTR_VAL
           
static int TOKEN_DOCUMENT
           
static int TOKEN_DTD_VAL
           
static int TOKEN_ENDING_TAG
           
static int TOKEN_PI_NAME
           
static int TOKEN_PI_VAL
           
static int TOKEN_STARTING_TAG
           
static short XPATH_STRING_MODE_LOWERCASE
           
static short XPATH_STRING_MODE_NORMAL
           
static short XPATH_STRING_MODE_UPPERCASE
           
 
Method Summary
 VTDNav cloneNav()
          Clone the VTDNav instance to get with shared XML, VTD and LC buffers The node position is also copied from the original instance
 int compareRawTokenString(int index, java.lang.String s)
          New in 2.0 Compare the string against the token at the given index value.
 int compareTokens(int i1, VTDNav vn2, int i2)
          New in 2.0 This method compares two VTD tokens of VTDNav objects The behavior of this method is like compare the strings corresponds to i1 and i2, meaning for text or attribute val, entities will be converted into the corresponding char, return 0 if two tokens are the identical when converted to Unicode String using toString() respectively
 int compareTokenString(int index, java.lang.String s)
          New in 2.0 Compare the string against the token at the given index value.
 boolean contains(int index, java.lang.String s)
          Test whether a given token contains s.
 void dumpElementFragmentNs(java.lang.String fileName)
          New in v2.12 Dump the ns compensated element fragment of xml into an XML file whose name is specified as fileName
 void dumpFragment(long l, java.io.OutputStream os)
          New in v2.12 Dump a fragement as specified by a long into an output stream
 void dumpFragment(long l, java.lang.String fileName)
          New in v2.12
 void dumpFragment(java.io.OutputStream os)
          New in v2.12 Dump an element fragment of xml into an output stream
 void dumpFragment(java.lang.String fileName)
          New in v2.12 Dump an element fragment of xml into an XML file whose name is specified as fileName
 void dumpState()
           
 void dumpXML(java.io.OutputStream os)
          Dump the in memory XML text into output stream
 void dumpXML(java.lang.String fileName)
          Dump the in-memory copy of XML text into a file
 VTDNav duplicateNav()
          Duplicate the VTDNav instance with shared XML, VTD and LC buffers This method may be useful for parallel XPath evaluation The node Position is at root element
 boolean endsWith(int index, java.lang.String s)
          Test the end of token content at index i matches the content of s, notice that this is to save the string allocation cost of using String's built-in endsWidth
 long expandWhiteSpaces(long l)
          New in v2.12 This method will take a segment descriptor and return a new descriptor that includes all the leading and trailing white spaces around the input segment It has no effect on CDATA A typical usage would be 'expandWhiteSpaces(getElementFragment())'
 void fillXPathString(FastIntBuffer indexBuffer, FastIntBuffer countBuffer)
           
 int getAttrCount()
          Return the attribute count of the element at the cursor position.
 int getAttrVal(java.lang.String an)
          Get the token index of the attribute value given an attribute name.
 int getAttrValNS(java.lang.String URL, java.lang.String ln)
          Get the token index of the attribute value of given URL and local name.
 long getContentFragment()
          Get content fragment returns a long encoding the offset and length of the byte segment of the content of current element, which is the byte segment between the starting tag and ending tag, -1 is returned if the current element is an empty element
 int getCurrentDepth()
          Get the depth (>=0) of the current element.
 int getCurrentIndex()
          Get the index value of the current element.
 long getElementFragment()
          Get the starting offset and length of an element encoded in a long, upper 32 bits is length; lower 32 bits is offset Unit is in byte.
 ElementFragmentNs getElementFragmentNs()
          getElementFragmentNS returns a ns aware version of the element fragment encapsulated in an ElementFragment object
 int getEncoding()
          Get the encoding of the XML document.
 long getIndexsize()
          Precompute the size of VTD+XML index
 int getNestingLevel()
          Get the maximum nesting depth of the XML document (>0).
 int getNormalizedStringLength(int index)
          Get the string length of a token as if it is converted into a normalized UCS string
 long getOffsetAfterHead()
          Return the charater (not byte) offset after head (the ending bracket of the starting tag, not including an empty element, in which case 0xffffffff 00000000 | len is returned)
 java.lang.String getPrefixString(int i)
          Return the prefix of a token as a string if the token is of the type of starting tag, attribute name, if the the prefix doesn't exist, a null string is returned; otherwise a null string is returned
 int getRawStringLength(int index)
          Get the string length as if the token is converted into a UCS string (entity not resolved)
 int getRootIndex()
          Get root index value , which is the index val of root element
 long getSiblingElementFragments(int i)
          Return the byte offset and length of up to i sibling fragments.
 int getStringLength(int index)
          getStringLength return the string length of a token as if the token is converted into a string (entity resolved for character data and attr val)
 int getText()
          This method returns of the token index of the type character data or CDATA.
 int getTokenCount()
          Get total number of VTD tokens for the current XML document.
 int getTokenDepth(int index)
          Get the depth value of a token (>=0).
 int getTokenLength(int index)
          Get the token length at the given index value please refer to VTD spec for more details Length is in terms of the UTF char unit For prefixed tokens, it is the qualified name length.
 int getTokenOffset(int index)
          Get the starting offset (unit in native char) of the token at the given index.
 int getTokenType(int index)
          Get the token type of the token at the given index value.
 com.ximpleware.IByteBuffer getXML()
          Get the XML document
 java.lang.String getXPathStringVal()
           
 java.lang.String getXPathStringVal(short mode)
          Return the String value of an Element Node
 boolean hasAttr(java.lang.String an)
          Test whether current element has an attribute with the matching name.
 boolean hasAttrNS(java.lang.String URL, java.lang.String ln)
          Test whether the current element has an attribute with matching namespace URL and localname.
 boolean matchElement(java.lang.String en)
          Test if the current element matches the given name.
 boolean matchElementNS(java.lang.String URL, java.lang.String ln)
          Test whether the current element matches the given namespace URL and localname.
 boolean matchRawTokenString(int index, java.lang.String s)
          Match the string against the token at the given index value.
 boolean matchTokens(int i1, VTDNav vn2, int i2)
          This method matches two VTD tokens of VTDNav objects
 boolean matchTokenString(int index, java.lang.String s)
          Match the string against the token at the given index value.
 boolean overWrite(int index, byte[] ba)
          overWrite is introduced in version 2.0 that allows you to directly overwrite the XML content if the token is long enough If the operation is successful, the new content along with whitespaces will fill the available token space, and there will be no need to regenerate the VTD and LCs !!! The current version (2.0) only allows overwrites on attribute value, character data, and CDATA Consider the XML below: good After overwriting the token "good" with "bad," the new XML looks like: bad as you can see, "goo" is replaced with "bad" character-by-character, and the remaining "d" is replace with a white space
 boolean overWrite(int index, byte[] ba, int offset, int len)
          overWrite is introduced in version 2.0 that allows you to directly overwrite the XML content if the token is long enough If the operation is successful, white spaces will be used to fill the available token space, and there will be no need to regenerate the VTD and LCs The current version (2.0) only allows overwrites on attribute value, character data, and CDATA Consider the XML below: good After overwriting the token "good" with "bad," the new XML looks like: bad as you can see, "goo" is replaced with "bad", and the remaining "d" is replace with a white space
 double parseDouble(int index)
          Convert a vtd token into a double.
 float parseFloat(int index)
          Convert a vtd token into a float.
 int parseInt(int index)
          Convert a vtd token into an int.
 long parseLong(int index)
          Convert a vtd token into a long.
 boolean pop()
          Load the context info from ContextBuffer.
 void push()
          Store the context info into the ContextBuffer.
 void recoverNode(int index)
          This method takes a vtd index, and recover its correspondin node position, the index can only be of node type element, document, attribute name, attribute value or character data, or CDATA
 void sampleState(FastIntBuffer fib)
           
 boolean startsWith(int index, java.lang.String s)
          Test the start of token content at index i matches the content of s, notice that this is to save the string allocation cost of using String's built-in startsWidth
 boolean toElement(int direction)
          A generic navigation method.
 boolean toElement(int direction, java.lang.String en)
          A generic navigation method.
 boolean toElementNS(int direction, java.lang.String URL, java.lang.String ln)
          A generic navigation method with namespace support.
 java.lang.String toNormalizedString(int index)
          This method normalizes a token into a string value of character data and attr val in a way that resembles DOM.
 java.lang.String toNormalizedString2(int index)
          (New since version 2.9) Shallow Normalization follows the rules below to normalize a token into a string *#xD#xA gets converted to #xA *For a character reference, append the referenced character to the normalized value.
 java.lang.String toNormalizedXPathString(int j)
           
 java.lang.String toRawString(int index)
          Convert a token at the given index to a String, (entities and char references not expanded).
 java.lang.String toRawString(int os, int len)
          Convert a segment of XML bytes a into string, without entity resolution
 java.lang.String toRawStringLowerCase(int index)
          Convert a token at the given index to a String, upper case chars get converted into lower case (entities and char references not expanded).
 java.lang.String toRawStringUpperCase(int index)
          Convert a token at the given index to a String, lower case chars get converted into upper case (entities and char references not expanded).
 java.lang.String toString(int index)
          Convert a token at the given index to a String, (entities and char references resolved character data and attr val).
 java.lang.String toString(int os, int len)
          Convert the byte content segment (in terms of offset and length) to String (entities are resolved)
 java.lang.String toStringLowerCase(int index)
          Convert a token at the given index to a String and any upper case character will be converted to lower case, (entities and char references resolved for character data and attr val).
 java.lang.String toStringUpperCase(int index)
          Convert a token at the given index to a String and any lower case character will be converted to upper case, (entities and char references resolved character data and attr val).
 long trimWhiteSpaces(long l)
          New in v2.12 This method will take a segment descriptor and return a new descriptor that removes all the leading and trailing white spaces around the input segment It has no effect on CDATA
 boolean verifyNodeCorrectness()
          This is for debugging purpose
 void writeIndex(java.io.OutputStream os)
          Write VTDNav's internal structure into an OutputStream
 void writeIndex(java.lang.String fileName)
          Write VTDNav's internal structure into a VTD+XML file
 void writeSeparateIndex(java.io.OutputStream os)
          Write VTDNav's VTD and LCs into an OutputStream (XML not written out)
 void writeSeparateIndex(java.lang.String fileName)
          Write VTDNav's internal structure (VTD and LCs, but not XML) into a file
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

FC

public static final int FC
See Also:
Constant Field Values

FIRST_CHILD

public static final int FIRST_CHILD
See Also:
Constant Field Values

FORMAT_ASCII

public static final int FORMAT_ASCII
See Also:
Constant Field Values

FORMAT_ISO_8859_1

public static final int FORMAT_ISO_8859_1
See Also:
Constant Field Values

FORMAT_ISO_8859_10

public static final int FORMAT_ISO_8859_10
See Also:
Constant Field Values

FORMAT_ISO_8859_11

public static final int FORMAT_ISO_8859_11
See Also:
Constant Field Values

FORMAT_ISO_8859_12

public static final int FORMAT_ISO_8859_12
See Also:
Constant Field Values

FORMAT_ISO_8859_13

public static final int FORMAT_ISO_8859_13
See Also:
Constant Field Values

FORMAT_ISO_8859_14

public static final int FORMAT_ISO_8859_14
See Also:
Constant Field Values

FORMAT_ISO_8859_15

public static final int FORMAT_ISO_8859_15
See Also:
Constant Field Values

FORMAT_ISO_8859_16

public static final int FORMAT_ISO_8859_16
See Also:
Constant Field Values

FORMAT_ISO_8859_2

public static final int FORMAT_ISO_8859_2
See Also:
Constant Field Values

FORMAT_ISO_8859_3

public static final int FORMAT_ISO_8859_3
See Also:
Constant Field Values

FORMAT_ISO_8859_4

public static final int FORMAT_ISO_8859_4
See Also:
Constant Field Values

FORMAT_ISO_8859_5

public static final int FORMAT_ISO_8859_5
See Also:
Constant Field Values

FORMAT_ISO_8859_6

public static final int FORMAT_ISO_8859_6
See Also:
Constant Field Values

FORMAT_ISO_8859_7

public static final int FORMAT_ISO_8859_7
See Also:
Constant Field Values

FORMAT_ISO_8859_8

public static final int FORMAT_ISO_8859_8
See Also:
Constant Field Values

FORMAT_ISO_8859_9

public static final int FORMAT_ISO_8859_9
See Also:
Constant Field Values

FORMAT_UTF_16BE

public static final int FORMAT_UTF_16BE
See Also:
Constant Field Values

FORMAT_UTF_16LE

public static final int FORMAT_UTF_16LE
See Also:
Constant Field Values

FORMAT_UTF8

public static final int FORMAT_UTF8
See Also:
Constant Field Values

FORMAT_WIN_1250

public static final int FORMAT_WIN_1250
See Also:
Constant Field Values

FORMAT_WIN_1251

public static final int FORMAT_WIN_1251
See Also:
Constant Field Values

FORMAT_WIN_1252

public static final int FORMAT_WIN_1252
See Also:
Constant Field Values

FORMAT_WIN_1253

public static final int FORMAT_WIN_1253
See Also:
Constant Field Values

FORMAT_WIN_1254

public static final int FORMAT_WIN_1254
See Also:
Constant Field Values

FORMAT_WIN_1255

public static final int FORMAT_WIN_1255
See Also:
Constant Field Values

FORMAT_WIN_1256

public static final int FORMAT_WIN_1256
See Also:
Constant Field Values

FORMAT_WIN_1257

public static final int FORMAT_WIN_1257
See Also:
Constant Field Values

FORMAT_WIN_1258

public static final int FORMAT_WIN_1258
See Also:
Constant Field Values

LAST_CHILD

public static final int LAST_CHILD
See Also:
Constant Field Values

LC

public static final int LC
See Also:
Constant Field Values

NEXT_SIBLING

public static final int NEXT_SIBLING
See Also:
Constant Field Values

NS

public static final int NS
See Also:
Constant Field Values

P

public static final int P
See Also:
Constant Field Values

PARENT

public static final int PARENT
See Also:
Constant Field Values

PREV_SIBLING

public static final int PREV_SIBLING
See Also:
Constant Field Values

PS

public static final int PS
See Also:
Constant Field Values

R

public static final int R
See Also:
Constant Field Values

ROOT

public static final int ROOT
See Also:
Constant Field Values

STRING_NORMALIZED

public static final int STRING_NORMALIZED
See Also:
Constant Field Values

STRING_RAW

public static final int STRING_RAW
See Also:
Constant Field Values

STRING_REGULAR

public static final int STRING_REGULAR
See Also:
Constant Field Values

TOKEN_ATTR_NAME

public static final int TOKEN_ATTR_NAME
See Also:
Constant Field Values

TOKEN_ATTR_NS

public static final int TOKEN_ATTR_NS
See Also:
Constant Field Values

TOKEN_ATTR_VAL

public static final int TOKEN_ATTR_VAL
See Also:
Constant Field Values

TOKEN_CDATA_VAL

public static final int TOKEN_CDATA_VAL
See Also:
Constant Field Values

TOKEN_CHARACTER_DATA

public static final int TOKEN_CHARACTER_DATA
See Also:
Constant Field Values

TOKEN_COMMENT

public static final int TOKEN_COMMENT
See Also:
Constant Field Values

TOKEN_DEC_ATTR_NAME

public static final int TOKEN_DEC_ATTR_NAME
See Also:
Constant Field Values

TOKEN_DEC_ATTR_VAL

public static final int TOKEN_DEC_ATTR_VAL
See Also:
Constant Field Values

TOKEN_DOCUMENT

public static final int TOKEN_DOCUMENT
See Also:
Constant Field Values

TOKEN_DTD_VAL

public static final int TOKEN_DTD_VAL
See Also:
Constant Field Values

TOKEN_ENDING_TAG

public static final int TOKEN_ENDING_TAG
See Also:
Constant Field Values

TOKEN_PI_NAME

public static final int TOKEN_PI_NAME
See Also:
Constant Field Values

TOKEN_PI_VAL

public static final int TOKEN_PI_VAL
See Also:
Constant Field Values

TOKEN_STARTING_TAG

public static final int TOKEN_STARTING_TAG
See Also:
Constant Field Values

XPATH_STRING_MODE_LOWERCASE

public static final short XPATH_STRING_MODE_LOWERCASE
See Also:
Constant Field Values

XPATH_STRING_MODE_NORMAL

public static final short XPATH_STRING_MODE_NORMAL
See Also:
Constant Field Values

XPATH_STRING_MODE_UPPERCASE

public static final short XPATH_STRING_MODE_UPPERCASE
See Also:
Constant Field Values
Method Detail

cloneNav

public VTDNav cloneNav()
Clone the VTDNav instance to get with shared XML, VTD and LC buffers The node position is also copied from the original instance

Returns:
a new instance of VTDNav

compareRawTokenString

public final int compareRawTokenString(int index,
                                       java.lang.String s)
                                throws NavException
New in 2.0 Compare the string against the token at the given index value. When a token is an attribute name or starting tag, qualified name is what gets compared against This method has to take care of the underlying encoding conversion but it doesn't resolve entity reference in the underlying document The behavior is the same as calling toRawString on index, then compare to s

Parameters:
index -
s -
Returns:
the result of lexical comparison
Throws:
NavException

compareTokens

public final int compareTokens(int i1,
                               VTDNav vn2,
                               int i2)
                        throws NavException
New in 2.0 This method compares two VTD tokens of VTDNav objects The behavior of this method is like compare the strings corresponds to i1 and i2, meaning for text or attribute val, entities will be converted into the corresponding char, return 0 if two tokens are the identical when converted to Unicode String using toString() respectively

Parameters:
i1 -
vn2 -
i2 -
Returns:
-1,0 (when equal), or 1
Throws:
NavException

compareTokenString

public final int compareTokenString(int index,
                                    java.lang.String s)
                             throws NavException
New in 2.0 Compare the string against the token at the given index value. When a token is an attribute name or starting tag, qualified name is what gets matched against This method has to take care of the underlying encoding conversion as well as entity reference comparison

Parameters:
index -
s -
Returns:
int
Throws:
NavException

contains

public final boolean contains(int index,
                              java.lang.String s)
                       throws NavException
Test whether a given token contains s. notie that this function directly operates on the byte content of the token to avoid string creation

Parameters:
index -
s -
Returns:
Throws:
NavException

dumpElementFragmentNs

public final void dumpElementFragmentNs(java.lang.String fileName)
                                 throws NavException,
                                        java.io.IOException
New in v2.12 Dump the ns compensated element fragment of xml into an XML file whose name is specified as fileName

Parameters:
fileName -
Throws:
NavException
java.io.IOException

dumpFragment

public final void dumpFragment(long l,
                               java.io.OutputStream os)
                        throws NavException,
                               java.io.IOException
New in v2.12 Dump a fragement as specified by a long into an output stream

Parameters:
l - upper 32 bit is length in byte, lower 32 bit is offset in byte
os -
Throws:
NavException
java.io.IOException

dumpFragment

public final void dumpFragment(long l,
                               java.lang.String fileName)
                        throws NavException,
                               java.io.FileNotFoundException,
                               java.io.IOException
New in v2.12

Parameters:
l - upper 32 bits are length in byte, lower 32 bits are offset in byte
fileName -
Throws:
NavException
java.io.FileNotFoundException
java.io.IOException

dumpFragment

public final void dumpFragment(java.io.OutputStream os)
                        throws NavException,
                               java.io.IOException
New in v2.12 Dump an element fragment of xml into an output stream

Parameters:
os -
Throws:
NavException
java.io.IOException

dumpFragment

public final void dumpFragment(java.lang.String fileName)
                        throws NavException,
                               java.io.FileNotFoundException,
                               java.io.IOException
New in v2.12 Dump an element fragment of xml into an XML file whose name is specified as fileName

Parameters:
fileName -
Throws:
NavException
java.io.FileNotFoundException
java.io.IOException

dumpState

public void dumpState()

dumpXML

public void dumpXML(java.io.OutputStream os)
             throws java.io.IOException
Dump the in memory XML text into output stream

Parameters:
os -
Throws:
java.io.IOException

dumpXML

public void dumpXML(java.lang.String fileName)
             throws java.io.IOException
Dump the in-memory copy of XML text into a file

Parameters:
fileName -
Throws:
java.io.IOException

duplicateNav

public VTDNav duplicateNav()
Duplicate the VTDNav instance with shared XML, VTD and LC buffers This method may be useful for parallel XPath evaluation The node Position is at root element

Returns:
a VTDNav instance

endsWith

public final boolean endsWith(int index,
                              java.lang.String s)
                       throws NavException
Test the end of token content at index i matches the content of s, notice that this is to save the string allocation cost of using String's built-in endsWidth

Parameters:
i -
Returns:
Throws:
NavException

expandWhiteSpaces

public final long expandWhiteSpaces(long l)
New in v2.12 This method will take a segment descriptor and return a new descriptor that includes all the leading and trailing white spaces around the input segment It has no effect on CDATA A typical usage would be 'expandWhiteSpaces(getElementFragment())'

Parameters:
l - upper 32 bits length of the segment, lower 32 bits offset of the segment, unit is byte offset
Returns:
a long 64 bit segment descriptor
Throws:
NavException

fillXPathString

public final void fillXPathString(FastIntBuffer indexBuffer,
                                  FastIntBuffer countBuffer)
                           throws NavException
Throws:
NavException

getAttrCount

public int getAttrCount()
Return the attribute count of the element at the cursor position. when ns is false, attr_ns tokens are considered attributes; otherwise, ns tokens are not considered attributes

Returns:
int

getAttrVal

public int getAttrVal(java.lang.String an)
               throws NavException
Get the token index of the attribute value given an attribute name.

Parameters:
an - java.lang.String
Returns:
int (-1 if no such attribute name exists)
Throws:
NavException - The exception if the underlying byte content contains various errors. Notice that we are being conservative in making little assumption on the correctness of underlying byte content. This is because the VTD etc can be generated by another machine from a load-balancer.
IllegalArguementException - if an is null

getAttrValNS

public int getAttrValNS(java.lang.String URL,
                        java.lang.String ln)
                 throws NavException
Get the token index of the attribute value of given URL and local name. If ns is not enabled, the lookup will return -1, indicating a no-found. Also namespace nodes are invisible using this method. One can't use * to indicate any name space because * is ambiguous!!

Parameters:
URL - java.lang.String (Name space URL)
ln - java.lang.String (local name)
Returns:
int (-1 if no matching attribute found)
Throws:
NavException - The exception if the underlying byte content contains various errors. Notice that we are being conservative in making little assumption on the correctness of underlying byte content. This is because the VTD etc can be generated by another machine from a load-balancer.
IllegalArguementException - if s is null

getContentFragment

public long getContentFragment()
                        throws NavException
Get content fragment returns a long encoding the offset and length of the byte segment of the content of current element, which is the byte segment between the starting tag and ending tag, -1 is returned if the current element is an empty element

Returns:
long whose upper 32 bite is length, lower 32 bit is offset
Throws:
NavException

getCurrentDepth

public final int getCurrentDepth()
Get the depth (>=0) of the current element. Creation date: (11/16/03 6:58:22 PM)

Returns:
int

getCurrentIndex

public final int getCurrentIndex()
Get the index value of the current element. Creation date: (11/16/03 6:40:25 PM)

Returns:
int

getElementFragment

public long getElementFragment()
                        throws NavException
Get the starting offset and length of an element encoded in a long, upper 32 bits is length; lower 32 bits is offset Unit is in byte. Creation date: (3/15/04 1:47:55 PM)

Throws:
NavException

getElementFragmentNs

public ElementFragmentNs getElementFragmentNs()
                                       throws NavException
getElementFragmentNS returns a ns aware version of the element fragment encapsulated in an ElementFragment object

Returns:
an ElementFragment object
Throws:
NavException

getEncoding

public final int getEncoding()
Get the encoding of the XML document.

Returns:
int

getIndexsize

public long getIndexsize()
Precompute the size of VTD+XML index

Returns:
size of the index

getNestingLevel

public final int getNestingLevel()
Get the maximum nesting depth of the XML document (>0). max depth is nestingLevel -1

Returns:
int

getNormalizedStringLength

public final int getNormalizedStringLength(int index)
                                    throws NavException
Get the string length of a token as if it is converted into a normalized UCS string

Parameters:
index -
Returns:
the string length
Throws:
NavException

getOffsetAfterHead

public final long getOffsetAfterHead()
Return the charater (not byte) offset after head (the ending bracket of the starting tag, not including an empty element, in which case 0xffffffff 00000000 | len is returned)

Returns:

getPrefixString

public java.lang.String getPrefixString(int i)
                                 throws NavException
Return the prefix of a token as a string if the token is of the type of starting tag, attribute name, if the the prefix doesn't exist, a null string is returned; otherwise a null string is returned

Parameters:
i - VTD index of a token
Returns:
Throws:
NavException

getRawStringLength

public final int getRawStringLength(int index)
                             throws NavException
Get the string length as if the token is converted into a UCS string (entity not resolved)

Parameters:
index -
Returns:
Throws:
NavException

getRootIndex

public final int getRootIndex()
Get root index value , which is the index val of root element

Returns:
int

getSiblingElementFragments

public long getSiblingElementFragments(int i)
                                throws NavException
Return the byte offset and length of up to i sibling fragments. If there is a i+1 sibling element, the cursor element would move to it; otherwise, there is no cursor movement. If the cursor isn't positioned at an element (due to XPath evaluation), then -1 will be returned

Parameters:
i - number of silbing elements including the cursor element
Returns:
a long encoding byte offset (bit 31 to bit 0), length (bit 62 to bit 32) of those fragments
Throws:
NavException

getStringLength

public final int getStringLength(int index)
                          throws NavException
getStringLength return the string length of a token as if the token is converted into a string (entity resolved for character data and attr val)

Parameters:
index -
Returns:
the string length as if the token is converted to a UCS string (entity resolved)
Throws:
NavException

getText

public int getText()
This method returns of the token index of the type character data or CDATA. Notice that it is intended to support data orient XML (not mixed-content XML). return the index of the text token, or -1 if none exists.

Returns:
int

getTokenCount

public final int getTokenCount()
Get total number of VTD tokens for the current XML document.

Returns:
int

getTokenDepth

public final int getTokenDepth(int index)
Get the depth value of a token (>=0).

Parameters:
index - int
Returns:
int

getTokenLength

public int getTokenLength(int index)
Get the token length at the given index value please refer to VTD spec for more details Length is in terms of the UTF char unit For prefixed tokens, it is the qualified name length. When ns is not enabled, return the full name length for attribute name and element name When ns is enabled, return an int with upper 16 bit for prefix length, lower 16 bit for qname length

Parameters:
index - int
Returns:
int

getTokenOffset

public final int getTokenOffset(int index)
Get the starting offset (unit in native char) of the token at the given index.

Parameters:
index - int
Returns:
int

getTokenType

public final int getTokenType(int index)
Get the token type of the token at the given index value. Creation date: (11/16/03 6:41:51 PM)

Parameters:
index - int
Returns:
int

getXML

public final com.ximpleware.IByteBuffer getXML()
Get the XML document

Returns:
IByteBuffer

getXPathStringVal

public final java.lang.String getXPathStringVal()
                                         throws NavException
Throws:
NavException

getXPathStringVal

public final java.lang.String getXPathStringVal(short mode)
                                         throws NavException
Return the String value of an Element Node

Parameters:
mode -
Returns:
Throws:
NavException

hasAttr

public final boolean hasAttr(java.lang.String an)
                      throws NavException
Test whether current element has an attribute with the matching name. "*" will match any attribute name, therefore is a test whether there is any attribute at all if namespace is disabled, this function will not distinguish between ns declaration and attribute otherwise, ns tokens are invisible Creation date: (11/16/03 5:50:26 PM)

Parameters:
an - java.lang.String
Returns:
boolean (true if such an attribute exists)
Throws:
NavException - The exception if the underlying byte content contains various errors. Notice that we are being conservative in making little assumption on the correctness of underlying byte content. This is because the VTD etc can be generated by another machine from a load-balancer.
IllegalArguementException - if an is null

hasAttrNS

public final boolean hasAttrNS(java.lang.String URL,
                               java.lang.String ln)
                        throws NavException
Test whether the current element has an attribute with matching namespace URL and localname. If ns is false, return false immediately

Parameters:
URL - java.lang.String (namespace URL)
ln - java.lang.String (localname )
Returns:
boolean
Throws:
NavException - The exception if the underlying byte content contains various errors. Notice that we are being conservative in making little assumption on the correctness of underlying byte content. This is because the VTD can be generated by another machine such as a load-balancer.
IllegalArguementException - if ln is null

matchElement

public final boolean matchElement(java.lang.String en)
                           throws NavException
Test if the current element matches the given name. Creation date: (11/26/03 2:09:43 PM)

Parameters:
en - java.lang.String
Returns:
boolean
Throws:
NavException - If the underlying raw char representation has errors.

matchElementNS

public final boolean matchElementNS(java.lang.String URL,
                                    java.lang.String ln)
                             throws NavException
Test whether the current element matches the given namespace URL and localname. URL, when set to "*", matches any namespace (including null), when set to null, defines a "always-no-match" ln is the localname that, when set to *, matches any localname

Parameters:
URL - java.lang.String
ln - java.lang.String
Returns:
boolean
Throws:
NavException - When there is any encoding conversion error or unknown entity.

matchRawTokenString

public final boolean matchRawTokenString(int index,
                                         java.lang.String s)
                                  throws NavException
Match the string against the token at the given index value. When a token is an attribute name or starting tag, qualified name is what gets matched against This method has to take care of the underlying encoding conversion but it doesn't resolve entity reference in the underlying document

Parameters:
index - int (index into the VTD token buffer)
s - java.lang.String
Returns:
boolean
Throws:
NavException - When if the underlying byte content contains various errors. Notice that we are being conservative in making little assumption on the correctness of underlying byte content. This is because the VTD can be generated by another machine such as a load-balancer.

matchTokens

public final boolean matchTokens(int i1,
                                 VTDNav vn2,
                                 int i2)
                          throws NavException
This method matches two VTD tokens of VTDNav objects

Parameters:
i1 - index of the first token
vn2 - the second VTDNav instance
i2 - index of the second token
Returns:
boolean true if two tokens are lexically identical
Throws:
NavException

matchTokenString

public final boolean matchTokenString(int index,
                                      java.lang.String s)
                               throws NavException
Match the string against the token at the given index value. When a token is an attribute name or starting tag, qualified name is what gets matched against This method has to take care of the underlying encoding conversion as well as entity reference comparison

Parameters:
index - int
s - java.lang.String
Returns:
boolean
Throws:
NavException - When if the underlying byte content contains various errors. Notice that we are being conservative in making little assumption on the correctness of underlying byte content. This is because the VTD can be generated by another machine such as a load-balancer.

overWrite

public final boolean overWrite(int index,
                               byte[] ba)
overWrite is introduced in version 2.0 that allows you to directly overwrite the XML content if the token is long enough If the operation is successful, the new content along with whitespaces will fill the available token space, and there will be no need to regenerate the VTD and LCs !!! The current version (2.0) only allows overwrites on attribute value, character data, and CDATA Consider the XML below: good After overwriting the token "good" with "bad," the new XML looks like: bad as you can see, "goo" is replaced with "bad" character-by-character, and the remaining "d" is replace with a white space

Parameters:
index -
ba - the byte array contains the new content to be overwritten
Returns:
boolean as the status of the overwrite operation

overWrite

public boolean overWrite(int index,
                         byte[] ba,
                         int offset,
                         int len)
overWrite is introduced in version 2.0 that allows you to directly overwrite the XML content if the token is long enough If the operation is successful, white spaces will be used to fill the available token space, and there will be no need to regenerate the VTD and LCs The current version (2.0) only allows overwrites on attribute value, character data, and CDATA Consider the XML below: good After overwriting the token "good" with "bad," the new XML looks like: bad as you can see, "goo" is replaced with "bad", and the remaining "d" is replace with a white space

Parameters:
index - the VTD record to which the change will be applied
ba - the byte array contains the new content to be overwritten
offset -
len -
Returns:
boolean as the status of the overwrite operation

parseDouble

public double parseDouble(int index)
                   throws NavException
Convert a vtd token into a double. Creation date: (12/8/03 2:28:31 PM)

Returns:
double
Throws:
NavException - The exception if the underlying byte content contains various errors. Notice that we are being conservative in making little assumption on the correctness of underlying byte content. This is because the VTD can be generated by another machine such as a load-balancer.

parseFloat

public float parseFloat(int index)
                 throws NavException
Convert a vtd token into a float. we assume token type to be attr val or character data Creation date: (12/8/03 2:28:18 PM)

Returns:
float
Throws:
NavException - The exception if the underlying byte content contains various errors. Notice that we are being conservative in making little assumption on the correctness of underlying byte content. This is because the VTD can be generated by another machine such as a load-balancer.

parseInt

public int parseInt(int index)
             throws NavException
Convert a vtd token into an int. This method will automatically strip off the leading and trailing we assume token type to be attr val or character data zero, unlike Integer.parseInt(int index) Creation date: (12/8/03 2:32:22 PM)

Parameters:
index - int
Returns:
int
Throws:
NavException - The exception if the underlying byte content contains various errors. Notice that we are being conservative in making little assumption on the correctness of underlying byte content. This is because the VTD can be generated by another machine such as a load-balancer.

parseLong

public long parseLong(int index)
               throws NavException
Convert a vtd token into a long. we assume token type to be attr val or character data Creation date: (12/8/03 2:32:59 PM)

Parameters:
index - int
Returns:
long
Throws:
NavException - The exception if the underlying byte content contains various errors. Notice that we are being conservative in making little assumption on the correctness of underlying byte content. This is because the VTD can be generated by another machine such as a load-balancer.

pop

public boolean pop()
Load the context info from ContextBuffer. Info saved including LC and current state of the context

Returns:
boolean

push

public void push()
Store the context info into the ContextBuffer. Info saved including LC and current state of the context Creation date: (11/16/03 7:00:27 PM)


recoverNode

public void recoverNode(int index)
                 throws NavException
This method takes a vtd index, and recover its correspondin node position, the index can only be of node type element, document, attribute name, attribute value or character data, or CDATA

Parameters:
index -
Throws:
NavException

sampleState

public void sampleState(FastIntBuffer fib)

startsWith

public final boolean startsWith(int index,
                                java.lang.String s)
                         throws NavException
Test the start of token content at index i matches the content of s, notice that this is to save the string allocation cost of using String's built-in startsWidth

Parameters:
i -
s -
Returns:
Throws:
NavException

toElement

public boolean toElement(int direction)
                  throws NavException
A generic navigation method. Move the cursor to the element according to the direction constants If no such element, no position change and return false. Creation date: (12/2/03 1:43:50 PM) Legal direction constants are
                        ROOT               0 
 
                    PARENT                 1 
 
                    FIRST_CHILD            2 
 
                    LAST_CHILD             3 
 
                    NEXT_SIBLING       4 
 
            PREV_SIBLING       5 
 

Parameters:
direction - int
Returns:
boolean
Throws:
NavException - When direction value is illegal.

toElement

public boolean toElement(int direction,
                         java.lang.String en)
                  throws NavException
A generic navigation method. Move the cursor to the element according to the direction constants and the element name If no such element, no position change and return false. "*" matches any element Creation date: (12/2/03 1:43:50 PM) Legal direction constants are
                ROOT            0  
 
                PARENT          1  
 
                FIRST_CHILD     2  
 
                LAST_CHILD      3  
 
                NEXT_SIBLING    4  
 
                PREV_SIBLING    5  
 

for ROOT and PARENT, element name will be ignored.

Parameters:
direction - int
en - String
Returns:
boolean
Throws:
NavException - When direction value is illegal. Or there are errors in underlying byte representation of the document
IllegalArguementException - if en is null

toElementNS

public boolean toElementNS(int direction,
                           java.lang.String URL,
                           java.lang.String ln)
                    throws NavException
A generic navigation method with namespace support. Move the cursor to the element according to the direction constants and the prefix and local names If no such element, no position change and return false. URL * matches any namespace, including undefined namespaces a null URL means hte namespace prefix is undefined for the element ln * matches any localname Creation date: (12/2/03 1:43:50 PM) Legal direction constants are
                ROOT            0  
 
                PARENT          1  
 
                FIRST_CHILD     2  
 
                LAST_CHILD      3  
 
                NEXT_SIBLING    4  
 
                PREV_SIBLING    5  
 

for ROOT and PARENT, element name will be ignored. If not ns enabled, return false immediately with no position change.

Parameters:
direction - int
URL - String
ln - String
Returns:
boolean
Throws:
NavException - When direction value is illegal. Or there are errors in underlying byte representation of the document

toNormalizedString

public java.lang.String toNormalizedString(int index)
                                    throws NavException
This method normalizes a token into a string value of character data and attr val in a way that resembles DOM. The leading and trailing white space characters will be stripped. The entity and character references will be resolved Multiple whitespaces char will be collapsed into one. Whitespaces via entities will nonetheless be preserved. Creation date: (12/8/03 1:57:10 PM)

Parameters:
index - int
Returns:
java.lang.String
Throws:
NavException - When the encoding has errors

toNormalizedString2

public java.lang.String toNormalizedString2(int index)
                                     throws NavException
(New since version 2.9) Shallow Normalization follows the rules below to normalize a token into a string *#xD#xA gets converted to #xA *For a character reference, append the referenced character to the normalized value. *For an entity reference, recursively apply step 3 of this algorithm to the replacement text of the entity. *For a white space character (#x20, #xD, #xA, #x9), append a space character (#x20) to the normalized value. *For another character, append the character to the normalized value.

Parameters:
index -
Returns:
Throws:
NavException

toNormalizedXPathString

public final java.lang.String toNormalizedXPathString(int j)
                                               throws NavException
Throws:
NavException

toRawString

public final java.lang.String toRawString(int index)
                                   throws NavException
Convert a token at the given index to a String, (entities and char references not expanded). Creation date: (11/16/03 7:28:49 PM)

Parameters:
index - int
Returns:
java.lang.String
Throws:
NavException - When the encoding has errors

toRawString

public final java.lang.String toRawString(int os,
                                          int len)
                                   throws NavException
Convert a segment of XML bytes a into string, without entity resolution

Parameters:
os - (in terms of chars not bytes)
len - (in terms of chars not bytes)
Returns:
Throws:
NavException

toRawStringLowerCase

public final java.lang.String toRawStringLowerCase(int index)
                                            throws NavException
Convert a token at the given index to a String, upper case chars get converted into lower case (entities and char references not expanded).

Parameters:
index -
Returns:
Throws:
NavException

toRawStringUpperCase

public final java.lang.String toRawStringUpperCase(int index)
                                            throws NavException
Convert a token at the given index to a String, lower case chars get converted into upper case (entities and char references not expanded).

Parameters:
index -
Returns:
Throws:
NavException

toString

public java.lang.String toString(int index)
                          throws NavException
Convert a token at the given index to a String, (entities and char references resolved character data and attr val). An attribute name or an element name will get the UCS2 string of qualified name Creation date: (11/16/03 7:27:19 PM)

Parameters:
index -
Returns:
java.lang.String
Throws:
NavException

toString

public final java.lang.String toString(int os,
                                       int len)
                                throws NavException
Convert the byte content segment (in terms of offset and length) to String (entities are resolved)

Parameters:
os - the char offset of the segment (not byte)
len - the length of the segment in char (not byte)
Returns:
the corresponding string value
Throws:
NavException

toStringLowerCase

public java.lang.String toStringLowerCase(int index)
                                   throws NavException
Convert a token at the given index to a String and any upper case character will be converted to lower case, (entities and char references resolved for character data and attr val).

Parameters:
index -
Returns:
Throws:
NavException

toStringUpperCase

public java.lang.String toStringUpperCase(int index)
                                   throws NavException
Convert a token at the given index to a String and any lower case character will be converted to upper case, (entities and char references resolved character data and attr val).

Parameters:
index -
Returns:
Throws:
NavException

trimWhiteSpaces

public final long trimWhiteSpaces(long l)
New in v2.12 This method will take a segment descriptor and return a new descriptor that removes all the leading and trailing white spaces around the input segment It has no effect on CDATA

Parameters:
l - upper 32 bits length of the segment, lower 32 bits offset of the segment, unit in byte
Returns:
a long 64 bit segment descriptor
Throws:
NavException

verifyNodeCorrectness

public boolean verifyNodeCorrectness()
This is for debugging purpose

Parameters:
fib -

writeIndex

public void writeIndex(java.io.OutputStream os)
                throws IndexWriteException,
                       java.io.IOException
Write VTDNav's internal structure into an OutputStream

Parameters:
os -
Throws:
IndexWriteException
java.io.IOException

writeIndex

public void writeIndex(java.lang.String fileName)
                throws java.io.IOException,
                       IndexWriteException
Write VTDNav's internal structure into a VTD+XML file

Parameters:
fileName -
Throws:
java.io.IOException
IndexWriteException

writeSeparateIndex

public void writeSeparateIndex(java.io.OutputStream os)
                        throws IndexWriteException,
                               java.io.IOException
Write VTDNav's VTD and LCs into an OutputStream (XML not written out)

Parameters:
os -
Throws:
IndexWriteException
java.io.IOException

writeSeparateIndex

public void writeSeparateIndex(java.lang.String fileName)
                        throws java.io.IOException,
                               IndexWriteException
Write VTDNav's internal structure (VTD and LCs, but not XML) into a file

Parameters:
fileName -
Throws:
java.io.IOException
IndexWriteException