How to publish google wave robot capabilities

In last post Developing Google Wave Extension Using .Net, I gave a quick overview of how to get started with wave robot development. In this post I will try to discuss how communicaton between your robot and wave client works.

What events get notified to client?

Communication between wave client and robot is based on event subscription model. What this means is that a robot has to specify what all events it wants to listen on. There are a lot of events that you can subscribe to. For this post's discussion I will limit it to some basic and important events. So first question you have is how do a robot subscribes for the events? In wave framework this happens by pubslishing of capabilities by robot. When your robot gets added to a wave, the client looks for Capabilities.xml file at your app engine's location. My sample robot is named wavebog. So I see a post request coming to the server for url http://wavebog.appspot.com/_wave/capabilities.xml. Here is example of Capabilities.xml from google wave api.

<w:robot xmlns:w="http://wave.google.com/extensions/robots/1.0">
<w:version>0.1</w:version>
<w:capabilities>
 <w:capability name="BLIP_SUBMITTED"/>
 <w:capability name="DOCUMENT_CHANGED"/>
</w:capabilities>
<w:profile name="Cartoony" 
  imageurl="http://cartoonybot.appspot.com/public/avatar.png" 
  profileurl="http://cartoonybot.appspot.com"/>
</w:robot>

There are two important parts of this file. Under the capbilities node, you specify what all capabilities (or events) the robots can handle. In this example, robot has published that it can handle two events, BLIP_SUBMITTED and DOCUMENT_CHANGED. I will talk about various events little later in the post. Second important piece of the data is Version. If you add more capabilities to your robot and do not change the version number, then your robot may not get notifications for newly added capabilities. So it is important that you handle the robot versioning very carefully. There is some other information in the capabilities file which I will discuss later.

Generating Capbilities.xml file for .Net robot

When you are using .Net API for creating your google wave robot, you do not have to explicitly create this file. The core framework takes care of this for you. I am going to jump ahead a little and give quick over view of how this file gets generated.

When wave client sends request for Capbilities.xml to your robot myrobot@appspot.com, the proxy (as I mentioned in first post), forwards the requests to your ASP.Net handler. The handler parses the request to check if the request is for ?/_wave/capabilities.xml path. If it is then it generates the XML file at run time and sends the response back to client. You will find following implementation in RobotHttpHandlerBase class.

internal XDocument CreateCapabilitiesDocument()
{
 ParticipantProfile profile = Profile;
 return new XDocument(new XDeclaration ("1.0", "UTF-8", null),
    new XElement(RobotNamespace + "robot",
    new XAttribute(XNamespace.Xmlns + "w", RobotNamespace),
    new XElement(RobotNamespace + "capabilities",
     MonitoredEvents.Select(type => type.ToXElement())),
     profile == null ? null : profile.ToXElement(),
     new XElement(RobotNamespace + "version", Version)
 ));
}

At run time it determines what all events your ASHX handler has implemented and then adds those to the xml response accordingly. It also generates unique version number ID based on the names of the events you are handling. So if in future you add implementation for more events, then version number will get changed automatically.

Handling events in your robot

As described in Hello World example, your create an ASHX ASP.Net handler in your web application. And then you change its base class to EventDrivenRobotBase. If you look inside this class you will find that there are lot of virtual methods corresponding to each event that you can possibly handle in your handler. So depending on functionality of your robot, you will override those methods in your handler. For example, based on the capabilities.xml file generated above, I added following methods in my robot.

public class WoBoCop : EventDrivenRobotBase {
protected override void OnWaveletSelfAdded(IEvent e)
{
 IBlip blip = e.Wavelet.AppendBlip();
 ITextView textView = blip.Document;
 textView.Append(string.Format("WaBo - Added to wave {0}", e.Wavelet.Title));
}

protected override void OnDocumentChanged(IEvent e)
{
 base.OnDocumentChanged(e);
 IBlip blip = e.Wavelet.AppendBlip();
 ITextView textView = blip.Document;
 textView.Append(string.Format("WaBo - Blip document changed [{0}]", 
   e.Blip.Document.Text));
}
}

There is some dummy implementation in these methods and mention of some wave concepts like blip, document, wavelet, etc. I will talk about them in next post. For this discussion I just want to concentrate on how you will publish capabilities of your robot.

Test It

To make sure that your robot is working correctly and is publishing correct capabilities, type following URL in your browser.

http://{myrobot}.appspot.com/_wave_capabilities.xml

If everything is working correctly then you should see valid XML document rendered in browser. If you are using Google Chrome then only thing you may see is version number. Do not panic. This does not mean that your robot is not working. There is only one text node in the file with version number. Chrome is rendering only that part. But if you look at the source of the page, you will find your correct XML document. Yeah, this kind of threw me into a loop for few minutes.

In next post I will discuss, what all events you can subscribe to and what is life cycle of a wave events.