Wave Robot API shortcomings

While building a Robot that inserts a Gadget into the wave I discovered something that made me shake my head. A lot of the Wave Robot API classes have methods that violate their documented contracts. The worst offender I think has to be the Event interface. Whenever an event is delivered to your Robot, you interrogate the event to gather the information the robot requires. But there are many different events that can occur and each is trying to tell the robot a different thing.

For example, one of the methods on the Event interface is getAddedParticipants(). This method makes sense only on an event where the participants have changed such as BLIP_CONTRIBUTORS_CHANGED. However the method is available for all events. The javadoc for this method is


Returns a list of participants added to the Wavelet (if applicable).
a list of participants.

You will of course note its contract specifies that it returns a list of participants. So you write your code so that it wil handle a Collection of participants. And if there are no added participants, it will return an empty collection. Except that it does not return an empty Collection when there are no added participants. It returns null. Um, that behaviour is not in the contract.

Another case that is really nasty is the case of Wavelet.getRootBlip(). There are many reasons why you may want to access the root blip. Maybe the robot created a widget there and wants access to it. Sometimes you might want to compare the id of the root blip to see if it is the same as the id of the modified blip in the event you just received. The javadoc says that it returns “the root blip”. Just don’t do the following while handling the BLIP_SUBMITTED event or you will be sorely surprised.

Apparently when you receive an event, you do not receive the entire wavelet, but rather only information about the current blip for which the event occurred and that blip’s parent. If neither of those is the root blip then wavelet.getRootBlip() returns a non-null value, but this blip is not the actual root blip and contains no blip data in violation of its contract. This blip has been described as empty or hollow. So when you call getBlipId() on what you thought was the root blip, a null pointer exception occurs in getBlipId() because it attempts to dereference a null blip data object within the hollow root blip.

However, using Wavelet.getRootBlipId() gives you the ID of the root blip without the API experiencing a null pointer exception. Which is fine if you only want to compare blip IDs, but does not help you if you want to actually examine the contents of the root blip, since you don’t have access to it. The recommendation from Google is to save all needed blips in your AppEngine datastore and update them as they change and retrieve them as necessary.

Hopefully these annoying API contract violations (and bugs) will be fixed soon.

One Reply to “Wave Robot API shortcomings”

Leave a Reply

Your email address will not be published. Required fields are marked *