Hulles - NetBeans

Tips on Using Lookup in NetBeans

nospam@example.com (Hulles) — Wed, 14 Jan 2009 07:43:27 +0100

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:

Create a public interface in the consumer module (SpellCheck in my example) that defines what is needed.
Add a lookup statement to the consumer to call for modules that implement the interface.
Create a provider module (BritishEnglishDict) that implements the interface.
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:

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!

...And Sorry For The Long Lines!

nospam@example.com (Hulles) — Sat, 03 Jan 2009 06:52:46 +0100

I try to remember to be RSS feed-friendly but my blog site editor wraps the lines when I preview the post and I have to manually cut them up for them to display correctly when I post. Obviously I forgot to do that with the last entry. That's probably why I'm on the blutwurst-refried beans-watery beer diet: it was preemptive retribution. -- Hulles

NB 6.5 Twitter SaaS Bug

nospam@example.com (Hulles) — Sat, 03 Jan 2009 05:06:55 +0100

This post concerns a bug in the Twitter SaaS service in NetBeans 6.5.

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.

-- Hulles

Guerrilla Software Developers' Reality Check

nospam@example.com (Hulles) — Thu, 01 Jan 2009 05:23:22 +0100

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!

-- Hulles

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.

More About Prism And NetBeans

nospam@example.com (Hulles) — Tue, 30 Dec 2008 03:53:56 +0100

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!

-- Hulles

NetBeans Tip: Prism Break

nospam@example.com (Hulles) — Sun, 28 Dec 2008 05:09:18 +0100

Let's Gain Ourselves An Extra Hour or Two of Productivity Per Day!

Hoo boy and way doggies, are you going to thank me for this one, especially if you are like me and do most of your work on an underpowered laptop. I'm not necessarily saying my laptop's old, but it has big clanky iron gears and uses vacuum tubes and requires a bevy of underdressed 20-something brunettes to continually fan it with ostrich feathers to keep it cool. While there are some advantages to the last requirement, it is a non-trivial exercise for me to actually go anywhere with my laptop because I have to wait forever while the bevy primps and gets ready to go out. Underdressing is an art, not a science, they tell me.

So what does that have to do with this NetBeans tip? Well, because my laptop is creaky and slow I find myself constantly avoiding looking up JavaDocs from within the NetBeans IDE Java Editor no matter how much I might need the information. This is because it takes as long for my laptop to start up Firefox and display the JavaDocs as it does for the aforementioned bevy to get ready to go out. Mind you, I would never call NetBeans fat, but it is certainly big-boned, and Firefox is no anorexic supermodel either. Between them they suck resources like -- well, never mind, just take my word for it that they suck a lot of resources.

Enter Prism. Alarums And Excursions.

Because of all this you can imagine my elation when I accidentally stumbled across a simple, lightweight, dedicated browser application called Prism the other day. Prism is a XULRunner-based project of Mozilla Labs, the people who bring you the Firefox browser among other things, and the goal of the project is to provide an application for your desktop that starts a small no-frills browser for a single purpose -- like displaying JavaDocs, just to pick an example at random. This concept is called a "Site Specific Browser" (SSB). Perfect! I downloaded some Prism-started apps like Google Reader, Google Mail (GMail), Facebook and Twitter(!) to try out and they all have their own desktop menu shortcuts and they all bring up a lightweight dedicated browser window with just their own specific application web site in it. See this Twitter screenshot for an example:

Notice the lack of nearly all normal browser accoutrements like menus, tabs, etc. Excellent! For our purposes all we typically need to do is look at a damn JavaDoc, not shop for ostrich feathers on eBay (at least while we're working). Note also the picture of the distinguished-looking rogue in the corner. Looks hungry and thirsty, doesn't he? See "Donate" button. His children run naked and his cat needs scotch.

So here's what we're going to do: we're going to create ourselves a little mini-application to display JavaDocs (and any other web application started from NetBeans) in a Prism window instead of in our bloated browser. The steps that we will perform are these:

Obtain the Prism application and install it on our computer.
Create a dummy Prism instance that we can use for displaying JavaDocs.
Add our new NetBeans Prism instance to the list of browsers in the NetBeans IDE.
Test the new NetBeans Prism browser by looking up JavaDocs in the IDE.
Sit back and feel smug.

Acquiring And Installing Prism

The Prism application is free and available for download from Mozilla Labs at this URL: http://labs.mozilla.com/projects/prism/. It is available for Windows, Mac OS X, and Linux. I personally use Ubuntu 8.10 Linux and I installed Prism from the Ubuntu Debian repository without any problems via the Applications menu "Add/Remove..." command, but your experience may vary. If you have trouble installing Prism look around on the Mozilla Labs site or in the Mozilla Wiki for help. As a last resort you can ask me, but I'm not sure how much help I can offer in this.

At the same time you download and install Prism itself you may want to download other Prism-driven apps like the ones I mentioned earlier just to try them out. I particularly find the Twitter and FaceBook Prism applications useful so I can maintain contact with my vast extended social network (both people) while slaving away inside the big-boned NetBeans IDE.

Incidentally, you can also try out your new Prism gizmo to create your very own Prism launcher, simply by starting Prism. It will give you a window that looks like this:

You can then fill in the URL and name of whatever web site you choose and Prism will place an icon on your desktop that opens the site in an SSB window like this:

Pretty nifty, isn't it? I can think of about a gazillion uses for this, but right now let's get back to our project at hand.

Creating A NetBeans Prism Launcher

This step is easy, and it's the same process as the one described in the previous section for creating your own Prism Launcher. First you need to start Prism:

In the spare and terse Prism window that comes up you need to enter a URL and a name for the NetBeans JavaDoc launcher:

I used a real JavaDoc local file URI in my example but you can actually use any URL; we're going to override it in the launcher later on. And by the way, while I called my launcher "NetBeans JavaDoc", it should more precisely be called "NetBeans Prism" or something of that nature because NetBeans will use it to open all web sites from within the IDE, not just JavaDocs.

Once you hit the "OK" button in the dialog, it will create a shortcut on your desktop to open the URL you specified inside a cute little Prism window. Next we're going to get the shortcut off the desktop and into an application start menu so we don't clutter up our desktop. This step is optional of course but I recommend it. In most operating systems you can accomplish this by dragging the icon from the desktop into your "Start Menu" or equivalent:

If you don't or can't do this last step however, don't worry about it. Everything should be fine if you just leave it on your desktop. You can even try deleting it altogether and seeing if the following steps work without any shortcut at all (in spite of what the Prism dialog says) but I haven't done this myself. I suspect it will work just fine anyway because I've seen artifacts of deleted launchers lurking around in the Prism internal directory. Let me know if you try this and it works (or doesn't work, for that matter).

Once you're done, start the launcher from wherever you put it and you should get your chosen web site, a JavaDoc in my case, displayed in a Prism window like this:

Adding The Prism Launcher To The IDE

Now we're going to do the most difficult part: adding a browser definition to the NetBeans IDE. It really isn't all that difficult, especially for you since I'm going to tell you how to do it. Of course I had to hunt for a Prism command line syntax reference document that apparently doesn't exist so I once again had to dig into the source code to find it, but hey, that's why I have this blog, so I can share the hard-won information. [Pats self on back, clears throat deprecatingly.]

To add our new browser definition to the IDE, you should first open the properties window of the shortcut that you created in the previous step:

This will give you the correct Prism command line for your operating system. Copy the command line to the clipboard and paste it into a new text document. It should look something like this (all on one line), though it will vary with different operating systems and versions:

xulrunner-1.9 /usr/share/prism/application.ini -webapp netbeans.javadoc@prism.app

Now start the NetBeans IDE, go into "Tools / Options" from the main menu, and click on the "General" icon.

Click the "Edit..." button next to the "Web Browser" combo box. In the next window, click the "Add..." button.

You should now be at a screen that looks similar to this:

Replace the default name with the same name that you used when you created your shortcut. From the text document containing your system's command line, copy the program portion of the command line into the "Process" field (xulrunner-1.9 in my case) and paste the rest of the command line into the "Arguments" field. In the "Arguments" field, add the following text to the end of the line:

-uri {URL}

This tells Prism to override the URL in its application definition with the one that NetBeans provides via the "{URL}" template, as it helpfully mentions in the forms "Arguments Hint" box.

Hit "OK" to save your new browser definition. Make sure that the new definition is selected in the "Web Browser" combo box. Close the Options window. You should be all set!

Testing The New Browserito (Browserita?)

To test your new Prism launcher, open any Java file in the editor, right-click on a class or method name, and choose "Show JavaDoc". If the element has an associated JavaDoc, it should open in a Prism window like this:

"Viola!", as we used to say in Iowa. You now have a lightweight JavaDoc browser at your beck and call within the IDE, ready to spring forth with speedy goodness to show you the errors of your coding ways. No more waiting for chubby old FireFox (or obese old Internet Explorer) to huff and puff into the foreground.

But Now We Have A New Problem

If your working machine is anything like my laptop Lucille II, this tip should cut out at least an hour a day of nonproductive time when all is said and done, maybe more. See "Donate" button. Show "Donate" button to boss and explain new productivity gains. (Seriously.) But as foreshadowed by the title to this section, this leaves us with a whole new problem: our bevy of ostrich feather wavers now have an extra hour or two of free time and nothing to do. How to occupy them? This I leave to you.

SPECIAL BONUS TIP!

One Prism anomaly that I ran across in my experimentation, at least on my Linux system, is that even if you check the "navigation buttons" box on the Prism application creation dialog box you don't get navigation buttons (i.e. back arrow and forward arrow) in your resulting Prism browser window. After trying everything I could think of I finally discovered that you can navigate backwards and forwards through visited web pages by holding down the "Alt" key and using the mouse scroll button. This works regardless of whether you checked the "navigation buttons" box at app creation time. And it's FAST! Try it. And that solves the one problem I was having with the Prism SSB, so now I'm happy and I hope you are too.

In Conclusion

I hope you found this article useful and possibly even entertaining. I also hope it helps your productivity as much as it helped mine. One thing I didn't mention earlier is that I think Prism will work as well with Internet Explorer as it does with FireFox. I think this because of the Mozilla documentation, but I haven't tested it. Let me and others know of your experiences by commenting here. Good luck and good coding. Namaste.

Canary III: It's Not A Turkey (Yet)

nospam@example.com (Hulles) — Wed, 17 Dec 2008 02:45:31 +0100

Canary is a lightweight Java desktop application that monitors the Twitter online message service. Links to the complete source code and a zipped jar are included at the end of the article. You can run the jar directly once you unzip it if you just want to try out the application or use it without futzing with the source code. Try "java -jar [wherever you put the jar file]" from your command line.

Well, the holiday season is upon us here in the USA, a time when everyone seems to put on a few unneeded pounds. Since the Canary project seems to have become yet another part-time job for me that pays nothing, I figured I ought to make our tiny little bird a bit heavier as well by adding a few more enhancements to it and fixing a bug that I overlooked in the original Canary incarnation.

A Bug! [Audience Gasps]

It seems that when I adapted this project from my original module implementation I forgot to include code that starts the query timer to wake Canary up to check statuses. This means that if you've followed along so far, you've probably been sitting patiently by your computer screen for the last several weeks waiting for your so-called friends to update their statuses and feeling like a complete loser. So let's fix that bug. And don't worry, you're not a loser. The reason I know this is: Losers don't read Hulles, and Hulles doesn't read losers.

The code to start the timer is pretty simple. It lives in the initialization paragraph of CanaryView.java and looks like this:

	...        
        queryInterval = pref.getInt("queryInterval", 300000);
        queryTimer = new Timer(queryInterval, new ActionListener() {
            public void actionPerformed(ActionEvent e) {
                if (verbose) System.out.println("CanaryView: querying server from timer");
                refresh();
            }
        });
        queryTimer.setRepeats(true);
	...
        refresh();
        queryTimer.start();
	...

Nothing to it. You just have to remember to include the code in your program is all. [Embarrassed cough....]

Making The Canary Hop

In this paragraph I originally intended to document a way for us to pop the Canary window up if it was iconified and we received a new message but I decided to cut that part out in the interest of time -- mine. Sorry; it wasn't cool enough to make the cut though. If you try this on your own, you'll need to pop up the window when either friendsStatus or directMessages change; I lied last time when I said friendsStatus includes DMs. [Another embarrassed cough.]

By the way, we could also make the window "flash" if its already displayed to signal a new message, possibly by changing the window focus, but I have not tried this.

Making The Canary Chirp More

As you can see, we're still not done beating the canary metaphor to death. Now we're going alter the way the verbose console messages work by changing the constant "VERBOSE" in CanaryView to a variable that we get from CanaryApp. We'll also change CanaryApp by adding Java code to look for a "--verbose" or "-v" argument in the command line. Since Canary is built on the "Java Desktop Application" framework, it may be non-trivial to figure out how to grab the command line args (unless of course you're a RTFM'er). One does this by overriding the "initialize" method in the Application object. We are also adding a property "getter" to CanaryApp to return the value of the "verbose" variable, and adding a small method to print the command line usage message to the console in something close to the standard that most console-based programs use.

Incidentally, one of the nice things about specifying the verbose option on the command line is that you can open the properties window of the Canary project in the NetBeans IDE and put the "--verbose" option in the Arguments field (see screenshot) so that it applies when you run Canary from the IDE but does not take effect when you run Canary as a standalone application.

    @Override
    protected void initialize(String[] args) {
        for (String arg : args) {
            if (("--verbose".equals(arg)) || ("-v".equals(arg))) {
                verbose = true;
            } else if (("--help".equals(arg)) || ("-h".equals(arg))) {
                showUsage();
                exit();
            } else {
                System.err.println("Error: invalid option for Canary_II");
                showUsage();
                exit();
            }
        }
    }

    private void showUsage() {
        System.out.println();
        System.out.println("Usage: Canary_II [options]");
        System.out.println();
        System.out.println("Options:");
        System.out.println("\t--verbose, -v\tPrint messages of interest on stdout");
        System.out.println();
    }

    protected boolean beVerbose() {
        return verbose;
    }

Making The Canary Title Metaphor Finally Die

Next we're going to add an item to the menu bar that allows us to force a Twitter status check without waiting for the timer to expire. I thought about making this a button, but I like having the status screen uncluttered so I made it a menu item instead, called "Check Now". I also added mnemonics and accelerators to the menu items. (For some reason they keep disappearing though, wonder if that's fixed in 6.5?) The design screen for CanaryView looks like this once you add the menu item:

The simple action that we add to CanaryView looks like this. Notice that it resets the timer as well:

    @Action
    public void checkNow() {
        refresh();
        queryTimer.restart();
    }

Improving The Refresh And Archive Tasks

And at this point I was going to talk about (and include code for) making the Refresh and Archive tasks more user-friendly by making them Application Tasks, but it proved to be too daunting to explain here since there is some dependency on what gets done when so I gave it up for a bad job. Sorry again! I did take the progress bar relics from the initial project template out of the source code in the zip files at the end of the article though since we (I) won't be using them after all.

Setting The Cursor To The Top Of The Documents

Finally we are going to fix something that has bugged me for a while by moving the cursor to the top of the documents after an update rather than leaving it positioned at the bottom. It's been like having a pebble in my shoe; at last I'm finally taking the shoe off and emptying out the damn rock. The code to accomplish this is trivial, I just never got around to it before. All we have to do is call JEditorPane's setCaretPosition method with an argument of 0 in the methods that update the form's text panes, like this:

	...
        sBuf.append("");
        archivePane.setText(sBuf.toString());
        archivePane.setCaretPosition(0);
	...

Going Further

These are just some of the additions, changes and enhancements that can be made to Canary. Note that this list contains the "Going Furthers" of the previous two articles for your convenience.

Change the AboutBox to reflect Canary's coolicity
Actually use the busy icons, status bar, etc. from the stock desktop application framework or get rid of the code [Got rid of the code in Canary III]
Create secure account ID and password storage
Create functioning tweet hyperlinks (the hyperlinks in the EditorPanes don't actually work, and making them do so is beyond the scope of this article)
The Direct Msgs tab should have its own way of sending direct messages as well as displaying them (drop down friend box, etc.)
Add fins and an automatic headlight dimmer to Canary (i.e. make it prettier; I was sorely tempted to do this but managed to restrain myself just in time so I can leave it for you to do) (but the orignal one I did for my clients has a purple gradient background...)
Improve the printed format of the archived tweets
Add a date/time stamp to the archived tweet output
Save the archived output to a file instead of (as well as?) copying it to the clipboard
When saving the archive to the clipboard, add some additional white space between tweets
Actually parse the XML returned from Twitter in case of an error, as opposed to just printing it as a string
Notify the user in some way (popup window, flash window, see above) that a new message has been received
Adapt Canary to NetBeans 6.5
Make the refresh and archive tasks Application Tasks, or at least get them off the dispatch thread
Add the ability to store multiple Twitter accounts and allow the user to select which one to use on the fly. (Thanks to TwitterFox for the idea.)

Yay, We're Done

So that wraps it up for this installment of the Canary project. To resurrect our canary metaphor -- stop groaning, we're almost done -- we've fed it some suet and fattened it up a little bit in the interest of user-friendliness, and we've learned some things about RESTful web services, desktop applications and metaphor beating in the process. Yet our little canary remains fairly small. It has a long way to go before it's a twenty-pound turkey. Although I don't seem to be able to stop adding stuff to it, so by next Thanksgiving maybe it will be a twenty-pound turkey. Great. I'll probably have to hire a staff of five to support the application....

As always, the source code and a distributable jar follow the article. (It's Canary_III now, by the way, at least in the zip file names.) And if anyone would like, I can whip this project into Google Code, Source Forge or maybe even NetBeans and it can become a community project. Just let me know is all. Namaste.

Source Code and Jar

Source code:

Canary_III_Source.tar.gz
Canary_III_Source.zip

Jar file (Java executable):

Canary_III_Dist.zip

Canary II: Feather Straightening and Cage Gilding

nospam@example.com (Hulles) — Tue, 25 Nov 2008 18:39:30 +0100

So I Lied...

The ink is still wet on my last entry and already I'm writing a follow-up article. Sigh. One would think I'm trying to get the NetBeans Merit Badge or something. But I thought to clarify a couple points that I didn't get to in the first article and as an extra bonus add an archive feature to Canary. So here goes.

Straightening A Couple Of Feathers

I'll start with mentioning a couple things that I neglected to talk about in The Canary Project. First, I forgot to tell you that I deleted the properties file that NetBeans created in org.netbeans.saas.twitter because we don't need it; we got rid of the popup login window that used it.

Second, I didn't tell you that, when you first drag a Twitter web service node onto your source code method, NetBeans also creates a library for you called TwitterResponse.jar. You can find it in the "Libraries" section of Canary in the project tab. Of course it only does this the first time you drag a node, which is why I forgot to mention it. Be aware though, that if you just grab the source zip for Twitter without actually working the first example where we dragged the node onto our source, you won't have the library in your project. If you don't have it and need it, the easiest way to get it is to create a dummy method and drag a Twitter node onto it. A caveat, however: if the node you drag onto your source is not one that's already there, NetBeans will add code to TWAYDS.java to support the new node. This doesn't hurt anything but I wanted you to be aware of it. You can also grab the library from the distribution Jar zip file at the end of this (and the previous) article should you prefer.

I tested Canary in NetBeans 6.5 and all went well. I did notice, however, that if you actually drag a Twitter node onto your source in 6.5 the generated code is different. In 6.5, a typical Twitter call aftermath looks like this:

    if (result.getDataAsObject(Statuses.class) instanceof Statuses) {
        Statuses resultObj = result.getDataAsObject(Statuses.class);
    } else if (result.getDataAsObject(NilClasses.class) instanceof NilClasses) {
        NilClasses resultObj = result.getDataAsObject(NilClasses.class);
    }

The NilClasses class is new in 6.5, and for it to work the TwitterResponse.jar library in your project also must be the version that 6.5 creates when you drag a node. In other words, don't mix 6.1 and 6.5 code and libraries. Normally this won't be a problem if you start a project from scratch, but again it's something I thought I should bring up.

Finally, I should also mention that if you try and incorporate Canary into a NetBeans module you will need to create a library wrapper for TwitterResponse.jar to include it in your module project. Create a dummy non-module (i.e. normal) Java project, drag a node onto some dummy source, then swipe the library from the dummy project for your module project and create a wrapper for it. That is really beyond the scope of this project, but I thought that bringing it up might be helpful to someone.

Gilding The Cage

And so we get to the enhancement, a new tab for Canary that lists an "archive" of your past tweets. Author par excellence that I am, every tweet I send is a literary gem and worth saving for posterity, so a means of saving them on my own laptop is a must. How else can I incorporate them into my novel? So let's add an archiving function without further ado.

First we are going to modify CanaryView.java and add a new tab called, appropriately, "Archive". It's going to look like this:

As you can see, we are creating this tab a little differently than the others. Since we want to be good Twitter citizens, we don't want to automatically grab our entire archive every time we start Canary, so there is a "Fetch" button to explicitly get our archive when we do indeed want it. You will also notice a "Copy to Clipboard" button. This will copy the entire contents of the archive pane to the system clipboard, mostly so I don't have to include file writing logic in this application. But it works just fine for our purposes, and the copy-to-clipboard functionality is frighteningly simple to implement, as you will see shortly.

The Java code that we need to change in CanaryView is pretty straightforward. There are two new actions for the buttons and code to populate the archive tab JEditorPane. The new code looks like this:

    private void showUserStatus() {
        List<StatusType> archiveList;
        List<StatusType> statusList;
        StringBuffer sBuf;
        String text;
        
        archivePane.setText(UPDATINGMSG);
        sBuf = new StringBuffer();
        archiveList = new ArrayList<StatusType>(MAXARCHIVE);
        for (int page = 1; page <= MAXPAGES ; page++) {
            statusList = twitter.getArchive(Integer.toString(page));
            if ((statusList == null) || (statusList.isEmpty())) {
                break;
            }
            if (VERBOSE) System.out.println("CanaryView: archive page count = "
                   + statusList.size());
            archiveList.addAll(statusList);
        }
        
        if (VERBOSE) System.out.println("CanaryView: archive total count = "
                  + archiveList.size());
        
        if (archiveList.isEmpty()) {
            archivePane.setText(NOHISTORYMSG);
            return;
        }
        
        sBuf.append("<html><body>");
        for (StatusType type : archiveList) {
            sBuf.append("<p>");
            text = TwitterUtils.tweetToHTML(type.getText());
            sBuf.append(text);
            sBuf.append("</p>");
        }
        sBuf.append("</body></html>");
        archivePane.setText(sBuf.toString());
    }
    
    @Action
    public void fetchArchive() {
        showUserStatus();
    }

    @Action
    public void copyToClipboard() {
        archivePane.selectAll();
        archivePane.copy();
        JOptionPane.showMessageDialog(mainFrame, "Archive copied to clipboard.", 
		"Copy to Clipboard", JOptionPane.INFORMATION_MESSAGE);
    }

The method ShowUserStatus() gets our archive from the Twitter servers, one page at a time, to a maximum of MAXPAGES (10, in this case) pages. We put a limit in it just to make it reasonably sane and not overload the Twitter servers. If you do change MAXPAGES, please have a little compassion for the Twitter folks and don't make it too large. While we're here, note the small amount of code in the copyToClipboard() action. That's all it takes to slam the text into the system clipboard with JEditorPane. Isn't that nice?

Next we're going to modify TwitterUtils and add the function getArchive(...). It looks like this, very similar to the other Twitter functions in the class:

    @SuppressWarnings("unchecked")
    public List<StatusType> getArchive (String page) {
        RestResponse result = null;
        List<StatusType> statusList;
        Statuses resultObj;
        String since = null;
        String sinceID = null;
        String format = "xml";
        
        statusList = Collections.EMPTY_LIST;
        try {
             result = TwitterWhatAreYouDoingService.getUserTimeline(since, sinceID, page, format);
             resultObj = result.getDataAsObject(Statuses.class);
             statusList = resultObj.getStatus();
        } catch (Exception ex) {
            if (LOGERRORS) {
                Logger.getLogger(TwitterUtils.class.getName()).log(Level.SEVERE, null, ex);
            }
            statusList = null;
        }
        return statusList;
    }

Finally, we're going to add a function to TwitterWhatAreYouDoingService.java, know as TWAYDS.java from here to save my aching fingers. This function also strongly resembles others of its ilk in TWAYDS.

    /**
     * Retrieves representation of an instance of webtest.GetUserTimelineResource
     * @param since resource URI parameter
     * @param sinceId resource URI parameter
     * @param page resource URI parameter
     * @param count resource URI parameter
     * @param format resource URI parameter
     * @return an instance of RestResponse
     */
    public static RestResponse getUserTimeline(String since, String sinceId, 
             String page, String format) throws IOException {
        TwitterWhatAreYouDoingServiceAuthenticator.login();

        String[][] pathParams = new String[][]{{"{format}", format}};
        String[][] queryParams = new String[][]{{"since", since}, {"since_id", sinceId}, {"page", page}};
        RestConnection conn = new RestConnection("http://twitter.com/statuses/user_timeline.{format}", 
		pathParams, queryParams);

        return conn.get(null);
    }

And there you have it. When you run it, the "Archive" tab on Canary should look something like this:

Woohoo! Of course, your output won't contain my literary gems, it will contain your own gems.

To recap, we added functionality to three classes, TwitterUtils.java, TWAYDS.java and CanaryView.java. These should be the only differences from the original Canary project. Even so, I am including updated source and jar files at the end of the article. The project is called Canary_II in these, however, to distinguish it from the original project so I can support both (to a greater or lesser extent). At any rate, I hope you enjoy the newly-gilded cage for your Canary. Namaste.

Going Further

There are many enhancements that can be made to Canary_II; here are a few:

Improve the printed format of the archived tweets.
Add a date/time stamp to the archived tweet output.
Save the archived output to file instead of / as well as copying it to the clipboard.
When saving to the clipboard, add some additional white space between tweets.

Source Code and Jar

Source code:

Canary_II_Source.tar.gz
Canary_II_Source.zip

Jar file (Java executable):

Canary_II_Dist.zip

The Canary Project

nospam@example.com (Hulles) — Mon, 24 Nov 2008 15:59:23 +0100

Hey, A New Project!

Well, it's been a while since I've put anything new up, but I think you'll like this project. Since GeeWhiz Prolog I've been working on a massive "rich-client application" based on the NetBeans IDE. This application involves creating a complete suite of programs to write and produce screenplays. It's an ambitious project to say the least.

Recently while working on this mare's nest (called "Sancho", by the way) I decided to incorporate a feature that allows access to the Twitter online service from within the application. This feature was not part of the original design specification but when I thought of it I knew it was just too cool to pass up, so I built it and stuck it into the project. Like the guy in "Field of Dreams," my philosophy has always been, "Build it and they will come, or at least do some heavy panting." Anyway, the clients (who introduced me to Twitter in the first place) loved it so I decided to make a stand-alone version for this blog so you can try it out for yourself.

What The Hell Is Twitter?

At this point I suppose I should explain what the Twitter service is for those of you who are unfamiliar with it. Twitter is a pretty straightforward free online messaging service where you set up a Twitter account then post messages to it that others who follow you can read. Likewise, you receive Twitter messages (called "tweets") from those people you follow. You can send and receive tweets from your computer or from your cell phone; by far the most common usage seems to be "twittering" from your cell phone. If you're standing in the grocery store you can bitch about the price of kohlrabi right from the produce aisle, for example, and your friends following you on Twitter will roll their eyes and decide to remove you from their follow list. I am "hulles" on Twitter, as you might expect. Should you want to follow me you can do that very simply from your Twitter account home page, though if you should choose to do so I should warn you my tweets are often a little bizarre. As you might expect.

Design Goals

This application, named Canary by me to continue the "twitter/tweet" metaphor, runs as a standalone Java application on your computer just like any other. It monitors Twitter using its RESTful Web Service and keeps you updated on what your friends are bitching about in the grocery store by querying Twitter's servers every 5 minutes to get updated tweets. It also allows you to send tweets, get replies and get direct messages as well.

Like all the stuff I put up here, this project is intended to teach someone relatively new to the NetBeans platform how to use various features of that environment without much in the way of prior knowledge. Finding documentation on those features is often challenging, especially if those features have been recently introduced, so I try to explain myself as I go and take you through building the project step by step without assuming too much background on your part.

For this project, we are going to be learning about and using two interesting pieces of the NetBeans platform, "RESTful Web Services" and "Java Desktop Applications". Originally I was going to make this a NetBeans plugin module (like I did for my clients in Sancho, see above) but doing so incorporated too much unrelated overhead that I have already covered in GeeWhiz Prolog. Thus I went with a Java Desktop Application instead. I think it actually turned out cooler that way, and besides I don't have much call to Twitter while working on Java projects anyway and doubt that many people do.

Besides illustrating the Java Desktop Application framework, another major design goal for Canary is to be a "thin client" for the online service. That is, most of the documentation you see about Web Services in NetBeans assumes that you want to create a service provider as well as a service consumer / client. We don't want to do that. Twitter already provides the service; we just want to consume it with as little additional overhead as we can get away with. So this is going to be a skinny standalone Canary. No WADL / WSDL shit for us manly programmers, no sir. Just give us the bottom line and we will be on our merry way, thank you very much.

A final design goal for Canary is to be a good Twitter citizen. We don't want to be constantly hitting the Twitter servers with spurious requests; instead we want to conserve bandwidth and the Twitter servers' disk drives by limiting our Twitter access to only what we need and by allowing a decent amount of time to pass between requests. So this is going to be a saintly, skinny, standalone Canary by the time we're done. A Canary to feel proud of, a Canary to brag about, a Canary to.... You get the picture.

Requirements

To build and run this project you need the following:

NetBeans 6.1 (should work on 6.5 but I haven't tried it yet....)
RESTful Web Services plugin module
Web Services plugin module (automatically included when you select the RESTful Web Services plugin)
Internet access and a (free) Twitter account with which to test the project

You can download and install the plugin modules from the NetBeans IDE menu via "Tools / Plugins." The modules are located in the standard NetBeans repository.

Before We Get Started

Prior to starting the project, I suggest that you select the "Services" tab in NetBeans, expand "Web Services", and check out the available services. (Don't have it? See Requirements, above.) I have no idea what half of the services are for, but the one we are interested in is the Twitter "What Are You Doing Service" (TWAYDS here from now on). Notice that if you right click the TWAYDS node, you get a choice of selecting the API documentation:

I strongly recommend that you do so and read Twitter's API documentation. It is succinct and well-written and should be your bible if you do any further work with Canary or the Twitter RESTful Service beyond the scope of this project.

Creating The Project Framework

To get started with Canary, you need to create a new project. In the NetBeans IDE menu, select "File / New Project...", then on the first screen of the wizard select the "Java" category and "Java Desktop Application" as the project type.

In the "Name and Location" screen of the wizard, enter "Canary" as the project name and "canary.CanaryApp" as the application class.

Make sure the application shell is set to "Basic Application," not "Database Application". We don't need no stinkin' database for this project. Hit "Finish" on the wizard and let it set up your new project for you. The wizard automatically creates resources folders, CanaryApp.java, CanaryAboutBox.java, and CanaryView.java.

Take a look at the basic desktop application shell the wizard creates if you've never done this before. You can even try it out at this point by clicking the "Run" button on the toolbar, just to see what it does. When you're finished playing with it, close all tabs for the files that the wizard created.

Adding Twitter Functionality

Now we'll start adding Twitter-related structure to Canary. Create a new Java class called "TwitterUtils" by right-clicking the "canary" source folder in the project and selecting "New / Java Class...".

On the wizard screen, the class name should be "TwitterUtils", the project should be "Canary" and the package should be "canary".

Hit the "Finish" button and the wizard will create a new empty Java class for you. In the TwitterUtils class, create a new public method called getFriendsStatus. The class should now be as follows (except for the author, of course):

/*
 * To change this template, choose Tools | Templates
 * and open the template in the editor.
 */

package canary;

/**
 *
 * @author hulles
 */

public class TwitterUtils {

	public void getFriendsStatus() {
	
	}
}

Perfect. Now we work our magic. Select the "Services" tab in the IDE and expose "Twitter / What Are You Doing Service / statuses / [friends_timeline] / [{id}.{format}] / getFriendsTimelineById". Drag the "getFriendsTimelineById" node from the Services window onto the "getFriendsStatus" method you just created above in the editor pane.

Accept (for now) the default values in the next screen:

Woohoo! I told you it was magic. NetBeans, bless its heart, creates application code in your method and creates "org.netbeans.saas" and "org.netbeans.saas.twitter" folders for you.

Before we move on, notice that there is no server code anywhere, implying (at least) that we can indeed use these clients as standalone functions without worrying about writing any web service provider crap. I wasn't sure of that before I tried this the first time, even after reading all the documentation I could find about Web Services and RESTful Web Services. Most of the documentation spends a lot of time talking about the server side of things, which we don't need at all. And that is, of course, why I'm taking the trouble to write this for you! Consuming RESTful Web Services is easy! So far.

By the way, the "saas" in the folder names stands for "Software as a Service," the acronym for which is usually seen as "SaaS" outside of code.

As you look at the new folders you now have in your project, notice especially that a method was added to org.netbeans.saas.twitter.TwitterWhatAreYouDoingService.java for the getFriendsTimelineById gizmo we dragged in above.

Every time you drag a new node onto your project, NetBeans adds the appropriate method to this class. This is important to remember if you branch out beyond what we cover in Canary, because it happens behind the scenes and you don't notice it at the time. Until, of course, it doesn't happen behind the scenes because you just copy and paste a method without dragging it from the Services tab.... Guess how I know that.

There is one more thing to point out in the generated code before we move on. TWAYDSAuthenticator has code for a popup login screen to collect the Twitter account and password. Don't worry about this for now because we're going to get rid of it shortly.

Some Magic Of Our Own

Now it's time to hack. We're going to replace the TwitterUtils.java class you created earlier (sorry, but you didn't have to type that much) with the following code:

/*
 * To change this template, choose Tools | Templates
 * and open the template in the editor.
 */

package canary;

import java.util.Collections;
import java.util.List;
import java.util.logging.Level;
import java.util.logging.Logger;
import org.netbeans.saas.RestResponse;
import org.netbeans.saas.twitter.TwitterWhatAreYouDoingService;
import twitter.whatareyoudoingservice.twitterresponse.DirectMessageType;
import twitter.whatareyoudoingservice.twitterresponse.DirectMessages;
import twitter.whatareyoudoingservice.twitterresponse.StatusType;
import twitter.whatareyoudoingservice.twitterresponse.Statuses;

/**
 *
 * @author hulles
 */
public class TwitterUtils {
    private final static boolean LOGERRORS = false;
    
    public TwitterUtils() {
    }
    
    @SuppressWarnings("unchecked")
    public List<StatusType> getFriendsStatus (String sinceID) {
        RestResponse result = null;
        List<StatusType> statusList;
        Statuses resultObj;
        String since = null;
        String page = "1";
        String format = "xml";
        
        statusList = Collections.EMPTY_LIST;
        try {
             result = TwitterWhatAreYouDoingService.getFriendsTimeline(since, 
                         sinceID, page, format);
             resultObj = result.getDataAsObject(Statuses.class);
             statusList = resultObj.getStatus();
        } catch (Exception ex) {
            if (LOGERRORS) {
                Logger.getLogger(TwitterUtils.class.getName()).log(Level.SEVERE, null, ex);
            }
            statusList = null;
        }
        return statusList;
    }
    
    @SuppressWarnings("unchecked")
    public List<StatusType> getReplies(String sinceID) {
        RestResponse result = null;
        List<StatusType> statusList;
        Statuses resultObj;
        String since = null;
        String page = "1";
        String format = "xml";
        
        statusList = Collections.EMPTY_LIST;
        try {
             result = TwitterWhatAreYouDoingService.getReplies(since, 
                         sinceID, page, format);
             resultObj = result.getDataAsObject(Statuses.class);
             statusList = resultObj.getStatus();
        } catch (Exception ex) {
            if (LOGERRORS) {
                Logger.getLogger(TwitterUtils.class.getName()).log(Level.SEVERE, null, ex);
            }
            statusList = null;
        }
        return statusList;
    }

    @SuppressWarnings("unchecked")
    public List<DirectMessageType> getDirectMsgs(String sinceID) {
        RestResponse result = null;
        List<DirectMessageType> msgList;
        DirectMessages resultObj;
        String since = null;
        String page = "1";
        String format = "xml";
        
        msgList = Collections.EMPTY_LIST;
        try {
             result = TwitterWhatAreYouDoingService.getDirectMessagesToMe(since, 
                     sinceID, page, format);
             resultObj = result.getDataAsObject(DirectMessages.class);
             msgList = resultObj.getDirectMessage();
        } catch (Exception ex) {
            if (LOGERRORS) {
                Logger.getLogger(TwitterUtils.class.getName()).log(Level.SEVERE, null, ex);
            }
            msgList = null;
        }
        return msgList;
    }

    public RestResponse updateStatus(String status) {
        String format = "xml";
//        StatusType resultObj;
        RestResponse result;
        
        try {
             result = TwitterWhatAreYouDoingService.updateStatus(status, format);
//             resultObj = result.getDataAsObject(StatusType.class);
        } catch (Exception ex) {
            if (LOGERRORS) {
                Logger.getLogger(TwitterUtils.class.getName()).log(Level.SEVERE, null, ex);
            }
            result = null;
        }
        return result;
    }
    
    public RestResponse verifyLogin() {
        String format = "xml";
        RestResponse result;
        
        try {
             result = TwitterWhatAreYouDoingService.verifyCredentials(format);
        } catch (Exception ex) {
            if (LOGERRORS) {
                Logger.getLogger(TwitterUtils.class.getName()).log(Level.SEVERE, null, ex);
            }
            result = null;
        }
        return result;
    }
    
    public void signOut() {
        RestResponse result;
        
        try {
            result = TwitterWhatAreYouDoingService.endSession();
        } catch (Exception ex) {
            if (LOGERRORS) {
                Logger.getLogger(TwitterUtils.class.getName()).log(Level.SEVERE, null, ex);
            }
        }
    }
    
    public static String tweetToHTML(String text) {
        String[] splitText;
        StringBuffer sBuf;
        
        sBuf = new StringBuffer();
        splitText = text.split(" ");
        for (String s : splitText) {
            if (sBuf.length() > 0) {
                sBuf.append(" ");
            }
            if (s.startsWith("http://")) {
                sBuf.append("<a href='");
                sBuf.append(s);
                sBuf.append("'>");
                sBuf.append(s);
                sBuf.append("</a>");
            } else if (s.startsWith("@") && (s.length() > 1)) {
                // doesn't check for malformed urls...
                sBuf.append("<a href='");
                sBuf.append("http://twitter.com/" + s.substring(1));
                sBuf.append("'>@"); // follow twitter format, @ is not part of link
                sBuf.append(s.substring(1));
                sBuf.append("</a>");
            } else {
                sBuf.append(s);
            }
        }
        return sBuf.toString();
    }
    
/*  Return codes (from Twitter API):   
    * 200 OK: everything went awesome.
    * 304 Not Modified: there was no new data to return.
    * 400 Bad Request: your request is invalid, and we'll return an error message 
              that tells you why. This is the status code returned if you've exceeded the 
              rate limit (see below). 
    * 401 Not Authorized: either you need to provide authentication credentials, or 
             the credentials provided aren't valid.
    * 403 Forbidden: we understand your request, but are refusing to fulfill it.  An 
             accompanying error message should explain why.
    * 404 Not Found: either you're requesting an invalid URI or the resource in question 
             doesn't exist (ex: no such user). 
    * 500 Internal Server Error: we did something wrong.  Please post to the group about it 
             and the Twitter team will investigate.
    * 502 Bad Gateway: returned if Twitter is down or being upgraded.
    * 503 Service Unavailable: the Twitter servers are up, but are overloaded with requests.  
             Try again later.
*/
    public static String requestResponse(RestResponse response) {
        String responseString;
        
        if (response.getResponseCode() == 200) {
            responseString = null;
        } else {
            responseString = response.getResponseMessage();
        }
        return responseString;
    }
}

This is really the heart of our Canary. There are four methods for the Twitter functions we need:

getFriendsStatus, to get tweets from the people we're following
getReplies, to get replies to our tweets (these are also included in getFriendsStatus, but it can be nice to look at them separately)
getDirectMessages, to get direct messages ("dm's") to us (also included in getFriendsStatus, and ditto)
updateStatus, to allow us to send new tweets from our desktop

The new TwitterUtils also includes a few utility functions: requestResponse, verifyLogin and signOut, that we won't worry about for now. However, there is also a method called tweetToHTML that does deserve some explanation. When Twitter serves up a tweet it doesn't do so in the nice format that everyone who uses Twitter is used to: hyperlinked @replies, hyperlinked external links, etc. The static method tweetToHTML just formats the text received from the Twitter server into HTML that looks like the tweets that Twitter users have come to expect. See your own Twitter home page, TwitterFox, et. al. for examples of this.

Next we're going to replace the initial TWAYDS class that NetBeans created with a new one that has all the methods we need in TwitterUtils. It looks like this:

/*
 *  TwitterWhatAreYouDoingService
 *
 * Created on September 2, 2008, 8:33 AM
 *
 * To change this template, choose Tools | Template Manager
 * and open the template in the editor.
 */

package org.netbeans.saas.twitter;

import java.io.IOException;
import org.netbeans.saas.RestConnection;
import org.netbeans.saas.RestResponse;

/**
 * TwitterWhatAreYouDoingService Service
 *
 * @author hulles
 */

public class TwitterWhatAreYouDoingService {

    /** Creates a new instance of TwitterWhatAreYouDoingService */
    public TwitterWhatAreYouDoingService() {
    }

    /**
     * Retrieves representation of an instance of webtest.GetFriendsTimelineResource
     * @param since resource URI parameter
     * @param sinceId resource URI parameter
     * @param page resource URI parameter
     * @param format resource URI parameter
     * @return an instance of RestResponse
     */
    public static RestResponse getFriendsTimeline(String since, String sinceId, 
                String page, String format) throws IOException {
        TwitterWhatAreYouDoingServiceAuthenticator.login();

        String[][] pathParams = new String[][]{{"{format}", format}};
        String[][] queryParams = new String[][]{{"since", since}, {"since_id", sinceId}, 
                {"page", page}};
        RestConnection conn = new RestConnection("http://twitter.com/statuses/friends_timeline.{format}", 
                pathParams, queryParams);






        return conn.get(null);
    }
    
    /**
     * Retrieves representation of an instance of webtest.GetDirectMessagesToMeResource
     * @param since resource URI parameter
     * @param sinceId resource URI parameter
     * @param page resource URI parameter
     * @param format resource URI parameter
     * @return an instance of RestResponse
     */
    public static RestResponse getDirectMessagesToMe(String since, String sinceId, String page, 
                String format) throws IOException {
        TwitterWhatAreYouDoingServiceAuthenticator.login();

        String[][] pathParams = new String[][]{{"{format}", format}};
        String[][] queryParams = new String[][]{{"since", since}, {"since_id", sinceId}, {"page", page}};
        RestConnection conn = new RestConnection("http://twitter.com/direct_messages.{format}", 
                pathParams, queryParams);

        return conn.get(null);
    }

    /**
     * Retrieves representation of an instance of webtest.GetRepliesResource
     * @param since resource URI parameter
     * @param sinceId resource URI parameter
     * @param page resource URI parameter
     * @param format resource URI parameter
     * @return an instance of RestResponse
     */
    public static RestResponse getReplies(String since, String sinceId, String page, 
                String format) throws IOException {
        TwitterWhatAreYouDoingServiceAuthenticator.login();

        String[][] pathParams = new String[][]{{"{format}", format}};
        // NOTE: differs from the NetBeans saas insert 
//        String[][] queryParams = new String[][]{{"page", page}};
        String[][] queryParams = new String[][]{{"since", since}, {"since_id", sinceId}, 
                {"page", page}};
        RestConnection conn = new RestConnection("http://twitter.com/statuses/replies.{format}", 
                 pathParams, queryParams);

        return conn.get(null);
    }

    /**
     * Retrieves representation of an instance of webtest.EndSessionResource
     * @return an instance of RestResponse
     */
    public static RestResponse endSession() throws IOException {
        TwitterWhatAreYouDoingServiceAuthenticator.login();

        RestConnection conn = new RestConnection("http://twitter.com/account/end_session");

        return conn.get(null);
    }

    /**
     * Retrieves representation of an instance of webtest.UpdateStatusResource
     * @param status resource URI parameter
     * @param format resource URI parameter
     * @return an instance of RestResponse
     */
    public static RestResponse updateStatus(String status, String format) throws IOException {
        TwitterWhatAreYouDoingServiceAuthenticator.login();

        String[][] pathParams = new String[][]{{"{format}", format}};
        String[][] queryParams = new String[][]{{"status", status}};
        RestConnection conn = new RestConnection("http://twitter.com/statuses/update.{format}", 
                pathParams, queryParams);

        return conn.post(null, queryParams);
    }
    

    /**
     * Retrieves representation of an instance of webtest.VerifyCredentialsResource
     * @param format resource URI parameter
     * @return an instance of RestResponse
     */
    public static RestResponse verifyCredentials(String format) throws IOException {
        TwitterWhatAreYouDoingServiceAuthenticator.login(true);

        String[][] pathParams = new String[][]{{"{format}", format}};
        RestConnection conn = new RestConnection("http://twitter.com/account/verify_credentials.{format}", 
                pathParams, null);

        return conn.get(null);
    }
}

Note that this class isn't really created by us. You could have created the same class by dragging the appropriate nodes from the Services tab onto the editor pane like the first one we did; I just thought I'd save you the trouble by presenting the finished product.

Next we're going to hack the TWADSAuthenticator class and excise the popup login screen so we can use one more suited to the desktop application framework. We're also going to use the Java "Preferences.userNodeForPackage" feature so we don't have to create our own external storage for accounts and passwords. I had never used this before but tried it out here and it seems to be just the ticket. I really didn't want to have to add file access code to this skinny little bird just to store the couple pieces of data that we need to remember from session to session. In the original version of this created for the rich-client app I was able to use NbPreferences and change the data in the Options panel but this works just as well, perhaps better. But please note: Twitter accounts and passwords are not stored securely using this method! It works just fine for a teaching example here but may not be the solution you need in a more robust application. You were warned.

Having said all that, here is the TWAYDSAuthenticator code:

/*
 * TwitterWhatAreYouDoingServiceAuthenticator.java
 *
 * Created on September 7, 2008, 6:46 AM
 *
 * To change this template, choose Tools | Template Manager
 * and open the template in the editor.
 */

package org.netbeans.saas.twitter;

import java.io.IOException;
import java.net.Authenticator;
import java.net.PasswordAuthentication;
import java.util.prefs.Preferences;
import canary.LoginDialog;

/**
 *
 * @author hulles
 */
public class TwitterWhatAreYouDoingServiceAuthenticator extends Authenticator {
    private static String userID;
    private static String password;

    private static TwitterWhatAreYouDoingServiceAuthenticator singleton = new 
            TwitterWhatAreYouDoingServiceAuthenticator();
    
    public static void login() throws IOException {
        login(false);
    }
    public static void login(boolean force) throws IOException {
        Preferences pref;
        LoginDialog loginDialog = null;
        
        if (!isValidUsernamePassword()) {
            pref = Preferences.userNodeForPackage(TwitterWhatAreYouDoingServiceAuthenticator.class);
            userID = pref.get("userID", "");
            password = pref.get("password", "");
            if (!isValidUsernamePassword()) {
                if (loginDialog == null) {
                    loginDialog = new LoginDialog(null);
                }
                loginDialog.setVisible(true);
                userID = pref.get("userID", "");
                password = pref.get("password", "");
                if (!isValidUsernamePassword()) {
                    throw new IOException("Invalid username and/or password");
                }
            }
        }
        
        Authenticator.setDefault(singleton);
    }
        
    private static boolean isValidUsernamePassword() {
        return (userID != null && userID.length() > 0 &&
                password != null && password.length() > 0);
    }

    private TwitterWhatAreYouDoingServiceAuthenticator() {
    }

    @Override
    protected PasswordAuthentication getPasswordAuthentication() {
        return new PasswordAuthentication(userID, password.toCharArray());
    }

}

Not much to it, is there? It doesn't fatten up our Canary very much at all.

Creating The Login Screen

Now we're going to make the login screen, where we collect the Twitter account and password information for our app. Making a separate form for the login fits in nicely with our desktop application framework, and allows us to once again use Preferences.userNodeForPackage to store the data. And once again I will warn you, this storage method is not secure and you are storing potentially sensitive information with it, so please use good judgment and common sense here, people.

The login screen is pretty simple, and looks like this:

You can either make your own in NetBeans using the following code as a guideline or just swipe the files from the complete source at the end of this article. If you're new to this, please note that you can't just paste the code below somewhere and expect it to work, however. You have to actually create the form if you want to do it yourself!

/*
 * LoginDialog.java
 *
 * Created on September 8, 2008, 3:57 PM
 */

package canary;

import java.awt.Frame;
import java.util.prefs.Preferences;
import javax.swing.JOptionPane;
import org.jdesktop.application.Action;
import org.netbeans.saas.RestResponse;
import org.netbeans.saas.twitter.TwitterWhatAreYouDoingServiceAuthenticator;

/**
 *
 * @author  hulles
 */
public class LoginDialog extends javax.swing.JDialog {
    private final Preferences pref;
    private String userID;
    private String password;
    private final TwitterUtils twitter;
    private Frame parentFrame;
    private boolean loggedIn = false;

    /** Creates new form LoginDialog */
    public LoginDialog(Frame parent) {
        super(parent,true);
        pref = Preferences.userNodeForPackage(TwitterWhatAreYouDoingServiceAuthenticator.class);
        this.parentFrame = parent;
        initComponents();
        getRootPane().setDefaultButton(okButton);
        twitter = new TwitterUtils();
        userID = pref.get("userID", "");
        password = pref.get("password", "");
        userIDField.setText(userID);
        passwordField.setText(password);
    }

    @Action
    public void cancelAction() {
        loggedIn = false;
        setVisible(false);
    }

    public boolean successfulLogin() {
        return loggedIn;
    }
    
    @Action
    public void okAction() {
        String saveUserID;
        String savePassword;
        RestResponse result;
        String resultString;
        
        setVisible(false);
        loggedIn = false;
        
        // TODO: returns clear text, might want to change that
        userID = userIDField.getText();
        password = new String(passwordField.getPassword());
        saveUserID = pref.get("userID", "");
        savePassword = pref.get("password", "");
        pref.put("userID", userID);
        pref.put("password", password);
        result = twitter.verifyLogin();
        if (result == null) {
            JOptionPane.showMessageDialog(LoginDialog.this, 
                    "Unable to verify Twitter login at this time.", "Log In Error", JOptionPane.ERROR_MESSAGE);
            pref.put("userID", saveUserID);
            pref.put("password", savePassword);
            userID = saveUserID;
            password = savePassword;
        } else {
            System.out.println("LoginDialog: result = " + result.getDataAsString());
            resultString = TwitterUtils.requestResponse(result);
            if (resultString != null) {
                JOptionPane.showMessageDialog(LoginDialog.this, resultString, "Log In Error", 
                        JOptionPane.ERROR_MESSAGE);
                pref.put("userID", saveUserID);
                pref.put("password", savePassword);
                userID = saveUserID;
                password = savePassword;
            } else { 
                // it worked, leave prefs as is
                JOptionPane.showMessageDialog(LoginDialog.this, "Login for " + userID + " successful.", 
                        "Logged In To Twitter", JOptionPane.INFORMATION_MESSAGE);
                loggedIn = true;
            }
        }
    }

    // Variables declaration - do not modify                     
    private javax.swing.JButton cancelButton;
    private javax.swing.JLabel jLabel1;
    private javax.swing.JLabel jLabel2;
    private javax.swing.JButton okButton;
    private javax.swing.JPasswordField passwordField;
    private javax.swing.JTextField userIDField;
    // End of variables declaration                   

}

All the login form really does is get the account ID and password from the user, try them out with Twitter's verifyLogin function and indicate success or failure.

Creating The Main Application Form

We're getting close to having a bird that tweets, but we have yet to create the main application screen CanaryView.java. It is going to look like this when we're done:

We are using tabs for the four main Twitter functions we're providing: "Recent", "Update", "Replies" and "Direct Msgs". "Recent" shows the most recent tweets from those we follow, "Update" lets us update our Twitter status (i.e. send a tweet), "Replies" shows @replies to us, and "Direct Msgs" shows direct messages to us.

The only "File" menu actions that we have are "Log In", which invokes our login dialog, and "Exit", which does pretty much what you would expect. I left the "Help / About" thing in the menu so you could play with it as you wish. I customized the application title and some other stuff in the resources for CanaryView; certainly you can modify this as well if you so desire. I also left the status bar, progress bar and timer stuff from the original Java Desktop Application framework intact so you can also tweak that.

Functionally, the form queries the Twitter servers once every five minutes for updated tweets from your pals. It caches status updates, dm's and replies in internal ArrayLists so we only ask for new stuff when we query the server (using the "sinceID" parameter which we also store). This is of course to satisfy our "good Twitter citizen" design goal, and Canary does just that quite nicely I believe. However, note that in this incarnation of Canary the caches are never cleaned out, just appended to, so if you let it run forever you're going to use up a lot of memory!

Something that may not be obvious from perusing the code is that, once we initially connect to the Twitter service, if routine status queries return errors Canary does not bitch or whine a bit, it just keeps displaying the queued tweets it has and silently keeps trying periodic queries like the saintly bird it is. There's a moral lesson in that somewhere I'm sure.

Another subtle feature of this application is the use of JEditorPanes to display the tweets' HTML. I have a love/hate relationship with JEditorPanes, but for this project they work out okay. A JEditorPane will do a decent job of displaying HTML without much accompanying overhead if you initialize it properly first. The little method initHTMLPane does this for us. And this paragraph alone is worth the price of admission, ladies and gentlemen. I have lost many of my few remaining hairs wrestling with JEditorPanes in the last few months.

Yet another thing worth pointing out is that the update screen has a character counter that is updated as you type. This is because Twitter tweets are (essentially) limited to a maximum of 140 characters. This is important enough for user friendliness that the means of counting characters and enabling and disabling buttons is relatively sophisticated, which is why the DocumentListener stuff is in there.

And speaking of "there," I suppose I should include the code for the form here as well. See the earlier caveat about copying and pasting it.

/*
 * CanaryView.java
 */

package canary;

import org.jdesktop.application.Action;
import org.jdesktop.application.ResourceMap;
import org.jdesktop.application.SingleFrameApplication;
import org.jdesktop.application.FrameView;
import org.jdesktop.application.TaskMonitor;
import java.awt.event.ActionEvent;
import java.awt.event.ActionListener;
import java.util.ArrayList;
import java.util.List;
import java.util.prefs.Preferences;
import javax.swing.Timer;
import javax.swing.Icon;
import javax.swing.JDialog;
import javax.swing.JEditorPane;
import javax.swing.JFrame;
import javax.swing.JOptionPane;
import javax.swing.event.DocumentEvent;
import javax.swing.event.DocumentListener;
import org.netbeans.saas.RestResponse;
import twitter.whatareyoudoingservice.twitterresponse.DirectMessageType;
import twitter.whatareyoudoingservice.twitterresponse.StatusType;

/**
 * The application's main frame.
 */
public class CanaryView extends FrameView {
    private final Preferences pref;
    private static final boolean VERBOSE = true;
    private static final String UPDATINGMSG = "<html><body>(updating...)</body></html>";
    private static final String CONNECTMSG = "<html><body>(unable to connect to Twitter)</body></html>";
    private static final int MAXLIST = 10;
    private TwitterUtils twitter;
    private List<StatusType> recentList;
    private List<StatusType> repliesList;
    private List<DirectMessageType> msgsList;
    private int queryInterval;
    private Timer queryTimer;

    private final Timer messageTimer;
    private final Timer busyIconTimer;
    private final Icon idleIcon;
    private final Icon[] busyIcons = new Icon[15];
    private int busyIconIndex = 0;

    private JDialog aboutBox;
    private LoginDialog loginDialog;
    private final JFrame mainFrame;

    public CanaryView(SingleFrameApplication app) {
        super(app);
        
        twitter = new TwitterUtils();
        pref = Preferences.userNodeForPackage(CanaryView.class);
        initComponents();

        // status bar initialization - message timeout, idle icon and busy animation, etc
        ResourceMap resourceMap = getResourceMap();
        int messageTimeout = resourceMap.getInteger("StatusBar.messageTimeout");
        messageTimer = new Timer(messageTimeout, new ActionListener() {
            public void actionPerformed(ActionEvent e) {
                statusMessageLabel.setText("");
            }
        });
        messageTimer.setRepeats(false);
        int busyAnimationRate = resourceMap.getInteger("StatusBar.busyAnimationRate");
        for (int i = 0; i < busyIcons.length; i++) {
            busyIcons[i] = resourceMap.getIcon("StatusBar.busyIcons[" + i + "]");
        }
        busyIconTimer = new Timer(busyAnimationRate, new ActionListener() {
            public void actionPerformed(ActionEvent e) {
                busyIconIndex = (busyIconIndex + 1) % busyIcons.length;
                statusAnimationLabel.setIcon(busyIcons[busyIconIndex]);
            }
        });
        idleIcon = resourceMap.getIcon("StatusBar.idleIcon");
        statusAnimationLabel.setIcon(idleIcon);
        progressBar.setVisible(false);

        // connecting action tasks to status bar via TaskMonitor
        TaskMonitor taskMonitor = new TaskMonitor(getApplication().getContext());
        taskMonitor.addPropertyChangeListener(new java.beans.PropertyChangeListener() {
            public void propertyChange(java.beans.PropertyChangeEvent evt) {
                String propertyName = evt.getPropertyName();
                if ("started".equals(propertyName)) {
                    if (!busyIconTimer.isRunning()) {
                        statusAnimationLabel.setIcon(busyIcons[0]);
                        busyIconIndex = 0;
                        busyIconTimer.start();
                    }
                    progressBar.setVisible(true);
                    progressBar.setIndeterminate(true);
                } else if ("done".equals(propertyName)) {
                    busyIconTimer.stop();
                    statusAnimationLabel.setIcon(idleIcon);
                    progressBar.setVisible(false);
                    progressBar.setValue(0);
                } else if ("message".equals(propertyName)) {
                    String text = (String)(evt.getNewValue());
                    statusMessageLabel.setText((text == null) ? "" : text);
                    messageTimer.restart();
                } else if ("progress".equals(propertyName)) {
                    int value = (Integer)(evt.getNewValue());
                    progressBar.setVisible(true);


                    progressBar.setIndeterminate(false);
                    progressBar.setValue(value);
                }
            }
        });
        
        updateField.getDocument().addDocumentListener(new FieldListener());
        
        queryInterval = pref.getInt("queryInterval", 300000);
	queryTimer = new Timer(queryInterval, new ActionListener() {
            public void actionPerformed(ActionEvent e) {
                refresh();
            }
        });

        if (VERBOSE) System.out.println("CanaryView: init");
        mainFrame = app.getMainFrame();
//        mainFrame = CanaryApp.getApplication().getMainFrame();
        if (!initialLogin()) {
            app.exit();
        }
        initHTMLPane(recentPane);
        initHTMLPane(directMsgsPane);
        initHTMLPane(repliesPane);
        recentList = new ArrayList<StatusType>(MAXLIST);
        repliesList = new ArrayList<StatusType>(MAXLIST);
        msgsList = new ArrayList<DirectMessageType>(MAXLIST);

        refresh();
    }

/***** STATUS UPDATES *****/
    
    private void showFriendsStatus() {
        List<StatusType> statusList;
        StringBuffer sBuf;
        String text;
        String startID;
        
        recentPane.setText(UPDATINGMSG);
        sBuf = new StringBuffer();
        startID = (recentList.isEmpty() ? null : recentList.get(0).getId());
        statusList = twitter.getFriendsStatus(startID);
        if (statusList == null) {
            if (startID == null) {
                // first time
                recentPane.setText(CONNECTMSG);
            }
            return;
        }
        statusList.addAll(recentList);
        recentList = statusList;
        sBuf.append("<html><body>");
        for (StatusType type : statusList) {
            sBuf.append("<p><strong>");
            sBuf.append(type.getUser().getScreenName());
            sBuf.append(": ");
            sBuf.append("</strong>");
            text = TwitterUtils.tweetToHTML(type.getText());
            sBuf.append(text);
            sBuf.append("</p>");
        }
        sBuf.append("</body></html>");
        recentPane.setText(sBuf.toString());
    }
    
    private void showReplies() {
        List<StatusType> statusList;
        StringBuffer sBuf;
        String text;
        String startID;
        
        repliesPane.setText(UPDATINGMSG);
        sBuf = new StringBuffer();
        startID = (repliesList.isEmpty() ? null : repliesList.get(0).getId());
        statusList = twitter.getReplies(startID);
        if (statusList == null) {
            if (startID == null) {
                // first time
                repliesPane.setText(CONNECTMSG);
            }
            return;
        } 
        statusList.addAll(repliesList);
        repliesList = statusList;
        sBuf.append("<html><body>");
        for (StatusType type : statusList) {
            sBuf.append("<p><strong>");
            sBuf.append(type.getUser().getScreenName());
            sBuf.append(": ");
            sBuf.append("</strong>");
            text = TwitterUtils.tweetToHTML(type.getText());
            sBuf.append(text);
            sBuf.append("</p>");
        }
        sBuf.append("</body></html>");
        repliesPane.setText(sBuf.toString());
    }
    
    private void showDirectMessages() {
        List<DirectMessageType> msgList;
        StringBuffer sBuf;
        String text;
        String startID;

        directMsgsPane.setText(UPDATINGMSG);
        sBuf = new StringBuffer();
        startID = (msgsList.isEmpty() ? null : msgsList.get(0).getId());
        msgList = twitter.getDirectMsgs(startID);
        if (msgList == null) {
            if (startID == null) {
                // first time
                directMsgsPane.setText(CONNECTMSG);
            }
            return;
        }
        msgList.addAll(msgsList);
        msgsList = msgList;
        sBuf.append("<html><body>");
        for (DirectMessageType type : msgList) {
            sBuf.append("<p><strong>");
            sBuf.append(type.getSenderScreenName());
            sBuf.append(": ");
            sBuf.append("</strong>");
            text = TwitterUtils.tweetToHTML(type.getText());
            sBuf.append(text);
            sBuf.append("</p>");
        }
        sBuf.append("</body></html>");
        directMsgsPane.setText(sBuf.toString());
    }
    
/***** HELPER FUNCTIONS *****/
    
    private void initHTMLPane(JEditorPane pane) {
        pane.setContentType("text/html;charset=UTF-8");
        pane.getEditorKit().createDefaultDocument();
        pane.setText("<html><body>(not updated)</body></html>");
    }
    
    private final class FieldListener implements DocumentListener {

        public void insertUpdate(DocumentEvent dEvt) {
            updateCharCount();
        }

        public void removeUpdate(DocumentEvent arg0) {
            updateCharCount();
        }

        public void changedUpdate(DocumentEvent arg0) {
            updateCharCount();
        }
        
        private void updateCharCount() {
            int charCount;
            
            charCount = updateField.getText().length();
            charCountLabel.setText(charCount + " of 140");
            sendButton.setEnabled((charCount <= 140) && (charCount > 0));
            clearButton.setEnabled(charCount > 0);
        }
    }

    private boolean initialLogin() {
        RestResponse result;
        String resultString;
        boolean workedOK = false;
        
        result = twitter.verifyLogin();
        if (result == null) {
            JOptionPane.showMessageDialog(mainFrame, 
                    "Unable to verify Twitter login at this time.", "Log In Error", JOptionPane.ERROR_MESSAGE);
        } else {
            if (VERBOSE) System.out.println("LoginDialog: result = " + result.getDataAsString());
            resultString = TwitterUtils.requestResponse(result);
            if (resultString != null) {
                JOptionPane.showMessageDialog(mainFrame, resultString, "Log In Error", JOptionPane.ERROR_MESSAGE);
            } else { 
                workedOK = true;
            }
        }
        return workedOK;
    }
    
/***** ACTIONS *****/
    
    @Action
    public void logIn() {
        if (loginDialog == null) {
            loginDialog = new LoginDialog(mainFrame);
            loginDialog.setLocationRelativeTo(mainFrame);
        }
        CanaryApp.getApplication().show(loginDialog);
        if (loginDialog.successfulLogin()) {
            refresh();
        }
    }
    
    @Action
    public void showAboutBox() {
        if (aboutBox == null) {
            aboutBox = new CanaryAboutBox(mainFrame);
            aboutBox.setLocationRelativeTo(mainFrame);
        }
        CanaryApp.getApplication().show(aboutBox);
    }

    @Action
    public void refresh() {
        if (VERBOSE) System.out.println("CanaryView: refresh");
        showFriendsStatus();
        showReplies();
        showDirectMessages();
    }
    
    @Action
    public void clearAction() {
        updateField.setText(null);        
    }
    
    @Action
    public void sendUpdate() {
        RestResponse result;
        String resultString;

        result = twitter.updateStatus(updateField.getText());
        if (result == null) {
            JOptionPane.showMessageDialog(mainFrame, 
                    "Unable to update your Twitter status at this time.","Status Update Error", 
                    JOptionPane.ERROR_MESSAGE);
            return;
        }
        resultString = TwitterUtils.requestResponse(result);
        if (resultString != null) {
            JOptionPane.showMessageDialog(mainFrame, resultString, "Status Update Error", 
                    JOptionPane.ERROR_MESSAGE);
            return;
        }
        updateField.setText(null);   
    }

    // Variables declaration - do not modify//GEN-BEGIN:variables
    private javax.swing.JLabel charCountLabel;
    private javax.swing.JButton clearButton;
    private javax.swing.JEditorPane directMsgsPane;
    private javax.swing.JPanel jPanel1;
    private javax.swing.JPanel jPanel2;
    private javax.swing.JPanel jPanel3;
    private javax.swing.JPanel jPanel4;
    private javax.swing.JScrollPane jScrollPane1;
    private javax.swing.JScrollPane jScrollPane2;
    private javax.swing.JScrollPane jScrollPane3;
    private javax.swing.JScrollPane jScrollPane4;
    private javax.swing.JTabbedPane jTabbedPane1;
    private javax.swing.JMenuItem loginMenuItem;
    private javax.swing.JPanel mainPanel;
    private javax.swing.JMenuBar menuBar;
    private javax.swing.JProgressBar progressBar;
    private javax.swing.JEditorPane recentPane;
    private javax.swing.JEditorPane repliesPane;
    private javax.swing.JButton sendButton;
    private javax.swing.JLabel statusAnimationLabel;
    private javax.swing.JLabel statusMessageLabel;
    private javax.swing.JPanel statusPanel;
    private javax.swing.JTextArea updateField;
    // End of variables declaration//GEN-END:variables
}

So Let's See If It Flies!

At last it's time to see if our Canary can fly. Hit the "Run" button on the IDE task bar (assuming that Canary is set as the main project) and let 'er rip. Canary should compile without errors and give you a small form that looks like this, once you've entered your account and password:

Woohoo! It works! (Like it worked for me the first time. As if.) Let it run on your PC and you can send and receive Twitter tweets to your heart's content without starting your bloated web browser every time you think your buddy might have finally left the grocery store and actually be doing something interesting for a change.

If you want to get fancy, create a starter icon in your OS that invokes Canary (probably "java -jar [wherever your Canary jar is]", per your compilation) and stick it onto your desktop or task bar. Congratulations. And if it doesn't work, please let me know. I am unable to promise any support for this project on an individual basis but if I screwed something up I'd like to know about it.

What We've Done

If you've gotten this far, you've done something to be proud of -- you've created a fun, useful and very sophisticated yet reasonably lightweight application without using exotic technology beyond POJOs (Plain Old Java Objects). Of course you had a lot of help from the frabjous NetBeans platform and, hopefully, yours truly. But still. The Canary is yours to do with what you will, so go crazy. And don't forget that other acronym, WORA: write once, run anywhere. Though I haven't spent the time to test this incarnation of the project, Canary should run flawlessly and seamlessly on Unix/Linux, Windows and even (some) Mac platforms. We like WORA. WORA good.

Going Further

There are lots of additions, changes and enhancements that can be made to Canary; here are some that I've thought of:

Change AboutBox to reflect Canary's coolicity
Actually usse the busy icons, status bar, etc. from the stock desktop application framework or get rid of the code
Create secure account ID and password storage
Create functioning tweet hyperlinks (the hyperlinks in the EditorPanes don't actually work, and making them do so is beyond the scope of this article)
The Direct Msgs tab should have its own way of sending direct messages as well as displaying them (drop down friend box, etc.)
Add fins and an automatic headlight dimmer to Canary (i.e. make it prettier; I was sorely tempted to do this but managed to restrain myself just in time so I can leave it for you to do) (but the orignal one I did for my clients has a purple gradient background...)

Source Code and Jar

Source code:

Canary_Source.tar.gz Canary_Source.zip

Jar file (Java executable):

Canary_Dist.zip

A Final Note

I am currently not planning on doing a follow-up article on Canary revisions and enhancements because I can't afford the time that these things take (LOTS!) but I may not be able to help myself. Also, see "Donate" button.

I hope you found this article entertaining, enlightening and useful. And if you have comments, I would love to hear from you. Namaste.

-- Hulles

Son Of GeeWhiz Prolog: Olio

nospam@example.com (Hulles) — Thu, 07 Aug 2008 21:10:57 +0200

This article describes an enhancement to GeeWhiz Prolog, a project to implement the Prolog language in the NetBeans IDE. See the GeeWhiz Prolog home page for more information.

What We'll Be Doing

In this installment of Son of GeeWhiz Prolog there really won't be much tutorial content. I'll do my best, but to be honest it's been long enough since I made the changes described here that I haven't been able to reassemble my notes properly, and I misplaced my screenshots. However I thought it would be better to post the new version of the source and NBM on the GeeWhiz Prolog home page rather than wait any longer. So here you go. I am not including separate source code in this article, so you'll need to download the source on the Home Page to find the changes. Dang, sorry.

Moving the Satellite Window to the Navigator

Probably the most obvious change is that the satellite view of the Prolog diagram has been transformed from a standalone JFrame window into a TopComponent that nestles into the Navigator window area. This is more convenient as it stays out of the way but remains accessible as you scroll around the larger diagram. It also makes us a "better NetBeans citizen": standalone JFrames bad, TopComponents good. We're leaving the popup code JFrame windows alone however, so I guess we're not that good a NetBeans citizen.

Another change is that we got rid of VPrologAction.java, which was the action living in the "Window" menu that opened up the demo/dummy diagram. Along with that, we eliminated the code in VPrologGraphScene to create the dummy diagram, and we added code to VPrologTopComponent to open and close the satellite navigator component. The final change regarding the satellite window is that we changed the "show / hide satellite" action in the right-click context menu in the main diagram. It is now just "show satellite", since you can close the satellite window like any other window whenever you want.

Minor Stuff

In the process of cleaning up GeeWhiz, it seemed to make more sense for the popup editor code to live in SceneUtils, so there it now resides. I also changed the phrase "1 instances" to read "1 instance" in the case where there is only 1 instance. Hey, it is too rocket science.

Problems, Setbacks and Failures

For Son 2 (this article) I wanted to experiment with FreeMarker, which is a scripting language that one can use to insert text into a template. This can automatically insert licensing information or whatever else you want into our trusty Prolog program template. Unfortunately I could not get it to work reliably. In the newest version of the source code I left the FreeMarker code in, but every time I tried to execute it outside of the top level of the source code I got a cryptic error:

WARNING [org.openide.WizardDescriptor] java.lang.StringIndexOutOfBoundsException: String index out of range: -1 at java.lang.String.substring(String.java:1938) at java.lang.String.substring(String.java:1905) ...

Ouch. As I mentioned this only happened when the template was not in the top level of the source, for some reason. I puzzled over it for a while then gave it up as a bad job. But I thought I'd pass it along anyway. I guess GeeWhiz Prolog was not destined to be the kind of application that has source code licenses....

Another experiment I thought I would try was to use the capability of the Visual Library to directly associate objects with scene nodes. This would allow us to eliminate the Prolog object lookup we need to do to translate from node to Prolog clause. Hmmm, I thought, simpler is better, it sounds good. However, I hammered away at associating any kind of object with the nodes in our diagram scene and kept getting assertion errors in the Visual Library that didn't tell me what the hell was wrong. I finally traced the VL source code and found out that in a GraphScene there is already an object associated with a node that lurks behind the scenes. At least I think that's what's happening; it looks like a String is hooked up to a node as an object, and you can only have one object per node. Consequently, we can't hook up our Prolog clauses to nodes that way unless we quit using GraphScene, which is a poor trade. So the list association we started with remains intact, bloody but unbowed. As a footnote, I've used the Visual Library a great deal since the experiment I described above, and every time I get an accursed assertion error from VL I know that it's a problem with trying to add multiple objects to a node. That would probably be a good thing to fix in the next release of the Visual Library. And it's a good thing to know if you're working with it.

Almost forgot - another problem I encountered has nothing directly to do with NetBeans: I have been trying to get some HTML windows to pop up from this blog platform that don't have the sidebars etc. so I can better display a few movies I made using Wink that demonstrate the use of GeeWhiz Prolog. I haven't been able accomplish that so I am posting the Flash videos just as links on the GeeWhiz Prolog home page. Check them out. I created the movies so that people who are interested in Prolog but who don't care to know anything about NetBeans can see what the program does without going through the process of downloading NetBeans and learning the IDE. I'm nice like that.

Going Further

Well, sort of a lame Son of GeeWhiz Prolog, I know, but I didn't want to post the updated source code and not provide an explanation to go with it. I don't have plans to post anything new here for a while as I am in the middle of a large project utilizing NetBeans, unless.... Well, we'll see.

Files From This Entry

(see the newly posted source code zip files and NBM on the GeeWhiz Prolog home page.)

Son Of GeeWhiz Prolog: Improving The Diagram

nospam@example.com (Hulles) — Tue, 27 May 2008 00:33:51 +0200

This article describes an enhancement to GeeWhiz Prolog, a project to implement the Prolog language in the NetBeans IDE. See the GeeWhiz Prolog home page for more information.

What We'll Be Doing

In this add-on to our GeeWhiz Prolog project, we're going to add some new features and Geewhizability to our predicate modeler. Big thanks go to David Kaspar who provided the Visual Library examples from which much of this material is ~~stolen~~ taken. The examples are located in the "main/contrib" section of the NetBeans Mercurial repository (although I haven't updated my own library yet to reflect this). You can find them at this link: http://hg.netbeans.org/main/contrib/file/ under "visual.examples".

Adding An Export Function

The first change we're going to make to our nifty Prolog predicate diagrammer is that we're going to add a means by which we can export our diagram to a Portable Network Graphics (PNG) file. Once we have a PNG file, we can print it, email it to Aunt Margaret in Philly, or (hypothetically) stick it on our GeeWhiz Prolog home page. So let's get started.

First, create a new Java class in your project called "SceneExport". Replace the empty class with this:

public class SceneExport { public void exportScene(VMDGraphScene scene) { JComponent view; Dimension dim; BufferedImage bufImage; Graphics2D graphics; File file; view = scene.getView(); dim = view.getSize(); bufImage = new BufferedImage (dim.width, dim.height, BufferedImage.TYPE_4BYTE_ABGR); graphics = bufImage.createGraphics (); scene.paint (graphics); graphics.dispose (); file = getPNGSaveFile(view); if (file != null) { diagramToPNG(file, bufImage); } } private File getPNGSaveFile (JComponent view) { JFileChooser chooser; File file; //TODO: save selected directory as default for next time chooser = new JFileChooser(); chooser.setDialogTitle("Export Scene As ..."); chooser.setDialogType(JFileChooser.SAVE_DIALOG); chooser.setMultiSelectionEnabled(false); chooser.setFileSelectionMode(JFileChooser.FILES_ONLY); chooser.setFileFilter(new FileFilter() { public boolean accept(File file) { if (file.isDirectory()) return true; return file.getName().toLowerCase().endsWith(".png"); } public String getDescription () { return "Portable Network Graphics (.png)"; } }); if (chooser.showSaveDialog (view) != JFileChooser.APPROVE_OPTION) { return null; } file = chooser.getSelectedFile (); if (! file.getName ().toLowerCase ().endsWith (".png")) file = new File (file.getParentFile (), file.getName () + ".png"); if (file.exists ()) { DialogDescriptor descriptor = new DialogDescriptor ( "File (" + file.getAbsolutePath () + ") already exists. Do you want to overwrite it?", "File Exists", true, DialogDescriptor.YES_NO_OPTION, DialogDescriptor.NO_OPTION, null); DialogDisplayer.getDefault().createDialog(descriptor).setVisible(true); if (descriptor.getValue() != DialogDescriptor.YES_OPTION) { return null; } } return file; } private void diagramToPNG(File file, BufferedImage bufImage) { try { ImageIO.write (bufImage, "png", file); // NOI18N } catch (IOException e) { ErrorManager.getDefault ().notify (e); } } }

What the above code does is copy the predicate diagram graphics to a BufferedImage then save the image to a PNG file. Pretty straightforward, and taken from Visual Library example code that I haven't been able to find again. So fix imports, save and close the SceneExport class then create a new Java class called "SceneUtils". Replace the empty class with this code:

public class SceneUtils { private static final String EXPORT_SCENE = "export"; private static final String ACTION_MOVE = "move"; private static final String REMOVE_LABEL = "remove"; private static final String REPLACE_LABEL = "replace"; private LabelWidget label; private Scene scene = null; private boolean isVMD; public SceneUtils(Scene scene) { this.scene = scene; isVMD = scene instanceof VMDGraphScene; } public void addContextMenu() { WidgetAction popup; if (scene == null) { return; } label = new LabelWidget (scene, "Right-click to open popup menu."); label.setPreferredLocation (new Point (100, 100)); scene.addChild (label); popup = ActionFactory.createPopupMenuAction (new MyPopupProvider ()); scene.getActions ().addAction (popup); // leave popup menu up (?) scene.createActions (ACTION_MOVE).addAction (popup); label.createActions (ACTION_MOVE).addAction (ActionFactory. createMoveAction ()); } private void exportScene() { SceneExport exporter; if (isVMD) { // TODO: thread exporter = new SceneExport(); exporter.exportScene((VMDGraphScene) scene); } } private void addMoveAction() { scene.setActiveTool(ACTION_MOVE); } private void removeLabel() { // removes it from the scene, doesn't delete it this.label.removeFromParent(); } private void replaceLabel() { if (label.getParentWidget() == null) { scene.addChild(label); scene.validate(); } } private final class MyPopupProvider implements PopupMenuProvider, ActionListener { private JPopupMenu menu; public MyPopupProvider () { menu = new JPopupMenu ("Popup menu"); JMenuItem item; if (isVMD) { item = new JMenuItem ("Export scene to PNG..."); item.setActionCommand (EXPORT_SCENE); item.addActionListener (this); menu.add (item); } item = new JMenuItem ("Move the label"); item.setActionCommand (ACTION_MOVE); item.addActionListener (this); menu.add (item); item = new JMenuItem ("Delete the label"); item.setActionCommand (REMOVE_LABEL); item.addActionListener (this); menu.add (item); item = new JMenuItem ("Replace the label"); item.setActionCommand (REPLACE_LABEL); item.addActionListener (this); menu.add (item); } public JPopupMenu getPopupMenu (Widget widget, Point localLocation) { return menu; } public void actionPerformed (ActionEvent e) { String cmd; cmd = e.getActionCommand (); if (cmd.equals(EXPORT_SCENE)) { exportScene(); } else if (cmd.equals(ACTION_MOVE)) { addMoveAction(); } else if (cmd.equals(REMOVE_LABEL)) { removeLabel(); } else if (cmd.equals(REPLACE_LABEL)) { replaceLabel(); } } } }

In SceneUtils we're creating a context menu that pops up when you right-click on our lovely model diagram. In this incarnation it was written to cope with any kind of Scene even though the export function only handles VMDGraphScene. The menu includes some choices that are of limited utility in practice but serve to demonstrate the capability of the right-click popup. We also introduce the LabelWidget, which we haven't seen before. So fix imports, save and close the SceneUtils file.

Finally, we're going to change the VPrologGraphScene class to use our SceneUtils class. At the beginning of each constructor, add the following code:

SceneUtils sceneUtils; sceneUtils = new SceneUtils(this); sceneUtils.addContextMenu();

At the very end of each constructor, add this line:

        layoutScene();

I found the "layoutScene" method by accident when I was working through some of David Kaspar's Visual Library examples. It automatically cleans up our diagram! Evidentally there is a more robust orthogonal link router in the works, but for our purposes this one works just fine and eliminates much of the haphazardness of the random way we were placing nodes before. Woohoo!

Save and close the file. Now we're ready to test the beast. Clean and build the project, then install it to the target IDE. (You missed doing that since completing the original GeeWhiz project, didn't you?) Open your Algorithms project and wait for the indexing to stop. Now we're ready to check out our new popup menu. Open the sieve.pro file (or any other Prolog file) and wait for the Navigator to fill in the statements and for the syntax to color. Then go to the menu and click "View" "Show Prolog Diagram" to bring up the predicate model of our program. ("Gee whiz!") Right-click on the diagram to get our popup menu.

First, try moving, deleting and re-adding the label. Then, when you're tired of playing with that, try exporting the diagram to a PNG file. Cool, eh? If you monkey around with it enough, however, you'll notice that if you zoom and pan the diagram prior to exporting the PNG the export doesn't work exactly right. For now my solution for this glitch is: don't zoom or pan the diagram prior to exporting the PNG. Someday I'll look into fixing this; I think that maybe I need to get the dimensions from something other than the view graphics. But we have other things to do now, so let's leave it alone.

And by the way, don't forget to gasp with delight at the way layoutScene() fixes up our diagram when it is first displayed! When you're done testing and fooling around you can close the target IDE.

Adding Editor Windows To Nodes

The next feature we're going to add is a window containing the text Prolog source code for the predicate that opens up when we double-click on a predicate node. You wondered why we built the text into our PrologClause class, didn't you? This is why. First, create a new JFrame Java class called "NodeContents" by right-clicking on the package and selecting "New" "JFrame Form..." This is going to be the window in which we display our source code. In the "Design" view, add a scroll pane that snaps to the preferred borders of the frame and then add a text area that fills the scroll pane. Rename the text area to "textArea", then in Properties give it a descriptive tool tip, unclick the "editable" property and change the tab size to 4. In the JFrame properties, change the defaultCloseOperation to "HIDE". Switch to "Source" and delete the Main method. Right below the constructor, insert the following code:

public void setText(String text) { textArea.setText(text); } public void changeTitle(String title) { this.setTitle(title); }

Save and close the file. Now open VPrologGraphScene and replace the whole VPrologGraphScene class with this:

public class VPrologGraphScene extends VMDGraphScene { private static final Image IMAGE_NODE = Utilities. loadImage ("org/hulles/geewhiz/node.png"); // NOI18N private static final Image IMAGE_EXTERNAL = Utilities. loadImage ("org/hulles/geewhiz/external.png"); // NOI18N private static final Image IMAGE_ITEM = Utilities. loadImage ("org/hulles/geewhiz/item.gif"); // NOI18N private static int pinID = 1; private static int edgeID = 1; private List<PrologClause> clauses; /** Creates a new instance of VPrologGraphScene */ public VPrologGraphScene() { // demo SceneUtils sceneUtils; sceneUtils = new SceneUtils(this); sceneUtils.addContextMenu(); createNode (this, 100, 100, IMAGE_NODE, "Clause1", "Internal", null); createPin (this, "Clause1", "start", IMAGE_ITEM, "Start", "Element"); createNode (this, 400, 100, IMAGE_NODE, "Clause2", "External", Arrays.asList (IMAGE_EXTERNAL)); createPin (this, "Clause2", "ok", IMAGE_ITEM, "okCommand1", "Command"); createEdge (this, "start", "Clause2"); createEdge (this, "ok", "Clause1"); layoutScene(); } public VPrologGraphScene(DataObject dObj) { PrologAST pTree; List<PrologClause> embedded; String nodeID; Integer instances; String newPinID; PrologClause existingClause; String eNodeID; List<String> eNodes; SceneUtils sceneUtils; VMDNodeWidget node; sceneUtils = new SceneUtils(this); sceneUtils.addContextMenu(); pTree = new PrologAST(dObj); clauses = pTree.getClauses(); // create all primary nodes first so they're available // to create edges to.... for (PrologClause clause : clauses) { instances = clause.getInstanceCount(); nodeID = makeNodeID(clause); node = createNode(this, randXPoint(), randYPoint(), IMAGE_NODE, nodeID, instances.toString() + " instances", null); addEditor(node, clause); } // now create pins and edges eNodes = new ArrayList<String>(); for (PrologClause clause : clauses) { nodeID = makeNodeID(clause); embedded = clause.getBody(); for (PrologClause e : embedded) { eNodeID = makeNodeID(e); newPinID = "pin" + VPrologGraphScene.pinID++; createPin(this, nodeID, newPinID, IMAGE_ITEM, eNodeID, "Embedded"); existingClause = PrologClause.findClause(clauses, e); if (existingClause == null) { if (!eNodes.contains(eNodeID)) { // externally defined (?) createNode(this, randXPoint(), randYPoint(), IMAGE_NODE, eNodeID, "External", Arrays.asList (IMAGE_EXTERNAL)); eNodes.add(eNodeID); } } createEdge(this, newPinID, eNodeID); } } layoutScene(); } private String makeNodeID(PrologClause clause) { String name; Integer arity; name = clause.getName(); arity = clause.getArity(); return name + "/" + arity.toString(); } private int randXPoint() { return (int) (Math.random() * 800); } private int randYPoint() { return (int) (Math.random() * 800); } private VMDNodeWidget createNode (VMDGraphScene scene, int x, int y, Image image, String name, String type, List<Image> glyphs) { VMDNodeWidget widget; widget = (VMDNodeWidget) scene.addNode (name); widget.setPreferredLocation (new Point (x, y)); widget.setNodeProperties (image, name, type, glyphs); scene.addPin (name, name + VMDGraphScene.PIN_ID_DEFAULT_SUFFIX); return widget; } private void createPin (VMDGraphScene scene, String nodeID, String pinID, Image image, String name, String type) { VMDPinWidget pinWidget; pinWidget = (VMDPinWidget) scene.addPin (nodeID, pinID); pinWidget.setProperties (name, null); } private void createEdge (VMDGraphScene scene, String sourcePinID, String targetNodeID) { String localEdgeId; localEdgeId = "edge" + VPrologGraphScene.edgeID ++; scene.addEdge (localEdgeId); scene.setEdgeSource (localEdgeId, sourcePinID); scene.setEdgeTarget (localEdgeId, targetNodeID + VMDGraphScene.PIN_ID_DEFAULT_SUFFIX); } private void addEditor(VMDNodeWidget node, PrologClause clause) { NodeEditor editor; WidgetAction nodeAction; editor = new NodeEditor(clause); nodeAction = ActionFactory.createEditAction(editor); node.getActions().addAction(nodeAction); } public void newLayout() { layoutScene(); } private class NodeEditor implements EditProvider { private final PrologClause clause; private final String popupTitle; private final String popupText; private NodeContents popup; public NodeEditor(PrologClause clause) { this.clause = clause; this.popup = null; popupTitle = makeNodeID(clause); popupText = clause.getText(); } public void edit(Widget node) { // assumes read-only text VMDNodeWidget myNode; myNode = (VMDNodeWidget) node; // lazy edit window construction if (popup == null) { java.awt.EventQueue.invokeLater(new Runnable() { public void run() { popup = new NodeContents(); popup.changeTitle(popupTitle); popup.setText(popupText); popup.setVisible(true); } }); } else { popup.setVisible(true); } } } }

What we're doing here is, for every defined node (as opposed to external node) that we create, we're adding an EditAction that creates a NodeContents window when the node is double-clicked. We hold off actually creating the NodeContents window until the node is double-clicked so we can be a good NetBeans neighbor. Also, notice that instead of disposing of the window when we close it we just hide it so we can set it visible again the next time it's clicked.

Adding A Satellite Window

Before we test the editor functionality we're going to go ahead and make another window that shows the entire diagram in miniature, called in Visual Library terms a satellite view. We're going to show it and hide it via our context menu. So create another new JFrame called NodeSatelliteView.

In "Design" mode add a panel to the frame that takes up the whole frame and make it "BorderLayout". Change the name from jPanel1 to satellitePanel and give it a tooltip "Prolog diagram satellite view". Change the JFrame defaultCloseOperation to "HIDE" and the title to "Prolog Satellite View". Switch to "Source" mode, remove the Main method, and add this method below the constructor.

public void addView(JComponent view) { satellitePanel.removeAll(); satellitePanel.add(view); }

Save and close the file. Now open "SceneUtils" and replace the entire class with this.

public class SceneUtils { private static final String EXPORT_SCENE = "export"; // NOI18N private static final String LAYOUT_SCENE = "layout"; // NOI18N private static final String PRINT_SCENE = "print"; // NOI18N private static final String SATELLITE_VIEW = "satellite"; // NOI18N private VPrologGraphScene scene = null; private NodeSatelliteView viewer; public SceneUtils(VPrologGraphScene scene) { this.scene = scene; } public void addContextMenu() { WidgetAction popup; if (scene == null) { return; } popup = ActionFactory.createPopupMenuAction (new MyPopupProvider ()); scene.getActions ().addAction (popup); // leave popup menu up (?) scene.createActions (LAYOUT_SCENE).addAction (popup); } private void exportScene() { SceneExport exporter; // TODO: thread exporter = new SceneExport(); exporter.exportScene((VMDGraphScene) scene); } private void reLayoutScene() { scene.newLayout(); } private void printScene() { // not yet implemented } private void makeSatelliteView() { if (viewer == null) { java.awt.EventQueue.invokeLater(new Runnable() { public void run() { JComponent view; viewer = new NodeSatelliteView(); view = scene.createSatelliteView(); viewer.addView(view); viewer.setVisible(true); } }); } else { if (viewer.isVisible()) { viewer.setVisible(false); } else { viewer.setVisible(true); } } } private final class MyPopupProvider implements PopupMenuProvider, ActionListener { private JPopupMenu menu; public MyPopupProvider () { menu = new JPopupMenu ("Popup menu"); JMenuItem item; item = new JMenuItem ("Print scene..."); item.setActionCommand (PRINT_SCENE); item.addActionListener (this); menu.add (item); item = new JMenuItem ("Export scene to PNG..."); item.setActionCommand (EXPORT_SCENE); item.addActionListener (this); menu.add (item); item = new JMenuItem ("Redo scene layout"); item.setActionCommand (LAYOUT_SCENE); item.addActionListener (this); menu.add (item); item = new JMenuItem ("Show / hide satellite view"); item.setActionCommand (SATELLITE_VIEW); item.addActionListener (this); menu.add (item); } public JPopupMenu getPopupMenu (Widget widget, Point localLocation) { return menu; } public void actionPerformed (ActionEvent e) { String cmd; cmd = e.getActionCommand (); if (cmd.equals(EXPORT_SCENE)) { exportScene(); } else if (cmd.equals(PRINT_SCENE)) { printScene(); } else if (cmd.equals(LAYOUT_SCENE)) { reLayoutScene(); } else if (cmd.equals(SATELLITE_VIEW)) { makeSatelliteView(); } } } }

Notice that we got rid of the label and label actions and tailored the class to be specific to our Prolog needs instead of generic. We added an empty printing function, a layout function, and a satellite view function to our context menu and implemented the satellite view within the class. Fix imports, save and close the file. Now we're ready to test the work we've done. You'll like this.

Testing The New Diagram

Clean and build the main project, then install to the target IDE. Open the "Algorithms" project and open "sieve.pro". When the Navigator comes up, start up the modeler ("View" "Show Prolog Diagram") and double-click on a node. If the node is defined and not external then a window should open with the text of all the clauses that make up the predicate.

Notice that you can open more than one predicate window at a time but only one window per node, which makes sense within the context of the diagram.

Now right-click on the diagram to bring up our context menu.

Move a node or two then try out the "Redo layout" function. Hold your breath, then try "Show / hide satellite view".

Move the cursor around on the satellite view and watch what happens to your underlying diagram. Gee whiz! Pretty awesome, right? To close the satellite view you can click "Show / hide..." again in the context menu or just close the window. As you might suspect, the satellite view is not very useful with small diagrams like the one sieve.pro generates, but with a larger diagram like that in the screen shot it can be very useful indeed. Plus, it's just plain fun to have it around.

Going Further

One of the funky things about what we accomplished in this entry is that the screens for the node text and the screen for the satellite window are all JFrames independent of the diagram TopComponent. If you close the diagram, the frames stick around anyway. While you could possibly make a case that the little text windows are useful independently of the diagram, at least the satellite window should be dependent on the TopComponent and go away when it goes away. It is not useful without the diagram. So a reasonable next step would be to make the "pop up" screens for node text and the satellite window JDialogs or close them when the TopComponent goes away.

Now that we have all these new features on our diagram, what else could we do? The first thing that comes to mind is to allow the user to edit the code in the popup node window and have the changes reflected in the editor window source code. This would take some careful design because of the way multiple clauses make up a predicate, but it could certainly be done using techniques we've already looked at. We could disembowel the PrologAST class and store line and column numbers in PrologClause, then use the same way we pop into the source code from the output window to go into the editor and change the text. But the usefulness of editing directly in the popup window is pretty questionable, at least for Prolog programming, so we won't go that route. I won't, anyway, but you certainly can...

An even more interesting (to me) idea is to use the stuff we learned in GeeWhiz to write a whole new language interface. It would be based on Java but instead of writing code you would just manipulate nodes and edges then compile the diagram! Theoretically a person would not even have to know Java to "program" with this new language. I know, I know, it sounds like UML but it would be way cooler. Actually, this is something I've always wanted to develop, so look for "Project PipeDreams" coming your way soon....

Files From This Entry

GeeWhiz Prolog - Part Eight - Creating An NBM

nospam@example.com (Hulles) — Fri, 23 May 2008 15:18:12 +0200

This is Part Eight, the ninth and final part of a series of entries describing an implementation of the Prolog language in the NetBeans IDE.

Part Zero, "About The Project," is here.
Part One, "Before We Start," is here.
Part Two, "Creating A File Type," is here.
Part Three, "Adding Language Support," is here.
Part Four, "A Visual Prolog Modeler" is here.
Part Five, "Adding The Compiler" is here.
Part Six, "Creating Prolog Projects" is here.
Part Seven, "Adding An Option Panel" is here.

What We'll Be Doing

Well, we've come a long way. Our NetBeans-embedded Prolog IDE has grown like Topsy (whoever Topsy is) and now threatens to take over NetBeans entirely and make everyone program in Prolog instead of Java. Okay, maybe not, but it has come a long way as I said. We will look at what we've accomplished in a post mortem in a little bit, but right now let's create a NetBeans plug-in module (NBM) from GeeWhiz Prolog and install the module into our development IDE at last.

Creating The NBM

As I'm sure you've noticed, one of the options on the GeeWhiz project context menu in NetBeans has always been "Create NBM". Go ahead and clean and build GeeWhiz, right-click on the project and select "Create NBM" now.

After some whirring and clanking (note to self: backup Aspen files!) the IDE settles down again and you've created the NBM file. Unless you have the output window open you might not even notice that anything happened as there is no user interaction for this process.

What we've done is generate a nifty little zip file called (in my case) "org-hulles-geewhiz.nbm" in the build folder of our project.

At this point, you should save the NBM file to another directory. I realized to my chagrin while writing this that the "clean" process in cleaning and building your project wipes out the build directory, including the NBM file. It's easy enough to regenerate, as we just saw, but still.... One wants to be sure the NBM file one thinks one has matches the file one thought one had, doesn't one? Yes one does, by golly.

I'm not sure you noticed in the above screenshot, but I had the properties for the NBM file open so you could see what I saw the first time I went through this process. "Hmm," says I to myself. "The size is a little larger than I thought it would be. And I guess the NetBeans folks forgot to put the 'kB' on the size property. It's still too large to host as a download, though." Then I went and looked at the file in the folder just to make sure and it's 47kB! Dang, that's like buying a case of beer for a dollar, it just doesn't happen that often these days. So it's a little file, is my point, and I can stick it on my blog site as a download without a further thought. Hell, I can even email it as an attachment to my Aunt Margaret in Philly who still has dial-up. (Not sure she has NetBeans, though....)

So now what do we do with our brand new (and shrimpy little) NBM file? For one thing, if we wanted to we could make it available to the whole world via the NetBeans Plug-In Download Center (or whatever it's called) but that's a bit outside the scope of this project and besides, it's not ready for implementation yet. But we can use it to finally install GeeWhiz Prolog in our development IDE if we want to. So let's do that.

Installing The NBM In Your IDE

There is probably a more dignified way to install a local NBM into your IDE, but the way I found works pretty well so we'll use that. In the main menu of your development IDE click "Tools", then "Plugins". Once the Plugins manager has started, select the Downloads tab. Click the "Add Plugins..." button and navigate to your NBM file and select it.

Now your new module looks all shiny and ready to go, doesn't it? You can change the information that shows up on the right by right-clicking the GeeWhiz project and selecting "Properties" and filling out the "Display" and "Packaging" tabs in the Properties window. Then of course you have to recreate your NBM file. Once you're ready to bite the bullet, select "GeeWhiz Prolog" then click the "Install" button.

On the first screen there isn't much to do but sit and admire the professional look of your work. When you're ready, click the "Next" button.

On the next screen, unless you created a GeeWhiz license when I wasn't looking, you can just go ahead and click "Install". Ignore the "not digitally signed" messages you will generate unless you also signed it when you created the license, you rascal.

Eventually the IDE will come back and tell you the module is installed. To check it, select "Tools" "Module Manager" from the main menu and there GeeWhiz Prolog is, under "Language Support".

Gee whiz! Ain't it great? Check it out in your IDE; all the functions we tested in the target IDE should be there. You might consider copying or moving the Algorithms project from the target project directory to your real project directory, just to have test fodder available.

Guess What - We're Done!

That wraps up our adventures with GeeWhiz Prolog, at least for now. I am in the process of creating a home page for GeeWhiz Prolog on my blog that you can check occasionally if you want. I will post the NBM there, plus a complete set of source files, plus a PDF of all the GeeWhiz blog entries for your convenience in downloading and reading offline. Any addenda and errata (as if) will be posted there as well. I already thought of one thing I forgot to mention, and that's that you can zoom in and out (ctrl + mouse button) and pan (hold middle mouse button) on the modeling diagrams we created earlier.

As a special bonus for acting now, you will also receive an additional Java class in the complete source file archive called SceneExport.java that may or may not create a .PNG file from the modeling diagram. I'm still working on it and haven't incorporated it into the diagram yet, but I'm sure I'll write about it when I do. It's based on a slightly cryptic code segment in the Visual Library API and... Oh, just wait and read the article when I write it.

It's hard to end this series. I feel like we just scratched the surface with GeeWhiz Prolog, but hey, the surface itched. So... ciao, it's been fun. I hope you found this series useful, informative and occasionally entertaining. -- Hulles

GeeWhiz Prolog Feature Summary

Incorporated as an integral part of the NetBeans IDE
Has a WYSIWYG source code editor
Provides Prolog syntax checking and highlighting
Works with the sidebar statement navigator
Generates a visual and interactive Prolog predicate model that personally rocks my world
Supports in-line Prolog source code compilation with error lines linked back to source
Is O/S- and compiler-independent
Is installable as a plug-in module to the NetBeans IDE
Is free
The source code is easily modifiable since you build the damn thing yourself
Did I mention it's free?

Going Further - My GeeWhiz Notes

Fixes And Improvements To Current Features

Use public API for Generic Languages Framework: Change PrologAST to not user ParserManagerImpl to get the AST root node so we can go back to the public API and not use an implementation version of GLF.
Change Names To Be More Descriptive: Change the name of the PrologClause class to PrologPredicate, e.g. In other words, refactor refactor refactor.
Improve the Prolog grammar definition: Improve the grammar defined in language.nbs for Prolog. I think it can be simplified and improved.
Improve threading in GeeWhiz: Analyze GeeWhiz and introduce threading, concurrency, Runnables and all of that kind of shit so it looks like I know what I'm doing in Java but that makes the code five times more complicated and harder to understand.
Take care of compiler warnings: Analyze the warnings produced by the IDE when it starts up the target IDE and see what I can fix and what I should leave alone.
Experiment with other SWI Prolog compiler options: Try the -s option instead of the -c option and actually read the SWI documentation a little more closely.
Fix remaining TODOs in code comments: Probably I'll need to look at the good old Task List (ctrl+6) sometime. Jeez, it's like being married....
Fix the *&$%!* coffee cup icon on my new Prolog projects: Enough said. Although while I'm at it I can see if there's anything else I can get rid of (or add) for new Prolog projects.
Add license and digital certificate to GeeWhiz: I should maybe make this an entry since a first glance at the docs available seemed less than promising.
Find out how to create a target platform that is leaner for performance reasons: Either that or buy a faster machine.

Additional Features That Could Be Added To GeeWhiz

Localize messages, strings, etc.: Be a good world citizen and stick all messages etc. in Bundle
Add help: Add JavaHelp to the project. This might be another entry as well. It's pretty cool how it works, though....
Make the static predicate visual model dynamic and refer back to source: This is complicated by the fact that the predicate / clause relationship is not 1:1, but maybe light up all source clauses when a widget is selected....
Add freemarker support: Oops, I was going to do that as part of the original project. Hopefully no one noticed.
Interact with SWI Prolog via IOProvider Reader: Just for fun we should try out the Reader in the output window.
Create a satellite view for the modeler: Make a satellite view of the diagram a la Geertjan's example but preferably in a different window (popup?) as opposed to a sidebar.
Add XPCE support: Add support for SWI Prolog's buddy XPCE somehow. That would be a challenge, I bet... Wonder if it's Windows-compatible.

Either They're IDE Bugs Or I'm Doing Something Wrong Dept.

On-again / off-again DataObject-dependent icons and menu items: Find out once and for all if the above is me or the IDE. Then yell at the IDE people regardless.
Wizards should be able to deal with icons already in the project directory: For creating actions e.g. the wizard shouldn't give an error if the icon is already in the directory.
Better reload support in "Install / reload to target": I shouldn't have to clean the project every damn time I retest. Look into security errors etc.

Areas For Further Research

NetBeans platforms and their creation
Visual Library, especially the VMD part
JavaHelp
DataObjects, cookies, and their ilk

GeeWhiz Prolog - Part Seven - Adding An Option Panel

nospam@example.com (Hulles) — Thu, 22 May 2008 17:05:13 +0200

This is Part Seven, the eighth part of a series of entries describing an implementation of the Prolog language in the NetBeans IDE.

Part Zero, "About The Project," is here.
Part One, "Before We Start," is here.
Part Two, "Creating A File Type," is here.
Part Three, "Adding Language Support," is here.
Part Four, "A Visual Prolog Modeler" is here.
Part Five, "Adding The Compiler" is here.
Part Six, "Creating Prolog Projects" is here.

What We'll Be Doing

Our Prolog IDE is quickly maturing into a comfortable, fun and feature-rich programming environment. But if you're like me -- and I hope for your sake you are not -- you've been laying awake at night, sweating, thinking to yourself,

"Gee whiz! I created this great Prolog IDE but I totally ruined it when I hard-coded the compiler command stuff into the project (see Part Five, "Adding The Compiler"). Now I can't make it into an NBM and distribute it and have everybody in the world use it and love it and have somebody write an article for NetBeans.org called 'Meet A NetBeans Module Writer: Hulles' with my picture in it and everything."

Well, we all need our sleep, so lay awake no longer. This time we're going to add an IDE-level Prolog options screen where we can set the compiler command and arguments outside of our code and have it retained between sessions. We're also going to clean up some code while we're at it so our project is a little more compatible with the NetBeans IDE -- a "better NetBeans citizen," as they say.

This entry is partially based on a Geertjan article in NetBeans called "NetBeans Options Window Module Tutorial". I recommend checking it out prior to doing this entry if you feel so inclined; he gives you more background than I give you here. And thanks to the author for that tutorial and all the other fine NetBeans articles he has done.

Adding An Options Panel

First off we're going to start up the New Options Wizard. Right-click on your GeeWhiz project and select "New" "Other".

Select the "Module Development" category and choose "Options Panel", then click "Next". On the next screen of the wizard we're going to create a tab for Prolog in the "Miscellaneous" section of the "Tools/Options" menu.

Select "Create Miscellaneous Panel" then enter "Prolog" for the title. Type "Prolog project options" for the tooltip text and hit "Next".

The next screen should come up already filled in for you, but check and make sure the project is "GeeWhiz Prolog", the class name prefix is "Geewhiz", and the package name is filled in correctly ("org.myorg.geewhiz"). Then click "Finish" and let the wizard generate the files.

Now we're going to take the panel that the wizard created and modify it for our own nefarious purposes. Open "GeewhizPanel.java" in design mode and from the Swing palette add a panel that fills the frame, then add two labels and two text fields to the panel, as in the screenshot.

Rename the top text field by right-clicking it and selecting "Change Variable Name...". Call it "compilerName". Add a tooltip to it in Properties that says "Enter the command to invoke the compiler, e.g. "swipl"". Rename the bottom text field to "compilerArgs" in the same way and add a tooltip that says "Enter arguments to the compiler command, e.g. "-c -r"". When you're satisfied, switch to source view and change the load and store methods to:

    void load() {
        compilerName.setText(NbPreferences.forModule(GeewhizPanel.class).
                get("compilerName", "swipl"));        
        compilerArgs.setText(NbPreferences.forModule(GeewhizPanel.class).
                get("compilerArgs", "-c"));        
    }

    void store() {
        NbPreferences.forModule(GeewhizPanel.class).put("compilerName", 
                compilerName.getText());
        NbPreferences.forModule(GeewhizPanel.class).put("compilerArgs", 
               compilerArgs.getText());
    }

What we're doing here is loading and storing the two data we need for our compiler, the compiler command and arguments string, in NetBeans Preferences. It may be necessary at some point to add environment and working directory information here, but for now we'll just leave it at the command and arguments.

Save and close the GeewhizPanel class.

Modifying The Compiler Class

Now we need to change our PrologCompiler class to use the NbPreferences we created in the Options panel. I went through several iterations of changes and testing with this class, and here is the final version (as if any programming code was ever final). Note: if you've made any changes to the class yourself from the version we created earlier, you should save your old version of PrologCompiler.java prior to making these changes. Whenever you're ready, change the class definition to the one listed below:

public class PrologCompiler {
    private DataObject dataObject;
    private String fileName;
    private String compilerName;
    private String compilerArgs;
    
    public PrologCompiler() {
        Preferences pref;
        
        this.dataObject = null;
        pref = NbPreferences.forModule(GeewhizPanel.class);
        this.compilerName = pref.get("compilerName", "");
        this.compilerArgs = pref.get("compilerArgs", "");
        
        pref.addPreferenceChangeListener(new PreferenceChangeListener() {
            public void preferenceChange(PreferenceChangeEvent evt) {
                if (evt.getKey().equals("compilerName")) {
                    compilerName = (evt.getNewValue());
                } else if (evt.getKey().equals("compilerArgs")) {
                    compilerArgs = (evt.getNewValue());
                }
            }
        });
    }
    
    public void compileDataObject(DataObject dObj) {
        ProcessBuilder procBuilder;
        Process process;
        List<String> cmd;
        Map<String, String> env;
        String line;
        InputOutput io;
        OutputWriter outputWriter;
        SaveCookie sCookie;

        
        // set DataObject and file name
        this.dataObject = dObj;
        File file = FileUtil.toFile(dObj.getPrimaryFile());
        this.fileName = file.getAbsolutePath();
        
        // save file first if it's been modified
        sCookie = dObj.getCookie (SaveCookie.class);
        if (sCookie != null) {
            try {
                sCookie.save();
                StatusDisplayer.getDefault().setStatusText("Save finished");
            } catch (IOException ex) {
                Exceptions.printStackTrace(ex);
            }
        }
        
        // get an output window tab
        io = IOProvider.getDefault().getIO("Prolog", false);
        io.select();
        outputWriter = io.getOut();

        // first see if we have a compiler available
        if (this.compilerName.isEmpty()) {
            outputWriter.println("You need to set up the compiler first.");
            outputWriter.print("In the main menu go to 'Tools / Options");
            outputWriter.println("/ Miscellaneous / Prolog'.");
            whiteLines(outputWriter);
            outputWriter.close();
            return;
        }

        // construct the SWI Prolog process command
        cmd = new ArrayList<String>();
        cmd.add(this.compilerName);
        cmd.add(this.compilerArgs);
        cmd.add(fileName);
        
        procBuilder = new ProcessBuilder(cmd);
        procBuilder.redirectErrorStream(true);
        try {
            process = procBuilder.start();
            InputStream is = process.getInputStream();
            InputStreamReader isr = new InputStreamReader(is);
            BufferedReader br = new BufferedReader(isr);
            // TODO: might want to clear the output window first...
            outputWriter.printf("Output of running %s is:\n\n",
                        commandString(cmd));
            while ((line = br.readLine()) != null) {
                if (lineIsNotable(line)) {
                    outputWriter.println(line, listener);
                } else {
                    outputWriter.println(line);
                }
            }
        } catch (IOException ex) {
            outputWriter.print("Error occurred running Prolog compiler. ");
            outputWriter.println("Check options.");
            outputWriter.print("In the main menu go to 'Tools / Options");
            outputWriter.println("/ Miscellaneous / Prolog'.");
            outputWriter.printf("Command string is %s.\n", commandString(cmd));
     //       Exceptions.printStackTrace(ex);
        } finally {
            whiteLines(outputWriter);
            outputWriter.close();
        }
    }

    private OutputListener listener = new OutputListener() {
        public void outputLineAction(OutputEvent ev) {
            String outputLine;
            Line editorLine;
            LineCookie lCookie;
            int lineNumber;
            int columnNumber;
            
            outputLine = ev.getLine();
            lineNumber = parseLineNumber(outputLine);
            columnNumber = parseColumnNumber(outputLine);
            lCookie = dataObject.getCookie (LineCookie.class);
            editorLine = lCookie.getLineSet ().getOriginal (lineNumber-1);
            editorLine.show (Line.SHOW_GOTO, columnNumber);

            StatusDisplayer.getDefault().setStatusText("Fix me!");
        }
        public void outputLineSelected(OutputEvent ev) {
            // Let's not do anything special.
        }
        public void outputLineCleared(OutputEvent ev) {
            // Leave it blank, no state to remove.
        }

    };

    
    private boolean lineIsNotable(String line) {
        boolean result = false;
        
        if (line.startsWith("Warning:") || line.startsWith("ERROR:")) {
            result = true;
        }
        return result;
    }
    
/*
 * SAMPLE SWI PROLOG LINES:
ERROR: /home/.../sieve.pro:16:0: Syntax error: Operator expected
Warning: (/home/.../sieve.pro:18): Singleton variables: [P]
*/
    
    private int parseLineNumber(String line) {
        int fpos;
        int startpos;
        int lineNumber;
        Character ch;
        StringBuffer numBuf;
        
        fpos = line.indexOf(this.fileName);
        // assuming there are no colons in file name!
        startpos = line.indexOf(":", fpos);
        if (startpos == -1) {
            // lineNumber is converted to lineNumber - 1
            //     this causes an exception in caller if this is 0
            //     so return 1 instead
            return 1;
        }
        numBuf = new StringBuffer();
        for (int i = startpos+1; i < line.length(); i++) {
            ch = line.charAt(i);
            if (Character.isDigit(ch)) {
                numBuf.append(ch);
            } else {
                break;
            }
        }
        lineNumber = Integer.parseInt(numBuf.toString());
        return lineNumber;
    }
    
    private int parseColumnNumber(String line) {
        int fpos;
        int startpos;
        int colNumber;
        Character ch;
        StringBuffer numBuf;
        int colstart = -1;
        
        fpos = line.indexOf(this.fileName);
        // assuming there are no colons in file name!
        startpos = line.indexOf(":", fpos);
        if (startpos == -1) {
            return 0;
        }
        for (int i = startpos+1; i < line.length(); i++) {
            ch = line.charAt(i);
            if (Character.isDigit(ch)) {
                // skip line number
            } else {
                colstart = i;
                break;
            }
        }
        if ((colstart == -1) || (line.charAt(colstart) != ':')) {
            return 0;
        }
        numBuf = new StringBuffer();
        for (int i = colstart+1; i < line.length(); i++) {
            ch = line.charAt(i);
            if (Character.isDigit(ch)) {
                numBuf.append(ch);
            } else {
                break;
            }
        }
        colNumber = Integer.parseInt(numBuf.toString());
        return colNumber;
    }
    
    private void whiteLines(OutputWriter ow) {
        final int limit = 3;
        
        for(int i = 0; i < limit; i++) {
            ow.println();
        }
    }
    
    private String commandString(List<String> cmds) {
        StringBuffer sBuf;
        
        sBuf = new StringBuffer();
        for (String cmd : cmds) {
            sBuf.append(cmd);
            sBuf.append(' ');
        }
        // leave extra space on the end
        return sBuf.toString();
    }
}

Actually, rather a lot has changed. Notice in the constructor that we are now getting the compiler command and arguments from NbPreferences and starting a listener to see if they change. Actually, the listener may be overkill for this application but as I mentioned above we're trying to be better NetBeans citizens so let's leave it in just in case we have a very quick typist on our hands.

Also notice that now we are checking for a SaveCookie before we start the compilation. If one exists, and it will if our source file has been modified since the last save, we grab it and use it to save the file prior to compiling it. I love how easy that is in NetBeans. We follow the NetBeans Java example of not asking prior to doing the save; we just go ahead and do it.

Note that we also are adding a couple helper methods to clean up our code (and the output) a little bit. White space rocks. And we're adding more cleanup -- we are finally closing the OutputWriter in our class.

Since we opened up the compiler command and arguments to user input, now we have to do some reality checks on the data prior to using it. First we check to make sure the NbPreference is there for the compiler command and issue an error if it is not. (The command arguments should be optional.) The compiler command will not be there if the user has not set up the compiler in our new options panel so we firmly order her/him to go to the options panel and set it up right the hell now. Hmph. The nerve.

We also changed the try/catch for the compiler invocation, since now we're executing whatever the user typed in for a command and arguments. Instead of doing a stack trace we're issuing an error message in the catch, since

is not considered good user feedback in most circles. Never mind how I got the screenshot, why do you think I changed it? Of course I left the stack trace in place but commented out, since no good Java programmer feels completely comfortable about a catch statement without a stack trace laying around somewhere.

I think that about covers the changes. Let's try it out. But before we do that, you might want to grab a new PrologAST from the archive to this article. I modified it to not print all the debugging information unless a constant is set, and if printing is requested to not keep the OutputWriter tied up quite so long. Good citizenship again, but not worth including the source code in this article.

Testing The Option Panel And The Compiler

You know the drill -- clean and build the GeeWhiz project then install it to the target IDE. Don't go into the options menu yet. Open up the "Algorithms" project (!) and open sieve.pro. Try to compile it with the menu bar button. You should get an error.

Next, from the main menu, select "Tools" "Options", then click the "Miscellaneous" tab then the "Prolog" tab.

Our options panel should appear with the default values from our load statements in GeewhizPanel. Click "OK". Now try compiling sieve.pro again. You should get a normal compilation.

Now go back into our option panel and change the values to something invalid for your compiler and platform, like :

Click "OK" to save them, then try compiling again. You should get an error.

You don't need to change the options back since they'll go away once the target IDE is destroyed in our clean and build. However, before you quit testing you should make sure you can still create a diagram with the modified PrologAST class without printing any text in the Prolog output tab if you installed the class from this article's archives. Then you can quit.

So now GeeWhiz is back to being platform- and compiler-independent and it's a little easier on the NetBeans enviroment. Now maybe we can all go get some sleep. Next time we'll create a NetBeans module (NBM) file for sharing with others, a fairly trivial task, and sum up what we've accomplished so far. Zzzzzz....

Files From This Entry

GeeWhiz Prolog - Part Six - Creating Prolog Projects

nospam@example.com (Hulles) — Thu, 22 May 2008 13:45:23 +0200

This is Part Six, the seventh part of a series of entries describing an implementation of the Prolog language in the NetBeans IDE.
Part Zero, "About The Project," is here.
Part One, "Before We Start," is here.
Part Two, "Creating A File Type," is here.
Part Three, "Adding Language Support," is here.
Part Four, "A Visual Prolog Modeler" is here.
Part Five, "Adding The Compiler" is here.

What We'll Be Doing

So far we've cobbled together a pretty decent Prolog IDE within the NetBeans environment. As far as features, it has... well, you can review the previous articles in the series yourself but it has a lot of Cool Stuff. Now we're going to create a new project template so when you want to start working on a new Prolog project you don't have to call it a Java class library or a web application just to be able to create new Prolog source files.

Create A New Project Template

First we need to create a sample project to use in the new project template wizard. This project should have what just what we need when we start a new Prolog project and no more. Since we're only working with text source files, that's pretty much all the project needs. We'll just copy one source file into the project since both Nature and Hulles abhor a vacuum. In the main menu, select "File" "New Project" and create yourself a new Java class library project called, appropriately enough, "NewProject".

Find a copy of sieve.pro in your target IDE directory and copy it into the src folder of NewProject. If you would prefer, you can extract a copy from the archive files at the end of this article.

Now we're going to pare down the project as much as we can, which isn't much at this point. Right-click on NewProject and select "Properties". In "Categories" select "Libraries", then click the "Compile Tests" tab. Delete the test libraries that are there.

Click "OK" to close the properties window. Now we have a simple project we can use as a base for creating new Prolog projects. Time to create our new project template. Right-click the GeeWhiz project and select "New" "Project Template...". In the first screen of the wizard select "NewProject".

Click "Next". On the next screen of the wizard, enter "NewProject" for the template name, "Prolog Application" for the display name, select "Other" for the category, and make sure the package is correctly filled in.

Once everything is correct, click "Finish".

Now we're going to customize our new project template a little bit. Edit "NewProjectDescription.html" and change the description to simply "Prolog project".

Save and close the file. Open the layer.xml file and traverse "this layer" down to "Templates" "Project" "Other".

Right-click on "Prolog Application" and select "Pick Icon...". Navigate to your package source folder and select "prolog-star.png", the dreaded Black Star of Prolog.

Click "OK" and you're done. You can now delete the "NewProject" project because we won't need it anymore. The necessary stuff from "NewProject" was zipped into our "GeeWhiz" project by the new project template wizard.

Testing The New Template

Our new Prolog project template should now be ready to test. Clean and build your main project and install it to the Target IDE. Once your "personal domain" is created, in the main menu select "File" "New Project" and you should see our new Prolog project option, complete with BSofP icon.

Select "Prolog Application" and fill in the necessary fields, calling your new project "Algorithms" in honor of our two hard-working sample Prolog programs, fib1.pro and sieve.pro.

Check out "Algorithms" and note that "sieve.pro" is include in the default package of our new project. If you want to be really loyal, copy fib1.pro into our new project and delete the "BraveNewWorld" project since we won't need it anymore.

While we're here, note also that there is a disturbing Java coffee cup icon on our new Prolog project. There is a way to change that, but that procedure is beyond the scope of this how-to series. This is because I have no idea what the procedure is. If you do, please let me know.

There, wasn't that easy? Now we have a way to create a Prolog project as a home for our precious Prolog source code. Next we'll do some housework in GeeWhiz and make it a "good NetBeans IDE citizen" (or at least a better one). In the process we'll make GeeWhiz Prolog platform- and compiler-independent once again. (It was until the last entry when we added the compiler.) Until next time.

Files From This Entry

GeeWhiz Prolog - Part Five - Adding The Compiler

nospam@example.com (Hulles) — Wed, 21 May 2008 20:46:21 +0200

This is Part Five, the sixth part of a series of entries describing an implementation of the Prolog language in the NetBeans IDE.
Part Zero, "About The Project," is here.
Part One, "Before We Start," is here.
Part Two, "Creating A File Type," is here.
Part Three, "Adding Language Support," is here.
Part Four, "A Visual Prolog Modeler" is here.

What We'll Be Doing

Up to this point we've created a Prolog editor within the NetBeans IDE with built-in syntax highlighting, navigation, a visual modeler, and some other stuff that I forget but that's probably pretty cool. Now we're going to add in-place compilation so we don't need to switch between NetBeans and whatever Prolog compiler we're using just to fix syntax errors and such.

In this entry I'll be using SWI Prolog as my Prolog compiler. It's a free, robust open-source compiler that runs on multiple platforms including, probably, yours. One thing it does not have, however, is a feature-rich IDE -- hence this project. When we're done with this segment, we'll be able to compile our Prolog source code directly from the NetBeans IDE and hotlink (whatever that means) the error lines back to our source code. In other words, it will function much like the Java compilation process within NetBeans that we all know and love.

By the way, if you currently use a different Prolog compiler, don't worry. Once we're done here it should be pretty obvious how to adapt this project to incorporate your favorite compiler as long as you can run it from a terminal command line. In fact part of the reason I'm writing this how-to is to allow you to adapt ANY language to the NetBeans IDE. I'm trying to assemble the knowledge that's scattered around the NetBeans universe in one place so that this series of articles gives you the ability to quickly and dirtily add your favorite language to the NetBeans IDE. We'll work on the "dirtily" part later; for now our goal is results, baby.

Adding Compiler Support

Adding compiler support to GeeWhiz turns out to be surprisingly easy. It's easy if you know where to look for info, that is. It took me for-effing-ever to find the information I needed to do this, but once I did, implementing support for an external compiler turned out to be almost trivial. But I digress. The first thing we need to do is create an action in our project to invoke the compiler. Right-click on our GeeWhiz project and select "New" "Action".

In the first screen of the New Action Wizard, once again select "Conditionally Enabled" and "User Selects One Node". Set the cookie class to "DataObject" since we want to only compile Prolog source files with our compiler. Hit the "Next" button.

On this wizard screen select "File" for a category (just for something different; we chose "Other" for our "ShowDiagram" action). (I've always wondered why it takes so long for this window to come up on my machine. I suspect that this is the place where NetBeans is sending encrypted information about my unspeakable habits to our shadowy overlords.) Uncheck "Global Menu Item" and check "Global Toolbar Button" (again, for something different). We're going to stick our toolbar button at the very end of the Build toolbar so select "Build" for the toolbar and "Profile Main Project... - HERE" as the position. Click "Next".

On this screen, enter "CompileProlog" for a class name and "Compile Prolog Program" for a display name. For icons, you'll need both a 16x16 and 24x24 icon in the same directory, called (in our case) compile16.png and compile24.png, otherwise the wizard will grumpily issue error messages until you do. You can use these if you'd like, another modified Black Star of Prolog. Right-click on them in your browser and save them to a directory that is not your project directory and let the wizard copy them. Fill in the path and file name of the 16x16 icon in the icon field in the wizard. Make sure your package node ("org.myorg.geewhiz") is filled in in the package field and click "Finish".

Note: in the last screenshot ignore the GeeWhiz2 reference. I didn't make screenshots of this process the first time around, probably because I didn't expect it to work the first time! I thought I'd have to do 8 or 9 trials to get it right like I did for the other stuff in this project. Gee whiz, I must be learning something....

Once the wizard creates our new action, you can close the icon files in the editor and add the following lines to the CompileProlog class, where it says "TODO: use DataObject":

        PrologCompiler compiler = new PrologCompiler();
        compiler.compileDataObject(dataObject);

Save and close the file. Great. We have a toolbar action, now all we need to do is write a PrologCompiler class. So let's do that.

Create a new Java class called "PrologCompiler" and replace the empty class with:

public class PrologCompiler {
    DataObject dataObject;
    String fileName;
    
    public PrologCompiler() {
        this.dataObject = null;
    }
    
    public void compileDataObject(DataObject dObj) {
        ProcessBuilder procBuilder;
        Process process;
        Map<String, String> env;
//        File currDir;
        List<String> cmd;
        String line;
        InputOutput io;
        OutputWriter outputWriter;

        // TODO: should save file first if it's been modified
        
        // set DataObject and file name
        this.dataObject = dObj;
        File file = FileUtil.toFile(dObj.getPrimaryFile());
        fileName = file.getAbsolutePath();
        
        // get an output window tab
        io = IOProvider.getDefault().getIO("Prolog", false);
        io.select();
        outputWriter = io.getOut();

        // construct the SWI Prolog process command
        cmd = new ArrayList<String>();
        cmd.add("swipl");
        cmd.add("-c");
        cmd.add(fileName);
        
        procBuilder = new ProcessBuilder(cmd);
        procBuilder.redirectErrorStream(true);
        // also s/b able to merge it into OutputWriter
//        env = procBuilder.environment();
//        env.put("VAR1", "myValue");
//        env.remove("OTHERVAR");
//        env.put("VAR2", env.get("VAR1") + "suffix");
//        currDir = procBuilder.directory();
//        if (currDir != null) {
//            System.out.printf("Current directory is %s.", currDir.toString());
//        }
//        procBuilder.directory(new File("myDir"));
        try {
            process = procBuilder.start();
            InputStream is = process.getInputStream();
            InputStreamReader isr = new InputStreamReader(is);
            BufferedReader br = new BufferedReader(isr);
            // TODO: might want to clear the output window first...
            outputWriter.printf("Output of running %s is:\n\n", cmd.toString());
            while ((line = br.readLine()) != null) {
                outputWriter.println(line);
            }
            // TODO: close outputwriter
        } catch (IOException ex) {
            Exceptions.printStackTrace(ex);
        }
    }
}

What we want this to do is invoke the SWI Prolog compiler with our source file, the name of which we retrieved from our trusty Prolog DataObject. We're using the IOProvider/OutputWriter we saw last time to write the output to the Output tab, just like a real adult language module does. We're also using ProcessBuilder to build a Process so we can execute an external command.

Just a couple of other things worth mentioning about the above class: one is that I left in some comments showing how to access the environment and change the working directory, just in case you need the info to make your compiler work. Also, note that the command line I used is for the Linux version of SWI Prolog. If you run on another platform, you'll probably need to change this. For example, I believe Windows uses "plwin". See the SWI Prolog site for more information.

Testing The First Version

So let's try it: clean and build your main project and install to the target IDE. Open up the BraveNewWorld project. Wait until the excitement dies down. Open up sieve.pro. Add a line somewhere in the program that says:

	gruesome(ugly error).

This introduces an error in our otherwise nearly pristine Prolog program. Save sieve.pro. Find our new compiler button on the toolbar and click it.

At this point my original notes say "holy shit it worked!" As indeed it did, the first time. Nothing works the first time, ever. Imagine my elation. If you look at the "Prolog" output tab (!), you'll see the gruesome ugly error we introduced does indeed give us an error in the compiler output. Also note in passing that our syntax parser did flag our gruesome ugly error statement as an error. Heh heh.

The compiler also gives us a warning that there is a singleton variable in one of the clauses. This means that the variable "P" in the statement "remove(P,[],[])." isn't used. In Prolog, instead of using a named variable here you should use an anonymous variable, the underscore. If you want you can change the statement to read "remove(_,[],[])." and recompile it to see that the warning goes away. When you're done muttering "Gee whiz!" you can close the target IDE.

Add Hotlinks (Whatever They Are)

Now we're going to add hyperlinks to our compiler output so when you click an error line in the output you are magically transported to the source code at the point of the error. I know, you're saying "Gee whiz!" to yourself again. Just wait....

In trying to add this feature, I knew exactly what I wanted to do but I really wasn't sure how to accomplish it. Until, that is, I found an article called "Meet A NetBeans Module Writer: Jens Trapp". In the article is a code snippet that does exactly what I wanted to do in about three lines of code! Thank you Mr. Trapp; may the rest of your days be happy ones. Who knew there was a LineCookie that plunked you right down in the middle of the source code editor? Probably the people who RTFD, that's who.... But for the rest of us there's Hulles.

So now we're going to change our PrologCompiler class to "hotlink" our compiler code to our source code. Open the class file and replace the class with this:

public class PrologCompiler {
    DataObject dataObject;
    String fileName;
    
    public PrologCompiler() {
        this.dataObject = null;
    }
    
    public void compileDataObject(DataObject dObj) {
        ProcessBuilder procBuilder;
        Process process;
        Map<String, String> env;
        List<String> cmd;
        String line;
        InputOutput io;
        OutputWriter outputWriter;

        // TODO: should save file first if it's been modified
        
        // set DataObject and file name
        this.dataObject = dObj;
        File file = FileUtil.toFile(dObj.getPrimaryFile());
        fileName = file.getAbsolutePath();
        
        // get an output window tab
        io = IOProvider.getDefault().getIO("Prolog", false);
        io.select();
        outputWriter = io.getOut();

        // construct the SWI Prolog process command
        cmd = new ArrayList<String>();
        cmd.add("swipl");
        cmd.add("-c");
        cmd.add(fileName);
        
        procBuilder = new ProcessBuilder(cmd);
        procBuilder.redirectErrorStream(true);
        // also s/b able to merge it into OutputWriter
        try {
            process = procBuilder.start();
            InputStream is = process.getInputStream();
            InputStreamReader isr = new InputStreamReader(is);
            BufferedReader br = new BufferedReader(isr);
            // TODO: might want to clear the output window first...
            outputWriter.printf("Output of running %s is:\n\n", cmd.toString());
            while ((line = br.readLine()) != null) {
                if (lineIsNotable(line)) {
                    outputWriter.println(line, listener);
                } else {
                    outputWriter.println(line);
                }
            }
            // TODO: close outputwriter
        } catch (IOException ex) {
            Exceptions.printStackTrace(ex);
        }
    }

    private OutputListener listener = new OutputListener() {
        public void outputLineAction(OutputEvent ev) {
            String outputLine;
            Line editorLine;
            LineCookie lCookie;
            int lineNumber;
            int columnNumber;
            
            outputLine = ev.getLine();
            lineNumber = parseLineNumber(outputLine);
            columnNumber = parseColumnNumber(outputLine);
//          System.out.printf("Showing line %d column %d.\n", 
//                      lineNumber, columnNumber);
            lCookie = (LineCookie) dataObject.getCookie (LineCookie.class);
            editorLine = lCookie.getLineSet ().getOriginal (lineNumber-1);
            editorLine.show (Line.SHOW_GOTO, columnNumber);

            StatusDisplayer.getDefault().setStatusText("Fix me!");
        }
        public void outputLineSelected(OutputEvent ev) {
            // Let's not do anything special.
        }
        public void outputLineCleared(OutputEvent ev) {
            // Leave it blank, no state to remove.
        }

    };
    
    private boolean lineIsNotable(String line) {
        boolean result = false;
        
        if (line.startsWith("Warning:") || line.startsWith("ERROR:")) {
            result = true;
        }
        return result;
    }
    
/*
SAMPLE SWI PROLOG ERROR AND WARNING LINES:
ERROR: /home/.../bravenewworld/sieve.pro:16:0: Syntax error: Operator expected
Warning: (/home/.../bravenewworld/sieve.pro:18): Singleton variables: [P]
*/
    
    private int parseLineNumber(String line) {
        int fpos;
        int startpos;
        int lineNumber;
        Character ch;
        StringBuffer numBuf;
        
        fpos = line.indexOf(this.fileName);
		// assumes there are no colons in file name!
        startpos = line.indexOf(":", fpos);
        if (startpos == -1) {
            return 1;
	// in caller, lineNumber is converted to lineNumber - 1,
	//    this causes an exception if this is 0
        }
        numBuf = new StringBuffer();
        for (int i = startpos+1; i < line.length(); i++) {
            ch = line.charAt(i);
            if (Character.isDigit(ch)) {
                numBuf.append(ch);
            } else {
                break;
            }
        }
        lineNumber = Integer.parseInt(numBuf.toString());
        return lineNumber;
    }
    
    private int parseColumnNumber(String line) {
        int fpos;
        int startpos;
        int colNumber;
        Character ch;
        StringBuffer numBuf;
        int colstart = -1;
        
        fpos = line.indexOf(this.fileName);
		// assumes there are no colons in file name!
        startpos = line.indexOf(":", fpos); 
        if (startpos == -1) {
            return 0;
        }
        for (int i = startpos+1; i < line.length(); i++) {
            ch = line.charAt(i);
            if (Character.isDigit(ch)) {
                // skip line number
            } else {
                colstart = i;
                break;
            }
        }
        if ((colstart == -1) || (line.charAt(colstart) != ':')) {
            return 0;
        }
        numBuf = new StringBuffer();
        for (int i = colstart+1; i < line.length(); i++) {
            ch = line.charAt(i);
            if (Character.isDigit(ch)) {
                numBuf.append(ch);
            } else {
                break;
            }
        }
        colNumber = Integer.parseInt(numBuf.toString());
        return colNumber;
    }
}

As you can see, we added an OutputListener that does the work of popping us into the editor at exactly the right place where the error is located. The parsing of the error / warning lines to get the line number and column number is ugly, but that's because A) I didn't want to have to relearn regular expression syntax for the umpteenth time, and B) I didn't have 244 Swiss Francs for the ISO Prolog error message standard so I was winging it from the SWI Prolog output. Actually, there are two ISO Prolog standards documents, so it would have been 488CHF. As if.

I suppose I should also mention the StatusDisplayer line. This is one of those things that I couldn't resist putting in but that gets obnoxious very quickly. When you go to an error line, it displays "Fix me!" on the status line at the bottom of the IDE. Hah hah. So take it out, you don't like it.

Testing The Final Version

Okay, let's give 'er a spin. Clean and build your project then install it to the target IDE as before. Open up the BraveNewWorld project. Wait. Open up sieve.pro. Unfix the error and the warning if you fixed them last time so we have something to work with. Click our "Compile Prolog" button on the toolbar.

We have hyperlinks! Click on an unlinked (white) line in the Prolog output tab to make that window current. Click on one hyperlink, then the other. Notice how the cursor is moved to the editor window to the line and column where the error occurred. Now leave sieve.pro open and open up fib1.pro. Introduce an error into the code, save it, and compile it with our shiny new button. The error hyperlink from that compile should take you to the error in fib1.pro. Now scroll up the Prolog output window to our first compile and click one of the original hyperlinks. Notice that sieve.pro is reselected and the error position is displayed again. Go ahead, say it, you know you want to: "Gee whiz!"

So now we can compile our little Prolog hearts out in the NetBeans IDE. We still need to open SWI Prolog to run the stuff, but that's not so bad. It should be possible to connect up a Reader in the same way we did with the OutputWriter to allow the interaction, however. Hmmm.... You're welcome to do that if you want. I haven't yet, but I'm sure it's only a matter of time before I have to try it. If you do, let me know how it comes out.

We now have a pretty decent Prolog IDE embedded within the NetBeans architecture. What's next? We're going to create a Prolog project template so we don't have to stick our lovely, elegant and erudite nonprocedural Prolog source code into an icky stinky Java class library, that's what's next. Stay tuned.