Running Javabot

NOTE: This page is outdated. Update is pending.

Browsing the source code online

Can I browse the source-code online?
Yes, you can do that here.

Building Javabot

First, you should already have checked out the source code from subversion using the following command:

A lot of text will scroll on your screen, this is subversion checking out all the files from the repository.

Now, that you have your source-code, type the following in a command-prompt:

  • cd fn-javabot/javabot

You are not in the root directory where the ant build.xml file resides. At this point, please make sure that you have Apache Ant installed. This tutorial will not cover this, please refer to the documentation on the Apache Ant site.

Now type:

  • ant war

You should see the following in some form
Buildfile: build.xml

deps:

init:

main: 

    [javac] Compiling 20 source files to /home/rob/fn-javabot/javabot/build/test

war: 

     [copy] Copying 1 file to /home/rob/fn-javabot/javabot/build/war
     [copy] Copying 1 file to /home/rob/fn-javabot/javabot/build/war/WEB-INF/classes
      [jar] Building jar: /home/rob/fn-javabot/javabot/build/javabot.war

BUILD SUCCESSFUL Total time: 8 seconds

What occurs is ant downloads all of javabot's dependencies, compiles the code, and creates a WAR file suitable for deploying within a servlet container such as jetty or tomcat.

You now have a war file, it is now time to deploy it. Javabot runs inside of a servlet context, and is started from an admin web interface.

Deploying to Apache Tomcat

I assume you have apache tomcat downloaded.

  • Copy javabot.war to the webapps directory.
  • From a command prompt or terminal window, cd to the tomcat directory.
  • On Windows, type bin/startup.bat
  • On Non-windows systems, type bin/startup.sh

Now, proceed to the "Starting javabot" section of this tutorial, as the war has already been deployed.

Deploying to Jetty

NOTE: For the purposes of this tutorial replace jetty with the name of the directory which you extracted to. Example: jetty to jetty-6.1.11/...

  • Download Jetty
  • Unzip it
  • move the javabot.war file, the path will be given to you when you run ant, as you've seen above and drop it in the webapps directory of jetty.

Next, you will need to delete two directories from the jetty-6.1.4rc1/webapps directory:

  • test
  • test-jaas

Also, delete the contents of jetty/contexts, BUT DO NOT delete the directory itself.

Completely remove jetty/webapps-plus.

These are not needed for the purpose of deploying javabot.

Now, copy javabot.war to the jetty webapps directory.

Starting jetty is easy. I'm going to assume that you just unzipped it to your home directory, (that is it's not installed globally).

If you're running GNU/Linux, *BSD, or Mac OSX just execute the following:

  • sh ~/jetty/bin/jetty.sh start

On windows, there is an NT service that you can install to run jetty as an NT service. These instruction assume you unzipped it to your My Documents directory. Replace username with your username.

  • cd C:\Documents and Settings\username\My Documents\jetty\bin
  • type Jetty-Service.exe

Starting javabot

Now, go to http://localhost:8080/javabot/admin, enter the username cheeser and the password cheeser, these are the default username/password pair to login to the administrative interface. Once logged in, you can add an admin with your own username and password.

The homepage is located at http://localhost:8080/javabot/javabot/home.

  • You can replace localhost with your IP Address. Just be sure to open the ports on your router if you're behind one.

Why do you have "javabot/javabot/home"?
The reason is, is that the servlet container uses the name of the war as its default context, then the deployment descriptor uses /javabot as a context, so this is why you see "javabot/javabot."

Now you've got javabot deployed, and running within jetty. Your next question is probably, how do I use this thing? Am I right? Well, I'm going to show you.

First, you'll want to go to the admin interface. And set up your bot, and start it up.

Javabot doesn't have plugins per se, rather it has operations. This is our way of allow you to extend javabot's functionality in a pluggable way. They're inside in the javabot.operations package. For specifics about they work, you can refer to the source code. It is assumed that you have basic java knowledge.

  • AolBonicsOperation is an operation that outputs a snarky comment each time it encounters a predefined "aolbonic."
  • DaysUntilChristmasOperation is an operation that displays how many days until Christmas.
  • DaysUtilOperation is an operation that displays how many days until a specific date is reached.
  • DictOperation allows you to retrieve dictionary entries from http://dictionary.reference.com. [CURRENTLY BROKEN!]
  • ForgetFactoidOperation allows removal of factoids from the database.
  • GoogleOperation allows you to generate a search query for google, giving you the url such: http://www.google.com/search?q=foo
  • GuessOperation enables the bot to guess what the users meant when they pull a factoid.
  • IgnoreOperation allows you to make the bot ignore a specific user.
  • InfoOperation allows you to retrieve information about who added factoids (the metadata).
  • JavadocOperation allows you to pull the URL to the javadoc (API) pages. Only supports Java 6 SE, not Java 5 EE.
  • KarmaChangeOperation allows you to increment or decrement a specific person's karma.
  • KarmaReadOperation allows you check the karma of a specific person.
  • LeaveOperation allows the bot to leave the channel.
  • LiteralOperation allows you to pull the factoid as it is in the database.
  • Magic8BallOperation acts exactly like a magic8 ball.
  • NickometerOperation allows you to check the lameness of a nick.
  • QuitOperation makes the bot quit from irc and terminate.
  • Rot13Operation performs a ROT13 (Caesar cipher) operation on the text given.
  • SayOperation makes the bot say something.
  • SeenOperation allows you to determine the last time a person was seen in the channel.
  • SpecialCasesOperation is a miscellaneous operation which provides "no, ..." operations and calls the other operations. You can just select this one.
  • StatsOperation displays uptime and other statistical information.
  • TellOperation redirects output to a specific user.
  • TimeOperation displays the current date/time.
  • UnixCommandOperation while this operation is loaded, if you type a unix command the bot will make a snarky remark in the channel.

Configuring the bot using the admin interface

  1. Add an admin: enter the username and password and click "Add Admin" (Currently, you can only ADD an admin, not edit.)
  2. Enter the server to connect to, bot's nick, nickserv password, and response prefix.
  3. Next, select the operations you wish to load at startup. However, DO NOT check DictOperation.
  4. Now, click "Save" (this will save your configuration to the database)
  5. The next step, you need to add channels to which the bot will be in. Enter the channel into the text field.
  6. Now, click "Add Channel." (Remember: It is rude to put your bot into channels which you do not have permission to do so.); Tick the checkbox under "Logged" next your channel underneath the "Channels Configured" table if you want the channel to be logged.
  7. Finally, click "Start," your bot will now connect to IRC and join the channels you have configured. It will also start logging immediately.

Using the web interface

Your bot should be running by now, and you should feel good at this point. Great Job!

Javabot homepage!

The homepage that is displayed when you go to the webpage.

Left panel contains the logged channels. The right contains links to the other pages.

Explaination of each page

  • Factoids is web front-end in which you can view all of the factoids.
  • Karma Ranking is a page in which you can view the karma ranking (DUH!)
  • ChangeLog is every change that has been made to the factoids database (this includes karma changes)

A few final things

  • DO NOT place your bot into ##java, it's not allowed there.
  • Always ask the owners of the channel you are in if you can place your bot there.
  • Never try to conceal the fact that you own your bot.
  • Above all, enjoy the bot!
  • To kill the bot, in a private message with the the bot, type quit nickservpass (replace nickservpass with the password you used for NickServ) However, for this to work, you MUST have QuitOperation loaded.

Writing additional operations for javabot

A quick tutorial with an example operation can be found here. It also explains the mechanics behind how they work.

If you have ANY questions, please ask, my /nick is r0bby.