Welcome to Episode 1 of this series. I plan to make this blog dedicated to experiments that I do with Google Wave. I have another blog called GAEJExperiments, where I chronicle my experiments with Google App Engine Java.

I had written an episode on GAEJExperiments : Episode 7 where I described how you can write your first Google Wave Robot using the Robot API. The Google Wave Team has released a *new* version of the Robot API V2, with exciting new features. Additionally, the old API is also deprecated and will stop functioning on 30th June 2010. Given that in mind, I have updated the original article in this blog post.

And moving forward, all my Google Wave experiments will be chronicled here. Hope you will find them useful. Lets go…

Google Wave, as you must have heard is a collaborative messaging platform from Google. A Wave is a collaboration between several participants (humans and non-humans) using threaded conversations/documents/gadgets to achieve their task. The task could be as simple as chatting among themselves to figure out where to dine tonight to as complex as achieving a Return Order process between a purchaser and seller.

I will not delve into the specifics of Google Wave and will assume that you have a high level idea of what it is. In fact, a great online book has just been released that covers Google Wave in depth. I strongly recommend you to read it if you want to look into Google Wave in detail. The book is named The Complete Guide to Google Wave and you can read it here.

What does this episode cover?

In this episode, we are going to look at how you can write a Google Wave Robot using the Google plugin in Eclipse. We will be using the latest version of the Robot API : version 2. We will then deploy it and host this robot in the Google App Engine cloud. This Robot is then live and can be added to any Wave and participate in the conversation.

It helps to see the final result before we start out. Even if you do not understand whats going on, just bear with me. So here is the screenshot:

Let us dissect this screen and in the process, I can hopefully explain to you some Google Wave terminology in a straightforward manner without too many details. The main points are:

1. What you see in the screen above is a Google Wave that me (the person with the photo created). A Wave is a collaboration between one or more participants (human or Robots).

2. Since we need participants to make it meaningful, you can add one or more of them. All you need to do is click the + sign that you see on the top. And  you can add one or more participants who are also signed up for Wave. In this case, my Robot GAEJ Application is hosted at http://waverobotv2.appspot.com and so I can add waverobotv2@appspot.com as a participant.

3. On adding the Robot participant, Google wave system pulls up its profile (image, etc) and adds it as a participant in the Wave that I created.

4. The Robot can receive events and it can respond to them. We shall see how to write them later (source code!!), but at this point it is enough to understand that the Robot can choose what events to listen to as the Wave collaboration happens and it can then react to them. So in the case of my Wave Robot, I have specified that I am interested in knowing when participants come and leave the Wave and when someone has submitted a message.

5. So you can see that the Wave Robot was notified when it was added to the Wave, so in response to that it printed out the message “Hello I am version 2.0 of the Robot API”. As participants get added (In this case the Robot itself), it displayed a message “Hello from Wave Robot Version 2.0 to all participants”. It will do that for any new participants added to the wave. Similarly, when I finished typing the message (Hello Robot Version 2.0), the Wave Robot got notified. It then took the message it simply echoed back what I typed.

Hope this makes things clear. But a few more terms first : Wave, Wavelet and Blip. Let me keep it simple. In the above example, the Wave was the entire container. A Wave consists of one or more Wavelets. A Wavelet can be thought of as a threaded conversation that can go on within the wave (both public and private). And each Wavelet consists of one or more messages known as a Blip. A Blip is the actual message that was typed and submitted by the user. So when I typed “Hello Robot Version 2.0” above, it was a Blip.

I have simplified things a bit here but even if things are not clear at this point, do not worry. Once you get your code working, things will fall in place.

A final note above Google Wave Extensions. Extensions are the mechanism by which you can extend Google Wave by adding your own creations. Extensions are of two types : Gadgets and Robots. Gadgets are like mini-applications that run within the Google Wave client. They can be typically thought of as a UI which several participants can share at the same time. A Robot is a full blown participant in the Wave. It can be aware of most things happening in the Wave by subscribing to Events. It also has a lot of potential to modify things in the Wave like messages, etc. This article focuses on writing a Robot. If you are interested in a good summary of Google Wave Extensions and some key differences between a Gadget and a Robot, read it here.

OK, so enough of theory. Let us get down to coding. If you are new to developing with the Google Plugin for Eclipse, please read my GAEJ Experiments episodes to setup your environment (Episode 1and Episode 5)

Let us move on to coding now. Launch Eclipse and follow the steps given next.

Create a New Project

We need to create a New Project first. Follow the steps below:

1. Either click on File –> New –> Other or press Ctrl-N to create a new project. Select Google and then Web Application project. Alternately you could also click on the New Web Application Project Toolbar icon as part of the Google Eclipse plugin.

2. In the New Web Application Project dialog, deselect the Use Google Web Toolkit and give a name to your project. I have named mine WaveRobotVersion2 and I suggest you go with the same name so that things are consistent with the rest of the article. The Screenshot is shown below:

3. Click on Finish. This will generate the project and also create a sample Hello World Servlet for you. But we will be writing our own Servlet. So I suggest that you can delete the Servlet Java class and the mappings made in the web.xml or you can leave it for now since we are going to write our own.

Adding Google Wave Robot JAR files to your Project Path

Since we are going to be writing a Wave Robot, we need some additional files on the client side. These additional files (JAR files) are required for the additional Wave API’s and also for deployment in your WEB-INF\lib folder, so that they are correctly deployed and available to the run-time engine. These JAR files do not ship along with the Google Eclipse plugin, so you will need to download them for a website. The Google code website for the JAR files is:

http://code.google.com/p/wave-robot-java-client/downloads/list

The web page when you navigate to the above URL is shown below:

Download all highlighted files (in yellow) the above files to your machine. Once you have downloaded the files, follow these steps to setup your Project Build Path and runtime correctly.

1. Copy all the 4 JAR files to the WEB-INF\lib folder of your Eclipse Project.

2. Right-click on the Project in the Project Hierarchy. Select Properties and then Java Build Path. Click on Add JARs and then select the 4 JAR files from your Project WEB-INF\lib folder as shown below and click on OK.

3. Your Project Build Path should like the screenshot below.

Click on OK to proceed. This completes your Build Path setup with the Google Wave Robot JAR files.

Writing the Google Wave Robot Servlet : MyFirstGoogleWaveRobot.java

Let us first create our Robot Java class. The steps are straightforward and given below. All we need to do is write our class that extends the com.google.wave.api.AbstractRobot class and provide the appropriate implementations for the Robot Profile and the events that you are interested in responding to.

Follow these steps:

1. Create a new Java class within the package listed below: com.waveexperiments.robot (You are free to go with your package name). The New Java Class dialog is shown below. I have named the class MyFirstGoogleWaveRobot as shown below. Note that the Superclass has been selected as com.google.wave.api.AbstractRobot.

Click on Finish. This will generate standard boilerplate code.

2. The next step is to override certain methods of the AbstractRobot class, so that our Robot can provide the implementations for them. All the Wave events that you are interested in capturing like Participants got added, removed, Blip submitted, Document changed, etc can be handled by your Robot by simply overriding those methods and providing your implementation.

3. From Eclipse, select Source -> Override/Implement Methods … This will bring up a dialog as shown below. Also shown are the methods that we are interested in overriding and I have selected those. They are listed below too:

  • getRobotAvatarURL()
  • getRobotProfilePageURL()
  • onBlipSubmitted(…)
  • onWaveletParticipantsChanged(…)
  • onWaveletSelfAdded(…)

I will discuss the methods in a short while, but for now, simply click on OK. And replace the code generated with the one listed below:

package com.waveexperiments.robot;

import java.util.logging.Level;
import java.util.logging.Logger;

import com.google.wave.api.AbstractRobot;
import com.google.wave.api.Blip;
import com.google.wave.api.event.BlipSubmittedEvent;
import com.google.wave.api.event.OperationErrorEvent;
import com.google.wave.api.event.WaveletParticipantsChangedEvent;
import com.google.wave.api.event.WaveletSelfAddedEvent;

public class MyFirstGoogleWaveRobot extends AbstractRobot {

 @Override
 protected String getRobotName() {
 return "Google Wave Robot Version 2.0";
 }

 @Override
 protected String getRobotAvatarUrl() {
 return "http://waverobotv2.appspot.com/_wave/myimage.jpg";
 }

 @Override
 protected String getRobotProfilePageUrl() {
 return "http://waverobotv2.appspot.com";
 }

 @Override
 public void onBlipSubmitted(BlipSubmittedEvent event) {
 Blip blip = event.getBlip();
 blip.append("\n You typed: "+blip.getContent());
 }

 @Override
 public void onWaveletParticipantsChanged(WaveletParticipantsChangedEvent event) {
 event.getWavelet().reply("\nHello from Wave Robot Version 2.0 to all the participants.");
 }

 @Override
 public void onWaveletSelfAdded(WaveletSelfAddedEvent event) {
 event.getWavelet().reply("\nHello. I am version 2.0 of the Robot API");
 }
}

Let us discuss the main points in the code

1. Your Robot class needs to extend the com.google.wave.api.AbstractRobot class

2. Your Robot needs to identify itself by providing Profile information. Profile information includes the following:

1. A Name for your Robot

2. A custom image for your Robot

3. A profile page for your Robot (a URL)

If you provide these, then the Google Wave client is able to retrieve them and set it for your Robot when it is added as a participant. This makes the Robot look more professional.

The Profile information is primarily provided by writing implementations for the 3 methods:

a. getRobotName() : This returns the name for the Robot. You can return any name that identifies your Robot

b. getRobotAvatarURL() : This is the image url that contains an image for your Robot. I have included here the url where the image can be found. In this case, I have used the same AppEngine application where I am hosting the Robot application.

c.  getRobotProfilePageURL(): This is a web page url where one can find more information about the Robot.

The next thing in our Robot coding is to decide which events we want to respond to. The Wave sends us events that we can subscribe to i.e. write event handlers for, so that when the event occurs, Wave will automatically invoke our method implementation and pass parameters into that method that will contain enough information for us to react to it. Let us look at the events that we are processing here.

3. We want our Robot to do is to announce itself to everyone when it is added to the Wave. This is done by overriding the onWaveletSelfAdded method. Here the implementation simply gets the wavelet from the event parameter passed and replies to it with a text message.

4. We want our Robot to send a hello/introductory message whenever the list of participants change. This is done by overriding the onWaveletParticipantsChanged method. Here we again simply reply to the wavelet with a message.

5. Finally, when anyone submits a blip (message) to the Wave, we want our Robot to get notified about it. This is done by overriding the onBlipSubmitted method. Here we extract out the content that was submitted. And then simply echo it back. But over here, you can do various kinds of processing like reacting to the command, fetching some information from the database, sending out an email, tweet, etc. The possibilities are endless. But most of the time, this is the place where you might be providing the bulk of your Robot logic.

That is all to writing a Robot but we still have some configuration to do to let Google Wave know that we have a Robot running in our GAEJ Application. And we will do that through the standard servlet entries in the web.xml

Configuring the Robot Servlet

We need to add the Robot Servlet <servlet/> and <servlet-mapping/> entry to theweb.xml file. This file is present in the WEB-INF folder of the project. The necessary fragment to be added to your web.xml file are shown below.


<servlet>

<servlet-name>WaveRobotV2</servlet-name>

<servlet-class>com.waveexperiments.robot.MyFirstGoogleWaveRobot</servlet-class>

</servlet>

<servlet-mapping>

<servlet-name>WaveRobotV2</servlet-name>

<url-pattern>/_wave/*</url-pattern>

</servlet-mapping>

In the above fragment, you will note that url-pattern /_wave/robot/jsonrpc has to be mapped to the Robot Servlet that you have written. This is because the Google Wave system will invoke this url to communicate with your Robot using its protocol.

Deploying the Application

To deploy the application, you will need to first create your Application ID. The Application Identifier can be created by logging in at http://appengine.google.com with your Google Account. You will see a list of application identifiers already registered under your account (or none if you are just getting started). To create a new Application, click on the Create Application button and provide the Application Identifier as requested. Please note this name down since you will be using it for deployment.

For e.g. I have registered an application identifier named waverobotv2.

To deploy the application, follow these steps (they should be familiar to you now):

  1. Click on the Deploy Icon in the Toolbar.
  2. In the Deploy dialog, provide your Email and Password. Do not click on Deploy button yet.
  3. Click on the App Engine Project settings link. This will lead you to a dialog, where you need to enter your Application ID [For e.g. my Application Identifier waverobotv2]
  4. Click on OK. You will be lead back to the previous screen, where you can click on the Deploy button. This will start deploying your application to the GAEJ cloud. You should see several messages in the Console window as the application is being deployed.
  5. Finally, you should see the message “Deployment completed successfully”.

Wave Robot in Action

Your application is going to be available at the http://yourapplicationid.appspot.com. In my case, the application is available at http://waverobotv2.appspot.com.

To test out the Robot, you need to launch the Google Wave client and login in with your account by going to http://wave.google.com. On successful login, you will be inside the Wave client from where you can create a new wave by clicking on the New Wave link as shown below:

ep7-11

When you do that, currently you are the only participant (myself) as shown in the screen below:

Click on the + sign next to your icon and you can add one or more participants as shown below:

NOTE : Your Google Wave Robot is going to be available at <YOURAPPLICATIONID>@appspot.com , hence I have added waverobotv2@appspot.com as that was my application id. But you can replace it with your application id.

If all goes well, you will see your Robot added as a participant (with the icon and all, since the Profile Servlet is invoked behind the scenes by the Google Wave system). Since the Robot got added, it received a WAVELET_SELF_ADDED Event and since we had coded our Robot Servlet to receive that event and print out the greeting message. And it will also get the event for WAVELET_PARTICIPANTS_CHANGED i.e. it got added, so it will print the message for that also.

Next I start typing a message “Hello Robot Version 2.0 ” as shown below. But note that I have still not pressed the Done button. Till the Done button is pressed, the BLIP_SUBMITTED is not fired.


Once I click on the Done button, the BLIP_SUBMITTED event is fired and our Robot Servlet gets the event. On receiving the event, it simply echoes back the message as shown below:

That is all there is to writing a Google Wave Robot. The example here is not useful as such but the intent of the article is to make sure you get your Robot running and have the right setup in place. Several examples are available over the web in which talented programmers are writing Robots that do clever stuff. Just look around and get inspired.

Till the next episode….

Advertisement