The Set Up

In reviewing the Sofia User’s Guide, I stumble upon their facility to implement a site map. Their site map is an XML file that can be used to edit page locations and preferences at runtime without a re-compile. Their GUI tools have great support for it, and it gets rid of all the mis-typed URL’s and saves some time.

What I Should Have Done

  1. Go to the vending machines and get some Code Red
  2. Think about what my real needs are for the linkage. I don’t need every last little bit of the Sofia capabilities, I just want a way to get “Dreamweaver-style” link assurances within Java code. In addition, I have my help files laid out in such a way that I can get those URL’s for free for any given page name—it’d be nice to include that too, with a little Javascript to make it pop up in a new window.
  3. Design an interface with appropriate methods for the above—like 
    getUrl(String key)
    and 
    getHelpUrl(String url)
  4. Implement the interface with a default implementation, passing those methods along to the appropriate Sofia site map calls.
  5. Set up a separate, constants class to represent keys for the various pages

What I Did Do

  1. Went to the vending machines and got some Code Red
  2. While sipping, put the calls to the site map functionality into the controller. This went on for weeks as I added more keys, and I refactored the code a bit in the middle. Since I needed the URL in some places (to append a query string before a redirect), and ordered a full redirect in others, I had several different methods of interacting with the site maps calls.

The Pinch

During development, I had noticed occassional spurts of

/opgi360/Jsp/admin/mail/participant.notification.jsp

becoming

/ant.ntofication.jsp

but since I was constantly editing the site map, and never had a major problem with whatever pages I was testing at the time, I chalked it up to computer gremlins and ignored it.

Obviously, the gremlins infested the deployed system. Major pages were unreachable.

Looking for a solution, I see that Sofia’s site map functionality is a pretty skeletal implementation over a SAX parser. I don’t know a ton about XML, but I do know, thanks to a workshop at SIGCSE that SAX parsing is the one I’m least likely to understand or enjoy working with, and that it’s a part of the 1.4 library.

In other words, I have little to no idea where to look for the bugs, and probably wouldn’t recognize them when or if I saw them. I could try to move the site map over to using a DOM parser, which I can understand more easily. But how on earth could I know how long that would take? And, the biggest test, what value does it add for the people using the system?

So, the solution is: rip out the site map functionality, replace the Dreamweaver links with something a little more hard-coded, and figure out something to do with the Java linkage.

What Should Have Happened

  1. Grab a drink
  2. Reimplement the interface, only this time the “keys” are constants that look like page names and represent the actual page URL’s.
  3. Rewrite the implementation’s methods to only operate on the “keys” instead of doing anything with the site map.
  4. Check out the Dreamweaver pages, searching for any Sofia links that could be replaced with regular links, and hard-coding the URL’s for the ones that could not.

Estimated time: a half day.

What Did Happen

  1. Wake up early to have Easter Sunday
  2. Check out the Dreamweaver pages, searching for any Sofia links that could be replaced with regular links, and hard-coding the URL’s for the ones that could not.
  3. Go to the class where I’ve been storing the keys and comment everything out.
  4. Freak out when I see how many times I link to another page in the hard code.
  5. Do a primitive separation of the interface and implementation.
  6. Go through the code, fixing compilation errors
  7. Stumble back and forth over whether to use an interface or an abstract class. (Conclusion: the keys are present for both, but have different semantics in each—I went the abstract class route). This decision ended up getting made at about 11PM.
  8. Go to sleep feeling very tired, and not that good.

Estimated time: a day and a half, on a holiday

Conclusion

Whenever I find an exciting new feature, it’s natural to want to dig in and start using it immediately. I need to stop doing it with code I depend on, and start doing that with DrJava’s interaction pane (which I now have set up in Eclipse as a plugin).

When you design away from the implementations and class instances, you end up with a nifty little Service Layer for whatever service you’re using. (It doesn’t have to be a domain model, like in the picture.) And, when you find out you need to pull everything apart, you aren’t ripping your code into pieces.

That’s today’s tip, from me to you