I found a reference this morning on OSGi’s “buddy classloading” in reference to Spring, OSGi, and GigaSpaces. In addition to being, like, informative (thanks, Steve), it also had a reference to something Steve called “non-docs”:
To press button B, click the B button.
That’s perfect. It sums up OSGi documentation perfectly. But there’s another level of poor documentation, far more common when it comes to tech: half-docs.
Imagine this sort of thing, if you would:
Half-docs are what you get when something is documented, but not documented cleanly or illustrated well. You might have references. You might have hundreds of pages of references, in fact. But it’s all stuff that assumes you grok everything; just like I mentioned in the “what happened to JDO?” post, it’s a quality of reference that serves you well provided you didn’t use the reference to get started in the first place.
Look at Spring-DM. Let’s be clear here: I love this stuff. (Well, platonically.) Spring and OSGi is a disruptive technology, in the best possible way.
But getting it to work? This requires lots and lots of stab and attack for me, where I try something, get a failure, try to figure out why, try something, get a failure, try to figure out why, rinse and repeat ad nauseum. Eventually something sort of works, and I’m wondering why, still.
When I add a custom Spring schema to an OSGi module, this is what the docs tell me, from section 5.4 of the Spring-DM docs:
All bundles deployed in the OSGi space (whether they are Spring-powered or not) are scanned by Spring-DM for custom Spring namespace declaration (by checking the bundle space for META-INF/spring.handlers and META-INF/spring.schemas). If these are found, Spring-DM will make the schemas and the namespaces available through an OSGi service that will be automatically used by Spring-powered bundles. This mean that if you deploy a bundle that uses a custom schema, all you have to do is deploy the library that provides the namespace parser and the schema.
Well… okay. I don’t know what those files are supposed to contain; are they just supposed to exist? (I mean, hey: checking for META-INF/spring.schemas would yield a hit, right?)
Well… no. According to Appendix B (section 5) of the Spring documentation, it’s a little more involved; these are plain text files that resolve a URL to where the schema or namespace handlers are in the bundle itself.
Okay, fine; but adding this yielded a sequence of classloader issues that stretched for maybe seven packages, so that the NamespaceHandler (which worked beautifully and transparently, BTW, once the XSD was located) could find all of the Spring classes it needed.
I had declared a dependency on the Spring OSGi modules in my module, though, which makes me wonder why I had to specify all those imported bundles… or why the specification of all of those bundles wasn’t made explicit to me when I look at the docs.
Thus: half-docs. They make sure the information’s available to you, but only if you look hard. Bleah.
This actually sums up my approach to trying to write docs, BTW: “What other resources are needed in addition to this doc, in order for someone to be able to run what I’m showing them?” I’m sure I’m not perfect; in addition to getting things wrong sometimes (as the Terracotta people are fond of pointing out), I have my own assumptions to deal with, where I know something and don’t realise when others don’t.
I try, though.
Author’s Note: This is a repost from maybe 2009 or so.