# XML for Java - README

VERSION: `1.0.0```

XML for Java is an Extensible Markup Language (XML) processor written in Java. XML for Java provides two main functions:

- Parsing an XML document and construction of a Java object tree
- Generation of an XML document from a Java object tree

## Installation

Windows95, WindowsNT (installable EXE)
  1. Install JDK-1.1.
  2. Download an installable EXE file, `xml4j.n.n.n.exe`.
  3. Execute it to install a directory.

     You will see the following files in the installed directory such as `C:\xml4j`

     > `FAQ.html` | FAQ
     > `README.html` | this file
     > `api/` | directory for API documents
     > `docs/` | directory for documents
     > `license.html` | license information
     > `personal.dtd` | sample DTD file
     > `personal.xml` | sample XML document
     > `src/` | directory for source code
     > `xml4j.jar` | class files

  4. Try the following command on MS-DOS prompt to test your installation. This test parses the input and then regenerates the same XML document.

         C:\xml4j>type personal.xml
         C:\xml4J>jre -cp xml4j.jar trlx -d personal.xml

Windows95, WindowsNT, OS/2 (ZIP archive)
  1. Install JDK-1.1 and `unzip` command.
  2. Download a distribution package in ZIP format.
  3. Unzip the distribution package, `xml4j.n.n.n.zip` into a directory.

         C:\>unzip some_directory\xml4j.n.n.n.zip
         C:\>cd xml4j
         C:\xml4j>

     You will see the following files in the `xml4j` directory:

     > `FAQ.html` | FAQ
     > `README.html` | this file
     > `api/` | directory for API documents
     > `docs/` | directory for documents
     > `license.html` | license information
     > `personal.dtd` | sample DTD file
     > `personal.xml` | sample XML document
     > `src/` | directory for source code
     > `xml4j.jar` | class files

  4. Try the following command to test your installation. This test parses the input and then regenerates the same XML document.

         C:\xml4j>type personal.xml
         C:\xml4J>jre -cp xml4j.jar trlx -d personal.xml

UNIX
  1. Install JDK-1.1 and GNU gzip.
  2. Download a distribution package in `.tar.gz` format. (If you have installed the `unzip` command for UNIX, ZIP format is also Ok.)
  3. Extract the distribution package into a directory.

         # cd /usr/local
         # gzip -dc some_directory/xml4j.n.n.n.tar.gz | tar xvf -
         # cd xml4j

     You will see the following files in the `xml4j` directory:

     > `FAQ.html` | FAQ
     > `README.html` | this file
     > `api/` | directory for API documents
     > `docs/` | directory for documents
     > `license.html` | license information
     > `personal.dtd` | sample DTD file
     > `personal.xml` | sample XML document
     > `src/` | directory for source code
     > `xml4j.jar` | class files

  4. Try the following command to test your installation. This program parses the input and then regenerates the same XML document.

         # cat personal.xml
         # jre -cp xml4j.jar trlx -d personal.xml

## Sample Applications

Some sample applications are provided:

trlx (Java application):

  trlx is an XML syntax checker. To check an XML document, type:

  > `jre -cp xml4j.jar trlx <xml-filename>`

SiteOutliner (Java application):

  SiteOutliner is a Java application that scans a Web site and reports its profile in CDF format. The profile contains a list of links to the pages, showing the structure of the site. The user can limit the files to be scanned by using some conditions, such as file types (extensions) and modified dates. The program can be used in both command prompt and window environments.

CDF Editor (Java application):

  CDF Editor is a Java application to edit CDF files. The user loads a CDF file and edits the channels and items.

CDF Viewer (Java applet):

  CDF Viewer is an applet that parses CDF files and visualizes their structures by using a tree.

Validating Generation sample (Java application):

  This sample generates a valid element tree according to the specified DTD.

  > `jre -cp xml4j.jar com.ibm.xml.sample.GeneratingSample personal.dtd`

XML Tree-View (Java application):

  A sample application using `com.ibm.xml.parser.util.TreeFactory`. You need to install JFC 1.1 (Swing-1.0) to run this program.

  > `jre -cp "xml4j.jar;C:/swing-1.0.2/swingall.jar" com.ibm.xml.sample.TreeView personal.xml`

XPointer Demonstration (Java application):

  A sample application using `com.ibm.xml.xpointer` package. You need to install JFC 1.1 (Swing-1.0) to run this program.

  > `jre -cp "xml4j.jar;C:/swing-1.0.2/swingall.jar" com.ibm.xml.sample.XPointerDemo personal.xml`

  This program has 2 function:

  Click a node:
    Display an XPointer expression of clicked node on a text field.
  Put an XPointer expression and press "Go" button:
    Select nodes pointed by the XPointer.

All the classes required to run these sample applications are in `xml4j.jar`.

## Program Development

This distribution archive includes a file named `xml4j.jar`. Add this file to your `CLASSPATH` environment variable, writing a command such as

> `set CLASSPATH=C:\xml4j\xml4j.jar;.` (for Windows)

(assuming that you have installed XML for Java in `C:\xml4j`.)

> `setenv CLASSPATH /usr/local/xml4j/xml4j.jar:.` (for UNIX, csh/tcsh)

> `export CLASSPATH="/usr/local/xml4j/xml4j.jar:."` (for UNIX, ksh/bash/zsh)

The following resources are provided for application development:

- Programming Guide
- Javadoc API
- Source files

## Release Note

This version of the processor is based on XML 1.0 Recomendation [10-Feb-1998]
The processor supports 19 encodings for ``<?xml encoding="...."`'
  ISO-10646-UCS-4, ISO-10646-UCS-2, UTF-8, UTF-16, US-ASCII, ISO-8839-1 ... ISO-8859-9, ISO-2022-JP, Shift_JIS, EUC-JP, GB2312, Big5
Validating Generation
  Applications can recognize information in the Document Type Definition (DTD) and generate a document that has correct structure. See `How to query DTD information' in the programming guide.
W3C Document Object Model (DOM) [16-Apr-1998] Support:
  Supported Interfaces:
    `Attribute, AttributeDefinition, AttributeList, CDATASection, Comment, Document, Element, Node, NodeIterator, Notation, PI, Text` (there are limitations in some methods)
  Unsupported Interfaces:
    `DocumentContext, DocumentFragment, DocumentType, DOM, ElementDefinition, ElementToken, EntityDeclaration, EntityReference, ModelGroup, PCDATAToken, TreeIterator, XMLNode`

  W3C DOM interfaces belong to a package named ``org.w3c.dom`'.

Simple API for XML (SAX) 1.0 Support
  `com.ibm.xml.parser.SAXDriver` provides the SAX interface.
Namespaces [27-Mar-1998] Support
  See the programming guide.
Element Digest
  See the DOMHASH document.
XPointer package
  `com.ibm.xml.xpointer` package provides parsing XPointer expression, generating an `XPointer` instance from a node in a document tree, searching for nodes pointed by an `XPointer` instance.

### CHANGES

Changes: 13-May-1998 to 12-Jun-1998
  - Integrated `EntityValue` and `Entity` into `Entity`; Removed `EntityValue`.
  - Added `java.io.Serializable` interface to object model classes.
  - XPointer implementation: `XPointer makeXPointer()` of `Child` class and `Pointed point(TXDocument)` of `XPointer` class.
  - New sample program: `com.ibm.xml.sample.XPointerDemo`
  - And fixed some bugs

Here is more description in HTML comment.

12 Jun 1998
  Public release.
16 Jun 1998
  Moved `Parser#setNamespace()` to `TXDocument#setNamespaceParameters()`
  Added `Parser#getNumberOfWarnings()`
  Added `Parser#setEndBy1stError()`
18 Jun 1998
  Gave all sources version number as "1.1".
  Removed `com.ibm.xml.xpointer.Version`
  Change format of `com.ibm.xml.parser.Version`
  Added `DTD#getInsertableElementsForValidContent()`
19 Jun 1998
  Fixed a bug of parameter entity references in an IGNORE section.

### TO DO

- Follow Namespace spec.
- More DOM support
- XLL support
- Performance improvement
- KNOWN PROBLEMS:
  - `NodeIterator`s aren't LIVE.
  - Multi threads safety

## Contact

Technical questions and comments to alphaWorks communityXchange or TAMURA, Kent (A Notes address for IBM employees is <`Kento Tamura/Japan/IBM@IBMJP`>)

Non-technical questions to MARUYAMA, Hiroshi (A Notes address is <`Hiroshi Maruyama/Japan/IBM@IBMJP`>)

[ IBM | alphaWorks | XML for Java | communityXchange - XML for Java | XML for Java (IBM Internal Only) ]

Last modified: Fri Jun 19 12:39:26 JST 1998