10 12 2007-02-14T07:43:35-05:00 $Date: 2007-04-25 07:53:59 -0400 (Wed, 25 Apr 2007) $ NormanWalsh 2007Norman Walsh Making resolvers easier for users. In addition to the API proliferation problem I mentioned the other day, resolvers have another significant shortcoming: they're designed for programmers. That's a problem because, by and large, it isn't the programmers who need them, it's the legions of users out there wanting to make applications do the right thing. This point was driven home quite forcefully the other day after an internal presentation I gave about the new resolver code. SantiagoPericas-Geersten said, roughly, “that looks great, I'd love to use it” but when I began to explain how he could, he interrupted with “no, no, I don't want to have to set anything up, I don't want a properties file, it should just work.” This is, in fact, manifestly the case. End users, the ones stuck with applications that need resolvers, can't usually tinker with the code involved. We kicked around some ideas about how this might be accomplished. Eventually we came up with a plan and I have now implemented that plan. It's not a perfect plan because it does require a little bit of setup work and it does, in at least one case, break the rules. On the other hand, it's a good plan because it should work with any Java application.

The plan is this: using the standard JAXP factory finder mechanisms, inject a special set of parser classes into the application. These classes behave exactly like the standard JAXP 1.4 parsers except that they always use a resolver. It turns out that this works quite well. If you instantiate the resolver versions of the SAXParserFactory, XMLInputFactory, and DocumentBuilderFactory then: The DOM LSResourceResolver will fallback to the XML catalog resolver code, the StAX XMLResolver will fallback to the XML catalog resolver code, the SAX EntityResolver2 will fallback to the XML catalog resolver code, and the SAX EntityResolver will always use the XML catalog resolver code. This is where the rules are broken. Because there's no way for the SAX EntityResolver to indicate that it didn't succeed, I never let the application specify one. Any attempt to do so is ignored and the XML catalog resolver is always used. The NamespaceResolver isn't actually used by anyone yet, so there's no hook for it in the platform. Any application that uses it will be using the XML catalog resolver code, at least for now.

There is a catch. You knew there would be a catch, didn't you? The catch is that I constructed these specialty factories by stealing code from the JAXP 1.4 implementation. But I didn't want to steal all the code, so the result depends on JAXP 1.4. In practice, this means that you'll need to be running at least Java 6 or using the standalone JAXP 1.4 code developed in the GlassFish Community.

To try out this new feature, you do need to do a few things (sorry, Santiago, TANSTAAFL): Make sure that you're using JAXP 1.4, either because you're using Java 6 or because you've got the JAXP 1.4 jar files in one of your java.endorsed.dirs. Download both the XML Resolver and the XML Resolver JAXP 1.4 Factories from the XMLResolver project. Put both of those jar files on your class path. Run your Java application with the following system property settings: javax.xml.parsers.SAXParserFactory=org.xmlresolver.sunjaxp.jaxp.SAXParserFactoryImpl javax.xml.stream.XMLInputFactory=org.xmlresolver.sunxml.stream.XMLInputFactoryImpl javax.xml.parsers.DocumentBuilderFactory=org.xmlresolver.sunjaxp.jaxp.DocumentBuilderFactoryImpl I haven't setup a special factory for the Transformer yet, so you'll still have to tell your application which URI Resolver to use if you're using XSLT. (I might fix that as well, depending on just how many classes I have to copy to make that work.) Naturally, I don't expect these alternate factories to have any consequences except improved resolver support. If you do have trouble, please let me know.

The other significant change I made was to enable caching by default. This means that you don't need to have a properties file, there are sensible defaults for all of the properties including the cache. The cache directory defaults to .xmlresolver/cache in your home directory. Of course, you can still override all the defaults with property settings. If you only care about the updated resolver and don't want to try the factories trick, you only need the XML Resolver jar file; you can ignore the XML Resolver JAXP 1.4 Factories.

The resolver uses the java.util.logging framework. By default, it only logs those few messages of priority “info” or higher to the console. If you want more details, specify the verbosity property (either in a properties file or as a system property, xml.catalog.verbosity). A setting of “fine” or even “finer” will give much more information about what the resolver is doing. Note that the Java console logger will only print messages of priority “info” or higher too, so if you want to see the finer messages, you also have to tell the logger to allow them through. I use java.util.logging.config.file="/home/ndw/java/logging.properties" Setting this information in two places is confusing and I'll probably unify it all into the logging framework for the next release. It all works for me, but I've been hacking pretty hard. Feedback of any sort is always welcome.