Eclipse Communication Framework (ECF)
Create an IRC bot
A bot is a useful daemon application for a user to automate tasks similar to a
script or a macro. An IRC bot is generally a bot that sits in an IRC channel
and performs tasks such as answering to commands and logging. This tutorial
will explain how to create an IRC bot using the bot framework.
Requirements
As regular expression pattern matching is used, a Java runtime environment of
1.4.2 or higher is required.
Project Setup
Dependencies
- Create a 'Plug-in Project' like how you normally would. Since this is a
bot that will be run in headless mode, we do not need any UI components. You do
not even need an activator class.
- Open the 'MANIFEST.MF' file and go to the 'Dependencies' tab.
- Add 'org.eclipse.ecf', 'org.eclipse.ecf.presence', and
'org.eclipse.ecf.presence.bot' as a 'Required Plug-in'.
- Now add 'org.eclipse.core.runtime' as an 'Imported Package'.
MANIFEST.MF
Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: Geir Plug-in
Bundle-SymbolicName: org.eclipse.ecf.example.geir;singleton:=true
Bundle-Version: 1.0.0
Require-Bundle: org.eclipse.ecf,
org.eclipse.ecf.presence,
org.eclipse.ecf.presence.bot
Import-Package: org.eclipse.core.runtime
Extensions
- Open the 'Extensions' tab.
- Add the 'org.eclipse.ecf.presence.bot.chatRoomRobot' and the
'org.eclipse.ecf.presence.bot.chatRoomMessageHandler' extension point.
- Select the 'org.eclipse.ecf.presence.bot.chatRoomRobot' extension.
- Fill in something unique for your 'id'. 'org.eclipse.ecf.example.bot.geir2'
- Fill in 'ecf.irc.irclib' for your 'containerFactoryName'.
- For the 'connectId', select an IRC server of your choice and a name for the
bot. 'irc://geir2@irc.freenode.net'
- For the 'chatRoom' field, pick the channel that you want your bot to join
upon successful connection to the server above. '#eclipse'
- Now select the 'org.eclipse.ecf.presence.bot.chatRoomMessageHandler' extension point.
- For your 'id', copy the same 'id' that you filled in above.
'org.eclipse.ecf.example.bot.geir2'
- In 'filterExpression', enter a regular expression that should be matched
for parsing purposes for your bot. '(~bug[0-9]*)
- Click on the 'class*' hyperlink and then create a new class that implements
the 'org.eclipse.ecf.presence.bot.IChatRoomMessageHandler' interface. For this
example, I will assume that your class's name is 'Geir2Bot' under the
'org.eclipse.ecf.example.bot' package..
plugin.xml
<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.2"?>
<plugin>
<extension
point="org.eclipse.ecf.presence.bot.chatRoomMessageHandler">
<handler
chatRoomRobotId="org.eclipse.ecf.example.bot.geir2"
class="org.eclipse.ecf.example.bot.Geir2Bot"
filterExpression="(~bug[0-9]*)">
</handler>
</extension>
<extension
point="org.eclipse.ecf.presence.bot.chatRoomRobot">
<chatRoomRobot
connectId="irc://geir2@irc.freenode.net"
containerFactoryName="ecf.irc.irclib"
id="org.eclipse.ecf.example.bot.geir2">
<chatRooms
name="#eclipse"<
>/chatRooms<
</chatRoomRobot>
</extension>
</plugin>
Writing the Code
- Open the 'Geir2Bot' class that you have created.
- Since we want our bot to be able to say something, we need to retrieve an
interface that will provide us with such a functionality.
- Add a field to the class of type 'IChatMessageSender'.
- We will retrieve our instance in the
'preChatRoomConnect(IChatRoomContainer, ID)' method. This method will be called
right before our bot joins the channel (#eclipse in our case). You can retrieve
an instance of an IChatMessageSender by calling 'getChatRoomMessageSender()' on
the provided 'IChatRoomContainer' instance.
- Now that our bot has a mechanism for replying, we should write some code to
parse the messages that the bot receives so that it can give a correct response.
To get the string that's been said, use the 'getMessage()' method from the
'IChatRoomMessage' interface that's passed into the
'handleRoomMessage(IChatRoomMessage)' method.
- Our regular expression of '(~bug[0-9]*)' implies that any string beginning
with ~bug followed by any number of digits will be a valid input for our bot to
read. So let's add some string handling code to route people to Eclipse's
bugzilla when they type something like ~bug150000 or ~bug180078.
- To send a reply to the IRC channel, simply use IChatRoomMessageSender's
'sendMessage(String)' method. This method will throw an 'ECFException', but
given this simple scenario, we won't bother to handle it.
org.eclipse.ecf.example.bot.Geir2Bot
package org.eclipse.ecf.example.bot;
import org.eclipse.ecf.core.IContainer;
import org.eclipse.ecf.core.identity.ID;
import org.eclipse.ecf.core.util.ECFException;
import org.eclipse.ecf.presence.bot.IChatRoomBotEntry;
import org.eclipse.ecf.presence.bot.IChatRoomMessageHandler;
import org.eclipse.ecf.presence.chatroom.IChatRoomContainer;
import org.eclipse.ecf.presence.chatroom.IChatRoomMessage;
import org.eclipse.ecf.presence.chatroom.IChatRoomMessageSender;
public class Geir2Bot implements IChatRoomMessageHandler {
private IChatRoomMessageSender sender;
public void handleRoomMessage(IChatRoomMessage message) {
// use substring 1 to just truncate the opening tilda (~)
String msg = message.getMessage().substring(1);
try {
if (msg.equals("bug")) { //$NON-NLS-1$
// if no number was provided, just send them to bugzilla
sender.sendMessage("https://bugs.eclipse.org/bugs/"); //$NON-NLS-1$
} else {
// otherwise, give the person a direct link to the bug
sender.sendMessage("https://bugs.eclipse.org/bugs/" //$NON-NLS-1$
+ "show_bug.cgi?id=" + msg.substring(3)); //$NON-NLS-1$
}
} catch (ECFException e) {
e.printStackTrace();
}
}
public void init(IChatRoomBotEntry robot) {
// nothing to do
}
public void preChatRoomConnect(IChatRoomContainer roomContainer, ID roomID) {
sender = roomContainer.getChatRoomMessageSender();
}
public void preContainerConnect(IContainer container, ID targetID) {
// nothing to do
}
}
Running the Example
- Open the 'Run' dialog and then right-click on 'Eclipse Application' and
select 'New'.
- From the combo drop down in the 'Program to Run' section, select 'Run an
pplication:' and choose 'org.eclipse.ecf.presence.bot.chatRoomRobot'.
- Click on the 'Plug-ins' tab.
- From the top, select 'plug-ins selected below only' from the drop down box.
- Pick the plug-in you created (in the example, this was
'org.eclipse.ecf.example.geir') and 'org.eclipse.ecf.provider.irc'.
- Click on the '''Add Required Plug-ins''' button on the right and then hit
'Run'.
- Moments later, your bot should appear in the server and channel that you
specified in the 'plugin.xml' file.
* geir2 (n=geir2@bas3-kitchener06-1096650252.dsl.bell.ca) has joined #eclipse
<user> ~bug
<geir2> https://bugs.eclipse.org/bugs/
<user> ~bug76759
<geir2> https://bugs.eclipse.org/bugs/show_bug.cgi?id=76759