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.

Parameter	Description
in	The input to parse.
rootName	The element to be used as root Element.
r	The reader containing XML data to parse.
url	The url which points to the XML document to parse.

reset()

Description

Resets the parser state.

Syntax

public void reset();

retainCDATASection()

Description

Switches to determine whether to retain CDATA sections.

Syntax

public void retainCDATASection( boolean flag);

Parameter	Description
flag	TRUE - keep CDATASections (default) FALSE - convert CDATASection to Text nodes

setAttribute()

Description

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

Syntax

public void setAttribute( String name, 
                          Object value);

Parameter	Description
name	The name of the attribute.
value	he value of the attribute.

setDebugMode()

Description

Sets a flag to turn on debug information in the document

Syntax

public void setDebugMode( boolean flag);

Parameter	Description
flag	Determines whether debug info is stored.

setErrorStream()

Description

Creates an output stream for the output of errors and warnings. If an output stream for errors is not specified, the parser will use the standard error output stream System.err for outputting errors and warnings. Additionally, an exception is thrown if the encoding specified is unsupported. The options are described in the following table.

Syntax	Description
public final void setErrorStream( java.io.OutputStream out);	Creates an output stream for the output of errors and warnings.
public final void setErrorStream( java.io.OutputStream out, String enc);	Creates an output stream for the output of errors and warnings. Throws an IOEexception if the encoding specified is unsupported.
public final void setErrorStream( java.io.PrintWriter out);	Creates a Print Writer for the output of errors and warnings. Throws IOException if I/O error occurs in setting the error stream.

Parameter	Description
out	Used for output of errors and warnings.
enc	The encoding to use.

setNodeFactory()

Description

Set the node factory. Applications can extend the NodeFactory and register it through this method. The parser will then use the user supplied NodeFactory to create nodes of the DOM tree. Throws XMLParseException if an invalid factory is set

Syntax

public void setNodeFactory( NodeFactory factory);

Parameter	Description
factory	The NodeFactory to set.

showWarnings()

Description

Switches to determine whether to print warnings.

Syntax

public void showWarnings( boolean flag);

Parameter	Description
flag	Determines whether warnings should be shown.

---

NodeFactory Class

---

Description of NodeFactory

This class specifies methods to create various nodes of the DOM tree built during parsing. Applications can override these methods to create their own custom classes to be added to the DOM tree while parsing. Applications have to register their own NodeFactory using the XMLParser's setNodeFactory() method. If a null pointer is returned by these methods, then the node will not be added to the DOM tree.

---

Syntax of NodeFactory

public class NodeFactory extends java.lang.Object implements 
java.io.Serializable
 
java.lang.Object
  |
  +--oracle.xml.parser.v2.NodeFactory

---

Implemented Interfaces of NodeFactory

java.io.Serializable

---

Methods of NodeFactory

Table 1-5 Summary of Methods of NodeFactory  

Method	Description
NodeFactory()	Class constructor.
createAttribute()	Creates and returns an attribute node with the specified tag, and text.
createCDATASection()	Creates and returns a CDATA node with the specified text.
createComment()	Creates and returns a comment node with the specified text.
createDocument()	Creates and returns a document node. This method cannot return a null pointer.
createDocumentFragment()	Creates and returns a document fragment node with the specified tag.
createElement()	Creates and returns an Element node with the specified tag.
createElementNS()	Creates and returns an Element node with the specified local name, prefix, namespaceURI
createEntityReference()	Creates and returns an entity reference node with the specified tag.
createProcessingInstruction()	Creates and returns a PI node with the specified tag, and text.
createTextNode()	Creates and returns s a text node with the specified text.

NodeFactory()

Description

Class constructor.

Syntax

public  NodeFactory();

createAttribute()

Description

Creates and returns an attribute node. The options are described in the following table.

Syntax	Description
public XMLAttr createAttribute( String tag, String text);	Creates and returns an attribute node with the specified tag and text.
public XMLAttr createAttribute( String localName, String prefix, String namespaceURI, String value);	Creates and returns an attribute node with the specified local name, prefix, namespaceURI, and value.

Parameter	Description
tag	The name of the node.
text	The text associated with the node.
localName	The name of the node.
prefix	The prefix of the node.
naemspaceURI	The namespace of the node.
value	The value associated with the node.

createCDATASection()

Description

Creates and returns CDATA node with the specified text.

Syntax

public XMLCDATA createCDATASection( String text);

Parameter	Description
text	The text associated with the node.

createComment()

Description

Creates and returns a comment node with the specified text.

Syntax

public XMLComment createComment( String text);

Parameter	Description
text	The text associated with the node.

createDocument()

Description

Creates and returns a document node. This method cannot return a null pointer.

Syntax

public XMLDocument createDocument();

createDocumentFragment()

Description

Creates a document fragment node with the specified tag.

Syntax

public XMLDocumentFragment createDocumentFragment();

Returns

The created document fragment node.

createElement()

Description

Creates and returns an Element node with the specified tag.

Syntax

public XMLElement createElement( String tag);

Parameter	Description
tag	The name of the element.

createElementNS()

Description

Creates and returns an Element node with the specified local name, prefix, and namespaceURI.

Syntax

public XMLElement createElementNS( String localName, 
                                   String prefix,
                                   String namespaceURI);

Parameters	Description
localName	The name of the element.
prefix	The prefix of an element.
namespaceURI	The namespace of the element.

createEntityReference()

Description

Creates and returns an entity reference node with the specified tag.

Syntax

public XMLEntityReference createEntityReference( String tag);

Parameter	Description
tag	The name of the node.

createProcessingInstruction()

Description

Creates and returns a ProcessingInstruction node with the specified tag, and text.

Syntax

public XMLPI createProcessingInstruction( String tag,
                                          String text);

Parameter	Description
tag	The name of the node.
text	The text associated with the node.

createTextNode()

Description

Creates and returns a text node with the specified text.

Syntax

public XMLText createTextNode( String text);

Parameter	Description
text	The text associated with the node.

---

oraxml class

---

Description of oraxml

The oraxml class provides a command-line interface to validate XML files

Table 1-6 Command-line interface of oraxml  

command	description
-help	Prints the help message.
-version	Prints the release version.
-novalidate	Parses the input file to check for well-formedness.
-dtd	Validates the input file with DTD validation.
-schema	Validates the input file with Schema validation.
-log <logfile>	Writes the errors/logs to the output file.
-comp	Compresses the input xml file.
-decomp	Decompresses the input compressed file.
-enc	Prints the encoding of the input file.
-warning	Show warnings.

---

Syntax of oraxml

public class oraxml extends java.lang.Object
 
java.lang.Object
  |
  +--oracle.xml.parser.v2.oraxml

---

Methods of oraxml

oraxml()

Syntax

public oraxml();

main()

syntax

public static void main( String[] args);

---

SAXAttrList Class

---

Description of SAXAttrList

This class implements the SAX AttributeList interface and also provides Namespace support. Applications that require Namespace support can explicitly cast any attribute list returned by an Oracle parser class to SAXAttrList and use the methods described here. It also implements Attributes (SAX 2.0) interface.

This interface allows access to a list of attributes in three different ways:

• by attribute index;
• by Namespace-qualified name; or
• by qualified (prefixed) name.

This interface replaces the now-deprecated SAX1 interface, which does not contain Namespace support. In addition to Namespace support, it adds the getIndex methods.

The order of attributes in the list is unspecified, and will vary from implementation to implementation.

---

Syntax of SAXAttrList

public class SAXAttrList
 
oracle.xml.parser.v2.SAXAttrList

---

Methods of SAXAttrList

Table 1-7 Summary of Methods of SAXAttrList  

Method	Description
SAXAttrList()	Class constructor.
addAttr()	Adds an attribute to the parent element node.
getExpandedName()	Returns the expanded name for an attribute in the list (by position).
getIndex()	Returns the index of an attribute.
getLength()	Returns the number of attributes in the list.
getLocalName()	Returns an attribute's local name by index.
getPrefix()	Returns the namesp.ace prefix for an attribute in the list by position.
getQName()	Returns an attribute's qualified name by index.
getType()	Returns an attribute's type.
getURI()	Returns an attribute's Namespace URI by index
getValue()	Returns the attribute's value as a string,
reset()	Resets the SAXAttrList.

SAXAttrList()

Description

Class constructor.

Syntax

public  SAXAttrList(int elems)

addAttr()

Description

Adds an attribute to the parent element node. The options are described in the following table.

Syntax	Description
public void addAttr( String pfx, String lname, String tag, String value, boolean spec, int type);	Adds attribute using prefix, local name, qualified name, value, specified flag, and attribute type.
public void addAttr( String pfx, String lname, String tag, String value, boolean spec, int type, String nmsp);	Adds attribute using prefix, local name, qualified name, value, specified flag, attribute type, and namespace.

Parameter	Description
pfx	The prefix of the attribute.
lname	The local name of the attribute.
tag	The qname of the attribute.
value	The attribute value.
spec	The specified flag.
type	The attribute type.
nmsp	The namespace.

getExpandedName()

Description

Returns the expanded name for an attribute in the list (by position).

Syntax

public String getExpandedName( int i);

Parameter	Description
i	The index of the attribute in the list.

getIndex()

Description

Returns the index of an attribute. Returns -1 if it does not appear in the list. The options are described in the following table.

Syntax	Description
public int getIndex( String qName);	Returns the index of an attribute by qualified name.
public int getIndex( String uri, String localName);	Returns the index of an attribute by namespace URI and local name.

Parameter	Description
qName	The qualified (prefixed) name.
uri	The Namespace URI, or the empty string if the name has no Namespace URI.
localName	The attribute's local name.

getLength()

Description

Returns the number of attributes in this list. The SAX parser may provide attributes in any arbitrary order, regardless of the order in which they were declared or specified. The number of attributes may be zero.

Syntax

public int getLength();

getLocalName()

Description

Returns an attribute's local name by index, or the empty string if Namespace processing is not being performed, or NULL if the index is out of range.

Syntax

public String getLocalName( int index);

Parameter	Description
index	The attribute index (zero-based).

getPrefix()

Description

Returns the namespace prefix for an attribute in the list by position.

Syntax

public String getPrefix( int index);

Parameter	Description
index	The attribute index (zero-based).

Parameters

i - The index of the attribute in the list.

getQName()

Description

Returns an attribute's XML 1.0 qualified name by index, or the empty string if none is available, or NULL if the index is out of range.

Syntax

public String getQName( int index);

Parameter	Description
index	The attribute index (zero-based).

getType()

Description

Returns an attribute's type. The attribute type is one of the strings "CDATA", "ID", "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY", "ENTITIES", or "NOTATION" (always in upper case). If the parser has not read a declaration for the attribute, or if the parser does not report attribute types, then it must return the value "CDATA" as stated in the XML 1.0 Recommendation (clause 3.3.3, "Attribute-Value Normalization"). For an enumerated attribute that is not a notation, the parser will report the type as "NMTOKEN". The options are described in the following table.

Syntax	Description
public String getType( int index);	Returns an attribute's type by index, or NULL if the index is out of range.
public String getType( String qName);	Returns an attribute's type by qualified name, or returns NULL if the attribute is not in the list or if qualified names are not available.
public String getType( String uri, String localName);	Returns an attribute's type by Namespace name, or returns NULL if the attribute is not in the list or if Namespace processing is not being performed.

Parameter	Description
index	The attribute index (zero-based).
qName.	The XML 1.0 qualified name.
uri	The Namespace URI, or the empty String if the name has no Namespace URI.
localName	The local name of the attribute.

getURI()

Description

Returns an attribute's Namespace URI by index, or the empty string if none is available, or null if the index is out of range.

Syntax

public String getURI( int index);

Parameter	Description
index	The attribute index (zero-based).

getValue()

Description

Returns the attribute's value as a string, or NULL if the index is out of range. If the attribute value is a list of tokens (IDREFS, ENTITIES, or NMTOKENS), the tokens will be concatenated into a single string with each token separated by a single space. The options are described in the following table.

Syntax	Description
public String getValue( int index);	Returns the attribute's value by index.
public String getValue( String qName);	Returns the attribute's value by qualified name.
public String getValue( String uri, String localName);	Returns the attribute's value by Namespace name.

Parameter	Description
index	The attribute index (zero-based).
qName	The XML 1.0 qualified name.
uri	The Namespace URI, or the empty String if the name has no Namespace URI.
localName	The local name of the attribute.

reset()

Description

Resets the SAXAttrList.

Syntax

public void reset();

---

SAXParser Class

---

Description of SAXParser

This class implements an eXtensible Markup Language (XML) 1.0 SAX parser according to the World Wide Web Consortium (W3C) recommendation. Applications can register a SAX handler to receive notification of various parser events.

XMLReader is the interface that an XML parser's SAX2 driver must implement. This interface allows an application to set and query features and properties in the parser, to register event handlers for document processing, and to initiate a document parse.

All SAX interfaces are assumed to be synchronous: the parse methods must not return until parsing is complete, and readers must wait for an event-handler callback to return before reporting the next event.

This interface replaces the (now deprecated) SAX 1.0 Parser interface. The XMLReader interface contains two important enhancements over the old Parser interface:

• it adds a standard way to query and set features and properties; and
• it adds Namespace support, which is required for many higher-level XML standards.

---

Syntax of SAXParser

public class SAXParser
 
oracle.xml.parser.v2.SAXParser

---

Methods of SAXParser

Table 1-8 Summary of Methods of SAXParser  

Method	Description
SAXParser()	Creates a new parser object.
getContentHandler()	Returns the current content handler.
getDTDHandler()	Returns the current DTD handler.
getFeature()	Returns the current state of the feature (true or false).
getProperty()	Returns the value of a property.
setContentHandler()	Registers a content event handler.
setDTDHandler()	Registers a DTD event handler.
setFeature()	Set the state of a feature.
setProperty()	Sets the value of a property.

SAXParser()

Description

Creates a new parser object.

Syntax

public  SAXParser()

getContentHandler()

Description

Returns the current content handler, or null if none has been registered.

Syntax

public org.xml.sax.ContentHandler getContentHandler();

getDTDHandler()

Description

Returns the current DTD handler, or null if none has been registered.

Syntax

public org.xml.sax.DTDHandler getDTDHandler();

getFeature()

Description

Returns the current state of the feature (true or false). The feature name is any fully-qualified URI. It is possible for an XMLReader to recognize a feature name but not be able to return its value; this is especially true in the case of an adapter for a SAX1 Parser, which has no way of knowing whether the underlying parser is performing validation or expanding external entities. Some feature values may be available only in specific contexts, such as before, during, or after a parse. Throws the following exceptions:

• org.xml.sax.SAXNotRecognizedException if the XMLReader does not recognize the feature name.
• org.xml.sax.SAXNotSupportedException if the XMLReader recognizes the feature name but cannot determine its value at this time.

The feature http://www.xml.org/sax/features/validation due to its binary input value only controls DTD validation. The value true sets DTD validation to TRUE. This feature cannot be used to control XML Schema based validation.

Implementors are free (and encouraged) to invent their own features, using names built on their own URIs.

Syntax

public boolean getFeature( String name);

Parameter	Description
name	Feature name.

getProperty()

Description

Returns the value of a property. The property name is any fully-qualified URI. It is possible for an XMLReader to recognize a property name but to be unable to return its state; this is especially true in the case of an adapter for a SAX1 Parser. XMLReaders are not required to recognize any specific property names, though an initial core set is documented for SAX2. Some property values may be available only in specific contexts, such as before, during, or after a parse. Implementors are free (and encouraged) to invent their own properties, using names built on their own URIs. Throws the following exceptions:

• org.xml.sax.SAXNotRecognizedException if the XMLReader does not recognize the feature name.
• org.xml.sax.SAXNotSupportedException if the XMLReader recognizes the feature name but cannot determine its value at this time.

Syntax

public Object getProperty( String name);

Parameter	Description
name	The property name, which is a fully-qualified URI

setContentHandler()

Description

Registers a content event handler. If the application does not register a content handler, all content events reported by the SAX parser will be silently ignored. Applications may register a new or different handler in the middle of a parse, and the SAX parser must begin using the new handler immediately. Throws java.lang.NullPointerException if the handler argument is null.

Syntax

public void setContentHandler( org.xml.sax.ContentHandler handler);

Parameter	Description
handler	The content handler.

setDTDHandler()

Description

Registers a DTD event handler. If the application does not register a DTD handler, all DTD events reported by the SAX parser will be silently ignored. Applications may register a new or different handler in the middle of a parse, and the SAX parser must begin using the new handler immediately. Throws java.lang.NullPointerException if the handler argument is null.

Syntax

public void setDTDHandler( org.xml.sax.DTDHandler handler);

Parameter	Description
handler	The DTD handler.

setFeature()

Description

Set the state of a feature. The feature name is any fully-qualified URI. It is possible for an XMLReader to recognize a feature name but to be unable to set its value; this is especially true in the case of an adapter for a SAX1 Parser , which has no way of affecting whether the underlying parser is validating, for example.

Some feature values may be immutable or mutable only in specific contexts, such as before, during, or after a parse. The feature "http:://www.xml.org/sax/features/validation" due to its binary input value only controls DTD validation. The value true sets DTD validation to TRUE. This feature cannot be used to control XML Schema based validation. Throws the following exceptions:

• org.xml.sax.SAXNotRecognizedException - When the XMLReader does not recognize the feature name.
• org.xml.sax.SAXNotSupportedException - When the XMLReader recognizes the feature name but cannot set the requested value.

Syntax

public void setFeature( String name, boolean value);

Parameter	Description
name	The feature name, which is a fully-qualified URI.
state	The requested state of the feature (true or false).

setProperty()

Description

Sets the value of a property. The property name is any fully-qualified URI. It is possible for an XMLReader to recognize a property name but to be unable to set its value; this is especially true in the case of an adapter for a SAX1 Parser. XMLReaders are not required to recognize setting any specific property names, though a core set is provided with SAX2. Some property values may be immutable or mutable only in specific contexts, such as before, during, or after a parse. This method is also the standard mechanism for setting extended handlers. Throws the following exceptions:

• org.xml.sax.SAXNotRecognizedException if the XMLReader does not recognize the property name.
• org.xml.sax.SAXNotSupportedException if the XMLReader recognizes the property name but cannot set the requested value.

Syntax

public void setProperty( String name, 
                         Object value);

Parameter	Description
name	The property name, which is a fully-qualified URI.
state	The requested value for the property.

---

XMLParseException Class

---

Description of XMLParseException

Indicates that a parsing exception occurred while processing an XML document

---

Syntax of XMLParseException

public class XMLParseException
 
oracle.xml.parser.v2.XMLParseException

---

Fields of XMLParseException

Table 1-9 Fields of XMLParseException

Field	Syntax	Description
ERROR	public static final int ERROR	Code for non-fatal error
FATAL_ERROR	public static final int FATAL_ERROR	Code for fatal error
WARNING	public static final int WARNING	Code for warning

---

Methods of XMLParseException

Table 1-10 Summary of Methods of XMLParseException  

Method	Description
XMLParseException()	Constructor for the XMLParse Exception class.
formatErrorMessage()	Formats error message at specified index.
getColumnNumber()	Returns column number of error at specified index.
getException()	Returns the exception that occurred in error at specified index.
getLineNumber()	Returns the line number of error at specified index.
getMessage()	Returns the error message at specified index.
getMessageType()	Returns the type of message at specified index.
getNumMessages()	Returns the total number of errors/warnings found during parsing.
getPublicId()	Returns the public id of input when error at specific index occurred.
getSystemId()	Returns the system ID of input when error at specific index occurred.

XMLParseException()

Description

Class constructor.

Syntax

public  XMLParseException( String mesg,
                           String pubId,
                           String sysId,
                           int line,
                           int col,
                           int type);

Parameter	Description
mesg	Message.
pubId	Public id.
sysId	System id.
line	Line.
col	Column.
type	Type.

formatErrorMessage()

Description

Returns the error message at specified index.

Syntax

public String formatErrorMessage( int i);

Parameter	Description
i	Index.

getColumnNumber()

Description

Returns the column number of error at specified index.

Syntax

public int getColumnNumber(int i);

Parameter	Description
i	Index.

getException()

Description

Returns the exception (if exists) that occurred in error at specified index.

Syntax

public java.lang.Exception getException(int i);

Parameter	Description
i	Index.

getLineNumber()

Description

Returns the line number of error at specified index

Syntax

public int getLineNumber(int i);

Parameter	Description
i	Index.

getMessage()

Description

Returns the error message at specified index

Syntax

public String getMessage(int i)

Parameter	Description
i	Index.

getMessageType()

Description

Returns the type of the error message at specified index.

Syntax

public int getMessageType(int i)

Parameter	Description
i	Index.

getNumMessages()

Description

Return the total number of errors/warnings found during parsing.

Syntax

public int getNumMessages();

getPublicId()

Description

Returns the public ID of input when error at specified index occurred.

Syntax

public String getPublicId(int i);

Parameter	Description
i	Index

getSystemId()

Description

Returns the system ID of input when error at specified index occurred.

Syntax

public String getSystemId(int i);

Parameter	Description
i	Index

---

XMLParser Class

---

Description of XMLParser

This class serves as a base class for the DOMParser and SAXParser classes. It contains methods to parse eXtensible Markup Language (XML) 1.0 documents according to the World Wide Web Consortium (W3C) recommendation. This class cannot be instantiated (applications may use the DOM or SAX parser depending on their requirements).

---

Syntax of XMLParse

public abstract class XMLParser
 
oracle.xml.parser.v2.XMLParser

---

Fields of XMLParser

Table 1-11 Fields of XMLParser  

Field	Syntax	Description
BASE_URL	public static final java.lang.String BASE_URL	Base URL used in parsing entities. Replaces setBaseURL(); Should be URL object.
DTD_OBJECT	public static final java.lang.String DTD_OBJECT	DTD Object to be used for validation. Replaces XMLParser.setDoctype().
SCHEMA_OBJECT	public static final java.lang.String SCHEMA_OBJECT	Schema Object to be used for validation. Replaces XMLParser.setXMLSchema().
STANDALONE	public static final java.lang.String STANDALONE	Sets the standalone property of the input files. If true the DTDs are not retrieved.
USE_DTD_ONLY_FOR_VALIDATION	public static final java.lang.String USE_DTD_ONLY_FOR_VALIDATION	If true, DTD Object is used only for validation and is not added to the parser document (Boolean.TRUE or Boolean.FALSE) This property/attribute is only if setDoctype is called to use a fixed DTD.

---

Methods of XMLParser

Table 1-12 Summary of Methods of XMLParser  

Method	Description
getAttribute()	Retrieves value of attribute of the implementation.
getBaseURL()	Returns the base URL.
getEntityResolver()	Returns the entity resolver.
getErrorHandler()	Returns the error handler.
getReleaseVersion()	Returns the release version.
getValidationModeValue()	Returns the validation mode value.
getXMLProperty()	Returns the value of a property.
isXMLPropertyReadOnly()	Returns TRUE if a given property is read-only.
isXMLPropertySupported()	Returns TRUE if a given property is supported.
parse()	Parses the XML.
reset()	Resets the parser state.
setAttribute()	Sets specific attributes on the underlying implementation.
setBaseURL()	Sets the base URL for loading external entities and DTDs.
setDoctype()	Sets the DTD.
setEntityResolver()	Sets the entity resolver.
setErrorHandler()	Registers an error event handler.
setLocale()	Sets the locale for error reporting.
setPreserveWhitespace()	Sets the white space preserving mode.
setValidationMode()	Sets the validation mode.
setXMLProperty()	Sets and returns an XMLProperty.
setXMLSchema()	Sets an XML Schema for validating the instance document.

getAttribute()

Description

Retrieves values of specific attributes on the underlying implementation. Throws IllegalArgumentException - thrown if the underlying implementation doesn't recognize the attribute.

Syntax

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

Parameter	Description
value	The value of the attribute.

getBaseURL()

Description

Returns the base URL.

Syntax

public java.net.URL getBaseURL();

getEntityResolver()

Description

Returns the current entity resolver.

Syntax

public org.xml.sax.EntityResolver getEntityResolver();

Returns

The current entity resolver, or null if none has been registered.

getErrorHandler()

Description

Returns the current error handler, or null if none has been registered.

Syntax;

public org.xml.sax.ErrorHandler getErrorHandler();

getReleaseVersion()

Description

Returns the release version of the Oracle XML Parser.

Syntax

public static String getReleaseVersion();

getValidationModeValue()

Description

Returns the validation mode value:

• 0 if the XML parser is NONVALIDATING
• 1 if the XML parser is PARTIAL_VALIDATION
• 2 if the XML parser is DTD_VALIDATION
• 3 if the XML parser is SCHEMA_VALIDATION

Syntax

public int getValidationModeValue();

getXMLProperty()

Description

Returns value of a property. The property is returned if present and supported, else null is returned

Syntax

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

Parameter	Description
name	Name of the property.

isXMLPropertyReadOnly()

Description

Returns TRUE if a given property is read-only Returns true if the property is not supported

Syntax

public boolean isXMLPropertyReadOnly( String name);

Parameter	Description
name	Name of the property.

isXMLPropertySupported()

Description

Returns TRUE if a given property is supported.

Syntax

public boolean isXMLPropertySupported( String name)

Parameter	Description
name	Name of the property.

parse()

Description

Parses the XML. Throws the following exceptions:

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

The options are described in the following table.

Syntax	Description
public void parse( org.xml.sax.InputSource in);	Parses the XML from given input source.
public final void parse( java.io.InputStream in);	Parses the XML from given input stream.
public final void parse( java.io.Reader in);	Parses the XML from given reader.
public void parse( String in);	Parses the XML from the URL indicated.
public final void parse( java.net.URL url);	Parses the XML document pointed to by the given URL and creates the corresponding XML document hierarchy.

Parameter	Description
in	Source containing XML data to parse.
url	The ULR pointing to the XML document which will be parsed.

reset()

Description

Resets the parser state.

Syntax

public void reset();

setAttribute()

Description

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

Syntax

public void setAttribute( String name, 
                          Object value);

Parameter	Description
name	The name of the attribute.
value	The value of the attribute.

setBaseURL()

Description

Sets the base URL for loading external entities and DTDs. This method should to be called if the parse() is used to parse the XML Document.

Syntax

public void setBaseURL( java.net.URL url);

Parameter	Description
url	The base URL.

setDoctype()

Description

Sets the DTD.

Syntax

public void setDoctype( DTD dtd);

Parameter	Description
dtd	The DTD to set and use while parsing.

setEntityResolver()

Description

Registers an entity resolver. Throws a NullPointerException if the resolver argument is null.

If the application does not register an entity resolver, the XMLReader will perform its own default resolution. Applications may register a new or different resolver in the middle of a parse, and the SAX parser must begin using the new resolver immediately.

Syntax

public void setEntityResolver( org.xml.sax.EntityResolver resolver);

Parameter	Description
resolver	The entity resolver.

setErrorHandler()

Description

Registers an error event handler. Throws java.lang.NullPointerException if the handler argument is null.

If the application does not register an error handler, all error events reported by the SAX parser will be silently ignored; however, normal processing may not continue. It is highly recommended that all SAX applications implement an error handler to avoid unexpected bugs. Applications may register a new or different handler in the middle of a parse, and the SAX parser must begin using the new handler immediately.

Syntax

public void setErrorHandler( org.xml.sax.ErrorHandler handler);

Parameter	Description
handler	The error handler.

Parameters

handler - The error handler.

setLocale()

Description

Sets the locale for error reporting. Throws a SAXException on error.

Syntax

public void setLocale( java.util.Locale locale);

Parameter	Description
locale	The locale to set.

setPreserveWhitespace()

Description

Sets the white space preserving mode.

Syntax

public void setPreserveWhitespace( boolean flag);

Parameter	Description
flag	The preserving mode.

setValidationMode()

Description

Sets the validation mode. This method sets the validation mode of the parser to one of the 4 types: NONVALIDATING, PARTIAL_VALIDATION, DTD_VALIDATION and SCHEMA_VALIDATION.

Syntax

public void setValidationMode(int valMode)

Parameter	Description
valMode	Determines the type of the validation mode to which the parser should be set.

setXMLProperty()

Description

Sets and returns an XMLproperty. The value of the property set is returned if successfully set, a null is returned if the property is read-only and cannot be set or is not supported.

Syntax

public java.lang.Object setXMLProperty( String name,
                                        Object value);

Parameter	Description
name	Name of the property.
value	Value of the property.

setXMLSchema()

Description

Sets an XMLSchema for validating the instance document.

Syntax

public void setXMLSchema( java.lang.Object schema);

Parameter	Description
schema	The XMLSchema object

---

XMLToken Class

---

Description of XMLToken

Basic interface for XMLToken. All XMLParser applications with Tokenizer feature must implement this interface. The interface has to be registered using XMLParser method setTokenHandler().

If XMLtoken handler isn't null, then for each registered and found token the parser calls the XMLToken call-back method token(). During tokenizing the parser doesn't validate the document and doesn't include/read internal/external entities. If XMLtoken handler == null then the parser parses as usual.

A request for XML token is registered (on/off) using XMLParser method setToken(). The requests could be registered during the parsing (from inside the call-back method) as well.

The XML tokens are defined as public constants in XMLToken interface. They correspond to the XML syntax variables from W3C XML Syntax Specification.

---

Syntax of XMLToken

public interface XMLToken

---

Fields of XMLToken of XMLToken

Table 1-13 Fields of XMLToken  

Field	Syntax	Description
AttListDecl	public static final int AttListDecl	AttListDecl ::= '<' '!' 'ATTLIST' S Name AttDef* S? '>'
AttName	public static final int AttName	AttName ::= Name
Attribute	public static final int Attribute	Attribute ::= AttName Eq AttValue
AttValue	public static final int AttValue	AttValue ::= '"' ([^<&"] | Reference)* '"' | "'" ([^<&'] | Reference)* "'"
CDSect	public static final int CDSect	CDSect ::= CDStart CData CDEnd CDStart ::= '<' '!' '[CDATA[' CData ::= (Char* - (Char* ']]>' Char*)) CDEnd ::= ']]>'
CharData	public static final int CharData	CharData ::= [^<&]* - ([^<&]* ']]>' [^<&]*)
Comment	public static final int Comment	Comment ::= '<' '!' '--' ((Char - '-') | ('-' (Char - '-')))* '-->'
DTDName	public static final int DTDName	DTDName ::= name
ElemDeclName	public static final int ElemDeclName	ElemDeclName ::= name
elementdecl	public static final int elementdecl	elementdecl ::= '<' '!ELEMENT' S ElemDeclName S contentspec S? '>'
EmptyElemTag	public static final int EmptyElemTag	EmptyElemTag ::= '<' STagName (S Attribute)* S? '/' '>'
EntityDecl	public static final int EntityDecl	EntityDecl ::= '<' '!' ENTITY' S EntityDeclName S EntityDef S? '>' | '<' '!' ENTITY' S '%' S EntityDeclName S PEDef S? '>' EntityDef ::= EntityValue | (ExternalID NDataDecl?) PEDef ::= EntityValue | ExternalID
EntityDeclName	public static final int EntityDeclName	EntityValue ::= '"' ([^%&"] | PEReference | Reference)* '"' | "'" ([^%&'] | PEReference | Reference)* "'"
EntityValue	public static final int EntityValue	EntityDeclName ::= Name
ETag	public static final int ETag	ETag ::= '<' '/' ETagName S? '>'
ETagName	public static final int ETagName	ETagName ::= Name
ExternalID	public static final int ExternalID	ExternalID ::= 'SYSTEM' S SystemLiteral | 'PUBLIC' S PubidLiteral S SystemLiteral
NotationDecl	public static final int NotationDecl	NotationDecl ::= '<' '!NOTATION' S Name S (ExternalID | PublicID) S? '>'
PI	public static final int PI	PI ::= '<' '?' PITarget (S (Char* - (Char* '?>' Char*)))? '?' '>'
PITarget	public static final int PITarget	PITarget ::= Name - (('X' | 'x') ('M' | 'm') ('L' | 'l'))
Reference	public static final int Reference	Reference ::= EntityRef | CharRef | PEReference EntityRef ::= '&' Name ';' PEReference ::= '%' Name ';' CharRef ::= '&#' [0-9]+ ';' | '&#x' [0-9a-fA-F]+ ';
STag	public static final int STag	STag ::= '<' STagName (S Attribute)* S? '>'
STagName	public static final int STagName	STagName ::= Name
TextDecl	public static final int TextDecl	TextDecl ::= '<' '?' 'xml' VersionInfo? EncodingDecl S? '?>'
XMLDecl	public static final int XMLDecl	XMLDecl ::= '<' '?' 'xml' VersionInfo EncodingDecl? SDDecl? S? '?' '>'

---

Methods of XMLToken

token()

Description

Receives an XML token and it's corresponding value. This is an interface call-back method.

Syntax

public void token( int token,
                   String value);

Parameter	Description
token	The XML token constant as specified in the interface.
value	The corresponding substring from the parsed text.

---

XMLTokenizer Class

---

Description of XMLTokenizer

This class implements an eXtensible Markup Language (XML) 1.0 parser according to the World Wide Web Consortium (W3C) recommendation.

---

Syntax of XMLTokenizer

public class XMLTokenizer
 
oracle.xml.parser.v2.XMLTokenizer

---

Methods of XMLTokenizer

Table 1-14 Summary of Methods of XMLTokenizer  

Method	Description
XMLTokenizer()	Creates a new Tokenizer object.
parseDocument()	Parses the document.
setErrorHandler()	Registers a new error event handler.
setErrorStream()	Registers a output stream for errors.
setToken()	Registers a new token for XML tokenizer.
setTokenHandler()	Registers a new XML tokenizer event handler.
tokenize()	Tokenizes the XML.

XMLTokenizer()

Description

Creates a new Tokenizer object. The options are described in the following table.

Syntax	Description
public XMLTokenizer();	Creates a new Tokenizer object.
public XMLTokenizer( XMLToken handler);	Creates a new Tokenizer object from a handler.

Parameter	Description
handler	The handler.

parseDocument()

Description

Parses the document.

Syntax

public void parseDocument();

setErrorHandler()

Description

Registers a new error event handler. This replaces any previous setting for error handling.

Syntax

public void setErrorHandler(org.xml.sax.ErrorHandler handler)

Parameter	Description
handler	The handler being registered.

setErrorStream()

Description

Registers a output stream for errors.

Syntax

public void setErrorStream( java.io.OutputStream out);

Parameter	Description
out	Error stream being registered.

setToken()

Description

Registers a new token for XML tokenizer.

Syntax

public void setToken( int token,
                      boolean val);

Parameter	Description
token	XMLToken being set.

setTokenHandler()

Description

Registers a new XML tokenizer event handler.

Syntax

public void setTokenHandler( XMLToken handler);

Parameter	Description
handler	XMLToken being registered.

tokenize()

Description

Tokenizes the XML. Throws the following exceptions:

• XMLParseException if syntax or other error encountered.
• SAXException, which could be any 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 tokenize( org.xml.sax.InputSource in);	Tokenizes the XML from given input source.
public final void tokenize( java.io.InputStream in);	Tokenizes the XML from given input stream.
public final void tokenize( java.io.Reader r);	Tokenizes the XML from given reader.
public final void tokenize( String in);	Tokenizes the XML from a string.
public final void tokenize( java.net.URL url);	Tokenizes the XML document pointed to by the given URL and creates the corresponding XML document hierarchy.

Parameter	Description
in	The source for parsing.
url	The URL which points to the XML document to parse.

---

NSName Class

---

Description of NSName

The NSName interface is part of the orace.xml.util package; it provides Namespace support for Element and Attr names.

---

Syntax of NSName

public interface oracle.xml.util.NSName

---

Methods of NSName

Table 1-15 Summary of Methods of NSName  

Method	Description
getExpandedName()	Returns the fully resolved name for this name.
getLocalName()	Returns the local name for this name.
getNamespace()	Returns the resolved Namespace for this name.
getPrefix()	Returns the prefix for this name.
getQualifiedName()	Returns the qualified name.

getExpandedName()

Description

Returns the fully resolved name for this name.

Syntax

public  String  getExpandedName();

getLocalName()

Description

Returns the local name for this name.

Syntax

public String getLocalName();

getNamespace()

Description

Returns the resolved Namespace for this name.

Syntax

public String getNamespace()

getPrefix()

Description

Returns the prefix for this name.

Syntax

public String getPrefix();

getQualifiedName()

Description

Returns the qualified name.

Syntax

public String getQualifiedName();

---

XMLError Class

---

Description of XMLError

This class of the oracle.xml.util package holds the error message and the line number where it occured.

---

Syntax of XMLError

public class XMLError
 
oracle.xml.util.XMLError

---

Fields of XMLError

Table 1-16 Fields of oracle.xml.util.XMLError

Field	Syntax
col	protected int[] col
errid	protected int[] errid
exp	protected java.lang.Exception[] exp
line	protected int[] line
mesg	protected java.lang.String[] mesg
pubId	protected java.lang.String[] pubId
sysId	protected java.lang.String[] sysId
types	protected int[] types

---

Methods of XMLError

Table 1-17 Summary of Methods of XMLError  

Method	Description
XMLError()	Default constructor for XMLError.
error()	Adds a new error to the vector.
error0()	Adds a new error to the vector, with no additional parameters.
error1()	Adds a new error to the vector, with 1 additional parameter.
error2()	Adds a new error to the vector, with 2 additional parameters.
error3()	Adds a new error to the vector, with 3 additional parameters.
flushErrorStream()	Flush all the error to the output stream output stream defaults or to error handler
formatErrorMesg()	Formats and error message.
getColumnNumber()	Returns the column number of error at specified index
getException()	Returns the exception (if exists) that occured in error at specified index
getFirstError()	Returns the first error.
getLineNumber()	Returns the line number of error at specified index.
getLocator()	Returns the registered locator.
getMessage()	Returns the error message at specified index
getMessage0()	Returns error message with no parameters.
getMessage1()	Returns error message with 1 parameter.
getMessage2()	Returns error message with 2 parameters.
getMessage3()	Returns error message with 3 parameters.
getMessage4()	Returns error message with 4 parameters.
getMessage5()	Returns error message with 5 parameters.
getMessageType()	Returns the type of the error message at specified index.
getNumMessages()	Returns the total number of errors/warnings found during parsing.
getPublicId()	Returns the public ID of input when error at specified index occured.
getSystemId()	Returns the system ID of input when error at specified index occured.
printErrorListener()	Flushes all the JAXP 1.1 errors to the ErrorListener If no ErrorListener was set, default to System.err.
reset()	Resets the error class.
setErrorStream()	Registers an output stream.
setException()	Registers an exception.
setLocale()	Registers a locale.
setLocator()	Registers a locator.
showWarnings()	Turns reporting warning on/off.

XMLError()

Description

Default constructor for XMLError.

Syntax

public  XMLError();

error()

Description

Adds a new error to the vector. The options are described in the following table.

Syntax	Description
public void error( int id, int type, String msg);	Adds a new error to the vector, with a message.
public void error3( int id, int type, String[] params);	Adds a new error to the vector, with an array of parameters.

Parameter	Description
id	Id of the error message.
type	Type of the error.
MESG	Error message (without parameters).
params	Parameter array.

error0()

Description

Adds a new error to the vector, with no parameters.

Syntax

public void error3( int id,
                    int type);

Parameter	Description
id	Id of the error message.
type	Type of the error.

error1()

Description

Adds a new error to the vector, with 1 parameter.

Syntax

public void error3( int id,
                    int type,
                    String p1);

Parameter	Description
id	Id of the error message.
type	Type of the error.
p1	Parameter 1.

error2()

Description

Adds a new error to the vector, with two parameters.

Syntax

public void error3( int id,
                    int type,
                    String p1,
                    String p2);

Parameter	Description
id	Id of the error message.
type	Type of the error.
p1	Parameter 1.
p2	Parameter 2.

error3()

Description

Adds a new error to the vector, with 3 parameters.

Syntax

public void error3( int id,
                    int type,
                    String p1,
                    String p2,
                    String p3)

Parameter	Description
id	Id of the error message.
type	Type of the error.
p1	Parameter 1.
p2	Parameter 2.
p3	Parameter 3.

flushErrorStream()

Description

Flushes all the error to the output stream output stream defaults or to error handler.

Syntax

public void flushErrorStream();

formatErrorMesg()

Description

Formats an error message.

Syntax

public String formatErrorMesg(int index);

Parameter	Description
i	Index.

getColumnNumber()

Description

Returns the column number of error at specified index.

Syntax

public int getColumnNumber(int i);

Parameter	Description
i	Index.

getException()

Description

Returns the exception (if exists) that occured in error at specified index.

Syntax

public java.lang.Exception getException(int i);

Parameter	Description
i	Index.

getFirstError()

Description

Returns the first error.

Syntax

public int getFirstError();

getLineNumber()

Description

Returns the line number of error at specified index.

Syntax

public int getLineNumber(int i);

Parameter	Description
i	Index.

getLocator()

Description

Returns the registered locator

Syntax

public org.xml.sax.Locator getLocator();

getMessage()

Description

Returns an error message. The options are described in the following table.

Syntax	Description
public String getMessage( int i);	Returns the error message at specified index.
public String getMessage( int errId, String[] params);	Returns error message with more than 5 parameters, packaged in an array.

Parameter	Description
i	Index.
errId	The error id.
param	An array of parameters.

getMessage0()

Description

Returns error message with no parameters.

Syntax

public String getMessage1( int errId);

Parameter	Description
errId	The error id.

getMessage1()

Description

Returns error message with 1 argument.

Syntax

public String getMessage1( int errId,
                           String a1);

Parameter	Description
errId	The error id.
a1	Parameter 1.

getMessage2()

Description

Returns error message with 2 parameters

Syntax

public String getMessage3(
     int errId,
     String a1,
     String a2);

Parameter	Description
errId	The error id.
a1	Parameter 1.
a2	Parameter 2.

getMessage3()

Description

Returns error message with 3 parameters.

Syntax

public String getMessage3(
     int errId,
     String a1,
     String a2,
     String a3);

Parameter	Description
errId	The error id.
a1	Parameter 1.
a2	Parameter 2.
a3	Parameter 3.

getMessage4()

Description

Returns error message with 4 parameters.

Syntax

public String getMessage4(
     int errId,
     String a1,
     String a2,
     String a3,
     String a4);

Parameter	Description
errId	The error id.
a1	Parameter 1.
a2	Parameter 2.
a3	Parameter 3.
a4	Parameter 4.

getMessage5()

Description

Returns error message with 5 parameters.

Syntax

public String getMessage5(
     int errId,
     String a1,
     String a2,
     String a3,
     String a4,
     String a5);

Parameter	Description
errId	The error id.
a1	Parameter 1.
a2	Parameter 2.
a3	Parameter 3.
a4	Parameter 4.
a5	Parameter 5.

getMessageType()

Description

Returns the type of the error message type at specified index

Syntax

public int getMessageType(int i);

Parameter	Description
i	Index

getNumMessages()

Description

Returns the total number of errors/warnings found during parsing

Syntax

public int getNumMessages()

getPublicId()

Description

Returns the public ID of input when error at specified index occured

Syntax

public String getPublicId( int i);

Parameter	Description
i	Index.

getSystemId()

Description

Returns the system ID of input when error at specified index occured.

Syntax

public String getSystemId(int i);

Parameter	Description
i	Index.

printErrorListener()

Description

Flushes all the JAXP 1.1 errors to the ErrorListener. If no ErrorListener was set, defaults to System.err.

Syntax

public void printErrorListener();

reset()

Description

Resets the error class.

Syntax

public void reset();

setErrorStream()

Description

Sets an output stream for error reporting. The options are described in the following table.

Syntax	Description
public void setErrorStream( java.io.OutputStream out);	Sets an output stream for error reporting. Throws IOException if an error occurs initializing the output stream.
public void setErrorStream( java.io.OutputStream out, String enc);	Sets an output stream for error reporting and its encoding. Throws IOException if an error occurs initializing the output stream.
public void setErrorStream( java.io.PrintWriter out);	Sets an print writer for error reporting.

Parameter	Description
out	Output for errors/warnings.
enc	Encoding of the output stream.

setException()

Description

Registers an exception.

Syntax

public void setException( java.lang.Exception exp);

Parameter	Description
exp	Last exception which occured.

setLocale()

Description

Registers a locale for error reporting.

Syntax

public void setLocale( java.util.Locale locale);

Parameter	Description
locale	The locale for error reporting.

setLocator()

Description

Register a locator

Syntax

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

Parameter	Description
locator	Locator to get lin/col/sysid/pubid information.

showWarnings()

Description

Turns reporting warning on/off.

Syntax

public void showWarnings(boolean flag);

Parameter	Description
flag	Controls reporting of warnings.

---

XMLException Class

---

Description of XMLException

The XML Exception class in package oracle.xml.util indicates that a parsing exception occurred while processing an XML document.

---

Syntax of XMLException

public class XMLException extends java.lang.Exception
 
java.lang.Object
  |
  +--java.lang.Throwable
        |
        +--java.lang.Exception
              |
              +--oracle.xml.util.XMLException

---

Implemented Interfaces of XMLException

java.io.Serializable

---

Fields of XMLException

Table 1-18 Fields of XMLException

Field	Syntax	Description
ERROR	public static final int ERROR	Code for non-fatal error
FATAL_ERROR	public static final int FATAL_ERROR	Code for fatal error
WARNING	public static final int WARNING	Code for warning

---

Methods of XMLException

Table 1-19 Summary of Methods of oracle.xml.util.XMLException  

Method	Description
XMLException()	Generates an XMLException.
formatErrorMessage()	Returns the error message at specified index.
getColumnNumber()	Returns the column number of error at specified index.
getException()	Returns the exception (if exists) that occured in error at specified index.
getLineNumber()	Returns the line number of error at specified index.
getMessage()	Returns the error message at specified index.
getMessageType()	Returns the type of the error message at specified index.
getNumMessages()	Returns the total number of errors/warnings found during parsing.
getPublicId()	Returns the public ID of input when error at specified index occured.
getSystemId()	Returns the system ID of input when error at specified index occured.
getXMLError()	Returns XMLError object inside XMLException.
printStackTrace()	Prints this Throwable and its backtrace.
setException()	Sets the underlying exception, if exists.
toString()	Returns any embedded exception.

XMLException()

Description

Generates an XML Exception. The options are described in the following table.

Syntax	Description
public XMLException( String mesg, String pubId, String sysId, int line, int col, int type);	Generates and XMLException from the message, public id, system id, line, column and type.
public XMLException( XMLError err, java.lang.Exception e);	Generates and XMLException from the error and exception.
public XMLException( XMLError err, int firsterr);	Generates and XMLException from the error and first error.
public XMLException( XMLError err, int firsterr, java.lang.Exception e);	Generates and XMLException from the error, exception and first error.

Parameter	Description
mesg	Message.
pubId	Public Id.
sysId	System Id.
line	Line.
col	Column.
type	Type.
err	Error.
e	Exception.
firsterr	First error.

formatErrorMessage()

Description

Returns the error message at specified index.

Syntax

public String formatErrorMessage( int i);

Parameter	Description
i	Index.

getColumnNumber()

Description

Returns the column number of error at specified index.

Syntax

public int getColumnNumber( int i);

Parameter	Description
i	Index.

getException()

Description

Returns the exception (if exists) that occured in error at specified index

Syntax

public java.lang.Exception getException( int i);

Parameter	Description
i	Index

getLineNumber()

Description

Returns the line number of error at specified index

Syntax

public int getLineNumber(int i);

Parameter	Description
i	Index.

getMessage()

Description

Returns the error message at specified index

Syntax

public String getMessage(int i).

Parameter	Description
i	Index.

getMessageType()

Description

Get the type of the error message at specified index

Syntax

public int getMessageType(int i);

Parameter	Description
i	Index.

getNumMessages()

Description

Returns the total number of errors/warnings found during parsing

Syntax

public int getNumMessages();

getPublicId()

Description

Returns the public ID of input when error at specified index occured

Syntax

public String getPublicId(int i);

Parameter	Description
i	Index.

getSystemId()

Description

Returns the system ID of input when error at specified index occured

Syntax

public String getSystemId(int i);

Parameter	Description
i	Index.

getXMLError()

Description

Get XMLError object inside XMLException.

Syntax

public XMLError getXMLError();

printStackTrace()

Description

Prints Throwable and its backtrace. The options are described in the following table.

Syntax	Description
public void printStackTrace();	Prints this Throwable and its backtrace to the standard error stream.
public void printStackTrace( java.io.PrintStream s);	Prints this Throwable and its backtrace to the specified print stream.
public void printStackTrace( java.io.PrintWriter s);	Prints this Throwable and its backtrace to the specified print writer.

Parameter	Description
s	Output for the stack trace.

setException()

Description

Sets the underlying exception, if it exists.

Syntax

public void setException(java.lang.Exception ex);

Parameter	Description
ex	The exception

toString()

Description

Returns any embedded exception.

Syntax

public String toString();