Integrating Growl - A Quick Start Guide

As promised, here is a quick start guide to integrating Growl support into a Cocoa application. The documentation expects that you've worked with Xcode before and are familiar with creating new build phases and writing Objective-C code. For the impatient and those that just want to play around I've created a gist with the project. You'll probably want to clone the project instead of looking at it online because it contains some binaries..

git clone git://gist.github.com/297221.git gist-297221

The first thing you'll need to get started is a copy of Growl.framework. As of this writing the latest is version 1.2. Once you have a copy of the framework you'll need to link your application against it. To do so, simply drag and drop the framework onto the Linked Frameworks item in your Xcode project. Since the framework will need to be shipped along with your application you'll also need to ensure that it gets copied into your application's bundle. Create a new Copy Files build phase for your application's target, make sure that you set the Destination to Frameworks. Drag and drop Growl.framework from Linked Frameworks to the newly created build phase. At this point your application will compile against the framework and include it when building.

The next thing you'll need to do is create a plist file called Growl Registration Ticket.growlRegDict containing the registration information that will be required by the framework. Below is an example of such a file. You'll need to make sure that this file makes it into the application, this can be done by ensuring that its in the Copy Bundle Resources build phase.

In order for Growl to allow your application to send notifications you'll need to register the notifications that your application will be sending with the framework. To do this you'll need to create and implement a bare-bones delegate. All that's required is that you implement the (NSDictionary*) registrationDictionaryForGrowl method. The implementation of this method will simply need to return a dictionary whose contents come from the plist file created previously. The body of this method can be as simple as:

- (NSDictionary*) registrationDictionaryForGrowl {
   NSString* path = [[NSBundle mainBundle] pathForResource: @"Growl Registration Ticket" ofType: @"growlRegDict"];
   NSDictionary* dictionary = [NSDictionary dictionaryWithContentsOfFile: file];
  return dictionary;
}

Once this method is implemented, and an instance of the class is set as Growl's delegate by calling [GrowlApplicationBridge setGrowlDelegate: X] you'll be able to send messages to Growl using [GrowlApplicationBridge notifyWithTitle:description:notificationName:iconData:priority:isSticky]

That's about all there is to it. It's a fairly simple framework to integrate with, but the documentation neglects the fact that you have to implement (NSDictionary*) registrationDictionaryForGrowl

An example project exists as a gist on github.

git clone git://gist.github.com/297221.git gist-297221

Trials and Tribulations with Growl

A few nights ago I had just finished getting the core piece of a new application I started working on finished. It occurred to me that my little application and its users would benefit from having Growl support. It was pretty late, midnight or so and I didn't want to be up much later so I just downloaded the framework and had a quick skim of the developer documentation. It seemed pretty simple, but it was late and I knew that if I started that late I'd be up few a few more hours getting no where and end up going to bed feeling defeated. "Tomorrow, " I thought, "I'll do this tomorrow. If its as easy as the docs say then I'll have enough time to add at least 2 other features!".

I got up the next morning feeling great, I knew that come that evening I'd have integrated Growl support. Evening rolled around and I sat down and got to work. I re-read the documentation...well, skimmed is more acurate, and started following the instructions. I created the plist file containing the information that the documentation said I needed. I added a build step to copy the plist to my application's Resources directory. I double checked the name of the file -- the documentation says it's case-sensitive. I linked Growl.framework to my application. I added a build step to copy the framework to my application's Frameworks directory. And lastly I added the code from the documentation to send a notification to Growl ensuring, of course, I was sending one of the notification names that was in my plist file.

I clicked the Build and Run button, and my application compiled and my application's Dock icon started to bounce. By this point I felt like a kid at Christmas. I'd written my letter to Santa, stuffed it in an envelope, and very carefully, in my tidiest printing I wrote the address: "North Pole." I placed my stamp and tossed it in the mailbox. My letter must have gotten there, it hadn't been returned to sender so I knew that good stuff was heading my way.

The Dock icon stopped bouncing and my application's window opened up. "This is it, " I thought to myself "the moment of truth!" I clicked the button to fire off the notification aannnddd...nothing.

Silence.

"That's ok," I thought "it's probably some silly little thing I did wrong."

I looked at my run logs and they were eerily quiet. No messages at all. Surely if I'd done something wrong the framework would tell me. That must mean that the framework didn't get copied to my application's bundle. But if that's the case, then shouldn't there have been an error in the log about my code trying to perform a selector on a class that didn't exist? So that must mean that my code that posts the notification was never called. This sounds like a job for Captain Breakpoint!

I placed a breakpoint on the first line of my method and started the application again. Application startup under the debugger always takes longer so I was caught off guard when my application's window opened up. I moved my mouse cursor over the button, knowing that I was one mouse click away from finding out that my code wasn't being called thereby giving me all the information I'd need to fix the problem. My eyes narrowed as I pressed the button.

Half a second later I was staring at the Xcode debugger, my line with the breakpoint highlighted and a stack trace showing me that execution was indeed stopped in my method. I felt totally disarmed like I'd just gathered up my courage to tell that guy what I really thought of him only to be knocked off my feet by an overpowering wall of cheap cologne.

"What...the...what?"

I gingerly stepped through the method stopping just shy of executing the line to post the notification. Pausing for a second to think about what could possibly happen next. If the debugger tosses me out of my method, I know that either the framework doesn't exist or my parameters are causing it to barf. If the debugger stops and the next statement in this method...well that doesn't sound easy to debug, so lets hope that doesn't happen. I stepped over the line and found myself looking back that beautiful line of code just after the call into the framework.

This doesn't make sense. The framework accepted my parameters without problem, ostensibly did something with them and succeeded. So what could it possibly be? The framework didn't log anything, so it must not be a problem with my code. But no notification showed up, so the problem must be that Growl just isn't running. At that moment notification showed up in Growl -- but not from my application.

"Well, if other apps can send notifications then it's gotta be something I'm doing wrong." Since the documentation told me that all I needed to do was create a plist file and make sure it was in my application's Resources folder I figured I'd double check, and sure enough it was there. I'd just been banished to developer's purgatory where I have to debug configuration..

I thought to myself, "If my application has to have one of these plists, then other apps must have to have them too!" The first few applications I found didn't have one of those plists and they were working just fine. Finally I found an application that had a plist. So I compared them to make sure I'd done it right and sure enough I found a problem with my configuration. I updated my file, saved, built and ran the app again. My application's window popped up and I clicked the button and this time...nothing happened...again.

Silence.

Not believeing that it was something that I'd done I cleaned, rebuilt, and ran the application a few times knowing that it shouldn't make any difference in the world but hoping that it would just magically start working. After several runs in vain I figured that maybe The Google would have an answer for me. Sure enough, after trying a few google-y incantations I found some source code buried on a page that showed how to initialize Growl implementing a delegate method. I modified my code in a similar way, saved and ran again. I clicked the button and was surprised to see my little notification appear on the screen - only an hour after I started.

---

Truth be told, the Growl documentation did mention that one could would have to implement a delegate if you were attempting to talk to Growl 0.7, but since my code was running against 1.2 I didn't think I'd need to. In any case I managed to get it to work, but not without some frustrations that could have very easily been avoided had the Growl team produced some other artifacts that were as easy to find as the developer's documentation.

The first of these is some sort of a quick-start guide that just provides the bare minimum steps that are needed to use the framework. The developer's guide was littered with documentation about old versions. I don't need to know that stuff. Just assume that I have the latest and tell me exactly what I need to do.

Another thing that would have really helped, especially for developers that like to get dirty is a downloadable example. I'm sure they have one somewhere, but I wasn't linked to from their documentation so it effectively didn't exist.

Last lastly, but certainly not least is some level of logging in the framework itself. This would have been immensely helpful since I'd be able to tell if the framework was finding my plist or not, or whether there was a problem with my parameters. Don't just leave me to figure it out on my own, give me some help!

I hope what I'm saying doesn't label me an Open Source Douchebag. Honestly, I'm really just trying to improve the project by making it easier to get people up to speed. And in the next few days (hopefully) I'm planning on uploading some sample code along with a quick-start blog post.

On Subclassing

And now for another excursion into the depths of my experience and thinking about object oriented design and philosophy. This time I'm going to talk about some pitfalls I've seen with one of the most commonly used, and abused tools in the object oriented developer's toolbox: subclassing and access modifiers.

Subclassing has been around since the dawn of objected oriented programming. It's just one of many ways to enhance code reuse, but I've seen enough blood shed due to the misuse of this feature that I've stopped using it in cases where I can get away with another approach. The core of the problem with subclassing tends to be an eagerness to reuse as much code as possible without any consideration of how code reuse decisions will effect the overall design. Yes, reusing code means that there are fewer places to change when a change must be made, but subclassing is a merely a means to an end. There are other, better approaches that give the same benefits without the problems.

So what are some of the problems with subclassing? I think the central failing is that subclassing is the most tight form of coupling there is. When you decide to subclass an implementation, you've solidified part of your implementation. A common word of wisdom is that you should always code to interfaces so that implementations can be changed at a later date with a minimal of fuss. By subclassing an implementation you are publically declaring that you are and always will be a subclass of X.

Another problem with subclassing is that you cannot narrow the interface of the class to anything smaller than the subclasses interface, even if it doesn't make sense. A textbook example of this in Java is the java.util.Stack class. java.util.Stack extends java.util.Vector which in turn extends java.util.AbstractList which is an abstract implementation of java.util.List. The java.util.List interface contains methods such as add, get, indexOf, etc. If you've followed along that means that java.util.Stack, in addition to its own interface also has these methods. A stack should really only have two methods for mutating the stack (push and pop) and perhaps some methods to determine how many items are on the stack. By subclassing, java.util.Stack has guaranteed that it implements the java.util.List interface and therefore has methods that allow a developer to work around the stack encapsulation. Ah, but you can override those methods in the subclass with ones that do nothing or throw a java.lang.MethodNotImplemented exception. Certainly you could, but then if an instance of java.lang.Stack was passed to a method that accepted java.util.List it would not produce the desired result -- either by throwing an exception or not performing the operation.

No discussion of subclassing would be complete without mentioning the Liskov Substitution Principle. I think it's great advice it theory, but as we've all seen it's not exactly easy to follow. If the JDK developers can make such an error with all of their review process, how does a lowly developer stand a chance?

Aside from these problems there's always the minefield of access modifiers. In my opinion there should really only be 2 at the class level: public and private. Protected variables are a major cause of headaches since subclasses can easily muck around with the internals of a superclass, violating encapsulation. Protected methods provide a second interface to the class which has to be maintained and documented -- as if a single interface wasn't enough problems. So, private and public is really all that's needed - stuff that's internal and stuff that's public.

So if not subclassing then what? In a word delegates, specifically the delegation pattern. With the delegation pattern you simply implement interfaces, if applicable, and delegate parts of the implementation to a concrete class. By doing so you don't have to expose any information about how your class works internally. And since you're not subclassing you don't inherit interface that doesn't make sense for your class. As an added bonus, since you're using the public interface to the concrete class you don't have to worry about methods internal to the implementation changing or becoming deprecated.

Delegates are also an effective strategy for reusing code. You can encapsulate logic into a single class and use it from anywhere in your application. This is a great benefit when you have an irregular class heirarchy, it effectively gives you mixins without the headaches of trying to figure out which pieces of implementation are coming from which mixin.

Obviously there are times when subclassing is the right thing to do. But in my experience I see it used much more often than it should be and usually for the wrong reasons. I hope my thoughts have given you something to think about next time you reach for that subclassing hammer.

First Impressions of Cocoa

Over the past few months I've been doing a lot of playing around with development on the Mac using Cocoa. Although I do disagree with some of the design decisions that have been made, but for the most part I really like both Objective-C and Cocoa. The developer community is extremely vibrant and very helpful, a feeling I haven't had elsewhere.

One of the things I really like about Cocoa is that it handles a lot of the mundane tasks for you. There's a technology called CoreData that handles object graph persistence. You simply setup your data model and the framework takes care of the rest. This is really great since one initial hurdle I always run into when coding, and where I usually lose steam is in persisting and reading data that my application is working with, CoreData takes care of this beautifully.

Another great technology is Bindings which is built on top of Key-Value-Coding and Key-Value-Observing. In essence, Bindings allows you to visually tie the value of a control to a piece of data in your data model. This removes the need for reams of "glue" code that you'd otherwise have to write to keep your View and Model consistent. With these two technologies all you really have to do is write your Controllers.

Granted, the Controller is generally where the rubber meets the road, but since the frameworks take care of the Model and View you're free to think almost exclusively on the problems and structure of the Controller.

So far I've been really happy with the results that I've been able to achieve with only a small time investment. Between the results and how supportive the developer community is I think the Mac is a great platform to develop for and look forward to doing so in the future.

inf-js: Selecting an Interpreter

The REPL (Read-Eval-Print-Loop) is a great way to interactively build and debug a program. A while back I wrote about an inferior mode for JavaScript that I had built called inf-js that provided a REPL for JavaScript development. The mode works by starting an interactive session with a JavaScript interpreter available on your machine. By default it will use rhino but it can also be configured to run spidermonkey or V8.

If you have multiple JavaScript interpreters on your machine you don't have to change the configuration to switch between them. inf-js will allow you to specify the process to run when you start call the interactive function `run-js` if you prefix it with a universal argument. You can do this by typing C-u M-x run-js . inf-js will ask you for the name of the program to run as the interpreter for the session.

This feature works really well when you want to interact with a server written in node.js that has a REPL.

class-mode.el

Yester-week I found myself in a situation where I needed to view the JVM opcodes for a class that was being generated. I was experiencing some very odd behaviour and figured it was probably a bug in the code, possibly but unlikely, a bug in the compiler. Now, I've read through JVM opcodes before, that isn't too tricky. The JDK comes with a tool called javap specifically for disassembling class files. The read pain was that I wasn't exactly sure what class the problem was in and all of the classes were in a jar file.

Being the lazy programmer that I am when I'm confronted with a task that can be automated, I automate it. In this particular case I was able to make use of some of the interesting features of my favourite editor, emacs. Emacs comes with a mode that allows you to edit zip files. You simply open the zip file and you're presented with a list of its contents like a directory listing. You can click on a file to open a file within the archive, change it, save it and have the archive update itself with your changes. Nothing truly spectacular, but really useful indeed. Since jar files are just zip files with another extension I was able to open and browse the jar files within emacs.

But, by default, emacs knows nothing about class files or how to open them, they are simply binary files, so I wrote a simple function that would take the contents of the current buffer, write it to disk, run javap on it and replace the contents of the buffer with the disassembly of the file. I hooked this function up as a major mode and assigned that major mode to be used when opening files with a .class extension. With this function and a minor change to the auto-mode-alist I was able to browse through the disassemblies of jar files with extreme ease.

After seeing the utility of this I made a few enhancements, such as the ability to use jad instead of javap if its installed, and created a new github repository for it. If you ever find yourself needing to view the disassembly of classes (be they in jars or not) and don't want the hassle of fiddling around with eclipse, have a look at class-mode.el for emacs.

The Polyglot Programmer

Those that know me know that I'm a real programming language geek. I'm always reading about programming languages. Why am I constantly seeking out new language while most other developers are happy knowing one or two languages? I think it comes down to not being satisfied with the status quo. When you code in a language for a long enough period of time you think in terms of the constructs that the language provides you.

This is certainly a good thing in terms of productivity. Thinking in a language is akin to speaking it as your native tongue. Your brain becomes hard wired to think in that way. The time from concept to implementation is shortened because you don't have to do any mental translation to convert a solution from one language to another. While this is all well and good, thinking only in the constructs of one language prevents you from seeing . As the old saying goes: when all you have is a hammer, every problem looks like a nail.

But while this is great in some respects, learning more languages has certain benefits. Each language is different, exposing you to different ways of approaching problems and different tools for solving them. As you step further and further away from the comfortable object oriented Aglol descendants you'll notice that the languages you used to use to solve every problem is woefully inadequate at solving certain classes of problems.

This comes from the fact that not all languages are created equal. Each language has a certain level of friction for a given problem domain. It's true that you can solve a problem in any turing complete language, but that doesn't mean that the solution will be easy to read, write, or maintain. By learning a variety of languages you'll be able to see which language are better suited to a particular problem.

Also, since each language tends of offer a different set of tools, you'll expand your mind. There is more to programming than what blub languages give you. For example, JavaScript gives you a language with dynamic typing, first class functions, closure, and prototypal inheritance. None of those features are available in a language like Java.

Features aren't the only thing that new languages expose you to either. As you venture further off of the beaten path you'll find some very interesting languages that look strange and alien. Take Factor for example. Factor is a concatenative language which is a language that is based around the idea of a mutable stack. Concatenative languages are just one class of languages and there are many others, all of which have interesting properties.

As you become exposed to more and more language concepts you'll be able to pick up new languages much more easily. Having been exposed to the concepts of a new language before, you will have flattened the learning curve of that language.

The most effective languages tend to be called Domain Specific Languages. A domain specific language is a language that is tailor made for solving problems in a specific domain. A great example of a domain specific language that most of us have dealt with is CSS. CSS provides a language to specifying styling of HTML elements. It doesn't have loops, it doesn't have conditionals, just pure unadulterated declarations that can be combined. Certainly there are problems with implementations of the language, but that isn't my point. My point is that CSS fills a void. You could probably do what CSS does with a general purpose language, but why? CSS is tailored to the problem it's trying to solve.

I'll leave you with an interesting thing I've noticed as more applications are moved into the web realm: if you want to stay relevant, you need to become a polyglot. Most applications aren't simply constrained to one language anymore. Modern web applications use at least 4 distinct languages between the server side, client side, build scripts, and configuration. If you can't be effective with all of them then you've got some learning to do.