G
XDK for PL/SQL: Specifications and Cheat Sheets

This Appendix describes Oracle XDK for PL/SQL specifications and includes syntax cheat sheets. It contains the following sections:

• XML Parser for PL/SQL

• XML Parser for PL/SQL Specifications

• XML Parser for PL/SQL: Parser() API

• XML Parser for PL/SQL: XSLT Processor API

• XML Parser for PL/SQL: W3C DOM API -- Types

• XML Parser for PL/SQL: W3C DOM API -- Node Methods, Node Types, and DOM Interface Types

XML Parser for PL/SQL

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.

Oracle XML Parser Features

The XML Parser for PL/SQL parses an XML document (or a standalone DTD) so that it can be processed by an application. Library and command-line versions are provided supporting the following standards and features:

• DOM (Document Object Model) support is provided compliant with the W3C DOM 1.0 Recommendation. These APIs permit applications to access and manipulate an XML document as a tree structure in memory. This interface is used by such applications as editors.

• SAX (Simple API for XML) support is also provided compliant with the SAX 1.0 specification. These APIs permit an application to process XML documents using an event-driven model.

• Support is also included for XML Namespaces 1.0 thereby avoiding name collisions, increasing reusability and easing application integration.

• Able to run on Oracle and Oracle Application Server.

• C and C++ versions initially available for Windows, Solaris, and Linux.

Additional features include:

• Validating and non-validating operation modes

• Built-in error recovery until fatal error

• DOM extension APIs for document creation Oracle XSL-Transform Processors

Version 2 of the Oracle XML Parsers include an integrated XSL-Transformation (XSL-T) Processor for transforming XML data using XSL stylesheets. Using the XSL-T processor, you can transform XML documents from XML to XML, HTML, or virtually any other text-based format. These processors support the following standards and features:

• Compliant with the W3C XSL Transform Proposed Recommendation 1.0

• Compliant with the W3C XPath Proposed Recommendation 1.0

• Integrated into the XML Parser for improved performance and scalability

• Available with library and command-line interfaces for Java, C, C++, and PL/SQL

Namespace Support

The Java, C, and C++ parsers also support XML Namespaces. Namespaces are a mechanism to resolve or avoid name collisions between element types (tags) or attributes in XML documents. This mechanism provides "universal" namespace element types and attribute names whose scope extends beyond the containing document. Such tags are qualified by uniform resource identifiers (URIs), such as <oracle:EMP xmlns:oracle="http://www.oracle.com/xml"/>. For example, namespaces can be used to identify an Oracle <EMP> data element as distinct from another company's definition of an <EMP> data element. This enables an application to more easily identify elements and attributes it is designed to process. The Java, C, and C++ parsers support namespaces by being able to recognize and parse universal element types and attribute names, as well as unqualified "local" element types and attribute names.

Validating and Non-Validating Mode Support

The Java, C, and C++ parsers can parse XML in validating or non-validating modes. In non-validating mode, the parser verifies that the XML is well-formed and parses the data into a tree of objects that can be manipulated by the DOM API. In validating mode, the parser verifies that the XML is well-formed and validates the XML data against the DTD (if any). Validation involves checking whether or not the attribute names and element tags are legal, whether nested elements belong where they are, and so on.

Example Code

See Chapter 29, "Using XML Parser for PL/SQL" for example code and suggestions on how to use the XML Parsers.

IXML Parser for PL/SQL Directory Structure

The following lists the XML Parser for PL/SQL directory structure in $ORACLE_HOME/xdk/plsql/parser:

• Windows NT
  • license.html - copy of license agreement

  • readme.html - release and installation notes

  • doc\ - directory for parser apis.

  • lib\ - directory for parser sql and class files

  • sample\ - sample code

• UNIX
  • license.html -- copy of license agreement

  • readme.html -- release and installation notes

  • doc/ -- directory for parser apis

  • lib/ -- directory for parser sql and class files

  • sample/ -- sample code files

DOM and SAX APIs

XML APIs generally fall into two categories: event-based and tree-based. An event-based API (such as SAX) uses callbacks to report parsing events to the application. The application deals with these events through customized event handlers. Events include the start and end of elements and characters. Unlike tree-based APIs, event-based APIs usually do not build in-memory tree representations of the XML documents. Therefore, in general, SAX is useful for applications that do not need to manipulate the XML tree, such as search operations, among others. For example, the following XML document:

<?xml version="1.0"?>
  <EMPLIST>
    <EMP>
     <ENAME>MARTIN</ENAME>
    </EMP>
    <EMP>
     <ENAME>SCOTT</ENAME>
    </EMP>
  </EMPLIST>

Becomes a series of linear events:

start document
start element: EMPLIST
start element: EMP
start element: ENAME
characters: MARTIN
end element: EMP
start element: EMP
start element: ENAME
characters: SCOTT
end element: EMP 
end element: EMPLIST
end document

A tree-based API (such as DOM) builds an in-memory tree representation of the XML document. It provides classes and methods for an application to navigate and process the tree. In general, the DOM interface is most useful for structural manipulations of the XML tree, such as reordering elements, adding or deleting elements and attributes, renaming elements, and so on.

XML Parser for PL/SQL Specifications

These are the Oracle XML Parser for PL/SQL specifications:

• Supports validation and non-validation modes

• Includes built-in error recovery until fatal error

• Supports the W3C XML 1.0 Recommendation

• Supports the W3C XSL-T Final Working Draft

This PL/SQL implementation of the XML processor (or parser) follows the W3C XML specification (rev REC-xml-19980210) and included 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.

XML Parser for PL/SQL: Default Behavior

The following is the default behavior for this PLSQL XML parser:

• A parse tree which can be accessed by DOM APIs is built

• The parser is validating if a DTD is found, otherwise it is non-validating

• Errors are not recorded unless an error log is specified; however, an application error will be raised if parsing fails

The types and methods described in this document are made available by the PLSQL package xmlparser.

• Integrated Document Object Model (DOM) Level 1.0 API

Supported Character Set Encodings

Supports documents in the following Oracle database encodings:

• BIG 5

• EBCDIC-CP-*

• EUC-JP

• EUC-KR

• GB2312

• ISO-2022-JP

• ISO-2022-KR

• ISO-8859-1to -9

• KOI8-R

• Shift_JIS

• US-ASCII

• UTF-8

Default:

UTF-8 is the default encoding if none is specified. Any other ASCII or EBCDIC based encodings that are supported by the Oracle database may be used.

Requirements

Oracle database with the Java option enabled.

Online Documentation

Documentation for Oracle XML Parser for PL/SQL is located in the doc directory in your install area and also in Oracle9i XML Reference.

Release Specific Notes

The Oracle XML parser for PL/SQL is an early adopter release and is written in PL/SQL and Java. It will check if an XML document is well-formed and, optionally, if it is valid. The parser will construct an object tree which can be accessed via PLSQL interfaces.

Standards Conformance

The parser conforms to the following standards:

W3C recommendation for Extensible Markup Language (XML) 1.0 at http://www.w3.org/TR/1998/REC-xml-19980210

W3C recommendation for Document Object Model Level 1 1.0 at http://www.w3.org/TR/REC-DOM-Level-1/

The parser currently does not currently have SAX or Namespace support. These will be made available in a future version.

Error Recovery

The parser also provides error recovery. It will recover from most errors and continue processing until a fatal error is encountered.

Important note: The contents of both the Windows and UNIX versions are identical. They are simply archived differently for operating system compatibility and your convenience.

XML Parser for PL/SQL: Parser() API

Table G-1 lists the XML Parser for PL/SQL Parser() API functions.

Table G-1 XML Parser for PL/SQL: Parser() API

Parser() Functions	Description
parse(VARCHAR2)	Parses xml stored in the given url/file and returns the built DOM Document
newParser	Returns a new parser instance
parse(Parser, VARCHAR2)	Parses xml stored in the given url/file
parseBuffer(Parser, VARCHAR2)	Parses xml stored in the given buffer
parseClob(Parser, CLOB)	Parses xml stored in the given clob
parseDTD(Parser, VARCHAR2, VARCHAR2)	Parses xml stored in the given url/file
parseDTDBuffer(Parser, VARCHAR2, VARCHAR2)	Parses xml stored in the given buffer
parseDTDClob(Parser, CLOB, VARCHAR2)	Parses xml stored in the given clob
setBaseDir(Parser, VARCHAR2)	Sets base directory used to resolve relative urls
showWarnings(Parser, BOOLEAN)	Turn warnings on or off
setErrorLog(Parser, VARCHAR2)	Sets errors to be sent to the specified file
setPreserveWhitespace(Parser, BOOLEAN)	Sets white space preserve mode
setValidationMode(Parser, BOOLEAN)	Sets validation mode
getValidationMode(Parser)	Gets validation mode
setDoctype(Parser, DOMDocumentType)	Sets DTD
getDoctype(Parser)	Gets DTD
getDocument(Parser)	Gets DOM document
freeParser(Parser)	Frees a Parser object

XML Parser for PL/SQL: XSLT Processor API

Table G-2 lists the XML Parser for PL/SQL XSL-T Processor API functions.

for the following interfaces:

• Processor interface type: Processor()

• Stylesheet interface type: Stylesheet()

  Table G-2 XML Parser for PL/SQL: XSL-T Processor() API Functions

  XSL-T Processor Functions	Description
  newProcessor	Returns a new processor instance
  processXSL(Processor, Stylesheet, DOMDocument)	Transforms input XML document using given DOMDocument and stylesheet
  processXSL(Processor, Stylesheet, DOMDocumentFragment)	Transforms input XML document fragment using given DOMDocumentFragment and stylesheet
  showWarnings(Processor, BOOLEAN)	Turn warnings on or off
  setErrorLog(Processor, VARCHAR2)	Sets errors to be sent to the specified file
  newStylesheet(DOMDocument, VARCHAR2)	Returns a new stylesheet using the given DOMDocument and reference URL
  newStylesheet(VARCHAR2, VARCHAR2)	Returns a new stylesheet using the given input and reference URLs
  transformNode(DOMNode, Stylesheet)	Transforms a node in a DOM tree using the given stylesheet
  selectNodes(DOMNode, VARCHAR2)	Selects nodes from a DOM tree which match the given pattern
  selectSingleNodes(DOMNode, VARCHAR2)	Selects the first node from the tree that matches the given pattern
  valueOf(DOMNode, VARCHAR2)	Retrieves the value of the first node from the tree that matches the given pattern
  setParam(Stylesheet, VARCHAR2, VARCHAR2)	Sets the value of a top-level stylesheet parameter
  removeParam(Stylesheet, VARCHAR2)	Remove a top-level stylesheet parameter
  resetParams(Stylesheet)	Resets the top-level stylesheet parameters
  freeStylesheet(Stylesheet)	Free a stylesheet object
  freeProcessor(Processor)	Free a processor object

XML Parser for PL/SQL: W3C DOM API -- Types

The Document Object Model (DOM) is an application programming interface (API) for HTML and XML documents. It defines the logical structure of documents and the way a document is accessed and manipulated. In the DOM specification, the term "document" is used in the broad sense - increasingly, XML is being used as a way of representing many different kinds of information that may be stored in diverse systems, and much of this would traditionally be seen as data rather than as documents. Nevertheless, XML presents this data as documents, and the DOM may be used to manage this data.

The XML Parser for PL/SQL W3C DOM APIs are listed on OTN at the following site: http://otn.oracle.com/tech/xml

Table G-3 XML Parser for PL/SQL: W3C DOM API Types 

Types	DOMException types	DOM interface types
DOM Node types	INDEX_SIZE_ERR	DOMNode
ELEMENT_NODE	DOMSTRING_SIZE_ERR	DOMNamedNodeMap
ATTRIBUTE_NODE	HIERARCHY_REQUEST_ERR	DOMNodeList
TEXT_NODE	WRONG_DOCUMENT_ERR	DOMAttr
CDATA_SECTION_NODE	INVALID_CHARACTER_ERR	DOMCDataSection
ENTITY_REFERENCE_NODE	NO_DATA_ALLOWED_ERR	DOMCharacterData
ENTITY_NODE	NO_MODIFICATION_ALLOWED_ERR	DOMComment
PROCESSING_INSTRUCTION_NODE	NOT_FOUND_ERR	DOMDocumentFragment
COMMENT_NODE	NOT_SUPPORTED_ERR	DOMElement
DOCUMENT_NODE	INUSE_ATTRIBUTE_ERR	DOMEntity
DOCUMENT_TYPE_NODE	DOMException types	DOMEntityReference
DOCUMENT_FRAGMENT_NODE	INDEX_SIZE_ERR	DOMNotation
NOTATION_NODE	DOMSTRING_SIZE_ERR	DOMProcessingInstruction
-	-	DOMText
-	-	DOMImplementation
-	-	DOMDocumentType
-	-	DOMDocument

XML Parser for PL/SQL: W3C DOM API -- Node Methods, Node Types, and DOM Interface Types

Node Methods

The following lists the DOM API Node methods:

• FUNCTION isNull(n DOMNode) RETURN BOOLEAN;

• FUNCTION makeAttr(n DOMNode) RETURN DOMAttr;

• FUNCTION makeCDataSection(n DOMNode) RETURN DOMCDataSection;

• FUNCTION makeCharacterData(n DOMNode) RETURN DOMCharacterData;

• FUNCTION makeComment(n DOMNode) RETURN DOMComment;

• FUNCTION makeDocumentFragment(n DOMNode) RETURN DOMDocumentFragment;

• FUNCTION makeDocumentType(n DOMNode) RETURN DOMDocumentType;

• FUNCTION makeElement(n DOMNode) RETURN DOMElement;

• FUNCTION makeEntity(n DOMNode) RETURN DOMEntity;

• FUNCTION makeEntityReference(n DOMNode) RETURN DOMEntityReference;

• FUNCTION makeNotation(n DOMNode) RETURN DOMNotation;

• FUNCTION makeProcessingInstruction(n DOMNode) RETURN DOMProcessingInstruction;

• FUNCTION makeText(n DOMNode) RETURN DOMText;

• FUNCTION makeDocument(n DOMNode) RETURN DOMDocument;

• PROCEDURE writeToFile(n DOMNode, fileName VARCHAR2);

• PROCEDURE writeToBuffer(n DOMNode, buffer IN OUT VARCHAR2);

• PROCEDURE writeToClob(n DOMNode, cl IN OUT CLOB);

• PROCEDURE writeToFile(n DOMNode, fileName VARCHAR2, charset VARCHAR2);

• PROCEDURE writeToBuffer(n DOMNode, buffer IN OUT VARCHAR2, charset VARCHAR2);

• PROCEDURE writeToClob(n DOMNode, cl IN OUT CLOB, charset VARCHAR2);

• FUNCTION getNodeName(n DOMNode) RETURN VARCHAR2;

• FUNCTION getNodeValue(n DOMNode) RETURN VARCHAR2;

• PROCEDURE setNodeValue(n DOMNode, nodeValue IN VARCHAR2);

• FUNCTION getNodeType(n DOMNode) RETURN NUMBER;

• FUNCTION getParentNode(n DOMNode) RETURN DOMNode;

• FUNCTION getChildNodes(n DOMNode) RETURN DOMNodeList;

• FUNCTION getFirstChild(n DOMNode) RETURN DOMNode;

• FUNCTION getLastChild(n DOMNode) RETURN DOMNode;

• FUNCTION getPreviousSibling(n DOMNode) RETURN DOMNode;

• FUNCTION getNextSibling(n DOMNode) RETURN DOMNode;

• FUNCTION getAttributes(n DOMNode) RETURN DOMNamedNodeMap;

• FUNCTION getOwnerDocument(n DOMNode) RETURN DOMDocument;

• FUNCTION insertBefore(n DOMNode, newChild IN DOMNode, refChild IN DOMNode) RETURN DOMNode;

• FUNCTION replaceChild(n DOMNode, newChild IN DOMNode, oldChild IN DOMNode)> RETURN DOMNode;

• FUNCTION removeChild(n DOMNode, oldChild IN DOMNode) RETURN DOMNode;

• FUNCTION appendChild(n DOMNode, newChild IN DOMNode) RETURN DOMNode;

• FUNCTION hasChildNodes(n DOMNode) RETURN BOOLEAN;

• FUNCTION cloneNode(n DOMNode, deep boolean) RETURN DOMNode;

DOM Node Types

The following lists the DOM API Node types:

• DOM Node types

• ELEMENT_NODE

• ATTRIBUTE_NODE

• TEXT_NODE

• CDATA_SECTION_NODE

• ENTITY_REFERENCE_NODE

• ENTITY_NODE

• PROCESSING_INSTRUCTION_NODE

• COMMENT_NODE

• DOCUMENT_NODE

• DOCUMENT_TYPE_NODE

• DOCUMENT_FRAGMENT_NODE

• NOTATION_NODE

DOMException Types

The following lists the DOMException types:

• INDEX_SIZE_ERR

• DOMSTRING_SIZE_ERR

• HIERARCHY_REQUEST_ERR

• WRONG_DOCUMENT_ERR

• INVALID_CHARACTER_ERR

• NO_DATA_ALLOWED_ERR

• NO_MODIFICATION_ALLOWED_ERR

• NOT_FOUND_ERR

• NOT_SUPPORTED_ERR

• INUSE_ATTRIBUTE_ERR

DOM Interface Types

The following lists the DOM Interface types:

• DOM interface types

• DOMNode

• DOMNamedNodeMap

• DOMNodeList

• DOMAttr

• DOMCDataSection

• DOMCharacterData

• DOMComment

• DOMDocumentFragment

• DOMElement

• DOMEntity

• DOMEntityReference

• DOMNotation

• DOMProcessingInstruction

• DOMText

• DOMImplementation

• DOMDocumentType

• DOMDocument