Episode 11: Develop Simple Google Wave Robots using the WadRobotFramework

Welcome to Episode 11 of this series. We saw in earlier Episode # 7, how you can write a Google Wave Robot. Please go through that tutorial to get familiar with the basics. This episode will be focused on writing a Google Wave Robot using a framework called the WadRobotFramework. This framework aims to help you develop your Robot quickly so that you can focus on the logic of your Robot, while letting the framework do the heavy lifting. Sure, you can do your programming with the Google Wave Robot API as explained in Episode 7, but this framework as we shall see wraps the details nicely so that you get to focus on your Robot logic.

What is the WadRobotFramework?

The WadRobotFramework is available at http://code.google.com/p/wadrobotframework. This framework is the work of  Jerome BATON, who has stated that the goal of the framework is to make writing Google Wave Robots in Java much simpler.

The framework goes ahead and defines two kinds of Robots: Simple and Advanced.

Simple Robots

Simple Robots are typically those that can react to a new Blip. This kind of Robots simply wait till a Blip is submitted. And on submission of the Blip, they will append a message to the Blip. It could be as simple as just analyzing the text of the blip and appending some new information or simply a fun sort of a Robot, which simply prints a random message.

An example of a this is shown below and which we will build in this episode:

In the above wave, there are two participants (myself and the Robot). The Robot announces itself when it is added to the Wave. Additionally, whenever I submit a Blip (for e.g. Hello), it simply appends a new blip with some text.

Simple Robots are also those that can modify the Blip Text instead of appending a new blip. For e.g. They could read the blip text and filter out the profanities, do automated spell checks or simply add some information to the existing Blip Text itself. In other words, it modifies the Blip Text.

Shown below is an example of a Simple Robot that modifies the Blip Text:

In the above wave, there are two participants (myself and the Robot). The Robot announces itself when it is added to the Wave. Additionally, whenever I submit a Blip (for e.g. Hello), it simply modifies the Blip Text by mentioning when I submitted the Blip text.

There is also a 3rd thing that the Simple Robots could do, which is very useful too. They can act in a stealth manner and simply do their work quietly. For e.g. whether you wish to write a Robot that appends a Blip or modifies a submitted Blip, you can simply chose not to append or modify but instead get the Blip text and do your work quietly. For e.g. count the words in the background, etc.

The WadRobotFramework also supports Advanced Robots, which are particularly interesting and will be covered in the Next Episode.

Advanced Robots are those that can react to commands in the Blips. Here are some samples of Advanced Robots and how they would react to commands from Blips:

1. A character Counting Advanced Robot:

Your submitted Blip Text contains : “Here is some text in the blip. Please count the length of this message for me. {mycountingrobot:count}”.

You can write an advanced Robot (mycountingrobot) that knows how to count the length of the message. So it gets notified when it there is a command (count) in the Blip. Your Advanced Robot can then count out the characters and then either append or modify a blip as needed.

2. A Tweeting Robot:

Your submitted Blip Text contains the following text : “{mytweetingrobot:tweet}

You can write an advanced Robot (mytweetingrobot) that knows how to tweet the message to Twitter. So it gets notified when it there is a command (tweet) in the Blip. Your Advanced Robot can then append a blip or modify a blip saying that the message has been tweeted.

The best part of it all is that you could combine all of this into a single Robot that can respond to one or more commands. For example, take a look at Today’s Special Robot (see http://ppandhi.wordpress.com/2009/11/08/todays-special-robot/) that can respond to more than one command. It can give you the quotes, day in history, word of the day, cricket score, your daily horoscope by simply responding to the command that you type in. With the WadRobotFramework, we shall see in the next episode how you can write such an Advanced Robot that responds to different commands. If you cannot wait, take a look at the documentation at the site (Advanced Robots).

Since this episode will be focusing on Simple Robots, let us recap what we know so far:  The WadRobotFramework supports Simple Robots in two flavours: The BlipAppenderRobot and the BlipModifierRobot. The BlipAppenderRobot is used to simply append to a Blip. The BlipModifierRobot is used to modify a submitted Blip.

Simple, isnt it? Lets develop and deploy our Simple Robots using the WadRobotFramework.

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 MyGoogleWaveRobot and I suggest you go with the same name so that things are consistent with the rest of the article (but if you wish to name it something else, that is fine too). 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 and WadRobotFramework JAR file 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-INFlib 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:

ep7-6

Download all the above files to your machine.

The WadRobotFramework JAR file is available at the following location :

http://code.google.com/p/wadrobotframework/downloads/list

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

Once you have downloaded the files, follow these steps to setup your Project Build Path and runtime correctly.

1. Copy all the 5 JAR files to the WEB-INFlib folder of your Eclipse Project. After copying you should see the files as shown in the project hierarchy below:

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 5 JAR files from your Project WEB-INFlib folder.

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 and WadRobotFramework JAR files.

Writing the Simple Robot: MyAppenderRobot : MyAppenderRobot.java

Let us first create our Simple Robot Java class based on the WadRobotFramework. This Simple Robot is the one that will react to a new Blip. So all we will do is to make the robot append to the blip, when the blip is submitted. The Robot demonstrated here will be straightforward and you can easily modify it to make it react in your own way.

As discussed, this is known as the BlipAppenderRobot and so all we need to do is to extend the BlipAppenderRobot class in the WadRobotFramework and provide our simple implementation.

The steps are straightforward and given below. All we need to do is write our class that extends the org.wadael.waverobotfrmwrk.simple.BlipAppenderRobot class and provide an implementation for the getTextToAppend method.

Follow these steps:

1. Create a new Java class within the same package. The New Java Class dialog is shown below. I have named the class MyAppenderRobot as shown below. Click on the Browse button to select a Super Class.

2. In the Superclass Selection dialog shown below, type the word BlipAppenderRobot (some part of it is also OK as the screenshot shows below) in the Choose a type field as shown. This will bring up the correct Matching items i.e. org.wadael.waverobotfrmwrk.simple.BlipAppenderRobot. Click on OK.


This will generate the code and you simply replace it with the following code listing given below:

 

package com.gaejexperiments.waverobot;

import org.wadael.waverobotfrmwrk.simple.BlipAppenderRobot;

public class MyAppenderRobot extends BlipAppenderRobot {

@Override
protected String getTextToAppend(String msg) {
return "I am appending some text too";
}

@Override
protected String getRobotSelfIntroduction() {
return "I am the Appender Robot";
}

}

 

Let us go through the code now:

1. We have extended the BlipAppenderRobot since all we want to do in this Robot is to react to the blip and append our own Blip

2. All we need to do as part of extending the BlipAppenderRobot class is to implement the getTextToAppend method. This method gets passed one parameter msg that is the blip text that was submitted. So in all essence, you could inspect what the text was in the blip submitted and then react to it.  The implementation simply returns the string that it wants to append. The WadRobotFramework’s BlipAppenderRobot will take care of creating a Blip and appending it to the current blip.

3. We also implement an optional method named getRobotSelfIntroduction. This method returns a string and  you can return something that identifies the addition of your Robot to the Wave. So when your Robot is added as a participant and if you have implemented the getRobotSelfIntroduction method, then it will display this message out. It is sort of announcing to the other wave participants about your presence.

That is all there is to implemented the MyAppenderRobot. If you would have studied the earlier tutorial on writing a Google Wave Robot, you would have noticed that the WadRobotFramework has done away with all the Event processing that you had to handle yourself and also shielded you from methods that you need to know to create a blip and append to it.

Configuring the MyAppenderRobot in web.xml

We need to add the MyAppenderRobot  in the <servlet/> and <servlet-mapping/> entry to the web.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>MyAppenderRobot</servlet-name>
<servlet-class>com.gaejexperiments.waverobot.MyAppenderRobot</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>MyAppenderRobot</servlet-name>
<url-pattern>/_wave/robot/jsonrpc</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.

Creating the MyAppenderRobot capabilities.xml files

We need an additional file to describe the capabilities of the Robot that we have written. This file is called the capabilities.xml and it needs to reside in a certain location. You need to create a _wave directory inside of the war directory of your project. The location of this file is  war/_wave directory.

You will need to create the _wave directory and create the capabilities.xml file over there. The capabilities file shown below is pretty straightforward and is shown below:

 

<?xml version="1.0" encoding="utf-8"?>
<w:robot xmlns:w="http://wave.google.com/extensions/robots/1.0">
<w:capabilities>
<w:capability name="BLIP_SUBMITTED" content="true" />
</w:capabilities>
<w:version>1</w:version>
</w:robot>

 

There are two elements of interest over here.

The <capability> element is of particular interest and we have registered for the BLIP_SUBMITTED event. This is important because it informs Google Wave that whenever a BLIP is submitted by a participated, then our Robot needs to be notified of it. The WadRobotFramework will notify the Robot by invoking the getTextToAppend method.

The other element is the <version> element. If you change any capabilities in your robot, then it is recommended that before you deploy, you change the version value over here, so that Google Wave can detect that there is a newer version and hence it can then query for your modified capabilities if any.

Writing our MyAppenderRobot Profile Servlet (not required but nice)

This is not a required step but it would be good practice to do so to make your Robot look more professional. A Profile Servlet is used to tell the following about your Robot:

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.

This profile information needs to be provided by you by writing a Profile Servlet. The Profile Servlet is nothing but extending the com.google.wave.api.ProfileServlet class and providing simple implementations for the overwritten methods.

Follow these steps to write the Profile Servlet:

1. Create a new Java class within the same package. Name the classs MyRobotProfileServlet and mention the Superclass as com.google.wave.api.ProfileServlet class. Click on OK.

2. This will generate a MyRobotProfileServlet.java file.

The simplest way to generate the stubs for the required methods would be to go to Source –> Override/Implement Methods. This will bring up the dialog box as shown below and you only need to select the 3 methods to override as shown:

ep7-14

Click on OK. This will generate the stubs, which you can then overwrite with the code shown below. The code is easy to understand, all we are doing is providing values for the Name, Avatar(Image) and the Profile Page URL. Note that for the Avatar, we are providing a file myimage.jpg present in the WAR/_wave folder. You will need to copy an appropriate image file for yourself and make sure that it is physically copied to the folder locally in your Eclipse project before you deploy your application.

I have used my AppId as myinfoagent but you can replace it with your AppId.

 

package com.gaejexperiments.waverobot;

import com.google.wave.api.ProfileServlet;

public class MyRobotProfileServlet extends ProfileServlet {

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

@Override
public String getRobotName() {
return "MyRobot";
}

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

}

Configuring the Profile Servlet

We need to add the Profile Servlet <servlet/> and <servlet-mapping/> entry to the web.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>MyRobotProfileServlet</servlet-name>
<servlet-class>com.gaejexperiments.waverobot.MyRobotProfileServlet</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>MyRobotProfileServlet</servlet-name>
<url-pattern>/_wave/robot/profile</url-pattern>
</servlet-mapping>

In the above fragment, you will note that url-pattern /_wave/robot/profile has to be mapped to the Profile Servlet that you have written. This is because the Google Wave system will invoke this url to get hold of your profile.

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

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 myinfoagent]
  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”.

MyAppenderRobot in Action

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

You can test for the presence of your robot capabilities file by simply typing in the following:

http://yourapplicationid.appspot.com/_wave/capabilities.xml [Replace yourapplicationid with the Application ID that you have] and you should see the capabilities.xml file being served up.

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. 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 myinfoagent@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). It announces itself and this was done via the implementation that we provided in the getRobotSelfIntroduction method.

Now I type a message “Hello” as shown below and click on the Done button, the BLIP_SUBMITTED event is fired and our Robot gets the event i.e. the getTextToAppend method is invoked on our Robot Java class. The method simply appends a blip as shown below:

Writing another Simple Robot: MyBlipModifierRobot : MyBlipModifierRobot.java

We saw how easy it was to create our Simple Robot that simply appended a blip to the wave conversation when a blip was submitted. Let us now write another Simple Robot that will modify the Blip Text when the blip is submitted.

As discussed, this is known as the BlipModifierRobot and so all we need to do is to extend the BlipModifierRobot class in the WadRobotFramework and provide our simple implementation.

The steps are straightforward and given below. All we need to do is write our class that extends the org.wadael.waverobotfrmwrk.simple.BlipModifierRobot class and provide an implementation for the modifyBlipText method.

Follow these steps:

1. Create a new Java class within the same package. Name it  MyBlipModifierAppenderRobot as shown below and mention the superclass as org.wadael.waverobotfrmwrk.simple.BlipModifierRobot

This will create the MyBlipModifierRobot.java file and you can replace it with the following source:

 

package com.gaejexperiments.waverobot;

import java.util.Date;
import org.wadael.waverobotfrmwrk.simple.BlipModifierRobot;

public class MyBlipModifierRobot extends BlipModifierRobot {

@Override
protected String modifyBlipText(String originalBlipText) {
return originalBlipText + " [You typed this at :" + new Date().toString() + "]";
}

@Override
protected String getRobotSelfIntroduction() {
return "I am the Blip Modifier Robot";
}

}

 

Let us go through the code now:

1. We have extended the BlipModifierRobot since all we want to do in this Robot is to modify the Blip that was submitted.

2. All we need to do as part of extending the BlipModifierRobot class is to implement the modifyBlipText method. This method gets passed one parameter originalBlipText that is the blip text that was submitted. So in all essence, you could inspect what the text was in the blip submitted and then modify it as needed .  The implementation above appends the text “You typed this at [DateTimeStamp]” to the originalBlipText and simply returns that string. The WadRobotFramework’s BlipModifierRobot will take care of modifying the Blip Text.

3. We also implement an optional method named getRobotSelfIntroduction. This method returns a string and  you can return something that identifies the addition of your Robot to the Wave. So when your Robot is added as a participant and if you have implemented the getRobotSelfIntroduction method, then it will display this message out. It is sort of announcing to the other wave participants about your presence.

That is all there is to implemented the MyBlipModifierRobot. If you would have studied the earlier tutorial on writing a Google Wave Robot, you would have noticed that the WadRobotFramework has done away with all the Event processing that you had to handle yourself and also shielded you from methods that you need to know to create a blip and append to it.

Configuring the MyBlipModifierRobot in web.xml

We need to add the MyBlipModifierRobot  in the <servlet/> and <servlet-mapping/> entry to the web.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>MyBlipModifierRobot</servlet-name>
<servlet-class>com.gaejexperiments.waverobot.MyBlipModifierRobot</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>MyBlipModifierRobot</servlet-name>
<url-pattern>/_wave/robot/jsonrpc</url-pattern>
</servlet-mapping>

 

If you wish to check out this Robot in action, you can do so with the same project. Simply replace the previous Robot’s (MyAppenderRobot) servlet entries with the one shown above. And deploy the application following the same steps in the Deploying the Application section. Leave the Profile Servlet and the capabilities.xml file as is because the same applies in this case too.

Once you deploy the MyBlipModifierRobot, you should see it in action as shown below. The first screen shows the MyBlipModifierRobot announcing itself and then the second screen shows how it modified the blip text that I submitted by appending the TimeStamp to it.

Conclusion

This concludes Episode 11 of the series. We saw how easy it was to write Simple Google Wave Robots using the WadRobotFramework. Several Google Wave Robots that are out there simply do one of the things that we have seen in this episode i.e. modify a blip’s contents or append a blip in reaction to a blip submitted. You can get going with such Robots by using this framework which hides you from the underlying Google Wave API.

In the next episode, we shall see how to write an Advanced Google Wave Robot that can implement several commands. Till then, unleash those Simple Robots!

In the Superclass Selection dialog shown below, type the word AbstractRobot (some part of it is also OK as the screenshot shows below) in the Choose a type field as shown. This will bring up the correct Matching items i.e. com.google.wave.api.AbstractRobotServlet. Click on OKep7-8

About these ads

About rominirani

Google Developer Expert Cloud 2014. Harnessing the power of software by learning, teaching and developing simple solutions. I love learning about new technologies and teaching it to others.
This entry was posted in Cloud Computing, Google App Engine. Bookmark the permalink.

10 Responses to Episode 11: Develop Simple Google Wave Robots using the WadRobotFramework

  1. Wadael says:

    Romin,

    Thank you for this article.
    Very clear as always.

    I’m glad you like my little framework.

    I add a link to this tutorial on the website.

    Jérôme

  2. Pingback: uberVU - social comments

  3. Pingback: Twitted by joomlacorner

  4. rominirani says:

    Jerome – Thanks for the feedback.

  5. Pingback: Episode 12 : Writing an Advanced Google Wave Robot using WadRobotFramework « Google App Engine Java Experiments

  6. Pingback: Twitted by TBGoogleWave

  7. David Cox says:

    Romin,

    Thanks for this tutorial. I was able to use these instructions to successfully develop a Google Wave Java Robot in Netbeans 6.7. I have created a blog post with details on how to do this. http://coxydave.blogspot.com/2009/12/google-wave-development-robots-in.html.

    Thanks again for your great GAEJ tutorials.

  8. Pamela Fox says:

    Today we launched a new version of the Robots API, and are effectively deprecating the old version, since the new one can do everything that the old one can, plus more.

    More info on the new API is in the launch blog post:
    http://googlewavedev.blogspot.com/2010/03/introducing-robots-api-v2-rise-of.html

    We are still linking to your article from the documentation “Articles” page, but we may remove the link soon, to reduce developer confusion and to encourage more use of the new API.

    We hope that you will find the time to try out this new API and port your article to utilize it, so that developers can continue learning from you. If you do port your article, please let us know.

    We also hope you like this new API. :)

    Thanks!

  9. Pingback: Google Wave Programming Articles Update « Google App Engine Java Experiments

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s