JDK-8223423 : New methods for creating DOM and SAX factories with Namespace support
  • Type: CSR
  • Component: xml
  • Sub-Component: jaxp
  • Priority: P3
  • Status: Closed
  • Resolution: Approved
  • Fix Versions: 13
  • Submitted: 2019-05-07
  • Updated: 2019-07-19
  • Resolved: 2019-05-19
Related Reports
CSR :  
JDK-8219692 - DOM and SAX parsers ignore namespace
Description
Summary
-------

Add newInstance methods that turn on Namespace support by default

Problem
-------

When the XML Namespace support was introduced in Java SE 1.4, it made the default setting of NamespaceAware feature false in order to maintain backward compatibility. To enable Namespace support, a method "setNamespaceAware" has to be called as demonstrated below:

    DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
    // turn on namespace support
    dbf.setNamespaceAware(true);
    DocumentBuilder db = dbf.newDocumentBuilder(); 

The problem is that users are often time not realizing or forgetting that the default setting for DOM and SAX is not Namespace aware and attempt to create a parser with a method chain such as:

    DocumentBuilder db = DocumentBuilderFactory.newInstance().newDocumentBuilder(); 

and then encounter processing errors such as missing namespaces or not being able to read namespace (e.g. a call to lookupNamespaceURI returns null).

While such issues can be resolved by setting Namespace aware, it is nonetheless a nuisance to the development process.

Solution
--------

Namespace support has been in the Java SE since 1.4. Since then, XML Namespace has become a norm for XML development. Having a parser that supports Namespace by default is long overdue and would be more user-friendly.

In the feature request, we would like to propose adding newInstance methods that shall turn on Namespace by default. The benefit is not only eliminating the trouble users may encounter as described in the problem section, but also reminding users that the old/existing corresponding methods would create factory instances that have Namespace support turned off.

The new methods add "NS" for Namespace as a prefix to the existing methods. With these new methods, users would be able to a chained method to create a parser with Namespace support, for DOM:

    DocumentBuilder db = DocumentBuilderFactory.newNSInstance().newDocumentBuilder(); 

and for SAX:

    SAXParser sp = SAXParserFactory.newNSInstance().newSAXParser();

Specification
-------------

Specdiff:
http://cr.openjdk.java.net/~joehw/jdk13/8219692/specdiff_02/overview-summary.html
Comments
Updated the specdiff to specdiff_v02. In this update, the explanatory paragraph is moved to a @ImplSpec section. The last sentence of the paragraph is moved to the API spec section. For the abbreviation ("NS") in the method names, the full-word alternative, e.g newDefaultNamespaceAwareInstance(), would be too long. While clearer, it's not helpful to keep the creation of a parser in one line. Consider: DocumentBuilder db = DocumentBuilderFactory.newDefaultNamespaceAwareInstance().newDocumentBuilder(); vs DocumentBuilder db = DocumentBuilderFactory.newDefaultNSInstance().newDocumentBuilder(); The later is 88 characters long that will be ok in one line, the former is 100 chars. Within the XML API, we do have some abbreviations as in: SAX, DOM, LS, plus "NS" is well-known prefix for Namespace support. I hope it is acceptable to be used in the proposed methods. For this version, I'll leave it as is. Please let us know whether this is okay or whether the full-word (NamespaceAware) version is more desirable.
20-05-2019
Moving to Approved. If the old newInstance should be deprecated at some point, that can be done as future work.
19-05-2019
I'm moving this CSR to Provisional rather than Approved to give a chance for some feedback to be acted upon. The explanatory paragraphs like " In addition to creating a factory instance using the same process as newDefaultInstance(), this method sets NamespaceAware to true. Parsers produced by the factory instance therefore will provide support for XML namespaces by default. " seem better handled as @implSpec tags if the straightforward implementation is intended to be mandated. The "NS" part of "newNSInstance" is a bit unusual, but offhand I don't have another suggestion for a different naming convention.
09-05-2019