Page Comparison

...

import javax.xml.parsers.DocumentBuilderFactory;
import javax.xml.parsers.DocumentBulder;
import org.w3c.dom.Document;

...

Document doc = DocumentBuilderFactory.newInstance().newDocumentBuilder().newDocument();

While the 2.4 uPortal DocumentFactory implementation used PropertiesManager to determine the name of the class that it should Class.forName().instance() to get an instance of IPortalDocument to return, the uPortal 2.5 DocumentFactory implementation will simply return DocumentBuilderFactory.newInstance().newDocumentBuilder().newDocument(). For most existing clients of DocumentFactory, this will be sufficient since they were using only the DOM Level 2 Document API, of which DOM Level 3 is a superset. For those clients that were recasting the return value from Document to IPortalDocument, this will no longer be possible and they will need to change to recognize that the return value is no longer an IPortalDocument and is instead a Document which directly provides the methods desired.

Why Deprecate DocumentFactory?

Why deprecate DocumentFactory and ask clients to use the javax.xml DocumentBuilderFactory API directly? After all,

Document doc = DocumentBuilderFactory.newInstance().newDocumentBuilder().newDocument();

is longer than

Document doc = DocumentFactory.getNewDocument();

The reason to deprecate DocumentFactory is to encourage direct use of the javax.xml API and thereby reduce dependency within uPortal code upon other uPortal code. Code that does not depend upon uPortal DocumentFactory will be more reusable outside of uPortal. DocumentFactory in uPortal 2.5 no longer has a unique role to play – the work it was doing has been assumed by the core Java XML API in its provision of a DocumentBuilderFactory.

While

DocumentBuilderFactory.newInstance().newDocumentBuilder().newDocument();

is long, it becomes idiom – the way one gets a fresh Document instance in Java, not just in uPortal.

The long version

If you're thinking "Wait, wait! You've been too concise – I really want to read a longer account of what's going on here." – here it is. This is a re-presentation of content ~gilbert presented to the Shibboleth community.

...