As promised, here’s my write-up on my first Google Wave Robot, Watexy (Java Port).
Just as the name suggests, it’s a port of the sample robot Watexy from Python to Java. The code looked simple enough to port so I decided to spend an entire Tuesday to port it.
Developing Google Wave Robots means developing for the Google App Engine. IDE choice is a given; Google has given Eclipse a lot of support in terms of plugins. I originally wanted to try using Netbeans, but Google Wave Robots still aren’t supported by the IDE. For revision control, I decided to use SVN and host the code over at Google Code.
I only used two robots as reference for this program. First is the original Watexy robot, and the other is the SAP ES robot. I chose the latter because it’s one of the few robots actually written in Java.
Anyway, without further ado, here are the lessons that I’ve learned from writing the robot. The list isn’t as long as the previous post, though.
Blip DOM is freaky.
Blips are basically a single message added by a user to a wave. One of the main uses for robots right now is to intercept blips, read and analyze them, then modify them as needed. And that’s just what Watexy does inside your waves.
The problem here is that the current structure of blips (at least the one exposed via the Robot API) is freaky. Freaky in the sense that it’s supposed to be XML-like, but the available APIs tend to break it.
The API provides TextView for modifying the blip document. The weird part about this interface is that it makes the blip look like a string instead of a structured document like XML. Appending text, elements, and even other blips is not that freaky, but having the ability to delete ranges makes things freaky.
Deletes the text bounded by the specified range. All annotations and entities that are wholly contained within this range will also be deleted. Annotations that overlap this range will be truncated accordingly.
So basically you’re dealing with your run of the mill string with annotation (metadata) markers. You’ll understand its freaky-ness once you get to visualize it.
The biggest problem I had with the DOM regarding Watexy was how images are inserted to the blip. Since all elements are just annotation markers in the text, it’s hard to determine whether inserting an image anywhere inside the blip document would insert the image at the right place or not. Also, it appears that manipulation commands are somehow queued and only applied sometime later down the line. Both of these problems prevent Watexy from properly handling multiple LaTeX snippets on the same blip.
(It’s a bug, BTW.)
Dev Guide docs are seriously lacking.
One good example of this is setting up the Robot Profile. It is discussed in the Robots Overview but.. well… see for yourself:
Note that a robot, by default, does not provide this profile information. For Java robots, you must add a Profile servlet to your application which responds with this data. In Python, you provide this information within the robot’s constructor. Consult the client library documentation for more information.
Okaaaay.
Would it be hard for Google to at least put a link to exactly what part of the API reference they are referring to? If it wasn’t for the SAP Robot, I wouldn’t have known how to implement the profile for Java.
API docs are seriously lacking.
Image – you annoying bastard.
Not only was this class annoying in blip manipulation, its Java API was missing a bunch of stuff. For example, how do you create an image without a height and width attribute (needed because mathTeX can return images of different sizes)?
In Watexy, it was:
image = document.Image('http://www.forkosh.dreamhost.com/mathtex.cgi?' + m.group(1), caption=m.group(1))
How do you do this in Java? Use this constructor?
Image image = new Image(imgUrl, -1, -1, caption);
Nope. Doesn’t work. It doesn’t add any element to the blip. It doesn’t even throw an error.
After some (hours of) trial and error, I got this:
Image image = new Image(); image.setUrl(imgUrl);
/facepalm
Note that the API reference doesn’t say what values are required and what values are accepted for this element. The height and width was misleading, but it’s not as bad as the url field: it has a freaking undocumented limit! I had to write a method to shorten the urls of very long LaTeX formulas via is.gd!
Runners up for the “most annoying portions of the API reference” are Event Types (where the hell is the explanation for each of these types?!?) and the available annotations for TextView.setAnnotation(name, value) (spoiler: some dude found it in the source and posted them here).
Google Wave assumes that you’re already familiar with Google App Engine.
For example, logging. Logging is not defined anywhere in the tutorial or the API docs of Google Wave Robots.
Turns out it is located at the Google App Engine docs.
Nice.
—
And that’s about it for this rant write-up. Tomorrow I’ll run down the capabilities and limitations of Robots and Gadgets to help you decide what programs to write for the Google Wave platform.
—
EDIT: For your LaTeX needs, I suggest you use Eqygadget. I also have a fork of that gadget here.
