XML Resolver refactor refactor

As of sometime this afternoon, all of the unit tests for both the Java and C# versions of XML Resolver passed. That’s a big milestone; it paves the way for official “6.0.0” releases.

I’m working my way through the JavaDoc and then I’ll have to go through whatever the C# version of that is called. Then I have to turn my attention to the user documentation.

It’s awkward because a lot of things are the same, but a lot of things are different. What I’ll probably end up doing is moving the current documentation under a /legacy/ URI and making the main pages about the new version.

The new version is a substantial improvement and I want to encourage folks to migrate. At the same time, it’s probably a bit of infrastructure in your project and I’ve done that annoying thing where I’ve changed the API, so I know it’s not something everyone will want to do immediately.

The biggest user-visible change, I think, is that a bunch of different objects that implemented different APIs have all gone away. The Resolver, StAXResolver, and XercesResolver objects are no more. Most of the APIs were implemented on Resolver, but there were several different resolver objects because the various systems have incompatible APIs.

Instead, now there’s an XMLResolver object that has methods that return instances of the different APIs. That feels a lot cleaner. You can also use the XMLResolver object to interrogate the catalog or resolve resources directly, if that’s a thing you want to do.

The design is more-or-less the same now in both Java and C#. I’ve worked harder to make the C# API more C#-like (using the naming conventions expected, for example, and treating nullable with care).

Where they diverge, I think it’s because there are fundamental differences in how the Java APIs and the C# API work. Aside from the thing that’s absolutely fucking broken on C#, those differences are a matter of design. I’d have made different choices, but no one asked me.

One slightly awkward thing on C# is that my object is called XmlResolver and the system API for setting up a resolver on C# is called System.Xml.XmlResolver. That means there’s a name clash. I’ve noodled around with various ways to fix that, but I don’t really like any of them.

This means that in C# you’re going to be left doing this:

XmlReaderSettings settings = new XmlReaderSettings();
settings.XmlResolver = XmlResolver.XmlResolver.GetXmlResolver();

Which is, on the one hand, kind of ugly. But on the other hand, that’s pretty much exactly the one line of code that you need, so I’m going to see if that’s ok.

Also up next: “integration testing”. That is, will it work on SaxonJ and SaxonCS? It probably won’t work in Saxon 12.x because of the API changes, so I’ll be focusing on V.next, the-thing-that-will-eventually-be-13.0.