| Oracle9i XML Database Developer's Guide - Oracle XML DB Release 2 (9.2) Part Number A96620-02 |
|
|
View PDF |
| Oracle9i XML Database Developer's Guide - Oracle XML DB Release 2 (9.2) Part Number A96620-02 |
|
|
View PDF |
This chapter describes the use of the APIs for XMLType in PL/SQL. It contains the following sections:
This chapter describes the PL/SQL Application Program Interfaces (APIs) for XMLType. These include the following:
XMLType objects. You can access both XML schema-based and non-schema-based documents. Before database startup, you must specify the read-from and write-to directories in the initialization.ORA file for example:
UTL_FILE_DIR=/mypath/insidemypath
The read-from and write-to files must be on the server file system.
This release maintains support for the XDK for PL/SQL:
to ensure backward compatibility. Therefore, most applications written for Oracle9i Release 1 (9.0.1) XML Parser for PL/SQL and XSLT Processor for PL/SQL instances will need no changes. In this release, new applications built with the updated PL/SQL DOM and the extensions to XMLType API do not need the XDK's XML Parser for PL/SQL and XSLT Processor for PL/SQL.
Applications that extensively use character-set conversions and file system interaction require some changes. The changes needed are due to the UTL_FILE package limitations, such as read/write to files in the UTL_FILE_DIR specified at database start-up.
|
Note: In this release, the PL/SQL packages |
This section explains differences between PL/SQL APIs native to Oracle XML DB and PL/SQL APIs available in XML Developer's Kits (XDK).
XMLType for developing applications that run on the server. PL/SQL APIs for XMLTYpe in Oracle XML DB provide native XML support within the database.|
Note: Oracle XML DB APIs are natively integrated in Oracle9i Release 2 (9.2) and not available separately. Oracle XML DB APIs cannot be downloaded from Oracle Technology Network (OTN). However, Oracle XDKs are available separately for download from OTN: |
The PL/SQL APIs for XMLTypeallow you to perform the following tasks:
XMLType tables, columns, and viewsXMLType dataXMLType data
See Also:
|
Because XMLType provides an in-memory or virtual Document Object Model (DOM), it can use a memory conserving process called lazy XML loading, also sometimes referred to as lazy manifestation. This process optimizes memory usage by only loading rows of data as they are requested. It throws away previously-referenced sections of the document if memory usage grows too large. Lazy XML loading supports highly scalable applications that have many concurrent users needing to access large XML documents.
The XMLType datatype has been enhanced in this release to include support for XML schemas. You can create an XML schema and annotate it with XML to object- relational mappings. To take advantage of the PL/SQL DOM API, first create an XML schema and register it. Then when you create XMLType tables and columns, you can specify that these conform to the XML schema you defined and registered with Oracle XML DB.
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's 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 DOM parser also provides methods for traversing the DOM tree and return data from it.
If you use the PL/SQL DOM API, 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.
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.
The only extensions to the W3C DOM API not supported in this release are those relating to client-side file system input and output, and character set conversions. This type of procedural processing is available through the SAX interface.
All Oracle XML DB APIs for accessing and manipulating XML comply with standard XML processing requirements as approved by the W3C. PL/SQL DOM supports Levels 1 and 2 from the W3C DOM specifications.
XMLType implements DOM Levels 1.0 and Level 2.0 Core, and is fully integrated in Oracle9i database through extensions to the XMLType API.The following briefly describe each level:
The generic APIs for XML can be classified in two main categories:
The DOM works by creating objects. These objects have child objects and properties, and the child objects have child objects and properties, and so on. Objects are referenced either by moving down the object hierarchy or by explicitly giving an HTML element an ID attribute. For example:
<img src="employee_jdoe.gif" ID="0123jdoe">
Examples of structural manipulations are:
The default behavior for the PL/SQL DOM API for XMLType (DBMS_XMLDOM) is as follows:
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) with the only difference being that the validation occurs when the object document is manifested. For example, if lazy manifestation is used, 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's structure and its mapping to a database schema.
|
Note: For backward compatibility and for flexibility, the PL/SQL DOM supports both XML schema-based documents and non- schema-based documents. |
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.
Additionally, Oracle XML DB uses the DOM to provide a standard way to translate data from multiple back-end data sources into XML and vice versa. This eliminates the need to use separate XML translation techniques for the different data sources in your environment. Applications needing to exchange XML data can use one native XML database to cache XML documents. Thus, Oracle XML DB can speed up application performance by acting as an intermediate cache between your Web applications and your back-end data sources, whether in relational databases or in disparate file systems.
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:
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:
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:
You can then:
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" .XMLType columns.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.
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.
| See Also:
Chapter 5, "Structured Mapping of XMLType" for more information and examples. |
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.
While elements and attributes declared within the XML schema get mapped to separate attributes within the corresponding SQL object type, some encoded information in an XML document is not represented directly. In order to guarantee that the returned XML document is identical to the original document for purposes of DOM traversals (referred to as DOM fidelity), a binary attribute called SYS_XDBPD$ is added to all generated SQL object types. This attribute stores all pieces of information that cannot be stored in any of the other attributes, thereby ensuring DOM fidelity for XML documents stored in Oracle XML DB.
Data handled by SYS_XDBPD$ that is not represented in the XML schema mapping include:
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.
Table 8-1 lists the PL/SQL DOM API for XMLType (DBMS_XMLDOM) methods supported in Release 2 (9.2.0.1).
The following DBMS_XMLDOM methods are not supported in Release 2 (9.2.0.2):
hasFeaturegetVersionsetVersiongetCharsetsetCharsetgetStandalonesetStandalonewriteExternalDTDToFilewriteExternalDTDToBufferwriteExternalDTDToClobTable 8-2 lists additional methods supported in Release 2 (9.2.0.2).
The following lists the PL/SQL DOM API for XMLType (DBMS_XMLDOM) exceptions. For further information, see Oracle9i XML Developer's Kits Guide - XDK.
The exceptions have not changed since the prior release:
INDEX_SIZE_ERRDOMSTRING_SIZE_ERRHIERARCHY_REQUEST_ERRWRONG_DOCUMENT_ERRINVALID_CHARACTER_ERRNO_DATA_ALLOWED_ERRNO_MODIFICATION_ALLOWED_ERRNOT_FOUND_ERRNOT_SUPPORTED_ERRINUSE_ATTRIBUTE_ERRIn 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_NODEATTRIBUTE_NODETEXT_NODECDATA_SECTION_NODEENTITY_REFERENCE_NODEENTITY_NODEPROCESSING_INSTRUCTION_NODECOMMENT_NODEDOCUMENT_NODEDOCUMENT_TYPE_NODEDOCUMENT_FRAGMENT_NODENOTATION_NODETable 8-3 shows the node types for XML and HTML and the allowed corresponding children node types.
Oracle XML DB DOM API for XMLType also specifies these interfaces:
This release introduces several extensions for character-set conversion and input and output to and from a file system. As stated earlier in this chapter, applications written against the PL/SQL Parser APIs in the previous release continue to work, but require some modifications that are described in the following sections.
PL/SQL API for XMLType is optimized to operate on XML schema-based XML instances.
A new function is provided, newDOMDocument that constructs a DOM Document handle given an XMLType value.
A typical usage scenario would be for a PL/SQL application to:
XMLType instanceDOMDocument node over the XMLType instanceNodeList and NamedNodeMap objects in the DOM are live; 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), those changes are automatically propagated in the NodeList, without further 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.
Figure 8-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.
newDOMDocument procedure processes the XMLTYpe or empty document. This creates a DOMDocument.createElement, createText, createAttribute, and createComment, and so on, to traverse and extend the DOM tree. See Table 8-1 for a full list of available methods.DOMElement, DOMText, and so on) can also be passed to makeNode to obtain the DOMNode interface.
This example illustrates how to create a DOMDocument handle for an example element PERSON:
-- 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; /
This example creates a DOM document from an XMLType:
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(dbms_xmldom.getNodeName(nelem)); dbms_output.put_line(dbms_xmldom.getNodeValue(nelem)); dbms_output.put_line(dbms_xmldom.getNodeType(nelem)); end; /
XML documents are made up of storage units, called entities, that 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 for imposing constraints on the storage layout and logical structure.
A software module called an XML parser or processor reads XML documents and provides access to their content and structure. An XML parser usually does its work on behalf of another module, typically the application.
In general, PL/SQL Parser API for XMLType (DBMS_XMLPARSER) performs the following tasks:
Table 8-4 lists the PL/SQL Parser API for XMLType (DBMS_XMLPARSER) methods.
Figure 8-2 illustrates the PL/SQL Parser for XMLType (DBMS_XMLPARSER) calling sequence:
parseBuffer, parseClob, parse(URI), and so on. See Table 8-4 for a full list of Parser methods.XMLType on the parsed XML document instance, you need to call getDocument on the Parser to obtain a DOMDocument interface.
This example parses a simple XML document and enables DOM APIs to be used.
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; /
W3C XSL Recommendation describes rules for transforming a source tree into a result tree. A transformation expressed in eXtensible Stylesheet Language Transformation (XSLT) is called an XSL stylesheet. The transformation specified is achieved by associating patterns with templates defined in the XSL stylesheet. A template is instantiated to create part of the result tree.
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's 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 (DBMS_XSLPROCESSOR) is Oracle XML DB's implementation of the XSL processor. This follows the W3C XSLT final recommendation (REC-xslt-19991116). It includes the required behavior of an XSL processor in terms of how it must read XSL stylesheets 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.
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 8-5 lists PL/SQL XSLT Processor (DBMS_XSLPROCESSOR) methods.
|
Note: There is no space between the method declaration and the arguments, for example: |
Figure 8-2 illustrates the XSLT Processor for XMLType (DBMS_XSLPROCESSOR) calling sequence:
newProcessor.Stylesheet from a DOM document use method newStylesheet.Stylesheet using the call setParams.processXSL using the processor and Stylesheet created in Steps 1 - 3.processXSL.DOMDocumentFragment interface can be operated on using the PL/SQL DOM API for XMLType.
This example transforms an XML document by using the processXSL call.Expect the following output (XML with tags ordered based on tag name):
<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; /
|
 Copyright © 2002 Oracle Corporation. All Rights Reserved. |
|