Book Review: Processing XML Documents with Oracle JDeveloper 11g by Deepak Vohra

A few months ago I came across a relatively new book: Processing XML Documents with Oracle JDeveloper 11g by Deepak Vohra (370 pages, Packt Publishing, ISBN 978-1-847196-66-8, February 2009).

It is an interesting mix of topics, all having to do with XML and most directly related to JDeveloper. The topcis and chapters do not at all times seem logically bundled together (for example design time and run time seem to be somewhat strangely intermingled in the book) but they provide a lot of useful information to any developer working on applications that involve XML in some way (and which one does not today) using JDeveloper as an IDE or Oracle XDK 11g..

And JDeveloper 11g’s XML capabilities may not be entirely on par with single issue IDEs such as XMLSpy, it certainly does a very good job at many frequent and less frequent XML tasks. This book does a good job at showing the various XML specific features of JDeveloper – although it also fails to mention one or two. It contains many examples of writing Java code to process XML in some way, primarily using XDK 11g; those examples are not always really specifically related to JDeveloper 11g, as the code uses standard libraries that can be used from any IDE. However, as examples of using XDK 11g for tasks like parsing, validating, transforming and querying (XPath) it is very valuable and will save developers a lot of googling.

The book’s cover states "Inspired by the author’s previous XML articles for the Oracle community, this expanded hands-on tutorial guides newcomers and intermediate users through JDeveloper 11g and XML document development. "  Inspired seems putting it mildly: much of the book’s contents seems to consist of slightly refined versions of technical articles previously published on the Oracle Technology Network and other websites or books. Which is not certainly not necessarily a bad thing by the way. On the one hand it means that the chapters can be read in pretty much any order you like as they are fairly stand-alone. At the same time, the book does not have a clear overall thread or storyline except for a simple example – a simple and not very exciting Oracle Magazine article catalog document that makes appearances in most chapters.

XDK 11g

On closer inspection the book is really more on Oracle XML Developer Kit (XDK) 11g than on JDeveloper. And while it states Processing XML documents in general, the book is clearly aimed at processing XML documents from Java and only Java programmers will get benefit from this book. The book does not go into Oracle XMLDB (except to almost suggest that you are better of with the embedded Oracle Berkeley DB XML database), nor does it discuss XSQL (it refers to another book by the author).

The Oracle XDK provides implementations of a number of very important XML APIs such as DOM, SAX, TRax and JAXB. The book does a good job of illustrating how Java developers can make use of such of these APIs – and especially of the extended implementations of these APIs in the Oracle XDK 11g. If you want to write Java code for parsing an XML document using either DOM or SAX parsing, querying the document using XPath and transforming the document using XSLT – all the core tasks required when writing Java applications that do XML manipulation – this book is a very useful tutorial and reference guide. The number of times I find myself trying to scrape these lines of code from the internet must be countless and here are the essentials bits all brought together and explained rather well.

Contents

Chapter 1 is a solid chapter, discussing the DOM and SAX API and its implementation in XDK 11g. It contains a number of useful code examples on the basic tasks of programmatically creating an XML document, writing it to some output channel, loading (and parsing) an XML document from file, using both (XDK) DOM and SAX API (implementations). I wonder why the STAX api is not mentioed. This chapter is all Java and XDK, and not specifically JDeveloper. The only value in this chapter of JDeveloper is the fact that it comes bundled with Oracle XDK 11g and you do not need to download it separately.

Chapter 2 is on the creation of an XML Schema definition. It has a brief introduction of XSD (too brief I would expect for developers who are new to XML Schema Definition, yet a useful refresher for irregular-users). It continues with a large number of screenshots for the visual XSD editor, which I find not overly useful. The Visual Editor to me is primarily used to verify the schema I am working on in the source view and is perhaps used for some small modifications. Yet most of the work on developing an XML Schema Definition is done in the source view. The chapter describes how a schema can be registered with JDeveloper – but fails to clearly explain why you should do that. It mumbles about file extensions that can be associated with that schema and mentions the fact that you can create XML instance documents based on that schema yet tells you (correctly) that you can do that for any XSD document on your file system. The true value of registering schemas as far as I know lies in the fact that when editing a document (partly) in the context of a namespaces ‘governed’ by one of the registered schemas, you will see the available elements in the component palette, will have code completion in the source view, property editing support in the property editor and validation support as you type the XML document. This becomes evident from the book to a very limited extent and in a very roundabout way.  This chapter suffers from a number of badly indented code examples – unlike the other chapters that are much more carefully laid out.

Chapter 3 is on XSD based validation of XML documents. A useful topic obviously. It describes how to do it in JDeveloper as well as programmatically. The latter topic is – justifiedly – discussed at much greater length. The former is not as clear as it could be on how validation can be performed against registered schemas, based on namespaces alone, without the need for the undesirable explicit schema references discussed in the book.

Chapter 4 is on XPath. It introduces the XPath search tool in the JDeveloper IDE. This chapter is very explicit on namespaces – which is excellent as that is an important yet puzzling concept. The book is not as clear on when/how/why to use the XPath search tool. Is it mainly for testing XPath expressions that developers use in the code – Java and XSLT – they are writing? Is it a serious alternative to the Search and Search in Files facilities in JDeveloper? Can the tool search across documents? Does it support ‘ click on search result and navigate to location in document’?

Chapter 5 is on XSLT – transformation of XML documents using the XML Stylesheet Language for Transformations. Here the book misses the opportunity to use the XSL Map facility in JDeveloper 11g, that allows developers to develop XSL-T Stylesheets in a more visual fashion and to test the XSLT document without writing any code – which is really very useful, especially for non-Java developers who need to create a bit of XSLT. The chapter does not teach readers XSLT – fair enough. It is pretty clear on how to do XSLT transformation using XDK 11g from Java programs.

The discussion on XSLT extensions functions is not what it could have been. It is a useful concept and I like the fact that the book discusses the topic at all. It mentions a good and simple example for an extension function: Fahrenheit-Celsius Temperature conversion. However, instead of showing the implementation of that straightforward example as an XSLT extension, it dives into a much more complex example of node manipulation functions that extend XSLT itself; it is very hard to understand exactly what the functions are doing. To make matters worse, it does not explain in the required detail how to create an extension function and how to register/install/configure/deploy it in such a way that the XSLT processor can find the classes that implement the extension functions.

Chapter 6 is on JSTL XML – the JSP taglibrary for processing XML. This topic is not necessarily especially related to either JDeveloper (11g) or XDK 11g – it is a discussion of the standard library. The author does not go into a discussion on when this library could be useful and when perhaps the XML processing is better left to the backing beans or business tier of the application. The role this library could play with AJAX is not discussed. I would suggest that there many situations where the architecture of the application is not served best by using these tags. But hey, if you want to do so, you can and this chapter will give you a head start for using them.

Chapter 7 and 8 discuss the DOM API release 3.0 functionality – loading and saving of XML with some filtering and manipulation capabilities as well as dynamic validation (trying out and validating potential changes to an XML document) – a new area for me. I found that especially interesting as that particular part of DOM had so far escaped my notice.

Chapter 9 is also a very important one, discussing JAXB 2.0 – the Java standard API for binding Java Classes to XML elements – and marshalling/unmarshalling from/to Java object structures to/from XML documents. The chapter demonstrates the creation of the JAXB 2.0 annotated classes based on an XSD document. It then explains how an XML document based on that schema can then be marshalled into an object graph using the classes generated by JAXB from the XSD. The other way – unmarshalling from an object graph to an XML document – is also demonstrated. The chapter concludes with a discussion of the JAXB 2.0 annotations for Java code. All in all very valuable and useful.

Chapter 10 introduces functionality in Oracle XDK 11g that was new to me: the class oracle.xml.differ.XMLDiff class that supports comparing of XML documents. This class supports various operations, including a simple boolean-returning test on equality of two XMLDocument objects, writing a human-readable textual output comparison report and the generation of an XSLT stylesheet that can be used to convert one of the compared XMLDocuments into the other. I have not yet tried it out, but seems interesting!

Chapter 11 introduces the Apache FOP library that can be used to create PDF documents using the XSL-FO language. As an XSL-FO document is XML, it can be created programmatically using the DOM API and it can be produced as the result of transforming source XML document using XSLT. The explanation on XSL-FO is a little terse. The code examples for creating XSL-FO from XML using XSLT and subsequentally processing the XSL-FO using Apache FOP to PDF (and possibly other FOP supported output formats not mentioned here) is useful.

Chapter 12 is on Apache POI – the open source Java library for creating Excel documents. POI provides an API through which an Excel document can be constructed: a workbook with worksheets with rows and cells. As data in XML documents frequently can be represented well in Excel, it can be useful to take data from an XML Document – using DOM API or JAXB for example – and use the data to construct the Excel document. That process is described in this chapter (related to a previously published article). The author chooses to use DOM based parsing of the XML document followed by querying using DOM based XPath. I am wondering why for example he does not use JAXB unmarshalling and the resulting Object graph to create the Excel document from. Note: I am not suggesting that it would be better, but I am interested in arguments for choosing either approach. All in all: chapter 12 is nice as you see a very practical use case. At the same time, it is mostly on POI, rather than on XML. You create Excel from Java – and the fact that the data comes from XML is not all that relevant. But now I am just being a bore.

Chapter 13 is on a somewhat surprising topic: Oracle Berkeley DB XML, not a topic immediately associated with XML processing in JDeveloper 11g. This chapter is a slightly reworked version of a paper published on XML.com – in May 2008. The introduction to the Berkeley DB XML database is useful – for me at least as I was hardly aware of its existence or potential. However, I would have liked the author to do more to explain to me and other readers when and why to engage the Berkeley DB XML database. When is the time to abandon file based XML documents that are processed using DOM Parsing and XPath querying and switch over to Berkeley DB XML? What does it add in terms of functionality or scalability? What is the price I pay for that added functionality or performance? Is it more complex? When should we not use Berkeley DB XML? The chapter mentions in the opening section: "Oracle databases (since Oracle 9i database R2) provide the Oracle XML DB feature to store and query XML documents in an XMLType data-type column, but you still need a DBA to manage the Oracle database. On the other hand, Oracle Berk[e]ley DB XML is an embeddable XML database for storing and retrieving XML documents, one which provides efficient querying of XML documents using XQuery." (the book has the same typo as the on-line article) I am not sure what exactly the author tries to tell me here. Is a DBA not needed for Oracle Berkely DB XML? Is a DBA a waste of money? Should I use Oracle Berkely DB XML even if I already have a ‘real’ Oracle database with DBA? A little guidance would have been very helpful.

Chapter 14 is one that I feel should have been left out of the book. It handles about XML Publisher and is an almost word for word rendition of an article published on OTN, in 2006. It discusses XML Publisher – which is not anymore known by that name, today it is BI Publisher – with  erroneous download instructions (not surprisingly for a more than 2 year old article) – and without any explanation on the licensing situation with BI Publisher (not a tool a developer can simply start using as the consequences can be quite serious). BI Publisher/XML Publisher is not naturally integrated with JDeveloper – it is available as a set of Java libraries that you can use in Java applications that you can develop with JDeveloper. They way this topic and chapter have been added to the book seem a bit too easy.

Missed opportunities

Despite the book’s value, it has missed some opportunities to enlighten the readers about XML capabilities in and around JDeveloper. Some are worth pointing out:

There is very little on XQuery, not even a single entry in the index. With XQuery as perhaps the most prominent upcoming standard, ready to largely take over from XSLT. XQuery only makes a brief appearance in the discussion of Berkeley DB, yet is displayed rather prominently in the screenshots that show the New Gallery wizard in JDeveloper with the XML category selected (create new XQuery file). Readers of the book remain unaware of how that type of file can be processed in JDeveloper 11g or Java code created inside JDeveloper 11g.

Those same screenshots show the node XML Localization File (XLIFF), but that particular topic is never mentioned in the book. The funny thing is that the New Gallery in my release of JDeveloper – 11.1.1.1.0, release in July after the publication of the book; yet the book nowhere mentions the exact release of JDeveloper it was written for – shows a number of options for XML that do not appear in the book. The "XML Schema from XML document" is a new one – quite interesting and only added in the July release. However, the options XSL Map and XSL Map from XSL Stylesheet have been around for somewhat longer (already available in 10g). These latter options really add value for XSLT developers – or rather developers who need to develop (simple) XSLT stylesheets and are not all that familiar with it. The XSL Map is a visual way to create an XSLT to transform between two XML structures defined in XML Schema Definitions. Definitely a topic that would have been worth a few pages in the book.

Perhaps the DTD to XSD conversion tool would have merited a remark somewhere in the book.

I find the book a little weak on the topic of namespaces. They are not explained very well. And they even seem to be avoided whenever possible. Most of the example XML documents do not use a namespace. As a result, some of the real life complexities that result from dealing with namespaces remain undiscussed – and that substracts value from the book for doing real XML work. Note that in some areas – like the XPath discussion – namespaces are brought into the picture and that immediately adds value for me.

Many of the screenshots in the book – and there are many – would have been much more useful as more attention was drawn – using markers, arrows, ovals – to the parts of the screen that are especially relevant in the given context. The screenshots are now almost always full screen (all of the JDeveloper IDE), half a book page and it is left to the reader to figure out which particular detail in the screenshot is the one you should look at. As such I find that many screenshots add very little value.

Errata

The errata for this book can be found on http://www.packtpub.com/support. However, at the time of writing this review, no errata have been published.

Conclusions

A useful collection of explanations and examples frequently needed when doing XML manipulation in Java applications, especially for developers using the Oracle XDK 11g. The book does not entirely live up to its title, as several XML specific facilities in jDeveloper are not discussed at all or enough to my taste. On the other hand, it is really not so much about JDeveloper to begin with – its more about XDK 11g and Java & XML in general. I feel that both to get a quick overview of the general approach for implementing various types of XML manipulations in Java as well as a guide with specific examples that can help out with the step-by-step implementation of real life use cases. I feel that the explanations of concepts and motivation of choices is somewhat lacking. Why, when and how to use certain mechanisms does not become very clear. At times the book suffers a little from the way it has been partially compiled from previous publications. All in all, it still certainly offers value for money.

 Resources

Book’s website on Packt Publishing: http://www.packtpub.com/processing-xml-documents-with-oracle-jdeveloper-11g/book.