1
XML Parser for Java

XML parsing facilitates the extension of existing applications to support XML by processing XML documents and providing access to the information contained in them through a variety of APIs. This chapter contains the following sections

• DefaultXMLDocumentHandler Class
• DocumentBuilder Class
• DOMParser Class
• NodeFactory Class
• oraxml class
• SAXAttrList Class
• SAXParser Class
• XMLParseException Class
• XMLParser Class
• XMLToken Class
• XMLTokenizer Class
• NSName Class
• XMLError Class
• XMLException Class

  See Also: Oracle9i XML Developer's Kits Guide - XDK Oracle9i Supplied Java Packages Reference

---

DefaultXMLDocumentHandler Class

---

Description of DefaultXMLDocumentHandler

This class implements the default behavior for the XMLDocumentHandler interface. Application writers can extend this class when they need to implement only part of the interface.

---

Syntax of DefaultXMLDocumentHandler

public class DefaultXMLDocumentHandler implements 
oracle.xml.parser.v2.XMLDocumentHandler
 
oracle.xml.parser.v2.DefaultXMLDocumentHandler

Implemented Interfaces of DefaultXMLDocumentHandler

XMLDocumentHandler

---

Methods of DefaultXMLDocumentHandler

Table 1-1 Summary of Methods of DefaultXMLDocumentHandler  

Method	Description
DefaultXMLDocumentHandler()	Constructs a default document.
cDATASection()	Receive notification of a CDATA Section.
comment()	Receive notification of a comment.
endDoctype()	Receive notification of end of the DTD.
endElement()	Receive notification of the end of an element.
endPrefixMapping()	End the scope of a prefix-URI mapping.
getHandler()	Get the next pipe-line node handler.
setDoctype()	Receive notification of DTD. Sets the DTD.
setError()	Receive notification of a XMLError handler.
setHandler()	Receive notification of a next pipe-line node handler.
setTextDecl()	Receives notification of a Text XML Declaration.
setXMLDecl()	Receives notification of an XML Declaration.
setXMLSchema()	Receives notification of a XMLSchema object.
skippedEntity()	Receives notification of a skipped entity.
startElement()	Receives notification of the beginning of an element.
startPrefixMapping()	Begins the scope of a prefix-URI Namespace mapping.

DefaultXMLDocumentHandler()

Description

Constructs a default document.

Syntax

public  DefaultXMLDocumentHandler();

cDATASection()

Description

Receive notification of a CDATA Section. The Parser will invoke this method once for each CDATA Section found. Throws org.xml.sax.SAXException, which could be any SAX exception, possibly wrapping another exception.

Syntax

public void cDATASection( char[] ch, 
                          int start, 
                          int length);

Parameter	Description
ch	The CDATA section characters.
start	The start position in the character array.
length	The number of characters to use from the character array.

comment()

Description

Receives notification of a comment. The Parser will invoke this method once for each comment found: note that comment may occur before or after the main document element. Throws org.xml.sax.SAXException, which could be any SAX exception, possibly wrapping another exception.

Syntax

public void comment( String data);

Parameter	Description
data	The comment data, or NULL if none is supplied.

endDoctype()

Description

Receives notification of end of the DTD. Throws org.xml.sax.SAXException, which could be any SAX exception, possibly wrapping another exception.

Syntax

public void endDoctype();

endElement()

Description

Receives notification of the end of an element. Throws org.xml.sax.SAXException, which could be any SAX exception, possibly wrapping another exception. The options are described in the following table.

Syntax	Description
public void endElement( NSName elem);	Receives notification of the end of an element using the element.
public void endElement( String namespaceURI, String localName, String qName);	Receives notification of the end of an element using the namespace, the local name, and the qualified name.

Parameter	Description
elem	NSName object.
uri	The Namespace URI, or the empty string if the element has no Namespace URI or if Namespace processing is not being performed.
localName	The local name (without prefix), or the empty string if Namespace processing is not being performed.
qname	The qualified XML 1.0 name (with prefix), or the empty string if qualified names are not available.

endPrefixMapping()

Description

End the scope of a prefix-URI mapping. Throws org.xml.sax.SAXException, which could be any SAX exception, possibly wrapping another exception.

Syntax

public void endPrefixMapping( String prefix);

getHandler()

Description

Returns the next pipe-line node handler node.

Syntax

public XMLDocumentHandler getHandler();

setDoctype()

Description

Sets the DTD so can subsequently receive notification of that DTD. Throws org.xml.sax.SAXException, which could be any SAX exception, possibly wrapping another exception.

Syntax

public void setDoctype( DTD dtd);

Parameter	Description
dtd	The DTD.

setError()

Description

Receives notification of a XMLError handler. Throws org.xml.sax.SAXException, which could be any SAX exception, possibly wrapping another exception.

Syntax

public void setError( XMLError he);

Parameter	Description
err	The XMLError object.

setHandler()

Description

Receive notification of a next pipe-line node handler. Throws org.xml.sax.SAXException, which could be any SAX exception, possibly wrapping another exception.

Syntax

public void setHandler( XMLDocumentHandler h);

Parameter	Description
h	The XMLDocumentHandler node.

setTextDecl()

Description

Receive notification of a Text XML Declaration. The Parser will invoke this method once for each text XML Decl. Throws org.xml.sax.SAXException, which could be any SAX exception, possibly wrapping another exception.

Syntax

public void setTextDecl( String version, 
                         String encoding);

Parameter	Description
version	The version number.
encoding	The encoding name, or NULL if not specified.

setXMLDecl()

Description

Receive notification of an XML Declaration. The Parser will invoke this method once for XML Decl. Throws org.xml.sax.SAXException, which could be any SAX exception, possibly wrapping another exception.

Syntax

public void setXMLDecl( String version, 
                        String standalone, 
                        String encoding);

Parameter	Description
version	The version number.
standalone	The Standalone value, or NULL if not specified.
encoding	The encoding name, or NULL if not specified.

setXMLSchema()

Description

Receive notification of a XMLSchema object. Throws org.xml.sax.SAXException, which could be any SAX exception, possibly wrapping another exception.

Syntax

public void setXMLSchema( Object s);

Parameter	Description
s	The XMLSchema object.

skippedEntity()

Description

Receives notification of a skipped entity. Throws org.xml.sax.SAXException, which could be any SAX exception, possibly wrapping another exception.

Syntax

public void skippedEntity( String name);

Parameter	Description
name	The name of the skipped entity. If it is a parameter entity, the name will begin with '%', and if it is the external DTD subset, it will be the string "[dtd]".

startElement()

Description

Receives notification of the beginning of an element. Throws org.xml.sax.SAXException, which could be any SAX exception, possibly wrapping another exception. The options are described in the following table.

Syntax	Description
public void startElement( NSName elem, SAXAttrList attrlist);	Receives notification of the start of an element using the element.
public void startElement( String namespaceURI, String localName, String qName, org.xml.sax.Attributes atts);	Receives notification of the start of an element using the namespace, the local name, and the qualified name.

Parameter	Description
elem	NSName object.
attlist	SAXAttrList for the element.
uri	The Namespace URI, or the empty string if the element has no Namespace URI or if Namespace processing is not being performed.
localName	The local name (without prefix), or the empty string if Namespace processing is not being performed.
qname	The qualified name (with prefix), or the empty string if qualified names are not available.
atts	The attributes attached to the element. If there are no attributes, it shall be an empty Attributes object.

startPrefixMapping()

Description

Begin the scope of a prefix-URI Namespace mapping. Throws org.xml.sax.SAXException, which could be any SAX exception, possibly wrapping another exception.

Syntax

public void startPrefixMapping( String prefix, 
                                String uri);

Parameter	Description
prefix	The Namespace prefix being declared.
uri	The Namespace URI the prefix is mapped to.

---

DocumentBuilder Class

---

Syntax of DocumentBuilder

public class DocumentBuilder
 
oracle.xml.parser.v2.DocumentBuilder

---

Description of DocumentBuilder

This class implements XMLDocumentHandler (deprecated) and ContentHandler to build a DOM Tree from SAX 2.0 events. XMLDocumentHandler events are supported for backward compatibility

---

Methods of DocumentBuilder

Table 1-2 Summary of Methods of DocumentBuilder  

Method	Description
DocumentBuilder()	Creates a document builder that can be used as XMLDocumentHandler.
attributeDecl()	Reports an attribute type declaration.
cDATASection()	Receives notification of CDATA Section data inside an element.
characters()	Receives notification of character data inside an element.
comment()	Receives notification of a comment.
elementDecl()	Reports an element type declaration.
endCDATA()	Reports the end of a CDATA section.
endDoctype()	Receives notification of end of the DTD.
endDocument()	Receives notification of the end of the document.
endDTD()	Reports the end of DTD declarations.
endElement()	Receives notification of the end of an element.
endEntity()	Reports the end of an entity.
externalEntityDecl()	Reports a parsed external entity declaration.
getCurrentNode()	Returns the current node being build.
getDocument()	Gets the document being build
ignorableWhitespace()	Receives notification of ignorable whitespace in element content.
internalEntityDecl()	Reports an internal entity declaration
processingInstruction()	Receives notification of a processing instruction.
retainCDATASection()	Sets a flag to retain CDATA sections
setDebugMode()	Sets a flag to turn on debug information in the document
setDoctype()	Receives notification of DTD Sets the DTD
setDocumentLocator()	Receives a Locator object for document events. By default, do nothing. Application writers may override this method in a subclass if they wish to store the locator for use with other document events.
setNodeFactory()	Sets an optional NodeFactory to be used for creating custom DOM trees
setTextDecl()	Receives notification of a Text XML Declaration. The Parser will invoke this method once for each text XML Decl.
setXMLDecl()	Receives notification of a XML Declaration. The Parser will invoke this method once for XML Decl.
startCDATA()	Reports the start of a CDATA section.
startDocument()	Receives notification of the beginning of the document.
startDTD()	Reports the start of DTD declarations, if any.
startElement()	Receives notification of the beginning of an element.
startEntity()	Reports the beginning of some internal and external XML entities. All start/indemnity events must be properly nested.

DocumentBuilder()

Description

Default constructor. Creates a document builder that can be used as XMLDocumentHandler.

Syntax

public  DocumentBuilder();

attributeDecl()

Description

Reports an attribute type declaration. Throws org.xml.sax.SAXException, which could be any SAX exception, possibly wrapping another exception.

Syntax

public void attributeDecl( String eName,
                           String aName,
                           String type,
                           String valueDefault,
                           String value);

Parameter	Description
eName	The name of the associated element.
aName	The name of the attribute.
type	A string representing the attribute type.
valueDefault	A string representing the attribute default ("#IMPLIED", "#REQUIRED", or "#FIXED") or null if none of these applies
value	A string representing the attribute's default value, or NULL if there is none.

cDATASection()

Description

Receives notification of CDATA Section data inside an element. Throws org.xml.sax.SAXException, which could be any SAX exception, possibly wrapping another exception.

Syntax

public void cDATASection( char[] ch,
                          int start,
                          int length);

Parameter	Description
ch	The CDATA characters.
start	The starting position in the array.
length	The number of characters to use from the array.

characters()

Description

Receive notification of character data inside an element. Throws org.xml.sax.SAXException, which could be any SAX exception, possibly wrapping another exception.

Syntax

public void characters( char[] ch,
                        int start,
                        int length)

Parameter	Description
ch	An array holding the character data.
start	The starting position in the array.
length	The number of characters to use from the array.

comment()

Description

Receives notification of a comment. Reports an XML comment anywhere in the document. Throws org.xml.sax.SAXException, which could be any SAX exception, possibly wrapping another exception. The options are described in the following table.

Syntax	Description
public void comment( char[] ch, int start, int length);	Receives notification of a comment using the parameters of the comment character array.
public void comment( String data);	Receives notification of a comment using the comment data.

Parameter	Description
ch	An array holding the characters in the comment.
start	The starting position in the array.
length	The number of characters to use from the array.
data	The comment data, or NULL if none was supplied.

elementDecl()

Description

Report an element type declaration. Throws org.xml.sax.SAXException, which could be any SAX exception, possibly wrapping another exception.

Syntax

public void elementDecl( String name,
                         String model);

Parameter	Description
name	The element type name.
model	The content model as a normalized string.

endCDATA()

Description

Reports the end of a CDATA section. Throws org.xml.sax.SAXException, which could be any SAX exception, possibly wrapping another exception.

Syntax

public void endCDATA();

endDoctype()

Description

Receives notification of end of the DTD. Throws org.xml.sax.SAXException, which could be any SAX exception, possibly wrapping another exception.

Syntax

public void endDoctype();

endDocument()

Description

Receives notification of the end of the document. Throws org.xml.sax.SAXException, which could be any SAX exception, possibly wrapping another exception.

Syntax

public void endDocument();

endDTD()

Description

Reports the end of DTD declarations. Throws org.xml.sax.SAXException, which could be any SAX exception, possibly wrapping another exception.

Syntax

public void endDTD();

endElement()

Description

Receives notification of the end of an element. Throws 
org.xml.sax.SAXException, which could be any SAX exception, possibly 
wrapping another exception. The options are described in the following table.

Syntax	Description
public void endElement( NSName elem);	Receives notification of the end of an element using the element.
public void endElement( String namespaceURI, String localName, String qName);	Receives notification of the end of an element using the namespace, the local name, and the qualified name.

Parameter	Description
elem	NSName object.
namespaceURI	The Namespace URI, or the empty string if the element has no Namespace URI or if Namespace processing is not being performed.
localName	The local name (without prefix), or the empty string if Namespace processing is not being performed.
qname	The qualified XML 1.0 name (with prefix), or the empty string if qualified names are not available.

endEntity()

Description

Reports the end of an entity. Throws org.xml.sax.SAXException, which could be any SAX exception, possibly wrapping another exception.

Syntax

public void endEntity( String name);

Parameter	Description
name	The name of the entity that is ending.

externalEntityDecl()

Description

Reports a parsed external entity declaration. Throws org.xml.sax.SAXException, which could be any SAX exception, possibly wrapping another exception.

Syntax

public void externalEntityDecl( String name, 
                                String publicId, 
                                String systemId);

Parameter	Description
name	The name of the entity. If it is a parameter entity, the name will begin with '%'.
publicId	The declared public identifier of the entity declaration, or null if none was declared.
systemId	The declared system identifier of the entity.

getCurrentNode()

Description

Returns the current XMLNode being build.

Syntax

public XMLNode getCurrentNode();

getDocument()

Description

Returns the document being build.

Syntax

public XMLDocument getDocument();

ignorableWhitespace()

Description

Receives notification of ignorable whitespace in element content. Throws org.xml.sax.SAXException, which could be any SAX exception, possibly wrapping another exception.

Syntax

public void ignorableWhitespace( char[] ch, 
                                 int start, 
                                 int length);

Parameter	Description
ch	The whitespace characters.
start	The start position in the character array.
length	The number of characters to use from the character array.

internalEntityDecl()

Description

Report an internal entity declaration. Throws org.xml.sax.SAXException, which could be any SAX exception, possibly wrapping another exception.

Syntax

public void internalEntityDecl( String name, 
                                String value);

Parameter	Description
name	The name of the entity. If it is a parameter entity, the name will begin with '%'.
value	The replacement text of the entity.

processingInstruction()

Description

Receives notification of a processing instruction. Throws org.xml.sax.SAXException, which could be any SAX exception, possibly wrapping another exception.

Syntax

public void processingInstruction( String target,
                                   String data);

Parameter	Description
target	The processing instruction target.
data	The processing instruction data, or NULL if none is supplied.

retainCDATASection()

Description

Sets a flag to retain CDATA sections

Syntax

public void retainCDATASection( boolean flag);

Parameter	Description
flag	Determines whether CDATA sections are retained; TRUE for storing, FALSE otherwise.

setDebugMode()

Description

Sets a flag to turn on debug information in the document.

Syntax

public void setDebugMode(b oolean flag);

Parameter	Description
flag	Determines whether debug info is stored; TRUE for storing, FALSE otherwise.

setDoctype()

Description

Sets the DTD so can subsequently receive notification of that DTD. Throws org.xml.sax.SAXException, which could be any SAX exception, possibly wrapping another exception.

Syntax

public void setDoctype( DTD dtd);

Parameter	Description
did	The DTD for the document.

setDocumentLocator()

Description

Sets the Locator so can subsequently receive notification for this Locator object for document events. By default, do nothing. Application writers may override this method in a subclass if they wish to store the locator for use with other document events.

Syntax

public void setDocumentLocator( org.xml.sax.Locator locator);

Parameter	Description
locator	A locator for all SAX document events.

setNodeFactory()

Description

Sets a optional NodeFactory to be used for creating custom DOM trees.

Syntax

public void setNodeFactory( NodeFactory f);

Parameter	Description
f	NodeFactory/

setTextDecl()

Description

Receive notification of a Text XML Declaration. The Parser will invoke this method once for each text XML Decl. Throws org.xml.sax.SAXException, which could be any SAX exception, possibly wrapping another exception.

Syntax

public void setTextDecl( String version,
                         String encoding);

Parameter	Description
version	The version number, or NULL if not specified.
encoding	The encoding name, or NULL if not specified.

setXMLDecl()

Description

Receive notification of a XML Declaration. The Parser will invoke this method once for XML Decl. Throws org.xml.sax.SAXException, which could be any SAX exception, possibly wrapping another exception.

Syntax

public void setXMLDecl( String version,
                        String standalone,
                        String encoding);

Parameter	Description
version	The version number.
standalone	The standalone value, or NULL if not specified.
encoding	The encoding name, or NULL if not specified.

startCDATA()

Description

Reports the start of a CDATA section. Throws org.xml.sax.SAXException, which could be any SAX exception, possibly wrapping another exception.

Syntax

public void startCDATA();

startDocument()

Description

Receive notification of the beginning of the document. Throws org.xml.sax.SAXException, which could be any SAX exception, possibly wrapping another exception.

Syntax

public void startDocument();

startDTD()

Description

Report the start of DTD declarations, if any. Throws org.xml.sax.SAXException, which could be any SAX exception, possibly wrapping another exception.

Syntax

public void startDTD( String name, 
                      String publicId,
                      String systemId);

Parameter	Description
name	The document type name.
publicId	The declared public identifier for the external DTD subset, or null if none was declared.
systemId	The declared system identifier for the external DTD subset, or null if none was declared.

startElement()

Description

Receives notification of the beginning of an element. Throws org.xml.sax.SAXException, which could be any SAX exception, possibly wrapping another exception. The options are described in the following table.

Syntax	Description
public void startElement( NSName elem, SAXAttrList attrlist);	Receives notification of the start of an element using the element.
public void startElement( String namespaceURI, String localName, String qName, org.xml.sax.Attributes atts);	Receives notification of the start of an element using the namespace, the local name, and the qualified name.

Parameter	Description
elem	NSName object.
attlist	SAXAttrList for the element.
naemspaceURI	The Namespace URI, or the empty string if the element has no Namespace URI or if Namespace processing is not being performed.
localName	The local name (without prefix), or the empty string if Namespace processing is not being performed.
qName	The qualified name (with prefix), or the empty string if qualified names are not available.
atts	The attributes attached to the element. If there are no attributes, it shall be an empty Attributes object.

startEntity()

Description

Reports the beginning of some internal and external XML entities. All start/endEntity events must be properly nested. Throws org.xml.sax.SAXException, which could be any SAX exception, possibly wrapping another exception.

Syntax

public void startEntity( String name);

Parameter	Description
name	The name of the entity. If it is a parameter entity, the name will begin with '%', and if it is the external DTD subset, it will be "[dtd]".

---

DOMParser Class

---

Syntax of DOMParser

public class DOMParser
 
oracle.xml.parser.v2.DOMParser

---

Description of DOMParser

This class implements an eXtensible Markup Language (XML) 1.0 parser according to the World Wide Web Consortium (W3C) recommendation. to parse a XML document and build a DOM tree.

---

Fields of DOMParser

Table 1-3 Fields of DOMParser

Field	Syntax	Description
DEBUG_MODE	public static final java.lang.String DEBUG_MODE	Sets Debug Mode Boolean.TRUE or Boolean.FALSE
ERROR_ENCODING	public static final java.lang.String ERROR_ENCODING	Encoding for errors report through error stream (only if ERROR_STREAM is set).
ERROR_STREAM	public static final java.lang.String ERROR_STREAM	Error stream for reporting errors. The object can be OutputStream or PrintWriter. This attribute is ignored if ErrorHandler is set.
NODE_FACTORY	public static final java.lang.String NODE_FACTORY	Set NodeFactory to build custom Nodes
SHOW_WARNINGS	public static final java.lang.String SHOW_WARNINGS	Boolean to ignore warnings Boolean.TRUE or Boolean.FALSE

---

Methods of DOMParser

Table 1-4 Summary of Methods of DOMParser

Method	Description
DOMParser()	Creates a new parser object.
getAttribute()	Returns specific attributes of the underlying implementation.
getDoctype()	Gets the DTD.
getDocument()	Gets the document.
parseDTD()	Parses the XML External DTD from given input source.
reset()	Resets the parser state
retainCDATASection()	Switches to determine whether to retain CDATA sections
setAttribute()	Sets specific attributes on the underlying implementation.
setDebugMode()	Sets a flag to turn on debug information in the document
setErrorStream()	Creates an output stream for errors and warnings.
setNodeFactory()	Sets the node factory.
showWarnings()	Switches to determine whether to print warnings

DOMParser()

Description

Creates a new parser object.

Syntax;

public  DOMParser();

getAttribute()

Description

Returns specific attributes on the underlying implementation. Throws IllegalArgumentException if the underlying implementation doesn't recognize the attribute.

Syntax

public java.lang.Object getAttribute( String name);

Parameter	Description
name	The name of the attribute.

getDoctype()

Description

Returns the DTD.

Syntax

public DTD getDoctype();

getDocument()

Description

Returns the document being parsed.

Syntax

public XMLDocument getDocument();

parseDTD()

Description

Parses the XML External DTD from given input stream. Throws the following exceptions:

• XMLParseException if syntax or other error encountered.
• SAXException, which could be SAX exception, possibly wrapping another exception.
• IOException in cases of I/O Error.

The options are described in the following table.

Syntax	Description
public final void parseDTD( org.xml.sax.InputSource in, String rootName);	Parses the XML External DTD from an input source.
public final void parseDTD( java.io.InputStream in, String rootName);	Parses the XML External DTD from an input stream. The base URL should be set for resolving external entities and DTD.
public final void parseDTD( java.io.Reader r, String rootName);	Parses the XML External DTD from a reader. The base URL should be set for resolving external entities and DTD.
public final void parseDTD( String in, String rootName);	Parses the XML External DTD from a string.
public final void parseDTD( java.net.URL url, String rootName);	Parses the XML External DTD document poi9nted to by the given URL and creates the corresponding XML document hierarchy.