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.
Subscribe