jbot-user-guide.doc - Java

bossprettyingΔιαχείριση Δεδομένων

28 Νοε 2012 (πριν από 4 χρόνια και 6 μήνες)

334 εμφανίσεις


i






JBot

User Guide


A Java IRC Bot





Home Page:
https://jbot.dev.java.net/


IRC: EFNet #java

ii


1

Introduction

................................
................................
................................
..........................

1
-
1

1.1

Why Another Bot Implementation?

................................
................................
.............

1
-
1

2

Deployment

................................
................................
................................
..........................

2
-
1

2.1

Compiling JBot

................................
................................
................................
............

2
-
1

2.2

Configuring JBot

................................
................................
................................
..........

2
-
1

2.3

Running JBot

................................
................................
................................
...............

2
-
3

2.4

Configuring Plugins

................................
................................
................................
.....

2
-
4

2.4.1

Bullshit

................................
................................
................................
....................

2
-
4

2.4.2

Command

................................
................................
................................
...............

2
-
4

2.4.3

Ebonify

................................
................................
................................
....................

2
-
4

2.4.4

Factoid

................................
................................
................................
....................

2
-
4

2.4.5

Google

................................
................................
................................
....................

2
-
4

2.4.6

Idle

................................
................................
................................
..........................

2
-
4

2.4
.7

Insult
................................
................................
................................
........................

2
-
4

2.4.8

Javadoc

................................
................................
................................
...................

2
-
4

2.4.9

Karma
................................
................................
................................
......................

2
-
4

2.4.10

Nickometer

................................
................................
................................
..............

2
-
4

2.4.11

Regex

................................
................................
................................
......................

2
-
5

2.4.12

Seen

................................
................................
................................
........................

2
-
5

2.4.13

Statistics

................................
................................
................................
..................

2
-
5

2.4.14

Time

................................
................................
................................
........................

2
-
5


2
-
1


1

Introduction

JBot is a Java
-
based IRC robot that provides functionality through dynamically loadable plugin
modules. The core kernel of JBot supplies IRC conn
ectivity, event management, plugin
management, user management, and response handling.


1.1

Why Another Bot Implementation?

A while ago, EFNet #java used to be entertained by an Infobot (
http://www.infobot.org/
) named
“jjava”. Infobot is written in Perl and pr
ovides a fun feature called factoids. The bot would key in
on phrases of the form,
key
phrase + (is|are) +
value
phrase.

For example: “Java is fun”.

It
would store the
key and value phrases and when some said something like, “What is Java?” the
bot woul
d respond with “Java is fun”.

The problem with Infobot was t
hat is wasn’t very modular


it
s components were fairly tightly
coupled


and it was written in Perl. After trying to coax Infobot to perform features it wasn’t
designed to handle (such as permis
sion
-
based factoid management), I decided to write my own
bot implementation. Additionally the tight coupling made it difficult to easily add or remove
functionality. This theme of tightly coupled feature sets continued with every bot implementation I
sa
w.

After some discussion on #java, I chose to base the first version on Pircbot
(
http://www.jibble.org/pircbot.php
) and implement a loosely coupled plugin architecture where
feature sets could be added or
removed by the bot owner based on their needs.

The first feature
sets I added were a time plugin (which acted as a “hello world” example plugin), a factoid plugin
to provide the same features as Infobot,
a karma plugin to track user karma,
and a command
p
lugin

to provide permission
-
based command handling from users to bot via the IRC channel.
Soon other #java users authored additional plugins from the Google search plugin to the
politically incorrect ebonify (English to Ebonics translator) plugin.

2

Deploym
ent

This guide will attempt to explain everything necessary to compile, configure, and run JBot.

2.1

Compiling JBot

JBot is compiled by running ant (
http://ant.apache.org/
) in the base directory of the project. The
buil
d.xml

ant script details the various build tasks, but running ant without a specific task
invokes the ‘all’ task which builds everything including the distribution zip file.

2.2

Configuring JBot

JBot is configured by modifying the
etc/jbot.properties

file.

Th
e following sections
describe all the currently supported JBot properties.


irc.proxy.class = jbot.proxy.PircbotProxy


The
irc.proxy.class

property declares which IRC implementation to instantiate to
communicate with the IRC server. Use a fully qualified
class

name which can be found via the
CLASSPATH

used when invoking JBot.


2
-
2


irc.servers

=

irc.choopa.net:6667 irc.blessed.net:6667

\


irc.he.net


The
irc.servers

property declares which IRC servers to attempt to use to connect to IRC.
Each serv
er is delimited by spaces and can be continued on following lines by using the
property
file continuation character
(

\

)

as the last character on the preceding line. IRC servers are
defined using the format:

servername[:port[:password]]

One server is con
nected to at a time. If a connection cannot be established or if disconnected,
JBot will move to the next server in the list and try to connect to it. If the last server is reached,
the connection manager starts again at the beginning of the list.


irc.n
ame

=

jbotv2


The
irc.name

property declares the IRC nickname by which this bot will be known.


irc.login

=

jbotuser


The
irc.login

property is the login name by which this bot will be known. This is typically the
user name of the user that is running the

bot.


irc.channels

= #jbottest2 #jbottest3


The
irc.channels

property declares one or more channels that

JBot will attempt to join upon
connecting with an IRC server.

Channel names are space
-
delimited and may span multiple lines
as long as the properties

file continuation character (‘
\
’) is the last character on the preceding line.


irc.connection.failures = 5


The
irc.connection.failures

property defines the number of times JBot will attempt to
connect before aborting. A value of zero means JBot will ne
ver abort and will continuously cycle
through the list of IRC servers attempting to connect. This number should be at least as large as
the number of servers or else JBot won’t attempt to connect to all of the servers. Server
connections are attempted on
e time before moving on to the next server.


addressing.mode = 1


The addressing.mode property defines the default method in which plugins will react to a public
message. If 0, the default plugin behavior will be to process every message it receives wheth
er
or not the bot has been addressed.

If the bot has not been addressed and its nickname does not
appear anywhere in the message, then only plugins with an addressing mode of 0 will process

2
-
3

this message.

A value of 1 indicates that a plugin should only r
espond if directly addressed.
Direct addressing appears as follows:

fate
-
sg> jbotv2, time

This snippet shows IRC user “fate
-
sg” asking the bot (nickname “jbotv2”) what time it is.

Plugins
with addressing modes of 0, 1, or 2 will respond to it.

If addres
sing.mode is 2 then the bot will
respond if its nickname appears anywhere in a public message. For example,


j
oeblow
_
gt>
I think this jbotv2 code is competent

When this message is received by JBot, plugins with addressing mode of 0 or 2 will respond to it.

Note that, typically, plugins will override the
addressing.mode

property.


plugins.directory = plugins


The
plugins.directory

defines the subdirectory from the JBot root directory (from which JBot
is executed) where the plugin manager will look for plugin
s.


# Plugin overrides


The method in which plugins are loaded allows properties defined in the plugin’s
jbot
-
plugin.properties

file to be overridden by identically named properties in the
jbot.properties

files. This way,
jbot.properties
, is the only prop
erties file a user need
change when deploying their own JBot.
This section is typically empty in a default JBot
installation. Below is an example of overridden plugin properties:


statistics.database.driver =
org.postgresql.Driver

statistics.database.c
lass = jbot.plugin.statistics.StatisticsJDBC

statistics.database.url

=
jdbc:postgresql://localhost/jjava

statistics.database.username = statistics

statistics.database.password = jBot314

statistics.collection.period = 15

statistics.ignore=joeblowgt

statistics.alias.1=tdrury joeblowg_ joeblowgg


The above example shows how the statistics plugin does not use the default Mckoi embedded
database to store user and channel statistics, but, instead uses a PostgreSQL database to store
the statistics. The co
llection period has been reduced from the default 30 minutes to 15 minutes
and an alias has been defined. The statistics for nickname “tdrury” will be combined with the
statistics from nicknames “joeblowg_” and “joeblowgg” under the nickname “tdrury”. T
he
nickname “joeblowgt” will be ignored by the statistics plugin. (Note: the ignore and alias features
came about from some asshat hijacking my long used nickname, “joeblowgt”)

2.3

Running JBot

A sample Windows command script has been supplied to show all tha
t is needed to run JBot.


set CP=lib/jbot.jar;lib/pircbot.jar;etc

java
-
cp %CP%
-
Djava.util.logging.config.file=etc/logging.properties

\


2
-
4



jbot.JBotImpl


The variable
CP

is used to define the JBot
CLASSPATH
. The
jbot.jar

obviously must be
included. Si
nce we’ve defined the Pircbot proxy to provide IRC connectivity, the
pircbot.jar

file must also be included. Lastly, the
etc/

subdirectory is included which allows JBot to find its
jbot.properties

file and the
logging.properties

file.

2.4

Configuring Plugins

Each plugin has its own properties file defined in the plugin jar in a file named
META
-
INF/jbot
-
plugin.properties
. Typically, these properties will never change. If they should be modified,
it is recommended they be overridden by defining the same proper
ty name in the JBot properties
file,
jbot.properties

and assigning the new value to it there.

2.4.1

Bullshit

tbd

2.4.2

Command

tbd

2.4.3

Ebonify

tbd

2.4.4

Factoid

tbd

2.4.5

Google

tbd

2.4.6

Idle

tbd

2.4.7

Insult

tbd

2.4.8

Javadoc

tbd

2.4.9

Karma

tbd

2.4.10

Nickometer

tbd


2
-
5

2.4.11

Regex

tbd

2.4.12

Seen

tbd

2.4.13

Statistics

tbd

2.4.14

Time

tbd