10 PL/SQL API for XMLType

PL/SQL APIs For XMLType Features

The PL/SQL APIs for XMLTypeallow you to perform the following tasks:

• Create XMLType tables, columns, and views

• Construct XMLType instances from data encoded in different character sets.

• Access XMLType data

• Manipulate XMLType data

  
  

  See Also: "Oracle XML DB Features", for an overview of the Oracle XML DB architecture and new features. Chapter 4, " XMLType Operations " Oracle XML API Reference

  
  

With PL/SQL APIs for XMLType You Can Modify and Store XML Elements

While typical XML parsers give read access to XML data in a standard way, they do not provide a way to modify and store individual XML elements.

An element is the basic logical unit of an XML document and acts as a container for other elements such as children, data, attributes, and their values. Elements are identified by start-tags, as in <name>, and end-tags, as in </name>, or in the case of empty elements, <name/>.

An embedded DOM parser accepts an XML-formatted document and constructs an in-memory DOM tree based on the document structure. It then checks whether or not the document is well-formed and optionally whether it complies with a specific Document Type Definition (DTD). A DTD is a set of rules that define the allowable structure of an XML document. DTDs are text files that derive their format from SGML and can either be included in an XML document by using the DOCTYPE element or by using an external file through a DOCTYPE reference. A DOM parser also provides methods for traversing the DOM tree and return data from it.

If you use the PL/SQL DOM API, then you can use the NamedNodeMap methods to retrieve elements from an XML file.

PL/SQL APIs for XMLType support processing on the server side only. Support for client-side processing is not provided in this release.

Introducing W3C Document Object Model (DOM) Recommendation

Skip this section if you are already familiar with the generic DOM specifications recommended by the World Wide Web Consortium (W3C).

The Document Object Model (DOM) recommended by the W3C is a universal API to the structure of XML documents. It was originally developed to formalize Dynamic HTML, which allows animation, interaction and dynamic updating of Web pages. DOM provides a language and platform-neutral object model for Web pages and XML document structures in general. The DOM describes language and platform-independent interfaces to access and to operate on XML components and elements. It expresses the structure of an XML document in a universal, content-neutral way. Applications can be written to dynamically delete, add, and edit the content, attributes, and style of XML documents. Additionally, the DOM makes it possible to write applications that work properly on all browsers and servers and on all platforms.

A brief summary of the state of the DOM Recommendations is provided in this section for your convenience.

<img src="employee_jdoe.gif" ID="0123jdoe">

PL/SQL DOM API for XMLType (DBMS_XMLDOM): Features

The default action for the PL/SQL DOM API for XMLType (DBMS_XMLDOM) is as follows:

• Produces a parse tree that can be accessed by DOM APIs.

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

• An application error is raised if parsing fails.

• The types and methods described in this document are made available by the PL/SQL package DBMS_XMLPARSER.

DTD validation follows the same rules that are exposed for the XML Parser available through the XDK in Oracle9i release 1(9.0.1). The only difference is that the validation occurs when the object document is manifested. For example, if lazy manifestation is used, then the document will be validated when it is used.

Oracle XML DB extends the Oracle XML development platform beyond SQL support for XML text and storage and retrieval of XML data. In this release, you can operate on XMLType instances using the DOM in PL/SQL and Java. Thus, you can directly manipulate individual XML elements and data using the language best suited for your application or plug-in.

This release has updated the PL/SQL DOM API to exploit a C-based representation of XML in the server and to operate on XML schema-based XML instances. Oracle XML DB PL/SQL DOM API for XMLType and Java DOM API for XMLType comply with the W3C DOM Recommendations to define and implement structured storage of XML in relational or object-relational columns and as in-memory instances of XMLType. See "Using PL/SQL DOM API for XMLType: Preparing XML Data", for a description of W3C DOM Recommendations.

PL/SQL DOM API for XMLType introduces XML schema support. Oracle XML DB uses annotations within an XML schema as metadata to determine both an XML document structure and its mapping to a database schema.

When an XML schema is registered with Oracle XML DB, the PL/SQL DOM API for XMLType builds an in-memory tree representation of the XML document as a hierarchy of node objects, each with its own specialized interfaces. Most node object types can have child node types, which in turn implement additional, more specialized interfaces. Some node types can have child nodes of various types, while some node types can only be leaf nodes and cannot have children nodes under them in the document structure.

Designing End-to-End Applications Using XDK and Oracle XML DB

When you build applications based on Oracle XML DB, you do not need the additional components in the XDKs. However, you can mix and match XDK components with Oracle XML DB to deploy a full suite of XML-enabled applications that run end-to-end. For example, you can use features in XDK for:

• Simple API for XML (SAX) interface processing. SAX is an XML standard interface provided by XML parsers and used by procedural and event-based applications.

• DOM interface processing for structural and recursive object-based processing.

Oracle XDKs contain the basic building blocks for creating applications that run on the client, in a browser or plug-in, for example, for reading, manipulating, transforming and viewing XML documents. To provide a broad variety of deployment options, Oracle XDKs are also available for Java, Java beans, C, C++, and PL/SQL. Unlike many shareware and trial XML components, Oracle XDKs are fully supported and come with a commercial redistribution license.

Oracle XDK for Java consists of these components:

• XML Parsers: Supports Java, C, C++ and PL/SQL, the components create and parse XML using industry standard DOM and SAX interfaces.

• XSLT Processor: Transforms or renders XML into other text-based formats such as HTML.

• XML Schema Processor: Supports Java, C, and C++, allows use of XML simple and complex datatypes.

• XML Class Generator: Automatically generates Java and C++ classes from DTDs and Schemas to send XML data from Web forms or applications. Class generators accept an input file and creates a set of output classes that have corresponding functionality. In the case of the XML Class Generator, the input file is a DTD and the output is a series of classes that can be used to create XML documents conforming with the DTD.

• XML Transviewer Java Beans: Displays and transforms XML documents and data using Java components.

• XML SQL Utility: Supports Java, generates XML documents, DTDs and Schemas from SQL queries.

• TransXUtility. Loads data encapsulated in XML into the database with additional functionality useful for installations.

• XSQL Servlet: Combines XML, SQL, and XSLT in the server to deliver dynamic web content.

  
  

  See Also: Oracle XML Developer's Kit Programmer's Guide

  
  

Using PL/SQL DOM API for XMLType: Preparing XML Data

To take advantage of the Oracle XML DB DOM APIs, you must follow a few processes to allow Oracle XML DB to develop a data model from your XML data. This is true for any language, although PL/SQL is the focus of this chapter. The process you use depends on the state of your data and your application requirements.

To prepare data for using PL/SQL DOM APIs in Oracle XML DB, you must:

1. Create a standard XML schema if you do not already use one. Annotate the XML schema with definitions for the SQL objects defined in your relational or object-relational database.

2. Register your XML schema to generate the necessary database mappings.

You can then:

• Use XMLType views to wrap existing relational or object-relational data in XML formats. This enables an XML structure to be created that can be accessed by your application. See also "Wrapping Existing Data into XML with XMLType Views" .

• Insert XML documents (and fragments) into XMLType columns.

• Use Oracle XML DB DOM PL/SQL and Java APIs to access and manipulate XML data stored in XMLType columns and tables.

Creating and registering a standard XML schema allows your compliant XML documents to be inserted into the database where they can be decomposed, parsed, and stored in object-relational columns that can be accessed by your application.

Generating an XML Schema Mapping to SQL Object Types

An XML schema must be registered before it can be used or referenced in any context. When you register an XML schema, elements and attributes declared within it get mapped to separate attributes within the corresponding SQL object types within the database schema.

After the registration process is completed, XML documents conforming to this XML schema, and referencing it with its URL within the document, can be handled by Oracle XML DB. Tables and columns for storing the conforming documents can be created for root XML elements defined by this schema.

An XML schema is registered by using the DBMS_XMLSCHEMA package and by specifying the schema document and its URL (also known as schema location). The URL used here is a name that uniquely identifies the registered schema within the database and need not be the physical URL where the schema document is located.

Additionally, the target namespace of the schema is another URL (different from the schema location URL) that specifies an abstract namespace within which the elements and types get declared. An instance of an XML document should specify both the namespace of the root element and the location (URL) of the schema that defines this element.

When instances of documents are inserted into Oracle XML DB using path-based protocols like HTTP or FTP, the XML schema to which the document conforms is registered implicitly, if its name and location are specified and if it has not been previously registered.

Wrapping Existing Data into XML with XMLType Views

To make existing relational and object-relational data available to your XML applications, you create XMLType views, which provide a mechanism for wrapping the existing data into XML formats. This exposes elements and entities, that can then be accessed using the PL/SQL DOM APIs.

You register an XML schema containing annotations that represent the bi-directional mapping from XML to SQL object types. Oracle XML DB can then create an XMLType view conforming to this XML schema.

PL/SQL DOM API for XMLType (DBMS_XMLDOM) Methods

Table 10-1 lists the PL/SQL DOM API for XMLType (DBMS_XMLDOM) methods supported in this release. Character data (CDATA) refers to the section in an XML document used to indicate the text that should not be parsed. This allows for the inclusion of characters that would otherwise have special functions, such as &, <, , and so on. CDATA sections can be used in the content of an element or in attributes.

isNull()

makeAttr()

makeCDataSection()

makeCharacterData()

makeComment()

makeDocumentFragment()

makeDocumentType()

makeElement()

makeEntity()

makeEntityReference()

makeNotation()

makeProcessingInstruction()

makeText()

makeDocument()

writeToFile()

writeToBuffer()

writeToClob()

getNodeName()

getNodeValue()

setNodeValue()

getNodeType()

getParentNode()

getChildNodes()

getFirstChild()

getLastChild()

getPreviousSibling()

getNextSibling()

getAttributes()

getOwnerDocument()

insertBefore()

replaceChild()

removeChild()

appendChild()

hasChildNodes()

cloneNode()

isNull()

getNamedItem()

setNamedItem()

removeNamedItem()

item()

getLength()

isNull()

item()

getLength()

isNull()

makeNode()

getQualifiedName()

getNamespace()

getLocalName()

getExpandedName()

getName()

getSpecifiied()

getValue()

setValue()

isNull()isNull()

makeNode()makeNode()

isNull()

makeNode()

getData()

setData()

getLength()

substringData()

appendData()

insertData()

deleteData()

replaceData()

isNull()

makeNode()

isNull()

hasFeature()

isNull()

makeNode()

isNull()

makeNode()

findEntity()

findNotation()

getPublicId()

getSystemId()

writeExternalDTDToFile()

writeExternalDTDToBuffer()

writeExternalDTDToClob()

getName()

getEntities()

getNotations()

isNull()

makeNode()

getQualifiedName()

getNamespace()

getLocalName()

getExpandedName()

getChildrenByTagName()

getElementsByTagName()

resolveNamespacePrefix()

getTagName()

getAttribute()

setAttribute()

removeAttribute()

getAttributeNode()

setAttributeNode()

removeAttributeNode()

normalize()

isNull()

makeNode()

getPublicId()

getSystemId()

getNotationName()

isNull()

makeNode()

isNull()

makeNode()

getPublicId()

getSystemId()

isNull()

makeNode()

getData()

getTarget()

setData()

isNull()

makeNode()

splitText()

isNull()

makeNode()

newDOMDocument()

freeDocument()

getVersion()

setVersion()

getCharset()

setCharset()

getStandalone()

setStandalone()

writeToFile()

writeToBuffer()

writeToClob()

writeExternalDTDToFile()

writeExternalDTDToBuffer()

writeExternalDTDToClob()

getDoctype()

getImplementation()

getDocumentElement()

createElement()

createDocumentFragment()

createTextNode()

createComment()

createCDATASection()

createProcessingInstruction()

createAttribute()

createEntityReference()

getElementsByTagName()

adoptNode()

FUNCTION adoptNode(doc DOMdocument,
 adoptednode domnode)RETURN DOMNode;

createDocument()

FUNCTION createDocument (namspaceURI IN
 VARCHAR2, qualifiedName IN VARCHAR2, 
doctype IN DOMType) RETURN DocDocument;

getPrefix()

FUNCTION getPrefix(n DOMNode) RETURN
 VARCHAR2;

setPrefix()

PROCEDURE setPrefix (n DOMNode) RETURN
 VARCHAR2;

hasAttributes()

FUNCTION hasAttributes (n DOMNode) RETURN
 BOOLEAN;

getNamedItem()

FUNCTION getNamedItem (nnm DOMNamedNodeMap,
 name IN VARCHAR2, ns IN VARCHAR2) RETURN
 DOMNode;

setNamedItem()

FUNCTION getNamedItem (nnm DOMNamedNodeMap,
 arg IN DOMNode, ns IN VARCHAR2) RETURN
 DOMNode;

removeNamedItem()

FUNCTION removeNamedItem (nnm
 DOMNamesNodeMap, name in VARCHAR2, ns IN
 VARCHAR2) RETURN DOMNode;

getOwnerElement()

FUNCTION getOwnerElement (a DOMAttr) RETURN
 DOMElement;

getAttribute()

FUNCTION getAttribute (elem DOMElement, name
 IN VARCHAR2, ns IN VARCHAR2) RETURN
 VARCHAR2;

hasAttribute()

FUNCTION hasAttribute (elem DOMElement, name
 IN VARCHAR2)  RETURN BOOLEAN;

hasAttribute()

FUNCTION hasAttribute (elem DOMElement, name
 IN VARCHAR2, ns IN VARCHAR2)  RETURN
 BOOLEAN;

setAttribute()

PROCEDURE setAttribute (elem DOMElement, name
 IN VARCHAR2, newvalue IN VARCHAR2, ns IN
 VARCHAR2);

removeAttribute()

PROCEDURE removeAttribute (elem DOMElement,
 name IN VARCHAR2, ns IN VARCHAR2);

getAttributeNode()

FUNCTION getAttributeNode(elem DOMElement,
 name IN VARCHAR2, ns IN VARCHAR2) RETURN
 DOMAttr;

setAttributeNode()

FUNCTION setAttributeNode(elem DOMElement,
 newAttr IN DOMAttr, ns IN VARCHAR2) RETURN
 DOMAttr;

createElement()

FUNCTION createElement (doc DOMDocument,
 tagname IN VARCHAR2, ns IN VARCHAR2) RETURN
 DOMElement;

createAttribute()

FUNCTION createAttribute (doc DOMDocument,
 name IN VARCHAR2, ns IN VARCHAR2) RETURN
 DOMAttr;

PL/SQL DOM API for XMLType (DBMS_XMLDOM) Exceptions

The following lists the PL/SQL DOM API for XMLType (DBMS_XMLDOM) exceptions. For more information, see Oracle XML Developer's Kit Programmer's Guide.

The exceptions have not changed since the prior release:

• 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

PL/SQL DOM API for XMLType: Node Types

In the DOM specification, the term "document" is used to describe a container for many different kinds of information or data, which the DOM objectifies. The DOM specifies the way elements within an XML document container are used to create an object-based tree structure and to define and expose interfaces to manage and use the objects stored in XML documents. Additionally, the DOM supports storage of documents in diverse systems.

When a request such as getNodeType(myNode) is given, it returns myNodeType, which is the node type supported by the parent node. These constants represent the different types that a node can adopt:

• 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

Table 10-2 shows the node types for XML and HTML and the allowed corresponding children node types.

Document

DocumentFragment

DocumentType

EntityReference

Element

Attr

ProcessingInstruction

Comment

Text

CDATASection

Entity

Notation

Oracle XML DB DOM API for XMLType also specifies these interfaces:

• A NodeList interface to handle ordered lists of Nodes, for example:

  • The children of a Node

  • Elements returned by the getElementsByTagName method of the element interface

• A NamedNodeMap interface to handle unordered sets of nodes, referenced by their name attribute, such as the attributes of an element.

Working with Schema-Based XML Instances

Oracle Database has several extensions for character-set conversion and input and output to and from a file system. PL/SQL API for XMLType is optimized to operate on XML schema-based XML instances. Function newDOMDocument() constructs a DOM document handle, given an XMLType value.

A typical usage scenario would be for a PL/SQL application to:

1. Fetch or construct an XMLType instance

2. Construct a DOMDocument node over the XMLType instance

3. Use the DOM API to access and manipulate the XML data

   
   

   Note: For DOMDocument, node types represent handles to XML fragments but do not represent the data itself. For example, if you copy a node value, DOMDocument clones the handle to the same underlying data. Any data modified by one of the handles is visible when accessed by the other handle. The XMLType value from which the DOMDocument handle is constructed is the actual data, and reflects the results of all DOM operations on it.

   
   

DOM NodeList and NamesNodeMap Objects

NodeList and NamedNodeMap objects in the DOM are active; that is, changes to the underlying document structure are reflected in all relevant NodeList and NamedNodeMap objects.

For example, if a DOM user gets a NodeList object containing the children of an element, and then subsequently adds more children to that element (or removes children, or modifies them), then those changes are automatically propagated in the NodeList, without additional action from the user. Likewise, changes to a node in the tree are propagated throughout all references to that node in NodeList and NamedNodeMap objects.

The interfaces: Text, Comment, and CDATASection, all inherit from the CharacterData interface.

PL/SQL DOM API for XMLType (DBMS_XMLDOM): Calling Sequence

Figure 10-1 illustrates the PL/SQL DOM API for XMLType (DBMS_XMLDOM) calling sequence.

You can create a DOM document (DOMDocument) from an existing XMLType or as an empty document.

1. The newDOMDocument procedure processes the XMLTYpe or empty document. This creates a DOMDocument.

2. You can use the DOM API methods such as createElement, createText, createAttribute, and createComment, and so on, to traverse and extend the DOM tree. See Table 10-1 for a full list of available methods.

3. The results of these methods (DOMElement, DOMText, and so on) can also be passed to makeNode to obtain the DOMNode interface.

Figure 10-1 PL/SQL DOM API for XMLType: Calling Sequence

Description of the illustration adxdb014.gif

PL/SQL DOM API for XMLType Examples

-- This example illustrates how to create a DOMDocument handle for an example
 element PERSON:
declare 
  var       XMLType; 
  doc       dbms_xmldom.DOMDocument; 
  ndoc      dbms_xmldom.DOMNode; 
  docelem   dbms_xmldom.DOMElement;
  node      dbms_xmldom.DOMNode; 
  childnode dbms_xmldom.DOMNode; 
  nodelist  dbms_xmldom.DOMNodelist;
  buf       varchar2(2000);
begin 
   var := xmltype('<PERSON> <NAME> ramesh </NAME> </PERSON>');

   -- Create DOMDocument handle:
   doc     := dbms_xmldom.newDOMDocument(var); 
   ndoc    := dbms_xmldom.makeNode(doc);

   dbms_xmldom.writetobuffer(ndoc, buf);
   dbms_output.put_line('Before:'||buf);

   docelem := dbms_xmldom.getDocumentElement( doc );

   -- Access element:
   nodelist := dbms_xmldom.getElementsByTagName(docelem, 'NAME');
   node := dbms_xmldom.item(nodelist, 0);
   childnode := dbms_xmldom.getFirstChild(node);

   -- Manipulate:
   dbms_xmldom.setNodeValue(childnode, 'raj');

   dbms_xmldom.writetobuffer(ndoc, buf);
   dbms_output.put_line('After:'||buf);
end;
/

declare
 doc  dbms_xmldom.DOMDocument;
  
 buf   varchar2(32767);
  
begin
  -- new document
  doc := dbms_xmldom.newDOMDocument(sys.xmltype('<person> <name>Scott</name>
  </person>'));
  dbms_xmldom.writeToBuffer(doc, buf);
  dbms_output.put_line(buf);
end;
/

-- This example creates an element node starting from an empty DOM document:
declare
 doc            dbms_xmldom.DOMDocument;
 elem           dbms_xmldom.DOMElement;
 nelem          dbms_xmldom.DOMNode;
begin
    -- new document
       doc := dbms_xmldom.newDOMDocument;
    
    -- create a element node
       elem := dbms_xmldom.createElement(doc, 'ELEM');
   
    -- make node
       nelem := dbms_xmldom.makeNode(elem);
       dbms_output.put_line('Node name = '||dbms_xmldom.getNodeName(nelem));
       dbms_output.put_line('Node value = '||
                            dbms_xmldom.getNodeValue(nelem));
       dbms_output.put_line('Node type = '||dbms_xmldom.getNodeType(nelem));
end;
/

PL/SQL Parser API for XMLType: Features

In general, PL/SQL Parser API for XMLType (DBMS_XMLPARSER) performs the following tasks:

• Builds a result tree that can be accessed by PL/SQL APIs

• Raises an error if the parsing fails

Table 10-3 lists the PL/SQL Parser API for XMLType (DBMS_XMLPARSER) methods.

parse

newParser

parse

parseBuffer

parseClob

parseDTD

parseDTDBuffer

parseDTDClob

setBaseDir

showWarnings

setErrorLog

setPreserveWhitespace

setValidationMode

getValidationMode

setDoctype

getDoctype

getDocument

freeParser

PL/SQL Parser API for XMLType (DBMS_XMLPARSER): Calling Sequence

Figure 10-2 illustrates the PL/SQL Parser for XMLType (DBMS_XMLPARSER) calling sequence:

1. newParser method can be used to construct a Parser instance.

2. XML documents can then be parsed using the Parser with methods such as parseBuffer, parseClob, parse(URI), and so on. See Table 10-3 for a full list of Parser methods.

3. An error is raised if the input is not a valid XML document.

4. To use the PL/SQL DOM API for XMLType on the parsed XML document instance, you must call getDocument on the Parser to obtain a DOMDocument interface.

Figure 10-2 PL/SQL Parser API for XMLType: Calling Sequence

Description of the illustration adxdb015.gif

PL/SQL Parser API for XMLType Example

declare
 indoc       VARCHAR2(2000);
 indomdoc    dbms_xmldom.domdocument;
 innode      dbms_xmldom.domnode;
 myParser    dbms_xmlparser.Parser;
begin
   indoc   := '<emp><name> Scott </name></emp>';
   myParser := dbms_xmlparser.newParser;
   dbms_xmlparser.parseBuffer(myParser, indoc);
   indomdoc   := dbms_xmlparser.getDocument(myParser);
   innode     := dbms_xmldom.makeNode(indomdoc);
-- DOM APIs can be used here
end;
/

Enabling Transformations and Conversions with XSLT

The Oracle XML DB PL/SQL DOM API for XMLType also supports eXtensible Stylesheet Language Transformation (XSLT). This enables transformation from one XML document to another, or conversion into HTML, PDF, or other formats. XSLT is also widely used to convert XML to HTML for browser display.

The embedded XSLT processor follows eXtensible Stylesheet Language (XSL) statements and traverses the DOM tree structure for XML data residing in XMLType. Oracle XML DB applications do not require a separate parser as did the prior release XML Parser for PL/SQL. However, applications requiring external processing can still use the XML Parser for PL/SQL first to expose the document structure.

PL/SQL XSLT Processor for XMLType: Features

PL/SQL XSLT Processor for XMLType (DBMS_XSLPROCESSOR) is the Oracle XML DB implementation of the XSL processor. This follows the W3C XSLT final recommendation (REC-xslt-19991116). It includes the required action of an XSL processor in terms of how it must read XSLT style sheets and the transformations it must achieve.

The types and methods of PL/SQL XSLT Processor are made available by the PL/SQL package, DBMS_XSLPROCESSOR.

PL/SQL XSLT Processor API (DBMS_XSLPROCESSOR): Methods

The methods in PL/SQL XSLT Processor API (DBMS_XSLPROCESSOR) use two PL/SQL types specific to the XSL Processor implementation. These are the Processor type and the Stylesheet type.

Table 10-4 lists PL/SQL XSLT Processor (DBMS_XSLPROCESSOR) methods.

newProcessor

processXSL

processXSL

showWarnings

setErrorLog

NewStylesheet

transformNode

selectNodes

selectSingleNodes

valueOf

setParam

removeParam

ResetParams

freeStylesheet

freeProcessor

PL/SQL Parser API for XMLType (DBMS_XSLPROCESSOR): Calling Sequence

Figure 10-3 illustrates the XSLT Processor for XMLType (DBMS_XSLPROCESSOR) calling sequence:

1. An XSLT Processor can be constructed using the method newProcessor.

2. To build a Stylesheet from a DOM document, use method newStylesheet.

3. Optionally, you can set parameters to the Stylesheet using the call setParams.

4. The XSLT processing can then be executed with the call processXSL using the processor and Stylesheet created in Steps 1 - 3.

5. Pass the XML document to be transformed to the call processXSL.

6. The resulting DOMDocumentFragment interface can be operated on using the PL/SQL DOM API for XMLType.

Figure 10-3 PL/SQL XSLT Processor for XMLType: Calling Sequence

Description of the illustration adxdb016.gif

PL/SQL XSLT Processor for XMLType Example

<emp>
   <empno>1</empno>
   <fname>robert</fname>
   <job>engineer</job>
   <lname>smith</lname>
   <sal>1000</sal>
</emp>

declare
 indoc       VARCHAR2(2000);
 xsldoc      VARCHAR2(2000);
 myParser    dbms_xmlparser.Parser;
 indomdoc    dbms_xmldom.domdocument;
 xsltdomdoc  dbms_xmldom.domdocument;
 xsl         dbms_xslprocessor.stylesheet;
 outdomdocf  dbms_xmldom.domdocumentfragment;
 outnode     dbms_xmldom.domnode;
 proc        dbms_xslprocessor.processor;
 buf         varchar2(2000);
begin
   indoc      := '<emp><empno> 1</empno> <fname> robert </fname> <lname>
 smith</lname> <sal>1000</sal> <job> engineer </job> </emp>';
   xsldoc     := 
   '<?xml version="1.0"?> 
    <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
      <xsl:output encoding="utf-8"/>
      <!-- alphabetizes an xml tree -->
      <xsl:template match="*">
        <xsl:copy>
         <xsl:apply-templates select="*|text()">
         <xsl:sort select="name(.)" data-type="text" order="ascending"/>
         </xsl:apply-templates>
        </xsl:copy>
      </xsl:template>
      <xsl:template match="text()">
        <xsl:value-of select="normalize-space(.)"/>
      </xsl:template>
    </xsl:stylesheet>';
   
   myParser := dbms_xmlparser.newParser;
   dbms_xmlparser.parseBuffer(myParser, indoc);
   indomdoc   := dbms_xmlparser.getDocument(myParser);
   dbms_xmlparser.parseBuffer(myParser, xsldoc);
   xsltdomdoc := dbms_xmlparser.getDocument(myParser);
   xsl        := dbms_xslprocessor.newstylesheet(xsltdomdoc, '');
   proc       := dbms_xslprocessor.newProcessor;

   --apply stylesheet to DOM document   
   outdomdocf := dbms_xslprocessor.processxsl(proc, xsl, indomdoc);
   outnode    := dbms_xmldom.makenode(outdomdocf); 
-- PL/SQL DOM API for XMLType can be used here
   dbms_xmldom.writetobuffer(outnode, buf);
   dbms_output.put_line(buf);
end;
/