A RIB_XML

The RIB_XML Procedural Language/Structured Query Language (PL/SQL) package contains a set of utilities to make the generation and parsing of XML documents easier. It is based on Oracle's XML Developer's Kit (XDK), and is designed to support application-specific Application Programming Interfaces (APIs) that read and write Extensible Markup Language (XML) messages.

The Oracle XML Developer's Kit (XDK) contains an XML parser and an implementation of the World Wide Web Consortium (W3C) Document Object Model (DOM). The RIB_XML package provides streamlined access to Oracle's APIs, allowing developers to quickly produce simple documents with a minimum of fuss.

The W3C DOM is an industry-standard set of data structures and APIs that allow developers to access and manipulate the contents of an XML document. The DOM is full-featured and is portable to a variety of platforms, but is generally considered unwieldy and over-structured for most people's needs. For our APIs, a more simplified model is used. The RIB_XML package attempts to hide most of the complexities of the W3C DOM and Oracle's implementation of the DOM behind a series of functions that take care of things like element generation and text node management.

In our simplified DOM, we only deal with element nodes. Documents, text nodes, and all the type-casting that one normally associates with the W3C DOM's everything-is-a-node philosophy are taken care of by the RIB_XML package. The utility functions in this package should be sufficient for nearly all documents, but since we are working with the standard structures and APIs, the full set of functionality is available if needed.

Generating XML Documents

Note: For a faster but more restrictive method of writing XML documents, you may want to use RIB_SXW.

An XML document is created by building a DOM tree and writing the contents of the tree to a CLOB or string. A new document is started by calling RIB_XML.newRoot(), which initializes an element and designates it the root of the DOM tree.

Adding Elements to the Tree

Elements other than root are added to the tree with the RIB_XML.addElement() procedure. If an element contains only text, it can be set by providing the optional value argument to addElement(). If no value is provided, the element will be empty. After calling addElement() with no value for the node, you can call addElementContents() to set the value. There is also a function form of AddElement() which returns the element it created, so that it can be further manipulated (for example: having elements added to it in turn).

In addition to using addElement() to add text values to a DOM tree, you can also use addDateElement() to add dates in a format-independent manner. The addDateElement() function takes the same parent, name, and value arguments asaddElement, but also adds an inclTime argument. This Boolean flag tells the package to include the timestamp (hour, minute, and second) with the date. If it is false, no timestamp is added, and only year, month, and day is added. The parameter is false by default.

The key to using addElement-type procedures and functions is to realize that each takes a parent element argument, and that the new element is added as the last child of this parent. As a result, when adding elements to the tree order counts. Furthermore, any message can be built with only addElement by adding elements in the order given by the message type format specification.

When the document is complete, it is written to the target CLOB with the RIB_XML.writeRoot() function. After a document is done with, resources are freed with the RIB_XML.freeRoot() procedure.

Example 1: Generating an XML document

This PL/SQL function:

create or replace procedure example1 is
   root    xmldom.DOMElement;
   message clob;
begin
   dbms_lob.createtemporary(message, TRUE);
   if rib_xml.newRoot(root, 'foobar') = FALSE then
      return;
   end if;
   --
   rib_xml.addElement(root, 'whine', 'Do I have to?');
   rib_xml.addElement(root, 'moan');
   rib_xml.addDateElement( root, 'foodate', sysdate, true );
   --
   if rib_xml.writeRoot(root, message, true) = FALSE then
      return;
   end if;
end;
/
show errors
Returns this XML document:
<foobar xmlns="http://www.oracle.com/retail/integration/payload/foobar"
xmlns:ribdate="http://www.oracle.com/retail/integration/payload/RIBDate"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.oracle.com/retail/integration/payload/foobar http://mspdev81:7777/rib-func-artifact/payload/xsd/foobar.xsd
http://www.oracle.com/retail/integration/payload/RIBDate http://mspdev81:7777/rib-func-artifact/payload/xsd/RIBDate.xsd">
  <whine>Do I have to?</whine>
  <moan/>
  <foodate>
    <ribdate:year>2007</ribdate:year>
    <ribdate:month>11</ribdate:month>
    <ribdate:day>30</ribdate:day>
    <ribdate:hour>10</ribdate:hour>
    <ribdate:minute>41</ribdate:minute>
    <ribdate:second>06</ribdate:second>
  </foodate>
</foobar>

Reading XML documents

An XML document is read from a CLOB and turned into a DOM tree, which a program can traverse or manipulate in whatever way it needs to. The RIB_XML.readRoot() function returns the root element of the DOM tree. For any given element, the RIB_XML.getChild() function returns the child element with the given name.

A very common task is to get the text out of a particular child of a given element. This is done by RIB_XML.getChildText(), which is really just a convenience method that calls getChild() and extracts the text value from that.

Just as with adding elements, there are convenience functions available for handing dates. The getChildDate() function works much like getChildText(), and finds the date for a child element with the given name.

If you have a series of child element with the same name (for example: multiple addresses for a supplier), use the RIB_XML.getChildren() function to get the whole list of children with the given name, and get a particular element out of the list with theRIB_XML.getListElement() function.

After all processing of a document is completed, any allocated resources are released by calling the freeRoot() function.

Example 2: Reading an XML document

This PL/SQL procedure:

create or replace procedure example2(data in clob) as
   root      xmldom.DOMElement;
   food      date;
begin
   root := rib_xml.readRoot(data, 'foobar');
   dbms_output.put_line( 'whine: ' ||
                         rib_xml.getChildText( root, 'whine' ) );
   food := rib_xml.getChildDate( root, 'foodate' );
   dbms_output.put_line( 'date: ' || to_char(food, 'YYYY/MM/DD HH24:MI:SS') );
   rib_xml.freeRoot( root );
end;
/
show errors
Prints these contents when provided with the XML document created in example 1:
whine: Do I have to?
date: 2007/11/30 10:41:06

Additional Reading

For more information, see the comments in the spec for the RIB_XML package describing each function.

For more information on XML, see http://www.xml.com">>http://www.xml.com/, ">>/www.w3.org/XMLhttp://, l.coverpages.org/index.htmlhttp://xm

For information on W3C DOM, seehttp://www.w3.org/DOM ">> /

For information on XML utilities and APIs, see http://www.oracle.com/technetwork/index.html">>http://www.oracle.com/technetwork/index.html.

The ideas for the RIB_XML package were taken from http://www.jdom.org">>http://www.jdom.org/, an XML-handling API for Java.