Welcome to version 2 of IBM's XML Parser for Java (XML4J). This release contains a large number of improvements.

This README contains information on setting up XML4J version 2 and running the samples. It also includes a history of the changes that have been made and a description of the limitations of this release.

At the end of the README is information on contacting IBM regarding XML4J version 2. We are very interested in bug reports and feedback, and we will do our best to respond to you in a timely way. Thank you for your interest in XML4J version 2!

 

Additional Documentation

Programmers Guide
API Documentation
TX Compatibility API Documentation
Frequently Asked Questions


Contents of Readme

 

Files in this Release
Installation

Windows NT/95/98
Unix

Running Samples

XJParse
XMLTreeViewer

Change History
Caveats
Contact


Files in this Release

 
Contents of the xml4j_2_0_0.zip and xml4j_2_0_0.tar.gz files are:
 

xml4j.jar Jar file containing all the parser class files
xml4jSamples.jar Jar file containing all sample class files
Readme.html This file
evaluation-license.html Evaluation License for XML4J Version 2
w3c_copyright_software.html W3C Copyright Notice for DOM
apiDocs/ Directory containing JavaDoc API for parser framework
docs/ Directory containing other documentation
data/ Directory containing sample data files
build/ Directory containing scripts to compile all sources and generate API documentation using JavaDoc
src/ Source files
samples/ Directory containing sample programs
TXapiDocs/ Directory containing JavaDoc API for the TX Compatibility classes.


Installation

 

Windows NT/95/98

 

To install XML4J version 2, unzip the .zip archive using a tool such as WinZip.

  1. unzip xml4j_2_0_0.zip

This will create an 'xml4j_2_0_0' sub-directory (in the current directory) which contains everything.

 

Unix (all flavors)

 

The archive is a gzipped tar file. To install it:

  1. Unzip it using 'gunzip'. This will create the .tar file.
    > gunzip xml4j_2_0_0.tar.gz
    				
  2. Extract the files from the .tar archive. This should create the 'xml4j_2_0_0' directory.
    > tar xvf xml4j_2_0_0.tar

This will create an 'xml4j_2_0_0' sub-directory (in the current directory) which contains everything.

 

Running the Samples

 
The command lines below use the Windows path separator ';'. On UNIX systems, use the ':' character to separate the various jar files in the classpath, and replace the Windows directory separator '\' with '/'.
 

XJParse

 
XJParse is a driver program that is used to invoke the parser on an XML document. By default, invoking XJParse will create a non-validating SAX parser whose handler counts the number of elements in the document. XJParse also displays the amount of time it took to complete its task. The command lines below expect the xml4j_2_0_0 directory to be the current directory.
 

To run XJParse with the default settings:

jre -cp "xml4j.jar;xml4jSamples.jar" XJParse data\personal.xml
XJParse also allows you to change the default behavior via the following command line flags:
  • -p Specify the parser class to be used. The set of available parser classes is: com.ibm.xml.parsers.SAXParser, com.ibm.xml.parsers.ValidatingSAXParser, com.ibm.xml.parsers.NonValidatingDOMParser, com.ibm.xml.parsers.DOMParser.

  • -h Specify the XJParse handler class to be used. XJParse has an associated handler class which tells XJParse what to do. This handler class implements the interface XJParseHandler The file SAXCount\SAXCountHandlers.java in the samples directory shows how to implement your own XJParseHandler.

  • -d For those parsers which create a DOM tree (com.ibm.xml.parsers.NonValidatingDOMParser, com.ibm.xml.parsers.DOMParser), the -d option allows you to specify a class which implements org.w3c.dom.Document, so that you can create specialized DOM trees.

  • -w If you are doing performance timings, you can use the -w flag to "warm up" the parser. This flag calls the parser on the file an extra time before it begins the timed call to the parser. This allows the parser code to be compiled by a JIT -- the overhead of JIT'ing the parser will not appear in the timing.

Running XJParse with the default settings is equivalent to running XJParse like this (type this in as one long command line):

jre -cp "xml4j.jar;xml4jSamples.jar" 
			  XJParse -p com.ibm.xml.parsers.SAXParser -h SAXCount.SAXCountHandlers data\personal.xml

To run XJParse with a Validating DOM Parser configuration: (which creates a default DOM tree instance of type com.ibm.domimpl.DocumentImpl (type this in as one long command line):

jre -cp "xml4j.jar;xml4jSamples.jar" 
			  XJParse -p com.ibm.xml.parsers.DOMParser data\personal.xml
We've supplied two sample handlers to be used with XJParse, SAXCount.SAXCountHandlers, and SAXPrint.SAXPrintHandlers. SAXCount counts the number of elements, attributes, spaces, and characters in its input file. SAXPrint prints out its input in a canonical form.
 

XMLTreeViewer

 
The XMLTreeViewer sample displays the input file in a graphical tree based interface. To run the XMLTreeviewer, type the following command line:
jre -cp "xml4j.jar;xml4jSamples.jar" XMLTreeViewer data\personal.xml

Change History

 
Feb 5, 1999 XML4J 2.0.0 Release
  • New Features
    • EBCDIC Support
  • Fixed defects
    • Improve internal error handling
    • Doesn't support unparsed entities that refer to notations declared afterward the referencing entity.
    • TX: setPreserveSpace not implemented correctly
    • TX: PI handling missing null check
    • TX: incompatible with XML4J 1.1.13
    • TX: user supplied TXDocument factory can result in null pointer exceptions
  • License
      To get better information on the commercial use of XML4J we have changed the license agreement. The Free Commercial Distribution License is STILL readily available. To get the free distribution license all you have to do is register (see license.html for details) and fill in a very short questionnaire. The free distribution license agreement will be emailed to the address specified in the registration form.

      To avoid you having to supply the information each time you do a download, we have removed the distribution license from the archive (.zip and .tar.gz file). The archive now contains only an Evaluation License, but you get all the source and other technical assets as before.

Jan 18, 1998 XML4J2 D06 Release
  • New Features
    • Re-validation of TX DOM trees.
  • Fixed defects
    • TX: Ignorable whitespace is not created correctly
Jan 15, 1998 XML4J2 D05 Release
  • Fixed defects
    • TX: Entity resolution cannot find relative entities.
    • TX: Errors are not reported.
    • TX: TXText Nodes created instead of CDATA Nodes.
Dec. 23, 1998 XML4J2 D04 Release
  • Fixed incorrect packaging. Sample files 'SAXCount...' are now included in the samples .jar file.
  • The parser can now be interrupted mid-stream (checked on a per-element basis).
  • Fixed defects
    • Correctly process FIXED attribute defaults.

Dec. 18, 1998

XML4J2 D03 Release

  • Added TX Compatibility classes
  • Added native catalog support for both TX style catalog and XCatalog
  • Update documentation

Dec. 07, 1998

XML4J2 D02 Release

  • Improved memory management architecture.
  • Fixed DOM defects..

Nov. 17, 1998

XML4J2 D01 Release

  • Improved documentation.

Nov. 06, 1998

XML4J2 Early access 1 Release

  • Supports
    • XML 1.0 Specification (Feb. 02, 1998)
    • DOM (Core) Level 1 Specification Version 1.0 (Oct. 01, 1998)
    • SAX 1.0 Specification
  • Rearchitecture and new implementation of XML4J.
  • Modular architecture.
  • Pre-bundled parser configurations included are
    • SAX Parser (with and without validation)
    • DOM Parser (with and without validation)

Caveats and Limitations

 
  • If there is an error in the encoding line, XML4J2 may report the location of the error as -1,-1
  • When parsing an unparsed entities which refer to notations declared after the entity reference, XML4J2 will report the error end of the DTD, not the point where the unparsed entity was declared.
  • Due to a bug in the JDK's handling of EBCDIC data, you must use IBM's JDK 1.1.6 if you want to use the EBCDIC support.

Contact

 
Please post technical questions and comments to alphaWorks communityXchange or xml4j@us.ibm.com.
Non-technical questions are also welcome at xml4j@us.ibm.com.
 

IBM

alphaWorks

XML For Java

communityXchange-XML for Java