XML Resolver 6.x SNAPSHOT

Why?

This major version update is motivated by two factors:

1. Several use cases have highlighted the fact that the current API doesn’t provide any way to interrogate the catalog without retrieving a resource. Refactoring the API to support that use case is an opportunity to further normalize and simplify the API.

2. The only interface that supports resolution with a nature and a purpose is the NamespaceResolver:

   Source resolveNamespace(String uri, String nature, String purpose);

   Unfortunately, that’s a fundamentally broken API for returning any resource other than an XML document. For example, returning a plain text document through that API is a violation of the meaning of Source.

   (I’ve banged my head squarely into this one twice.)

What?

The new design for the underlying API is based around the idea of constructing a request object and getting back a response object. (There is something like this in parts of the 5.x API, but this is made more complete and uniform in 6.x)

The new API aims to be backwards compatible. That limits the design choices somewhat, for example it means that existing resolver methods have to return null where it would be more consistent to have them return a non-null response object that indicated the request was unsuccessful. But the hit of making the API backwards incompatible seems too large at this point.

The following list summarizes the significant, public facing changes. It doesn’t detail every change.

1. A new ResourceRequest object encapsulates all of the possible aspects of a request (URI, base URI, nature, purpose, etc.).

2. There’s a new CatalogQuerier API. (suggestions for better names happily accepted). The querier API will interrogate the catalogs and indicate what resolved URI was found without attempting to open or retrieve it.

   The CatalogQuerier returns CatalogResponse objects.

3. There are new methods on ResolvedResource:

   getEncoding()

   returns the resource encoding, if it’s known.

   getHeader(String name)

   returns the first header with the matching name.

   getRequest()

   returns the request to which this is a response.

   isResolved()

   returns true if the request was successfully resolved.

4. The Resolver gains several new methods for constructing request objects and a new method for resolving a request object into a response.

   The response is an instance of the new ResourceResponse object.

5. The entire caching mechanism has been pulled out and discarded. That’s probably the only significant backwards incompatible change.

   1. An integrated cache seemed like a good idea, but it was problematic. Users were surprised by it and applications embedding the resolver suddenly had to worry about where the cache would be stored and when it was accessed.
   2. Eventually, it was disabled by default. Consequently, almost no on ever uses it.
   3. It was a burdonsome complexity in the resolver that didn’t seem justified any longer.

   If anyone misses it, it would be possible to build a caching resolver layer on top of the resolver.

To get more insite into the new API, see the Javadoc.

To compare the two APIs, you may find it useful to “diff” an XML representation of the old API against a representation of new API.

Where?

You can get the new API from the release page or via the Maven Sonatype snapshot repository:

https://oss.sonatype.org/content/repositories/snapshots/

Using the coordinates org.xmlresolver:xmlresolver:6.0.3-SNAPSHOT.

Feedback!

Please kick the tires (or tyres, if you prefer). Try it in your projects. Report any problems you encounter by opening an issue.