For the Teamprise product line, I’ve always had a focus on providing comprehensive runtime diagnostics. This feature gets used any time we have a customer report a problem. With just a few clicks, the customer can produce a zip archive containing a complete set of diagnostic data that our support team can peruse through. This kind of thing really cuts down on the back-and-forth usually involved with customer support. I should really do a complete blog entry sometime on the entire diagnostic system, since it’s a pretty neat piece of engineering. But today, I’m going to talk about just one aspect of our runtime diagnostic system.

When a customer invokes our support dialog, one of the tabs is labeled “BeanShell” and looks like this:

BeanShell is a popular script engine for Java. It interprets a lightweight, dynamically typed scripting language that has syntax very similar to Java syntax. BeanShell has a small footprint and is perfect for being embedded in other applications. Embedded BeanShell could be used for many purposes - a plug-in system, an administrative console, and lots of others. In the Teamprise support dialog, we use Embedded BeanShell to allow us to run arbitrary diagnostic commands at runtime.

The basic idea is that a Teamprise contact can provide a customer with a snippet of BeanShell code that was composed to track down a problem. The customer pastes the snippet into the BeanShell dialog, and presses the eval button. Any results of the snippet are logged as well as displayed in the dialog. The customer can then either send us their logs or report on what the output was.

Of course, for this kind of thing to be useful, the BeanShell script must be able to access important objects in the system. BeanShell has the perfect feature for this - when setting up the interpreter programmatically, you can predefine certain variables that the script can then access. We predefine variables for the Eclipse workspace, the TFS connection object, and lots of other important “root” objects in our system.

Just as an example, here is a snippet of BeanShell. When run in our support dialog this will print out all the work item queries for the first Team Project on the server:

workItemClient = tfsConnection.getClient(com.teamprise.core.WorkItemClient.class);
project = workItemClient.getProjects().getProjects()[0];
for (query:project.getStoredQueries().getQueriesByScope(null)) {
  print(project.getName() + “/” + query.getName() + “:\n” + query.getQueryText() + “\n”);
}

This script makes use of the predefined tfsConnection variable, which is our connection to the TFS server.

No matter how comprehensive a diagnostic reporting system is, there will always be data you don’t have the forethought to collect at development time. Using an embeddable scripting language like this gives us control to run diagnostic code at runtime and allows our customers to quickly run new diagnostic tests that we create for them.

I spend a lot of my time these days developing Eclipse-based applications. My employer (Teamprise) makes, among other things, the Teamprise Plug-In for Eclipse and Teamprise Explorer (an RCP app), both of which allow access to Microsoft’s TFS. As I’ve spent time developing for the Eclipse platform, I’ve come to realize that finding the proper resources is critical to getting the job done right. In this article I’ll share a few tips and pointers to resources I’ve come to rely on. Hopefully this brief article will be of help to someone who is just starting off developing for Eclipse - this is the list of resources I wish I had pre-compiled when I started.

Developing against Eclipse can be both simple and complex at the same time. Many of the individual tasks are quite simple (once you understand enough context around the task). At the same time, the “big picture” for Eclipse can be very complex. Eclipse has a huge codebase, a huge user community, and a huge number of people developing solutions on top of it. These are very good things. The chances that you will encounter a totally unique Eclipse programming problem that no one has ever had to solve are pretty slim. There is a lot of help out there. However, these can be bad things at times too. Eclipse is a moving target. Advice given for some previous version of Eclipse may no longer be valid for a current version. There is often so much information out there that finding the needle in the haystack can seem impossible.

Books
If you’re doing professional Eclipse development, there is no excuse for not having a library of books on the topic. Even if you’re programming against Eclipse for a hobby, a small investment in books will pay dividends down the road.

The primary book anyone developing Eclipse plug-ins must own is Eclipse: Building Commercial-Quality Plug-ins by Eric Clayberg and Dan Rubel. This book could be considered the Bible of Eclipse plug-in development. A second edition was recently published, so make sure you get that version. Here at Teamprise we keep the first version around as well since we also target older versions of Eclipse with our products. If you only buy one Eclipse development book, this is the one you should get. Keep in mind that this book is really geared toward the topic of plugin development only. It doesn’t go deeply into other important topics like SWT, JFace, or RCP applications.

You’ll also need at least one book as a reference to SWT and JFace. SWT is the cross-platform GUI toolkit Eclipse is built with, and JFace is an abstraction library on top of SWT. Since much of the work you do will involve writing GUI code, you need a book that both explains the mechanisms of SWT and serves as a reference to the many classes that make up SWT. To fill this need, I currently recommend The Definitive Guide to SWT and JFace by by Robert Harris and Rob Warner. This isn’t a spectacular book on SWT/JFace, but it is the best that I’ve come across so far. This book isn’t of the same caliber as Building Commercial-Quality Plug-ins, but it serves as a basic reference book. It is pretty dated at this point, as it covers the version of SWT that was released with Eclipse 3.0. Hopefully there will be a second edition at some point.

The Java Developer’s Guide to Eclipse is a good book to have on the bookshelf as well. This one is very broad, but does not go deeply into the topics. Unlike the other books I mentioned, this book includes information on how to use Eclipse as well as how to develop for it, making this book a good choice for someone totally new to Eclipse. There have been a number of times that I could only find something I was looking for in this book as it covers such a wide range of topics.

Probably the best solution is to have a number of Eclipse books on hand, including at least the ones mentioned above. Since Eclipse development is such an extensive topic, there can never be a single book that covers everything you need to know.

Articles on eclipse.org
If you haven’t already bookmarked http://www.eclipse.org/articles/, then you’ve been missing out on a very valuable Eclipse development resource. The coverage here is very deep, but not necessarily broad. Whenever starting a new or unfamiliar task in Eclipse, take a few moments to see if there is an article on the topic. These articles are often great supplements to the class javadoc for the Eclipse APIs. Even better, the articles are often written by people very familiar with the Eclipse implementation code, so the information here is straight from the horse’s mouth so to speak. Note that anyone from the Eclipse community can contribute articles, so if you have extensive knowledge on a topic, consider submitting an article for the benefit of others.

Newsgroups
One of the most important Eclipse development resources has to be the newsgroups. You can search through the extensive archives or browse all postings. There are lots of different groups, so at first it can be confusing knowing which group to look in. Luckily, you can search across all of them, and it pretty quickly becomes clear what ends up where. There’s not really much more to say about the newsgroups - there’s a wealth of information there, so take advantage of it.

Bugs
Believe it or not, some of the best information about various Eclipse development topics can be found in the official Eclipse bug tracker. This is especially true for newer topics and things that have changed recently and haven’t yet been covered by other resources. I recommend always doing a keyword search here before starting on an unfamiliar topic. There are lots of nuggets of information here (if you can find them).

Community Websites
Like most large software communities, Eclipse has its share of third party websites. The one I frequent most often is EclipseZone, which has articles and forums. There are also a number of blogs written by Eclipse committers. users, and third-party developers. This is by no means an extensive list of Eclipse-related blogs, but a quick scan through my feed reader turned up these:
http://alblue.blogspot.com/index.html
http://borisoneclipse.blogspot.com/
http://eclipse-desudation.blogspot.com/index.html
http://www.ji.co.za/unplugged
http://tom-eclipse-dev.blogspot.com/index.html
http://www.edwardthomson.com/blog/ (also a Teamprise developer)
http://ianskerrett.wordpress.com/
http://inside-swt.blogspot.com/index.html (Steve Northover’s blog, highly recommended)
http://milinkovich.blogspot.com/index.html (Mike Milinkovich, executive directory of the Eclipse foundation)
http://jroller.com/page/mpermar
http://www.woodwardweb.com/ (also a Teamprise developer)
http://jroller.com/page/murphee
http://mea-bloga.blogspot.com/index.html

Code
There is a wealth of code out there to study and use as starting points. Besides Eclipse itself being open source (under a very commercial-friendly license) there are numerous open source third-party plug-ins for Eclipse to look at. At a minimum, take some time to look over the code included with the Eclipse plug-ins that your plug-ins depend on. The public Eclipse API is usually well documented and the code itself is pretty readable. Another great code resource is the SWT Snippets page. Chances are, if you’re trying to do something with SWT, you can find an example snippet on that page.

Eclipse Help
Finally, don’t forget about one of the most useful Eclipse development resources - the help that ships with the Eclipse SDK! This often overlooked resource contains valuable information about developing Eclipse plug-ins. In fact, this should probably be your first stop when looking for information about a topic. The built-in help has consistently improved from release to release.

I’ll start off by saying I am a big proponent of pair programming. It’s a very effective programming style when used in moderation. I read stories about some places that pair all of the time for everything - while I’ve never worked in that kind of environment, I can’t imagine it would be too pleasant. There are too many programming activities that involve “think time” in which you’re not talking, not typing, not reading, but simply processing. Depending on the kind of work you’re doing, this think time may be a big or small part of your day, but either way it’s an important part.

However, pair programming is great for some tasks. Lately I’ve been pairing with a colleague to hammer out the finishing touches on a feature for an upcoming release, and pairing to do this is working really well. Along the way, I’ve done a few small things to make the overall pair programming experience as effective as possible.

Environment
If you’re going to be pair programming for any length of time (more than an hour or two), getting the environmental factors right is crucial. Pairing in a noisy environment isn’t as effective as pairing with fewer distractions. At the same time, realize that pairing creates a fair amount of extra noise in the environment that wouldn’t otherwise be there (especially if you work in an office environment), so be respectful of your non-pairing coworkers.

A clean and open work space is a must. Both programmers have to feel comfortable - if your counterpart has to dig through last week’s sandwich wrappers and who knows what else in order to find a place to work, you’re probably not going to have an effective pairing experience. If you will be doing some extended pairing, spend some time before you start cleaning up your work environment. By reducing the amount of clutter and having clean work surfaces, your pair will feel much more comfortable and willing to invest in the effort.

Along these same lines, consider closing programs which pop up intrusive notifications for the duration of the pairing session. This includes things like mail readers and feed readers that have the habit of popping up temporary windows to alert you of new items. This will only distract from the pairing session and your pairing partner probably doesn’t care to see the notifications anyway. If you’re worried about missing important mail, just take a 10 minute break every couple of hours and check for any urgent messages then.

Another point is that you need lots of collaboration material. At a minimum this means a large, clean whiteboard with plenty of markers and an eraser. It’s surprising to notice the psychological effect of a whiteboard that’s been freshly cleaned with whiteboard cleaner compared to one that’s dirty and lightly erased with a felt eraser. Also good to have on hand is plenty of pads of paper and pens for jotting down quick notes and diagrams.

Input Devices
Ideally pair programming doesn’t work like drivers ed. Each participant should be just that - a participant and not an observer. It’s great that you can show off your mad programming skillz to your pairing partner, but that isn’t really the point of the exercise. The ideal pairing setup involves dual everything - 2 keyboards, 2 mice, and 2 monitors. In my case I had only a single monitor handy but there are plenty of extra mice and keyboards laying around, so I plugged in a second set of input devices and we were off to the races.

The ability to have both pairs able to code without having to play chair tetris or keyboard shuffle saves a lot of time. Often this means one of the programmers can pick up in the middle of a block of code where the other left off, and you don’t have to context switch at all. This also means that you’re not bumping elbows when trying to scroll around through a class (personal space is important to many programmers :)).

If you are going to use only a single monitor, be sure to position the monitor so that it can be easily seen by both. Often this is a different position from what is optimal for a single programmer so don’t be afraid to slide the monitor around when starting the pairing session to find the best spot.

Of course it goes without saying that you need to have two comfortable chairs and plenty of space to sit in. If you want to go all out there is always the PairOn. :)

Fonts
A prerequisite for this kind of extended pairing session is to increase the font size in the tools you’ll be using together. This is less of an issue if you’re using multiple monitors, but it’s still important to consider it. That 10 point font you use with your 21″ 1600×1200 monitor doesn’t look nearly as good when your face isn’t 4 inches from the screen. In Eclipse, I set the text font to be Consolas at 14pt, which works great for pairing off of a single monitor. Consolas looks great on LCD monitors with cleartype enabled, and if you are legally allowed to install it on your machine I can’t recommend it enough. Of course, the downside of larger fonts is that you can’t see as much code at a time, but it means that you don’t get eyestrain or headaches and both programmers have a good view.

ZoomIt
Finally, I highly recommend installing the ZoomIt utility from Sysinternals on the computer before beginning the pairing session. This utility was written to help aid presentations, but it’s perfect for pair programming.

ZoomIt has two extremely useful features for pairing. First, with the press of a hotkey, you can use the mouse wheel to zoom in on any portion of the screen. Even if you’ve bumped up the font sizes as I suggested above, there will probably still be times that a little zooming is needed to narrow in on something. If you or your pairing partner need to often lean closer to the monitor to try to read something, ZoomIt will be a huge help.

Secondly, ZoomIt has a great annotation feature that allows you to draw on the screen. This can be great for pairing - instead of smudging up the screen every time you need to point out something, simply press a hotkey and use the annotation feature instead. This is a really underrated feature for pairing - how many times have you wanted to point at a section of the code or highlight a particular block? Again, this feature is all hotkey driven and the ZoomIt utility overall is very well done.

Conclusion
Keep in mind that pair programming can be mentally draining. Often a 6 hour work day pairing is easily the equivalent of an 8 hour work day alone, especially if you don’t pair often. When done right, you can temporarily boost your effective output, but when done wrong, it can be an excuse to slack. Also I’ve found that during pairing you will often discover tasks that one or the other of you need to do, but doing those tasks as a pair would be a waste of time. The best thing to do is to keep a list of “action items” that are related to the task at hand but will be completed outside of a pairing session. If you do this, be sure to put appropriate TODOs in the code and keep your parter informed about the progress of your action items.

Over on Artima, Bill Venners posted a question about exception handling. When an API declares that an exception could be thrown, it is saying that something could go wrong. This is, of course, a conditional declaration (if an exception was thrown every time, the API would not be very useful). As it happens, often the API makes a guarantee that under certain conditions, an exception will never be thrown. As a client of the API, how do you handle the case when you’re calling in and are guaranteed to be in a case where an exception will not happen?

Here’s (roughly) the example from the linked article:

// Processes the given input string using the given character encoding. 
// If the given encoding is not supported, throws an UnsupportedEncodingException.
// The “UTF-8″ encoding is guaranteed to always be supported.

public String doSomething(String input, String encoding) throws UnsupportedEncodingException
{
   …
}

Java’s checked exceptions make this situation worse. In other languages that support exceptions but don’t have the concept of compile-time checking of exception handling, developers usually ignore this case. And after all, why not? If you are calling an API in such a way that an exception is guaranteed to not be thrown, then there is no reason to put in exception handling code. Unless, of course, you are programming in Java and the exception is checked, in which case you must handle the exception whether you want to or not, even when you are guaranteed by the API that your handling code will never get called.

The usual thing to do here is to simply handle the “impossible” exception by rethrowing it wrapped in an unchecked exception, like RuntimeException. This looks something like:

try
{
   doSomething(”an input value”, “UTF-8″);
}
catch (UnsupportedEncodingException shouldNeverHappen)
{
   // according to the API docs, “UTF-8″ is always supported
   throw new RuntimeException(shouldNeverHappen);
}

But I’d like to look at this from the point of view of the API producer and not the API consumer. The fact that the API consumer has this problem about how to handle an “impossible” exception indicates an API bug. The fix is to split the API into multiple methods that have different guarantees, adding the following method in addition to the method above:

// Processes the given input string using the “UTF-8″ character encoding.
// To process with another character encoding, see doSomething(String input, String encoding).

public String doSomethingUtf8(String input)
{
   …
}

Since the API is smart enough to guarantee a special case (no UnsupportedEncodingException) for UTF-8 in the API documentation, why not make that special case explicit? As it often happens (eg java.net.URLEncoder.encode) the special non-exception case is the normal case. Why not optimize for the normal case?

There are many ways to do this. If there are multiple “good” values that will result in no exception being thrown, create a version of the API that takes an enumerated value (and doesn’t throw) and one that takes a simple data type like String (and throws).

Of course, if the API didn’t use checked exceptions, this would all be a moot point. I rarely throw checked exceptions when writing new code, and encourage others to do the same. Checked exceptions are useful in certain situations, and I enjoy having them in the Java tool chest. However, they’re vastly overused and in most cases APIs that throw checked exceptions should be converted to throw unchecked. I’ve touched on this point before, and there’s plenty of opinion in agreement (and disagreement :)) out there on the web.

BTW, in the example code above, you could make an argument that the exception should really be an IllegalArgumentException (which is unchecked). UnsupportedEncodingException extends IOException, which is a bit strange to throw as an argument validation exception when IllegalArgumentException exists for that purpose.

State-based and interaction-based unit tests differ greatly in style, although they each have the same end goal, which is verification of a unit of code. The ultimate difference between the two is what attributes of a unit of code are tested in order to consider whether or not the unit of code is correct. It’s important for a software developer to know both styles and to understand the differences between the two.

State-based testing
A state-based unit test is written in a style of unit testing that many software developers would be familiar with. In fact it wouldn’t be far off to call this “traditional” unit testing. In a state-based test, the first step is to initialize the unit under test. This initialization may include creation of test data and graphs of supporting objects necessary to exercise the unit under test. The test then exercises the unit by calling methods on it. When the test has finished exercising the unit, assuming no errors have yet been raised, the test then proceeds to verify expected state of the unit. In JUnit parlance, this verification is usually done using the assert*() methods. No matter what testing harness is used, this verification takes the form of testing state and raising errors if the actual state differs from expected state.

A little more about those supporting objects alluded to in the previous paragraph. One of the challenges of unit testing is to sufficiently decouple the multiple units of code that make up an application so that each unit can be tested individually. Otherwise, you end up with a “unit” test that’s really more like an integration test. Often this decoupling can be hard. A variety of techniques have been developed to help in this decoupling, but the most important technique is to program to interfaces instead of concrete classes. There should be an interface at all of the coupling boundaries of your unit of code. If this single condition is met, writing effective unit tests will become much easier. Often the supporting objects used by a test harness to properly exercise a unit are stubs. A stub is a trivial implementation of an interface that exists for the purpose of collecting state during a unit test.

Stubs are most often written by hand, although they don’t have to be. Usually you will end up creating a graph of stubs and trivial real objects that parallels the graph of real objects (both complex and trivial) present when the application is running. As the unit under test uses the stubs, they stubs collect state that can be verified at the end of the test. We’ll come back to stubs later on when we talk about mock objects. For now, keep in mind that stubs are often created by hand and exist to collect state for verification purposes.

How a state-based unit test works shouldn’t be a surprise to anyone who’s ever written a unit test. One of the advantages of this style of unit testing is its simplicity. It doesn’t take long to teach someone how to write tests in this style, and the overall behavior of the test is intuitive. It kind of feels like the way we might test something outside of the realm of software development.

The important thing to note is what criteria the state-based unit test is considering about the unit under test. It is, not surprisingly, all about state. If the unit under test reaches a certain state, it is considered correct. The state-based unit test doesn’t really care how the unit got to that state, but only that it is there at the end. The phrase “the end justifies the means” is apt here. The means (behavior of the unit) doesn’t matter nearly as much as the end (state). In fact, the only thing a state-based unit test verifies about the means is that the behavior of the unit didn’t include raising any errors during the test.

Are state-based unit tests effective? Absolutely. The best evidence of which is that most unit tests today are being written in this style. The end state of a unit is in many cases very significant from a verification standpoint. The end user of an application certainly cares more about state than behavior (here, behavior being that of internal objects and not external behavior of the application itself). When you’re using an online banking application the bottom line is that you want your balance to be the correct one.

Interaction-based testing
An interaction-based unit test is different. The easiest way to explain would be to say that an interaction-based test verifies the behavior of a unit instead of verifying the unit’s end state. From the point of view of an interaction-based test, the correctness of a unit is based on how it interacts with its neighbors, and not with internal state of the unit.

An interaction-based unit test first initializes the unit under test. This is done by creating “fake” stand-ins for all of the unit’s immediate neighbors. A neighbor is any object that the unit under test passes messages to (calls methods on). These stand-ins are called mock objects, and are usually created by a test framework library. When the initialization is complete, the only “real” thing in the graph of objects is the unit under test. Everything that the unit is hooked up to is a mock object - capable of receiving the same messages as the real object.

There is then a second step to the initialization of an interaction-based unit tests. After all of the mock objects have been initialized, expectations are set on the mocks. This is exactly what it sounds like - the test code programs the mocks and tells them what messages to expect from the unit under test. This can include many things such as what order to expect messages in, what the parameters to method calls should look like, and often how the mock should respond to these messages.

Contrast mocks and stubs. I know that in many places these two terms are used synonymously, but they are really very different from each other. A mock is often generated by a test framework library, while a stub is often created by hand. The internal state of a mock doesn’t matter at all - only the expectations it has about the messages it receives. A stub exists to collect state. Stubs are often used in conjunction with “real” objects. For instance, if an existing real object is very simple and lightly coupled to the rest of the code base, it is often brought in by testing code as a supporting object to the unit under test. A stub is normally only created when the real object can’t be used in a test harness for various reasons (coupling, external dependencies, etc). Mocks are used exclusively in an interaction-based unit test - all of the unit’s immediate neighbors are mocks, even when the real object is trivial.

The final stage in an interaction-based unit test exercises the unit. During this phase, the test code is invoking methods on the unit under test, which itself is interacting with the mock objects. A test error will be raised by the mocks if expectations are not met. An expectation can fail to be met for a variety of reasons, including if methods are called in the wrong order, if parameters have unexpected values, if the wrong methods are called, or if the right methods are not called. At the end of this phase the interaction-based unit test completes. There is no state-checking of the unit under test. If all expectations of the mock objects have been met, then the unit has been verified from the point of view of the test.

Are interaction-based unit tests effective? To really answer that question you have to look at the motivation for this style of testing. Object-oriented development might have been called behavior-driven development if it had been invented in this decade. (I know that there is an existing methodology termed behavior-driven development, but it is really based on OO being done right if you look closely). What is a more useful measure of the correctness of a unit - its behavior or its state? A OO purist would hopefully answer that behavior is key while state should be internal and encapsulated. An interaction-based unit test verifies behavior, while a state-based unit test verifies state.

Interaction-based unit tests are great for completely isolating the unit under test, and thereby are very true unit tests. A properly done interaction-based test cannot be testing anything other than the unit, while it is not hard for a state-based test to rely on side effects and be a little sloppy about boundaries between the unit under test and other units in the application. Interaction-based testing is most useful when applied uniformly throughout a code base. The objects that you create mocks for in a interaction-based test will themselves need interaction-based tests in order to feel confident about the code base as a whole.

Deciding which style to use
One of the premises of this article is that it’s important for today’s software developer to understand the large differences between state-based and interaction-based unit testing. However, for any of this to be of practical use, you will eventually have to make decisions about which style to use when writing a test.

I find that interaction-based testing feels a little unnatural. You can certainly make the argument that an interaction-based unit test is more tightly coupled to the implementation of a unit than a state-based unit test is (the counter-argument is that this is a good thing, not a bad thing). I’ve also noticed that interaction-based unit tests tend to have a lot more plumbing code that state-based tests. Coming back to a state-based unit test after a few months is usually easy - coming back to an interaction-based test often involves lots of inspection to get back up to speed. In other words, I posit that interaction-based unit tests have a higher maintainability cost than state-based tests. I think a lot of this is a reflection of the current state of languages and libraries in which interaction-based tests are written. This is still a fairly new testing style, and over time much improvement will be made in the libraries and frameworks that support it.

Finally, I’d like to suggest that different kinds of code benefit differently from each style. Some code is very stateful, and is best tested with a state-based test. Other code is more stateless and can be fully tested only with an interaction-based style. Perhaps the right question isn’t about knowing which style is better in an absolute sense, but more about being able to recognize which style will be most effective for a particular piece of code.

Further reading
Martin Fowler: Mocks Aren’t Stubs
If interaction-based unit testing is new to you, start by reading this article. You’re likely also going to have to spend some time writing interaction-based tests against a code base you know well before the differences between the two styles start to sink in. This is one of those cases where “armchair programming” isn’t going to help - you have to dive in and try it to fully appreciate the differences between the two styles.

Behavior-Driven Development (BDD)
Many of the motivations behind interaction-based testing come from an increasing focus on behavior and less on state. From the linked site: “It must be stressed that BDD is a rephrasing of existing good practice, it is not a radically new departure.”

Mock Roles, not Objects (PDF)
A paper written by the authors of JMock, a popular Java mock object library. The paper is short and very readable. I highly recommend it to anyone trying to understand the purpose of mock objects and how they differ from stubs and state-based testing.

State vs. Interaction Based Testing Example
A blog entry by Nat Pryce, one of the developers on the JMock project, that gives an example of a state-based and an interaction-based unit test for the same piece of code.

It looks like there’s a very good chance that the Java language will finally get closures. This is, of course, a direct result of the influence of the programming techniques that Ruby (and Rails) has popularized. After all, Sun has considered the issue of closures before. Back when Microsoft had J++ Sun published a whitepaper declaring that a new J++ feature called delegates (a form of closures) was totally unneccessary. The Sun party line has always been that inner classes provide all the benefits of closures without adding additional language constructs.

Of course, J++ is now gone, Microsoft has .NET (with delegates), Ruby on Rails has exploded in popularity, and Java programmers are starting to envy their counterparts who can do in one line of code what takes them 5. Maybe inner classes aren’t the answer to everything. Heck, maybe even objects aren’t a panacea.

I really hope this makes it into the language. My top three wishes for the Java language are closures, type inference, and eliminating checked exceptions, so it’s great to know that at least one of those has a chance at being reality. Of course, as the closures feature is slated for Java 7, it will still be many years before most Java programmers will get to use closures in day to day work (how many shops are still on Java 1.3?).

Occasionally I hear the claim that creating an interface is only justified if there are multiple implementations of the interface. Developers will sometimes claim that an interface with only one implementation is a violation of YAGNI or is an example of an unnecessary complex (ie overengineered) design. While it certainly is possible to misuse and abuse interfaces, claims like these show misunderstanding of some of the most important reasons for using an interface.

Interfaces are commonly used to provide polymorphic behavior, and this is of course a valid use. It’s also the way that interfaces are usually taught, so this is the scenario that many developers associate with interface use. However there are lots of other uses for interfaces, including some that involve only having a single implementation.

Contracts

If you asked me to define what an interface is, I’d reply that an interface defines a contract. Of course, a class defines a contract as well, so I should refine that definition. An interface defines an only a contract - nothing more. I often use interfaces solely for the purpose of clarifying an existing implicit contract between two classes and making it explicit.

Why is it important to think in terms of contracts? It’s all about coupling. Explicitly defining the contracts in play during class interactions forces you to think hard about how coupled together classes are. Thinking in terms of contracts often leads to refactorings that can greatly improve the design of code, which leads me to…

Separation of Concerns

Here’s an experiment. Randomly choose one of the biggest classes in the codebase that you work on (remembering that this article is primarily about Java and Java-like languages). For many projects this would be a class that’s more than a few thousand lines long. I’m going to make a claim that the majority of the time, this class is suffering from either a) lack of separation of concerns, b) duplicated code, or c) both. If the class contains many blocks of code with a striking resemblance to each other, it’s probably a victim of the copy-and-paste coding technique, and a little bit of refactoring might go a long way towards cleaning that up. On the other hand, if the class contains lots of dissimilar code it’s probably a “spaghetti” class and could use some separation of concerns.

Interfaces are great for separating out concerns in a class like this. By identifying each concern, writing an interface that defines that concern, and then altering the class to code to the interface, you can greatly reduce the size and complexity of the class. (Arguably, you may also be increasing the overall complexity of the system - it’s always a tradeoff). I would almost always rather see a set of small classes with interfaces that define the contracts between them rather than one huge mangled class.

API Publishing

Interfaces are great to use when publishing APIs. By publishing an interface and keeping the implementation undocumented and internal, you can achieve benefits for both the API producer and consumer. Producers gain the advantage of having a clear delineation between what is API and what isn’t, and consumers won’t be tempted to depend on “implementation details”.

Interfaces are a reification of the “what not how” principle of design. By publishing only the “what” as public API, you are free to make internal structural changes to the “how” without causing any client breakages.

Of course, the argument is often made that abstract classes are better for APIs than interfaces because more changes can be made to an abstract class without breaking existing clients. There is certainly merit to this argument, but I think it is mostly true when interfaces have been misused. Interfaces should be short and focused. There are many techniques for evolving an interface based API, most of which involve using composition and adapters to allow for both new and old interfaces to coexist peacefully.

Use Interfaces

Interfaces carry few costs (including having little or no performance costs) and have many advantages that go beyond simplistic polymorphism use cases. Interfaces have the ability to break up complex designs and make clear the dependencies between objects. There are many important use cases I haven’t even touched on at all, like using interfaces to make objects more testable and using interfaces to increase configurability of systems.

I like to think of interface use as a tool for increasing the clarity of my designs, and it’s a tool I’m glad to have in my toolbox.

Recently I was fixing a bug in some code I’m responsible for, and the bug was interesting and general enough to share the details of.

A common approach in Java is to use dynamic proxies to provide decorator-style behavior. Doing this allows you to add additional behavior “around” an object without the object itself or it’s callers being aware of the decorating. The only requirement to use this built-in dynamic proxying is that the object must be accessed through an interface (third-party bytecode generation products like cglib do not have this restriction). For an example of how this technique is used, see my entry about Java active objects.

The key part of creating a dynamic proxy is to implement the InvocationHandler interface. The dynamic proxy object (which is generated by Java library code) calls the invoke method of this interface to dispatch method invocations at runtime.

An extremely common pattern is to implement the InvocationHandler interface something like this:

class MyHandler implements InvocationHandler {
    private Object delegate;

    public MyHandler(Object delegate) {
        this.delegate = delegate;
    }

    public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {
        // wrapping behavior could go here, before the real method is invoked ....
        Object value = method.invoke(delegate, args);
        // ... or here, after the real method returns
        return value;
    }
}

The idea here is that the dynamic proxy is providing some AOP-style behavior (resource management, logging, security, etc), but the real work is being done by a delegate object. The delegate object directly implements the interface that is being proxied, and all of the interface methods are forwarded to the delegate by the InvocationHandler (using Java reflection).

There is a subtle bug with the above code, and any InvocationHandler written as above should be treated as suspect.

If you read the documentation for the java.lang.reflect.Method.invoke method you’ll see that it can throw an InvocationTargetException. This occurs when the method being reflectively invoked throws any exception.

Part of the reason the InvocationTargetException class exists is because of Java’s checked exceptions. Since reflectively calling a method could result in a checked exception being thrown but not handled (since the signature of Method.invoke does not declare it), all exceptions thrown by the target are wrapped in a checked InvocationTargetException, which is declared in the signature of Method.invoke.

Normally when calling Method.invoke() the InvocationTargetException must be explicitly handled, since it is a checked exception. However, in the above case we’re calling it from inside an InvocationHandler’s invoke method, whose signature declares that it throws Throwable. Because of this, it is very easy to write an InvocationHandler that throws an InvocationTargetException out of its invoke method (which the above code will do).

Now if you read the documentation for the InvocationHandler.invoke method, you’ll see that it describes how Java dynamic proxies respond to any Throwable thrown out of the InvocationHandler. In particular, if the exception is either a checked exception that is declared by the proxied interface, or is an unchecked exception, it will be propagated directly to the caller of the proxied method. However, if the exception is checked and is not declared by the proxied interface, it will first be wrapped in an UndeclaredThrowableException. This is analogous in some ways to how Method.invoke wraps all exceptions in an InvocationTargetException. Again, the reason has a lot to do with the checked exception system in Java.

Remembering that InvocationTargetException is a checked exception, what this all boils down to is that any InvocationHandler written as above does not explictly handle the InvocationTargetException from Method.invoke() and will end up propogating an UndeclaredThrowableException to client code. The client code calling the proxied method is hardly ever going to expect this exception.

Given that most of the time, the goal of dynamic proxying is to provide transparent proxying of a service, this situation is hardly going to result in transparency. When client code invokes a proxied method, and the “real” implementation throws any exception (checked or unchecked), that exception should propagated to the calling client code. Any other implementation will result in client code that needs to be aware of the proxying, which means losing one of the main advantages of using dynamic proxies in the first place.

Here’s the correct implementation of the InvocationHandler.invoke() method from the above code:

public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {
    try {
        Object value = method.invoke(delegate, args);
        return value;
    }
    catch (InvocationTargetException ex) {
        throw ex.getCause();
    }
}

This implementation has all the right properties: any exception (checked or unchecked) thrown by the “real” method will be directly propagated to callers of the dynamic proxy. Re-throwing the InvocationTargetHandler’s cause will not repopulate that exception’s stack trace, so the client code will be able to see the real cause of the exception including the original stack trace.

If the thrown exception will propagate all the way to the top of the call stack, the distinction between the above two methods doesn’t really matter much. That is, in the case where the exception is totally unexpected by client code and will be caught by a top-level exception handler, the second approach isn’t technically needed. However, client code often explicitly handles exceptions and performs some sort of recovery. The only way to allow client code that does that is to properly handle the InvocationTargetException as in the second code example.

Admittedly the first code example is buggy. However, a lot of this complexity could have been avoided were it not for the Java language’s checked exception design. This feature is a source of controversy among Java programmers - some love checked exceptions while others have grown to hate them. I admit that I can see both sides of the argument, but I fall firmly on the side of the fence that says checked exceptions were a nice experiment but have proven to be a failure.

Note:

One commenter noted that InvocationTargetException.getTargetException() should be used instead of getCause(). The two methods are actually equivalent for InvocationTargetException, so using either works.

One of the books I’ve been reading lately is Software Conflict 2.0. It’s a collection of essays by Robert Glass that was originally published as a book in 1990. The “2.0″ version of the book contains all the original (unedited) essays along with a handful of short retrospectives written by Glass for the second version of the book.

Robert Glass is a prolific author, and I’ve enjoyed his work before. The collection of essays in this book is no exception: despite being 15 years old they feel incredibly relevant to software engineering today. Particularly interesting are the portions of the book where Glass relates anecdotes of the early days of software development (room-sized computers, etc) and successfully ties the stories into today’s industry landscape. As a young practitioner in the software field, it’s often easy for me to think that the issues of today are somehow new and original. Reading older material like this is enlightening: the issues (the very same issues) that we discuss, debate, and write articles about today were being discussed, debated, and written about decades ago. In many ways, the software industry as a whole has re-learned the same lessons over and over again. I’ll save my opinions about why I think that happens for another blog post.

One of the authors Glass makes frequent reference to in his essays is David Parnas. I’ve heard of Parnas before but have never made the time to read anything he wrote. So today I searched Amazon and found a collection of Parnas’ most influential papers entitled Software Fundamentals. I’ve added the book to my soon-to-read list: I think it’s high time I become familiar with some of Parnas’ ideas and writing.

I’d recommend reading Software Conflict 2.0 to anyone with a general interest in software engineering. For more, check out the book site where you can sample a few of the essays:
http://www.developerdotstar.com/books/software_conflict_glass.html

Reading a blog post by Oren Eini reminded me of how much more productive I’ve been since I started using virtual desktop software on my day-to-day development machine (Windows). I used to set my taskbar to be 2 rows high, and it was almost always full (Oren set his 3 lines high and I probably would have too but I couldn’t stand losing that much real estate).

At some point I got sick of an order N search through the taskbar buttons to try to find the window I was looking for, and decided to get set up with virtual desktops. There are quite a few utilities out there to provide this functionality under Windows - even Microsoft offers an option as a powertoy. I ended up using a program called Virtual Dimension which is great. You can define as many virtual desktops as you like, and the software has all the features you’d expect like customizable hotkeys and on-screen displays.

I set my hotkeys to be Ctrl+Alt+[number], which seems convenient to type quickly. I typically use 4-5 virtual desktops, but I’ll increase to more if I’m doing a lot of multitasking on a given day. There’s no pattern to which windows go where - on a given day I group the windows in whatever way seems most efficient at the moment. Just for fun, here’s what I have on each desktop right now:

– Desktop 0: Campfire browser window, Thunderbird, FeedDemon, a few assorted Firefox windows
– Desktop 1: Reflector, an explorer window, a few text editor windows
– Desktop 2: Eclipse, SQL Server Management Studio Express
– Desktop 3: Word, more explorer windows, a text editor window
– Desktop 4: VMWare Server Console, Visual Studio, more text editors

I expected a slight gain in productivity when I switched to using virtual desktops, but I was blown away by how much of a difference it made. If you like to multitask, or just find yourself having lots of applications open at a time, give it a try.