Using DBMS_XMLPARSER
, you can access the contents and structure of XML documents. XML describes a class of data XML document objects. It partially describes the behavior of computer programs which process them. By construction, XML documents are conforming SGML documents.
XML documents are made up of storage units called entities, which contain either parsed or unparsed data. Parsed data is made up of characters, some of which form character data, and some of which form markup. Markup encodes a description of the document's storage layout and logical structure. XML provides a mechanism to impose constraints on the storage layout and logical structure.
A software module called an XML processor is used to read XML documents and provide access to their content and structure. It is assumed that an XML processor is doing its work on behalf of another module, called the application. This PL/SQL implementation of the XML processor (or parser) follows the W3C XML specification REC-xml-19980210 and includes the required behavior of an XML processor in terms of how it must read XML data and the information it must provide to the application.
The default behavior for this PL/SQL XML parser is to build a parse tree that can be accessed by DOM APIs, validate it if a DTD is found (otherwise, it is non-validating), and record errors if an error log is specified. If parsing fails, an application error is raised.
This chapter contains the following topics:
Table 127-1 DBMS_XMLPARSER Package Subprograms
Method | Description |
---|---|
Frees a parser object. |
|
Gets parsed DTD. |
|
Gets DOM document. |
|
Returns the release version of Oracle XML Parser for PL/SQL. |
|
Returns validation mode. |
|
Returns a new parser instance |
|
Parses XML stored in the given url/file. |
|
Parses XML stored in the given buffer |
|
Parses XML stored in the given clob |
|
Parses DTD stored in the given url/file |
|
Parses DTD stored in the given buffer |
|
Parses DTD stored in the given clob |
|
Sets base directory used to resolve relative URLs. |
|
Sets DTD. |
|
Sets errors to be sent to the specified file |
|
Sets white space preserve mode |
|
Sets validation mode. |
|
Turns warnings on or off. |
Frees a parser object.
PROCEDURE freeParser( p Parser);
Parameter | IN / OUT | Description |
---|---|---|
p |
(IN) |
Parser instance. |
Returns the parsed DTD; this function must be called only after a DTD is parsed.
FUNCTION getDoctype( p Parser) RETURN DOMDocumentType;
Parameter | IN / OUT | Description |
---|---|---|
p |
(IN) |
Parser instance. |
Returns the document node of a DOM tree document built by the parser; this function must be called only after a document is parsed.
FUNCTION GETDOCUMENT( p Parser) RETURN DOMDocument;
Parameter | IN / OUT | Description |
---|---|---|
p |
(IN) |
Parser instance. |
Returns the release version of the Oracle XML parser for PL/SQL.
FUNCTION getReleaseVersion RETURN VARCHAR2;
Retrieves validation mode; TRUE
for validating, FALSE
otherwise.
FUNCTION GETVALIDATIONMODE( p Parser) RETURN BOOLEAN;
Parameter | IN / OUT | Description |
---|---|---|
p |
(IN) |
Parser instance. |
Returns a new parser instance. This function must be called before the default behavior of Parser can be changed and if other parse methods need to be used.
FUNCTION newParser RETURN Parser;
Parses XML stored in the given URL or file. An application error is raised if parsing fails. There are several versions of this method.
Syntax | Description |
---|---|
FUNCTION parse(
|
Returns the built DOM Document. This is meant to be used when the default parser behavior is acceptable and just a url/file needs to be parsed. |
PROCEDURE parse(
|
Any changes to the default parser behavior should be effected before calling this procedure. |
Parameter | IN / OUT | Description |
---|---|---|
url |
(IN) |
Complete path of the url/file to be parsed. |
p |
(IN) |
Parser instance. |
Parses XML stored in the given buffer. Any changes to the default parser behavior should be effected before calling this procedure. An application error is raised if parsing fails.
PROCEDURE PARSEBUFFER( p Parser, doc VARCHAR2);
Parameter | IN / OUT | Description |
---|---|---|
p |
(IN) |
Parser instance. |
doc |
(IN) |
XML document buffer to parse. |
Parses XML stored in the given clob. Any changes to the default parser behavior should be effected before calling this procedure. An application error is raised if parsing fails.
PROCEDURE PARSECLOB( p Parser, doc CLOB);
Parameter | IN / OUT | Description |
---|---|---|
p |
(IN) |
Parser instance. |
doc |
(IN) |
XML document buffer to parse. |
Parses the DTD stored in the given URL or file. Any changes to the default parser behavior should be effected before calling this procedure. An application error is raised if parsing fails.
PROCEDURE PARSEDTD( p Parser, url VARCHAR2, root VARCHAR2);
Parameter | IN / OUT | Description |
---|---|---|
p |
(IN) |
Parser instance. |
url |
(IN) |
Complete path of the URL or file to be parsed. |
root |
(IN) |
Name of the root element. |
Parses the DTD stored in the given buffer. Any changes to the default parser behavior should be effected before calling this procedure. An application error is raised if parsing fails.
PROCEDURE PARSEDTDBUFFER( p Parser, dtd VARCHAR2, root VARCHAR2);
Parameter | IN / OUT | Description |
---|---|---|
p |
(IN) |
Parser instance. |
dtd |
(IN) |
DTD buffer to parse. |
root |
(IN) |
Name of the root element. |
Parses the DTD stored in the given clob. Any changes to the default parser behavior should be effected before calling this procedure. An application error is raised if parsing fails.
PROCEDURE PARSEDTDCLOB( p Parser, dtd CLOB, root VARCHAR2);
Parameter | IN / OUT | Description |
---|---|---|
p |
(IN) |
Parser instance. |
dtd |
(IN) |
DTD Clob to parse. |
root |
(IN) |
Name of the root element. |
Sets base directory used to resolve relative URLs. An application error is raised if parsing fails.
PROCEDURE setBaseDir( p Parser, dir VARCHAR2);
Parameter | IN / OUT | Description |
---|---|---|
p |
(IN) |
Parser instance. |
dir |
(IN) | Directory used as a base directory. |
Sets a DTD to be used by the parser for validation. This call should be made before the document is parsed.
PROCEDURE setDoctype( p Parser, dtd DOMDocumentType);
Parameter | IN / OUT | Description |
---|---|---|
p |
(IN) |
Parser instance. |
dtd |
(IN) |
DTD to set. |
Sets errors to be sent to the specified file.
PROCEDURE setErrorLog( p Parser, fileName VARCHAR2);
Parameter | IN / OUT | Description |
---|---|---|
p |
(IN) |
Parser instance. |
fileName |
(IN) |
Complete path of the file to use as the error log. |
Sets whitespace preserving mode.
PROCEDURE setPreserveWhitespace( p Parser, yes BOOLEAN);
Parameter | IN / OUT | Description |
---|---|---|
p |
(IN) |
Parser instance. |
yes |
(IN) |
Mode to set: TRUE - preserve, FALSE - don't preserve. |
Sets validation mode.
PROCEDURE setValidationMode( p Parser, yes BOOLEAN);
Parameter | IN / OUT | Description |
---|---|---|
p |
(IN) |
Parser instance. |
yes |
(IN) |
Mode to set: TRUE - validate, FALSE - don't validate. |
Turns warnings on or off.
PROCEDURE showWarnings( p Parser, yes BOOLEAN);
Parameter | IN / OUT | Description |
---|---|---|
p |
(IN) |
Parser instance. |
yes |
(IN) |
Mode to set: TRUE - show warnings, FALSE - don't show warnings. |