 |
|
|
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.
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:
- Unzip it using 'gunzip'. This will create the .tar file.
> gunzip xml4j_2_0_0.tar.gz
- 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
- 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
|
|
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. |
|
|