Monday, February 8, 2010

OpenSearch for JLS

My previous blog entry has a lot of references to sections of the Java Language Specification. Instead of being hyperlinks to the official online version of the document, however, they're merely plain non-clickable text (that was copied-and-pasted from elsewhere).

I could've modified the post and added the links manually, but then:
  • Finding the target URL for each section is tedious.
  • The blog entry source will be cluttered.
  • I'd have to repeat this for all my future posts.
  • More importantly, I'd still see unlinked references in forum posts, e-mail discussions, and even some official JLS documents.
After a quick research, I settled on a simple solution for my problem: an OpenSearch engine to perform the URL lookup. Once added to Firefox's list of search engines, one can:
  • Look up any section directly from the search bar
  • Look up a highlighted section number reference in a page from the search action in the context menu.
    • By default, Firefox uses the currently selected search engine.
    • Add-ons such as Context Search allow users to select from all previously-added search engines.
I opt for this approach instead of, say, writing a Greasemonkey script to automatically convert the references to hyperlinks, because such a script is way too complicated for what it's worth.
  • There's no official way to refer to the JLS, e.g. "(§ 5.2)", "[JLS 4.10.2, 8.4.8, Liskov87]", or just plain "6.3.1" are all commonly used patterns. Worse still, not all strings that match these patterns are JLS references.
  • It's harder to generalize this approach to multiple reference documents. There are already 3 editions of the JLS, and ideally the solution should be naturally generalizable to other documents as well.
  • There are many other complicating factors, e.g. the need to monitor dynamically-loaded content, possible interaction with other scripts that modifies the DOM, etc.
That said, this approach does have some appeal:
  • One-click look up is still most convenient.
  • Previously looked up references are distinguishable as visited links.
  • Links can be augmented with section title, say as a tooltip text.
On the other hand, the OS approach has its own benefits:
  • Each document simply has its own engine.
  • It provides direct "random access" to any section of the document.
  • The look up process naturally follows the search workflow in Firefox.
  • It only serves when requested. Its presence is virtually undetectable otherwise.
  • It's simple.
So here's my initial version of the OpenSearch engines. There's a lot of room for improvement, but they serve my purpose for now.
Java assertion spec/guide - honestly, I just found out about this. Apparently this was added in 1.4?
"Why provide an assertion facility at all, given that one can program assertions atop the Java programming language with no special support?"

Update 2/14: added bookmarklets! Much simpler to use than add-ons!

Update 2/20: added yubnub commands!


  1. Interesting way to use the search box in Firefox. Was it a lot of work (coding) to add it?


  2. The OpenSearch description file is an XML file of about a dozen lines. Enabling auto-discovery is just adding a link element in the hosting HTML.

    The "search engine" itself is quite straightforward, obviously. Ideally an entirely client-side solution is probably better since the look up tables are static and small.

  3. You know that docref is broken, right?

  4. What do you mean by broken? I'm aware of subtle bugs (e.g. for the bookmarklets, the Javascript is not universal across all browsers), and I suspect that my free hosting is not 100% reliable, but it works for me whenever I need it.

  5. Ah, I think I know what you mean. I tried accessing that subdomain from some proxies and they can't find the IP address. Frankly I'm not an expert in all this DNS stuff, but I'm hoping that things will resolve itself in a few days.