Hulles

GeeWhiz Prolog lives, and is ready to kick ass in NetBeans 7.0! Geertjan Wielenga has updated GeeWhiz Prolog for NetBeans 7.0 and published it as a NetBeans plugin module (.nbm). You can find the module at http://plugins.netbeans.org/plugin/39471/. Thanks tons, Geertjan!

Many of you have asked about updating GeeWhiz Prolog for newer versions of NetBeans, and unfortunately I just haven't had the time to address this. Luckily, Geertjan leapt into the breech and blew the dust off of it and polished it up and turned it into an NBM for NetBeans 7.0. Of course, to get him to do this I had to call him 5 times a day for six months and beg and plead and whine...but hey, it was worth the outrageous phone bills and the loss of my last remaining speck of self-respect. I'm kidding about this, of course; he did it on his own. Still, w00t, whatever that means.

So click on the Black Star of Death Prolog in the upper right hand corner of this blog just to pay a courtesy call to the hoary old original GeeWhiz Prolog, then go try out the new NBM.

And since I'm finally writing here again, albeit briefly, I note in passing that the irritating NetBeans Twitter SAAS bug I mentioned here was (I believe) finally fixed in NetBeans 7.0. Not a moment too soon, either. So another w00t. Whatever that means.

Oh yeah, one more thing, sorry but I've had to turn off comments to this blog for a while due to some spam attacks. If you desperately need to get in touch see the About page.

Recently I decided I had better bite the bullet and share with you some of the results of my experimentation with the Lookup functionality in NetBeans. I have always found the Lookup documentation confusing, and since the Lookup implementation itself seems to have evolved over the years it is difficult to separate out the currently-preferred Lookup syntax and usage from that of previous incarnations. So here are a couple tips that I discovered that might help you if you're in the same boat.

First, just a bit about what Lookup is and what it does: Lookup is designed to decouple providers and consumers of functionality within a NetBeans application. To borrow (I believe) Tim Boudreau's example, if you have a module SpellCheck that needs to look up words in a set of dictionaries and determine if a given word is spelled correctly, you can use the Lookup function to determine at run time what dictionary modules are available to use. SpellCheck does not need to know at compile time what providers will be available; it just defines an interface that can be implemented by anybody who cares to and at run time looks around to see who showed up.

If you've done a lot of development, you understand the beauty of this: I develop a module SpellCheck, I provide a dictionary specification in the form of a public interface, and you can write a module BritishEnglishDict that implements the interface. I then go on to create a module suite called FancyEditor that includes my spiffy little SpellCheck module and your module in it as well if I think Brits might be using it and if they sent me a cheque. When FancyEditor is run, within SpellCheck there is a Lookup statement that grabs all available implementing modules of the dictionary interface, including yours, and gives them to SpellCheck to use in looking up the spelling of a given word. Neither you nor I need to know anything about the other's module other than the contract provided by the interface. Both compile independently in NetBeans just fine without the presence of the other, thanks to Lookup.

So how do you implement Lookup? That's a harder question because there are a lot of ways to do it. I found at least three in my research: cookies, META-INF/Services, and layer file. Of the three, you should use the layer file approach unless you need a) backwards compatibility with previous NetBeans versions (cookies) or b) compatibility with JDK ServiceProvider syntax (META-INF/Services). Assuming that neither of these conditions is the case, use the layer file as it seems to be the preferred way to do things these days in NetBeans country. (And if I'm wrong, please tell me, it's difficult to stay current if you're a rugged lone-wolf renegade like me.)

By the way, you might notice that I'm trying to speak of "providers" and "consumers" without talking about services here. That's because it's easy to confuse JDK ServiceProvider services, NetBeans Lookup "services", and the myriad of other services available out there. So forget about the word "services" and let us never mention it again. Tough to find a good synonym though, but we'll get through this.

In this article (which is already a lot longer than I intended!) I will only discuss the layer file approach. The layer file is the means by which you tell NetBeans Lookup that your module BritishEnglishDict can provide dictionary functionality as specified in my interface. All you need to do is this:

1. Create a public interface in the consumer module (SpellCheck in my example) that defines what is needed.
2. Add a lookup statement to the consumer to call for modules that implement the interface.
3. Create a provider module (BritishEnglishDict) that implements the interface.
4. Create a layer file in the provider that announces to NetBeans (and Lookup) that our provider module implements the interface.

If all goes well, your brand new module suite will function perfectly and you can write ten more dictionary provider modules for various dialects of English without changing a thing in the consumer module.

How To Make All Go Well

To illustrate with some concrete code, first let's specify the interface in a hypothetical SpellCheck module that will be checking the spelling of some imaginary documents :

package org.hulles.spellcheck;

public interface SpellDictionary {

    public boolean isCorrect(String word);

}

Not much to it, for our example purposes. We just want to query a set of dictionaries and find if our word is spelled correctly. Next, let's add our Lookup to a class in SpellCheck:

...
public List<SpellDictionary> getDictionaries() {
    Collection<? extends SpellDictionary> dicts;

    StatusDisplayer.getDefault().setStatusText("Loading dictionaries....");
    dicts = Lookup.getDefault().lookupAll(SpellDictionary.class);
    return new ArrayList<SpellDictionary>(dicts);
}
...

In my example we're using the "lookupAll" method to get all implementations of our interface but there are variations that you can use as well to get, for example, either zero or one implementation. And also notice there is no "Lookup.Result" in there either. We'll stick with "lookupAll" to keep it simple. You might also note the status message; while not strictly relevant to what we're discussing it's such a damn good use of the NetBeans platform that I left it in anyway.

Now we're done with the consumer module. Let's move to the provider module, BritishEnglishDict. It's pretty simple as well -- it contains one class that implements the SpellDictionary interface, called "MyOED":

package org.hulles.dictionaryprovider;

import org.hulles.spellcheck.SpellDictionary;

public class MyOED implements SpellDictionary {

    public boolean isCorrect(String word) {
        return ("cheque".equals(word));
    }

}

Great! Now we have a provider that, in spite of its Oxonian title, just fulfills its contract with the interface by returning true if the word passed to it is 'cheque'. That's good enough for our purposes. The only step remaining is to announce our new spelling dictionary to the world by adapting the layer file for the "org.hulles.dictionaryprovider" package.

The layer file that I'm talking about is a file generally called "layer.xml" in NetBeans and is an XML file that informs the NetBeans platform of, well, stuff pertaining to its owning module. See other documentation wherever you can find it for more information on this; further discussion here is beyond our scope. The layer.xml file can be created automatically when you create the module in NetBeans, and if you think you're going to use one you should check the appropriate box at creation time to let NetBeans do this for you. If you didn't you can create your own, but be sure to add it to the module's manifest by adding a line to the manifest similar to:

OpenIDE-Module-Layer: org/hulles/dictionaryprovider/layer.xml

If you don't do this, NetBeans won't find your layer file and none of these great Lookup gizmos will work correctly. If you generate it when you create the module, this is added to the manifest automatically.

To add the necessary declaration for Lookup to find your provider, in the layer.xml file you should add lines similar to the following to whatever may already be in there:

<folder name="Services">
<folder name="Hidden">
<file name="org-hulles-dictionaryprovider-MyOED.instance">
<attr name="instanceClass"
    stringvalue="org.hulles.dictionaryprovider.MyOED"/>
<attr name="instanceOf"
    stringvalue="org.hulles.spellcheck.SpellDictionary"/>
<attr name="position" intvalue="400"/>
</file>
</folder>
</folder>

I didn't format the XML very nicely here because I don't want the lines to run too long (!), but you can automatically format the XML in your own file by right-clicking in the editor and selecting "Format". Formatting aside, you can see that we're just informing the NetBeans platform that our class MyOED exists as an implementation of SpellDictionary. This is all Lookup needs to find it within our module suite. Simple, no? By using a layer file, you don't need to use cookies nor do you need to use a "META-INF/Services" folder. It works just fine as it is.

I should also mention that you can include more than one provider class in your module. If you should write another class called, say, "MyWebsters" in the same module, you just need to add another definition to the "Services/Hidden" structure in your layer file. This was not crystal clear to me from the documentation until I tried it, but it works just fine. Your new layer file would then contain:

<folder name="Services">
<folder name="Hidden">
<file name="org-hulles-dictionaryprovider-MyOED.instance">
<attr name="instanceClass"
    stringvalue="org.hulles.dictionaryprovider.MyOED"/>
<attr name="instanceOf"
    stringvalue="org.hulles.spellcheck.SpellDictionary"/>
<attr name="position" intvalue="400"/>
</file>
<file name="org-hulles-dictionaryprovider-MyWebsters.instance">
<attr name="instanceClass"
    stringvalue="org.hulles.dictionaryprovider.MyWebsters"/>
<attr name="instanceOf"
    stringvalue="org.hulles.spellcheck.SpellDictionary"/>
<attr name="position" intvalue="300"/>
</file>
</folder>
</folder>

Of course you could also put your "MyWebsters" class into a different module, and probably should if your module is called "BritishEnglishDict" to avoid confusion. If you were to do this, I might then include both of your modules in my suite to check my word against both of your dictionaries. In this case, the position attribute in the layer.xml file comes into play. Lookup will return its results in the order specified by the position attribute in the layer file if it is present. Thus, my spell checker would first check to see if its word was in "MyWebsters", then it would check "MyOED" (via the List implementation in the example). There. We're done!

Too Bad It Doesn't Work

If you followed the above steps exactly, your Lookup should work just fine. But if it doesn't, it's harder than hell to debug it because the compiler doesn't know about the relationship between the provider and the consumer! Of course this is the trade-off for the decoupling we sought, but it can certainly make our life difficult until we get it right. And that's the real reason I'm writing this.

I actually modified a spell checker recently (Jazzy) to work with an application, and I could not get my Lookup to find my providers no matter what I tried. This is how I learned the things I did about Lookup that I've been discussing in this article, but it's all to no avail if the sucker don't work! Finally, after much agony and shouting of "Ogg Vorbis!" and "Bogofilter!", I realized that my provider modules were declared as type "Autoload" in the "API Versioning" section of the module properties. This meant that the modules weren't being loaded because there was no direct invocation of the provider modules anywhere, and modules of type "Autoload" are only loaded when they are invoked. I did away with direct references to the code in the providers when I used Lookup, so when the consumer called for providers it was whistling in the dark -- none were loaded. (The layer file for a module is only added to the application's layers when the module is loaded.) I switched the modules' types to "Regular", cleaned and rebuilt the modules, and it worked wonderfully at last. But to find this I really had to understand how it all worked, so I thought I would once again try to pass the hard-won knowledge along to you. Hope it helps someone!

If you're using or have tried to use the Twitter SaaS service in NetBeans 6.5, you may have encountered a bug in NetBeans that gives you an error that looks something like this:

javax.xml.bind.UnmarshalException: unexpected element (uri:"", local:"nilclasses").
            Expected elements are <{}authenticated>,<{}authorized>,<
            {}direct-messages>,<{}direct_message>,<{}friends>,<
            {}hash>,<{}nil-classes>,<{}ok>,
            <{}status>,<{}statuses>,<{}user>
        at com.sun.xml.internal.bind.v2.runtime.unmarshaller.UnmarshallingContext...
        at com.sun.xml.internal.bind.v2.runtime.unmarshaller.Loader.reportError(Lo...
        at com.sun.xml.internal.bind.v2.runtime.unmarshaller.Loader.reportError(Lo...
        at com.sun.xml.internal.bind.v2.runtime.unmarshaller.Loader.reportUnexpe...
        at com.sun.xml.internal.bind.v2.runtime.unmarshaller.UnmarshallingContex...
        at com.sun.xml.internal.bind.v2.runtime.unmarshaller.UnmarshallingContex...
...

I reported the bug via the official NetBeans channel but it's my first occasion to do that. Hopefully I did it correctly and will not be harshly reprimanded by the NetBeans Ministry of Love and put on a diet of blutwurst, refried beans and watery beer. Although come to think of it I'm on that diet anyway; I must have done something else bad recently to warrant it.

The error results from a small bug in the updated Twitter SaaS service code in NetBeans 6.5. It occurs when you (for example) try to get direct messages and there are no new ones. Under these circumstances Twitter now replies with a 200 (everything went swell) code but returns NilClasses, whereas it used to give a 310 error code. I can only imagine that someone somewhere is trying to migrate away from returning error codes when things happen normally so that consumer code doesn't throw exceptions.

Speaking of which, if you mask out the exception handling in the caller function you won't see the above message, you'll just get anomalous results in your direct messages (e.g.). This drove me crazy for a couple of days until I tracked down the result. "Bogofilter!" I muttered. "Ogg Vorbis!" (I swear when I'm frustrated.) Hence this short article to pass along the hard-won information.

I am also including a modified TwitterResponse.jar that you can plug into your code as a workaround until the bug is fixed by the NetBeans folks. Please note that you use it at your own risk. It was a simple change and I've used it without a hitch many many times since I created it, but it hasn't gone through the (presumably) rigorous QA process that happens at NetBeans HQ, wherever the hell that is. So my recommendation is that you should only download and install the jar if you work in a production environment and need the fix to stay productive; otherwise I strongly urge you to wait for the official fix. Also, if you don't already know what to do with the attached jar file you should probably wait as well. This patch is just to keep the fires burning for American industry until the real fix. You non-Americans can use the patch as well of course but you should delay installing it for a bit so that we in the United States can get a much-needed head start toward regaining our technical edge.

I hope this helps any others out there (American or not) who are currently muttering "Bogofilter!" to themselves. Let me know how it goes. Namaste.

In my last two articles (NetBeans Tip: Prism Break and More About Prism And NetBeans) I discussed using the Mozilla Labs Prism application to create dedicated "mini-browser" windows to reduce the overhead involved in (e.g.) looking up JavaDocs within the NetBeans IDE. My primary stated reason for using Prism from within NetBeans was to improve the performance of Lucille II, my aging laptop, bless her little 1.6GHz CPU.

However, one mustn't lose sight of one's overall goals as one mucks about in the fascinating but stinky cesspool of software development, and if results matter the number one rule for improving the performance of any piece of software should be: throw hardware at it. This is because since the 70's hardware costs have trended dramatically downward and software (i.e. people) costs have done the reverse until recently. It is nearly always a better idea economically to upgrade hardware before even thinking about software solutions, let alone discussing such solutions, let alone actually implementing them.

To reinforce this point, I'd like to point out that a certain unnamed consumer electronics retail chain is currently offering what seems to be a Best Buy for laptop owners like myself: 1GB memory modules for US$19.99. To max out Lucille's memory at 2GB (currently she packs 512MB under her skirt) costs under US$40! That is substantially less than it cost me to write this blog entry in terms of person costs, assuming that I had something better to do.

The moral of the story is that if you're a guerrilla software developer or otherwise work in the real world you should keep the big picture in mind and Do The Right Thing, no matter how attractive it might otherwise be to f*** around with the latest and greatest SSB or any of my other blog posts for that matter (except this one). If on the other hand you work for Sun you probably couldn't care less. I understand they actually pay you guys to write blogs! (Hire me and I'll quit giving you shit and go back to making fun of Microsoft Windows operating systems.)

Namaste and Happy New Year!

P.S. Of course the purpose for my writing these articles is to entertain and elucidate, as opposed to trying to stroke and bore your Sony VAIO so that it kicks the ass of all the other laptops in your coffee shop. But still... US$40! I'm off to buy memory, which at my age is an unexpected luxury.

As I mentioned in my last post, NetBeans Tip: Prism Break, the Prism application from Mozilla Labs has changed my (NetBeans) life. I can now use Lucille II, my laptop, to actually do NetBeans development work in a productive and efficient manner. I have been using the Prism SSB a lot from within the IDE for a couple of weeks now and I love it, particularly since finding out how to navigate back and forth between pages [see "special bonus tip" at the bottom of the Prism Break article]. So, since I'm still pretty excited about how well it works for me, I thought I'd discuss it a little bit more in this follow-up post.

Prism As A Self-Contained Browser

In the closing paragraph of the last post I said, "One thing I didn't mention earlier is that I think Prism will work as well with Internet Explorer as it does with Firefox." What I should have said was that "Prism will work as well on a machine that uses Internet Explorer as its default (or only) browser as well as one that uses Firefox." Prism seems to be a self-contained browser and does not appear to rely on the presence or absence of Firefox. I have been reluctant to de-install Firefox on any of my boxes to test this out but the more I have worked with it and researched it the more this seems to be the case. So I hope that clarifies what I stated in the previous article. And as I said there, please let me know of your experiences in this regard.

Prism On Windows

Since I published the Prism Break entry I decided to install Prism on Aspen, a custom-built desktop PC that I have in my home office to provide extra heat in the winter. Aspen is a little less underpowered than Lucille II; as opposed to her it has Delrin® gears and discrete transistors and doesn't require a bevy, underdressed or otherwise. It boots both Windows 2000 and Ubuntu, so I fired up W2K and downloaded and installed Prism on it. It installed flawlessly. (You can't imagine how elated I am every time I get to say that.) When I started Prism up in W2K it gave me a slightly different dialog than the Ubuntu Linux one, viz:

One gets a few more options than in Linux, but it is fundamentally the same. I created a miniapp to open up Mozilla Labs and it worked just fine.

Is that great or what? Now I use Prism on Aspen all the time as well as on good old Lucille II. Incidentally, I don't seem to get nav buttons in W2K either but I'm happy to say that the special bonus tip from last time works as well there as it does in Linux.

Other Software Development Uses For Prism

I've found that, in addition to the intra-IDE JavaDoc usage I mentioned in the previous post, Prism is quite useful in other ways as I carefully craft clean custom code (and concatenate consonants) on my computer. For example with Sancho, my Big NetBeans Platform Rich Client Application (BNPRCA), I need to be able to document changes that I make on a web site to be able to better communicate with my non-paying clients. To do this now I just leave a Prism window open to the web site and switch over to it whenever I need to. Because of Prism's dainty footprint I can afford to do this resource-wise, where once I couldn't and instead had to keep copious illegible paper notes laying around in my workspace for my cat to play in.

Still other uses I've found for Prism vis-à-vis software development include: keeping the old social networking applications open while I work (as I mentioned last time), having an on-line dictionary readily available to look up "vis-à-vis", tuning in to Last.fm (can't code without tunes!), and leaving a feed window open to catch the latest scoops in Planet NetBeans. And at this point I will somewhat shamefacedly admit that every time Hulles pops up in Planet NetBeans I whoop with delight and scare the shit out of my cat who then knocks more papers off my desk in retaliation. No one said the life of a renegade NetBeans Java programmer was going to be easy, I suppose. If they had I would have gotten it in writing then sued the pants off 'em.

The Prism Firefox Add-In

I didn't mention it before but there also exists a plug-in for Firefox called (I believe) Refractor that can generate a Prism desktop miniapp for whatever web page you happen to be on at the time. I used this for a short while but I found that, as seldom as I used it, it didn't add much value compared to simply starting Prism from the desktop and filling in the dialog fields. Ironically, adding the Prism plug-in into Firefox makes Firefox just that much more bloated, which is why I started using Prism in the first place! So I 86'ed the plug-in out of Firefox. You may like it however so give it a try if you want. It can be found in the normal Firefox add-in arena under Prism.

Heh Heh. The Cat's Asleep On The Scanner.

So that's it for this Prism follow-up. I'm going to post it now and wait for it to show up in Planet NetBeans. Namaste and Happy New Year!