docs/faq-migrate.xml

<?xml version="1.0" standalone="no"?>
<!DOCTYPE faqs SYSTEM "./dtd/faqs.dtd">

<faqs title="Migrating to &javaparsernamelong;">
	<faq title="What should I be aware of when using various DOM parsers?">
		<q>What should I be aware of when using various DOM parsers?</q>
		<a><p>There are a couple of points to note when using the various 
			DOM parsers. This FAQ discusses some of the differences between the 
			Xerces, Oracle and Sun XML parsers:</p>
			<ol>
				<li><em>Parsing methods:</em>
					<br/>The &javaparsername; and Oracle parsers have a parser object that parses 
					XML files and constructs a DOM tree which is queried 
					<ref>after</ref> parsing. 
					<br/>The Sun parser calls a static method on the 
					<code>XmlDocument</code> class 
					to parse and construct a DOM tree.</li>
				<li><em>Specifying the source file:</em>
					<br/>All three parsers allow specifying the source of the 
					XML document using the SAX <code>InputSource</code> object 
					as well as parsing from <code>java.io.InputStream</code> 
					and <code>java.io.Reader</code> object.</li>
				<li><em>Error handling:</em>
					<br/>The &javaparsername; parser uses the SAX <code>ErrorHandler</code> mechanism 
					on all parser types, including DOM. 
					<br/>The Oracle parser only allows you to specify which 
					output stream or writer you want the error to be written. 
					<br/>The Sun parser has no way to request 
					error notification when parsing XML files into DOM trees. 
					An exceptions will be thrown if an error occurs during 
					parsing.</li>
				<li><em>Validation:</em>
					<br/>The &javaparsername; and Oracle DOM parsers use a method to 
					set validation. 
					<br/>Because of the way that DOM documents are constructed from XML files 
					in the Sun parser, validation is set via a parameter to the static 
					<code>createXmlDocument</code> method.</li>
				<li><em>Standard versus proprietary features:</em>
					<br/>If the user has written their programs using the W3C DOM API, 
					then migrating to &javaparsername; is easy. If however, the user takes 
					advantage of non-standard, proprietary features of the Oracle and Sun 
					parsers and DOM implementations, migration will be harder. 
					This document does not 
					go into any detail regarding migration of features specific to each 
					parser&apos;s implementation that are non-standard.</li>
			</ol>
			<p><em>Samples:</em></p>
			<p>Xerces 1.0.x:</p>

<source>// instantiate parser
org.apache.xerces.parsers.DOMParser parser;
parser = new org.apache.xerces.parsers.DOMParser();

// specifying validation
boolean validate = /* true or false */;
parser.setFeature("http://xml.org/sax/features/validation", validate);

// installing error handler
org.xml.sax.ErrorHandler handler = /* SAX error handler */;
parser.setErrorHandler(handler);

// parsing document from URI string
String uri = /* uri */;
parser.parse(uri);

// parsing document from input stream
java.io.InputStream stream = /* input stream */;
parser.parse(new org.xml.sax.InputSource(stream));

// parsing document from reader
java.io.Reader reader = /* reader */;
parser.parse(new org.xml.sax.InputSource(reader));

// querying document after parse
org.w3c.dom.Document document;
document = parser.getDocument();</source>

<p>Oracle 2.0.2.x:</p>

<source>// instantiate parser
oracle.xml.parser.v2.DOMParser parser;
parser = oracle.xml.parser.v2.DOMParser();

// specifying validation
boolean validate = /* true or false */;
parser.setValidationMode(validate);

// installing error stream to output stream (with and without encoding)
java.io.OutputStream output = /* output stream */;
String encoding = /* Java encoding name */;
parser.setErrorStream(output);
parser.setErrorStream(output, encoding);

// installing error stream to print writer
java.io.PrintWriter printer = /* print writer */;
parser.setErrorStream(printer);

// parsing document from URI string
String uri = /* uri */;
parser.parse(uri);

// parsing document from input stream
java.io.InputStream stream = /* input stream */;
parser.parse(stream);

// parsing document from reader
java.io.Reader reader = /* reader */;
parser.parse(reader);

// querying document after parse
org.w3c.dom.Document document;
document = parser.getDocument();</source>

<p>Sun TR2:</p>

<source>// parsing document from URI string
String uri = /* uri */;
Document document;
document = com.sun.xml.tree.XmlDocument.createXmlDocument(uri);

// parsing document from URI string (with validation)
boolean validate = /* true or false */;
document = com.sun.xml.tree.XmlDocument.createXmlDocument(uri, validate);

// parsing document from input stream
java.io.InputStream stream = /* input stream */;
document = com.sun.xml.tree.XmlDocument.createXmlDocument(stream, validate);

// parsing document from reader
java.io.Reader reader = /* reader */;
document = com.sun.xml.tree.XmlDocument.createXmlDocument
           (new org.xml.sax.InputSource(reader), validate);</source>
		</a>
	</faq>
	
	<faq title="What should I be aware of when using various SAX parsers?">
		<q>What should I be aware of when using various SAX parsers?</q>
		<a><p>There are a couple of points to note when using the various 
		SAX parsers:</p>
			<p>The SAX API has detailed specifications on how documents are parsed 
			and entities are resolved, so little migration effort required. 
			The only change is the construction of the SAX parser. 
			See the following examples for construction details.</p>

			<note>Regarding validation: 
			<br/>If a parser is SAX2 
			compliant, there is a standard way of turning on validation. The 
			Xerces parser implements the appropriate methods today, even 
			though they haven't been finalized, yet. The parsers downloaded 
			from Oracle and Sun do not yet implement these methods. 
			The Oracle parser has a method to turn validation on and 
			off. The Sun parser requires you to instantiate a 
			separate parser object to perform validation.</note>
			
			<p><em>Samples:</em></p>
			<p>Xerces 1.0.x:</p>
<source>// instantiate parser
org.apache.xerces.parsers.SAXParser parser;
parser = new org.apache.xerces.parsers.SAXParser();

// specifying validation
boolean validate = /* true or false */;
parser.setFeature("http://xml.org/sax/features/validation", validate);

// installing error handler
org.xml.sax.ErrorHandler errorHandler = /* SAX error handler */;
parser.setErrorHandler(errorHandler);

// installing document handler
org.xml.sax.DocumentHandler documentHandler = /* SAX document handler */;
parser.setDocumentHandler(documentHandler);

// parsing document from URI string
String uri = /* uri */;
parser.parse(uri);

// parsing document from input stream
java.io.InputStream stream = /* input stream */;
parser.parse(new org.xml.sax.InputSource(stream));

// parsing document from reader
java.io.Reader reader = /* reader */;
parser.parse(new org.xml.sax.InputSource(reader));</source>
			<p>Oracle 2.0.2.x:</p>
<source>// instantiate parser
oracle.xml.parser.v2.SAXParser parser;
parser = oracle.xml.parser.v2.SAXParser();

// specifying validation
boolean validate = /* true or false */;
parser.setValidationMode(validate);

// ... the rest is the same as Xerces ...</source>
			<p>Sun TR2:</p>
<source>// instantiate parser
boolean validate = /* true or false */;
com.sun.xml.parser.Parser parser;
if (validate) {
    parser = new com.sun.xml.parser.ValidatingParser();
}
else {
    parser = new com.sun.xml.parser.Parser();
}

// ... the rest is the same as Xerces ...</source>

		</a>
	</faq>
	
	<faq title="Migrating from XML4J Version 2.0.x">
		<q>How do I migrate my code from XML4J Version 2.0.x?</q>
		<a>
	     <p>Migrating from the version 2.0.x native SAX and DOM parser
	      classes should be straight forward.</p>
		<table>
			<tr><th>change this XML4J class</th><th>to this &javaparsername; class</th></tr>
			<tr><td>com.ibm.xml.parsers.SAXParser</td> <td>org.apache.xerces.parsers.SAXParser</td></tr>
			<tr><td>com.ibm.xml.parsers.ValidatingSAXParser</td>  <td>org.apache.xerces.parsers.SAXParser + switch</td></tr>
			<tr><td>com.ibm.xml.parsers.NonValidatingDOMParser</td>  <td>org.apache.xerces.parsers.DOMParser</td></tr>
			<tr><td>com.ibm.xml.parsers.DOMParser</td>  <td>org.apache.xerces.parsers.DOMParser + switch</td></tr>
		</table>
		<p>Table entries that say " + switch" mean that you should use the
		Configurable API to turn validation on.  See the answer in <link idref="faq-general" anchor="valid">Validation</link>.</p>
		</a>
	</faq>
	
</faqs>