Skip to content

Conversation

@jcflack
Copy link
Contributor

@jcflack jcflack commented Aug 23, 2023

Java 17 adds (and prominently documents in the java.xml module-info javadocs), new, standardized, easy-to-remember names for a dozen or so of the XML implementation-specific properties and features.

And the standardized names are ... different from the old ones.

More names to feed into setFirstSupported{Feature,Property} when trying to adjust things.

The naming headaches are now visible outside of just the implementation module, because there are new standardized names for a Transformer property and feature also, which are used in the XSLT example code in PassXML.

So this is a good time to factor a setFirstSupported(...) generic function out of the various copies buried in SQLXMLImpl, and expose it in the Adjusting.XML API so client code can use it too, and use it that way in that example.

The Adjusting.XML API was added in some haste, and it used to say "the adjusting methods are best-effort and do not provide an indication of whether the requested adjustment was made". In fact it was pushed with some debug code doing exception stacktraces to standard error, which may have been an annoyance at any site that was using the feature heavily.

Take this opportunity to do something more systematic, and add a lax(boolean) method allowing it to be tailored. Stacktraces will still be logged if no tailoring is done, but may be more concise, as all of the exceptions that might be encountered in a chain of adjustments will be chained together with addSuppressed(), and common stacktrace elements should be elided when those are logged.

In passing, copyedit some Adjusting.XML javadoc to use styleguide-favored third-person rather than second-person phrasing.

Java 17 adds (and prominently documents in the java.xml
module-info javadocs), new, standardized, easy-to-remember
names for a dozen or so of the XML implementation-specific
properties and features.

And the standardized names are ... different from the old
ones.

More names to feed into setFirstSupported{Feature,Property}
when trying to adjust things.

The naming headaches are now visible outside of just the
implementation module, because there are new standardized
names for a Transformer property and feature also, which
are used in the XSLT example code in PassXML.

So this is a good time to factor a setFirstSupported(...)
generic function out of the various copies buried in
SQLXMLImpl, and expose it in the Adjusting.XML API
so client code can use it too, and use it that way
in that example.

The Adjusting.XML API was added in some haste, and used to
say "the adjusting methods are best-effort and do not
provide an indication of whether the requested adjustment
was made". In fact it was pushed with some debug code
doing exception stacktraces to standard error, which may
have been an annoyance at any site that was using the
feature heavily.

Take this opportunity to do something more systematic,
and add a lax(boolean) method allowing it to be tailored.
Stacktraces will still be logged if no tailoring is done,
but may be more concise, as all of the exceptions that
might be encountered in a chain of adjustments will be
chained together with addSuppressed(), and common
stacktrace elements should be elided when those are logged.

In passing, copyedit some Adjusting.XML javadoc to use
styleguide-favored third-person rather than second-person
phrasing.
A couple of the supplied examples strive to be usable
for real work, so this new method should be available
there too.
@jcflack jcflack merged commit 83f5f5a into REL1_6_STABLE Aug 26, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants