ParseFile vs Parse: A Quick Comparison
VTDGen has two main methods in version 2.12 that you can call to parse XML documents.
The first one is parse(), which accepts a boolean indicating the namespace awareness of the parsing operation. It throws a variety of exceptions, corresponding to various parsing errors, such as encoding errors, invalid entity reference, or name-space qualification errors , etc. You need to catch those exceptions in your code, and then choose to obtain the detailed diagnostic message about the nature of error. Parse() always works in conjunction with a pair of setDoc() methods, which either accepts a byte array containing the entire input XML, or a byte array and a pair of integers delimiting the segment in the byte array that contains the XML document. The maximum file size limit is 2 GB without namespace awareness, and 1 GB with. Also remember that you will need to manually read the file content into memory and the whole parsing takes about six to ten lines of code.
The second one is parseFile(), which accepts the full path qualified file name of an XML document, and a boolean, which switches on/off the name space awareness of the parsing routine. Built on top of setDoc() and parse(), parseFile(), it returns the status of parsing as a boolean. If for any reason parsing fails, whether the file does not exist, or there is a wellformedness error, it will only return false, and furnishes no detailed diagnostic information. So if you don’t concern yourself with the nitty-gritty of exception handling or simply want to avoid the clutter, then choose parseFile() and parsing requires no more than two lines of code.
There is More
Cast in the same mold as parseFile(), there are actually three more purpose-built parsing methods at your disposal serving to simplify coding. Those methods are:
- parseFileHttpURL()- obtain XML docs via HTTP URL , parse it, and then return
- parseZIPFile()- parse a ZIP compressed XML file, it will inflate the document into an in-memory byte array before parsing
They offer the same benefit/limitation argument for their intended use cases as parseFile() is for reading uncompressed, local XML files.
In addition, the following routines help you configure the run-time behavior of the parser.
- setLcDepth() configures VTDGen to generate Location Cache of either depth 3 or 5. Before version 2.12, the default depth is 3. After, 5 is the default.
- enableIgnoredWhiteSpace() enables the parser to collect all white spaces, including the trivial white spaces. By default, trivial white spaces are ignored
Hope this article has provided a glimpse of VTDGen‘s parsing methods. As you have noticed there are a few more VTDGen‘s member methods this article has not covered.They pertain to advanced features and capabilities of VTD-XML –namely, buffer reuse and loading/writing index. Both subjects will be covered in detail in a later article.