PircBot Java IRC Bot

org.jibble.pircbot
Class PircBot

java.lang.Object
  extended byorg.jibble.pircbot.PircBot
All Implemented Interfaces:
ReplyConstants

public abstract class PircBot
extends Object
implements ReplyConstants

PircBot is a Java framework for writing IRC bots quickly and easily.

It provides an event-driven architecture to handle common IRC events, flood protection, DCC support, ident support, and more. The comprehensive logfile format is suitable for use with pisg to generate channel statistics.

Methods of the PircBot class can be called to send events to the IRC server that it connects to. For example, calling the sendMessage method will send a message to a channel or user on the IRC server. Multiple servers can be supported using multiple instances of PircBot.

To perform an action when the PircBot receives a normal message from the IRC server, you would override the onMessage method defined in the PircBot class. All onXYZ methods in the PircBot class are automatically called when the event XYZ happens, so you would override these if you wish to do something when it does happen.

Some event methods, such as onPing, should only really perform a specific function (i.e. respond to a PING from the server). For your convenience, such methods are already correctly implemented in the PircBot and should not normally need to be overridden. Please read the full documentation for each method to see which ones are already implemented by the PircBot class.

Please visit the PircBot homepage at http://www.jibble.org/pircbot.php for full revision history, a beginners guide to creating your first PircBot and a list of some existing Java IRC bots and clients that use the PircBot framework.

Version:
1.4.6 (Build time: Wed Apr 11 19:20:59 2007)
Author:
Paul James Mutton, http://www.jibble.org/

Field Summary
static String VERSION
          The definitive version number of this release of PircBot.
 
Fields inherited from interface org.jibble.pircbot.ReplyConstants
ERR_ALREADYREGISTRED, ERR_BADCHANMASK, ERR_BADCHANNELKEY, ERR_BANNEDFROMCHAN, ERR_CANNOTSENDTOCHAN, ERR_CANTKILLSERVER, ERR_CHANNELISFULL, ERR_CHANOPRIVSNEEDED, ERR_ERRONEUSNICKNAME, ERR_FILEERROR, ERR_INVITEONLYCHAN, ERR_KEYSET, ERR_NEEDMOREPARAMS, ERR_NICKCOLLISION, ERR_NICKNAMEINUSE, ERR_NOADMININFO, ERR_NOLOGIN, ERR_NOMOTD, ERR_NONICKNAMEGIVEN, ERR_NOOPERHOST, ERR_NOORIGIN, ERR_NOPERMFORHOST, ERR_NOPRIVILEGES, ERR_NORECIPIENT, ERR_NOSERVICEHOST, ERR_NOSUCHCHANNEL, ERR_NOSUCHNICK, ERR_NOSUCHSERVER, ERR_NOTEXTTOSEND, ERR_NOTONCHANNEL, ERR_NOTOPLEVEL, ERR_NOTREGISTERED, ERR_PASSWDMISMATCH, ERR_SUMMONDISABLED, ERR_TOOMANYCHANNELS, ERR_TOOMANYTARGETS, ERR_UMODEUNKNOWNFLAG, ERR_UNKNOWNCOMMAND, ERR_UNKNOWNMODE, ERR_USERNOTINCHANNEL, ERR_USERONCHANNEL, ERR_USERSDISABLED, ERR_USERSDONTMATCH, ERR_WASNOSUCHNICK, ERR_WILDTOPLEVEL, ERR_YOUREBANNEDCREEP, ERR_YOUWILLBEBANNED, RPL_ADMINEMAIL, RPL_ADMINLOC1, RPL_ADMINLOC2, RPL_ADMINME, RPL_AWAY, RPL_BANLIST, RPL_CHANNELMODEIS, RPL_CLOSEEND, RPL_CLOSING, RPL_ENDOFBANLIST, RPL_ENDOFINFO, RPL_ENDOFLINKS, RPL_ENDOFMOTD, RPL_ENDOFNAMES, RPL_ENDOFSERVICES, RPL_ENDOFSTATS, RPL_ENDOFUSERS, RPL_ENDOFWHO, RPL_ENDOFWHOIS, RPL_ENDOFWHOWAS, RPL_INFO, RPL_INFOSTART, RPL_INVITING, RPL_ISON, RPL_KILLDONE, RPL_LINKS, RPL_LIST, RPL_LISTEND, RPL_LISTSTART, RPL_LUSERCHANNELS, RPL_LUSERCLIENT, RPL_LUSERME, RPL_LUSEROP, RPL_LUSERUNKNOWN, RPL_MOTD, RPL_MOTDSTART, RPL_MYPORTIS, RPL_NAMREPLY, RPL_NONE, RPL_NOTOPIC, RPL_NOUSERS, RPL_NOWAWAY, RPL_REHASHING, RPL_SERVICE, RPL_SERVICEINFO, RPL_SERVLIST, RPL_SERVLISTEND, RPL_STATSCLINE, RPL_STATSCOMMANDS, RPL_STATSHLINE, RPL_STATSILINE, RPL_STATSKLINE, RPL_STATSLINKINFO, RPL_STATSLLINE, RPL_STATSNLINE, RPL_STATSOLINE, RPL_STATSQLINE, RPL_STATSUPTIME, RPL_STATSYLINE, RPL_SUMMONING, RPL_TIME, RPL_TOPIC, RPL_TOPICINFO, RPL_TRACECLASS, RPL_TRACECONNECTING, RPL_TRACEHANDSHAKE, RPL_TRACELINK, RPL_TRACELOG, RPL_TRACENEWTYPE, RPL_TRACEOPERATOR, RPL_TRACESERVER, RPL_TRACEUNKNOWN, RPL_TRACEUSER, RPL_UMODEIS, RPL_UNAWAY, RPL_USERHOST, RPL_USERS, RPL_USERSSTART, RPL_VERSION, RPL_WHOISCHANNELS, RPL_WHOISCHANOP, RPL_WHOISIDLE, RPL_WHOISOPERATOR, RPL_WHOISSERVER, RPL_WHOISUSER, RPL_WHOREPLY, RPL_WHOWASUSER, RPL_YOUREOPER
 
Constructor Summary
PircBot()
          Constructs a PircBot with the default settings.
 
Method Summary
 void ban(String channel, String hostmask)
          Bans a user from a channel.
 void changeNick(String newNick)
          Attempt to change the current nick (nickname) of the bot when it is connected to an IRC server.
 void connect(String hostname)
          Attempt to connect to the specified IRC server.
 void connect(String hostname, int port)
          Attempt to connect to the specified IRC server and port number.
 void connect(String hostname, int port, String password)
          Attempt to connect to the specified IRC server using the supplied password.
protected  DccChat dccAcceptChatRequest(String sourceNick, long address, int port)
          Deprecated. As of PircBot 1.2.0, use onIncomingChatRequest(DccChat)
protected  void dccReceiveFile(File file, long address, int port, int size)
          Deprecated. As of PircBot 1.2.0, use onIncomingFileTransfer(DccFileTransfer)
 DccChat dccSendChatRequest(String nick, int timeout)
          Attempts to establish a DCC CHAT session with a client.
 DccFileTransfer dccSendFile(File file, String nick, int timeout)
          Sends a file to another user.
 void deOp(String channel, String nick)
          Removes operator privilidges from a user on a channel.
 void deVoice(String channel, String nick)
          Removes voice privilidges from a user on a channel.
 void disconnect()
          This method disconnects from the server cleanly by calling the quitServer() method.
 void dispose()
          Disposes of all thread resources used by this PircBot.
 boolean equals(Object o)
          Returns true if and only if the object being compared is the exact same instance as this PircBot.
 String[] getChannels()
          Returns an array of all channels that we are in.
 InetAddress getDccInetAddress()
          Returns the InetAddress used when sending DCC chat or file transfers.
 int[] getDccPorts()
          Returns the set of port numbers to be used when sending a DCC chat or file transfer.
 String getEncoding()
          Returns the encoding used to send and receive lines from the IRC server, or null if not set.
 String getFinger()
          Gets the internal finger message of the PircBot.
 InetAddress getInetAddress()
          Returns the InetAddress used by the PircBot.
 String getLogin()
          Gets the internal login of the PircBot.
 int getMaxLineLength()
          Gets the maximum length of any line that is sent via the IRC protocol.
 long getMessageDelay()
          Returns the number of milliseconds that will be used to separate consecutive messages to the server from the outgoing message queue.
 String getName()
          Gets the name of the PircBot.
 String getNick()
          Returns the current nick of the bot.
 int getOutgoingQueueSize()
          Gets the number of lines currently waiting in the outgoing message Queue.
 String getPassword()
          Returns the last password that we used when connecting to an IRC server.
 int getPort()
          Returns the port number of the last IRC server that the PircBot tried to connect to.
 String getServer()
          Returns the name of the last IRC server the PircBot tried to connect to.
 User[] getUsers(String channel)
          Returns an array of all users in the specified channel.
 String getVersion()
          Gets the internal version of the PircBot.
protected  void handleLine(String line)
          This method handles events when any line of text arrives from the server, then calling the appropriate method in the PircBot.
 int hashCode()
          Returns the hashCode of this PircBot.
 void identify(String password)
          Identify the bot with NickServ, supplying the appropriate password.
 long ipToLong(byte[] address)
          A convenient method that accepts an IP address represented by a byte[] of size 4 and returns this as a long representation of the same IP address.
 boolean isConnected()
          Returns whether or not the PircBot is currently connected to a server.
 void joinChannel(String channel)
          Joins a channel.
 void joinChannel(String channel, String key)
          Joins a channel with a key.
 void kick(String channel, String nick)
          Kicks a user from a channel.
 void kick(String channel, String nick, String reason)
          Kicks a user from a channel, giving a reason.
 void listChannels()
          Issues a request for a list of all channels on the IRC server.
 void listChannels(String parameters)
          Issues a request for a list of all channels on the IRC server.
 void log(String line)
          Adds a line to the log.
 int[] longToIp(long address)
          A convenient method that accepts an IP address represented as a long and returns an integer array of size 4 representing the same IP address.
protected  void onAction(String sender, String login, String hostname, String target, String action)
          This method is called whenever an ACTION is sent from a user.
protected  void onChannelInfo(String channel, int userCount, String topic)
          After calling the listChannels() method in PircBot, the server will start to send us information about each channel on the server.
protected  void onConnect()
          This method is called once the PircBot has successfully connected to the IRC server.
protected  void onDccChatRequest(String sourceNick, String sourceLogin, String sourceHostname, long address, int port)
          Deprecated. As of PircBot 1.2.0, use onIncomingChatRequest(DccChat)
protected  void onDccSendRequest(String sourceNick, String sourceLogin, String sourceHostname, String filename, long address, int port, int size)
          Deprecated. As of PircBot 1.2.0, use onIncomingFileTransfer(DccFileTransfer)
protected  void onDeop(String channel, String sourceNick, String sourceLogin, String sourceHostname, String recipient)
          Called when a user (possibly us) gets operator status taken away.
protected  void onDeVoice(String channel, String sourceNick, String sourceLogin, String sourceHostname, String recipient)
          Called when a user (possibly us) gets voice status removed.
protected  void onDisconnect()
          This method carries out the actions to be performed when the PircBot gets disconnected.
protected  void onFileTransferFinished(DccFileTransfer transfer, Exception e)
          This method gets called when a DccFileTransfer has finished.
protected  void onFinger(String sourceNick, String sourceLogin, String sourceHostname, String target)
          This method is called whenever we receive a FINGER request.
protected  void onIncomingChatRequest(DccChat chat)
          This method will be called whenever a DCC Chat request is received.
protected  void onIncomingFileTransfer(DccFileTransfer transfer)
          This method is called whenever a DCC SEND request is sent to the PircBot.
protected  void onInvite(String targetNick, String sourceNick, String sourceLogin, String sourceHostname, String channel)
          Called when we are invited to a channel by a user.
protected  void onJoin(String channel, String sender, String login, String hostname)
          This method is called whenever someone (possibly us) joins a channel which we are on.
protected  void onKick(String channel, String kickerNick, String kickerLogin, String kickerHostname, String recipientNick, String reason)
          This method is called whenever someone (possibly us) is kicked from any of the channels that we are in.
protected  void onMessage(String channel, String sender, String login, String hostname, String message)
          This method is called whenever a message is sent to a channel.
protected  void onMode(String channel, String sourceNick, String sourceLogin, String sourceHostname, String mode)
          Called when the mode of a channel is set.
protected  void onNickChange(String oldNick, String login, String hostname, String newNick)
          This method is called whenever someone (possibly us) changes nick on any of the channels that we are on.
protected  void onNotice(String sourceNick, String sourceLogin, String sourceHostname, String target, String notice)
          This method is called whenever we receive a notice.
protected  void onOp(String channel, String sourceNick, String sourceLogin, String sourceHostname, String recipient)
          Called when a user (possibly us) gets granted operator status for a channel.
protected  void onPart(String channel, String sender, String login, String hostname)
          This method is called whenever someone (possibly us) parts a channel which we are on.
protected  void onPing(String sourceNick, String sourceLogin, String sourceHostname, String target, String pingValue)
          This method is called whenever we receive a PING request from another user.
protected  void onPrivateMessage(String sender, String login, String hostname, String message)
          This method is called whenever a private message is sent to the PircBot.
protected  void onQuit(String sourceNick, String sourceLogin, String sourceHostname, String reason)
          This method is called whenever someone (possibly us) quits from the server.
protected  void onRemoveChannelBan(String channel, String sourceNick, String sourceLogin, String sourceHostname, String hostmask)
          Called when a hostmask ban is removed from a channel.
protected  void onRemoveChannelKey(String channel, String sourceNick, String sourceLogin, String sourceHostname, String key)
          Called when a channel key is removed.
protected  void onRemoveChannelLimit(String channel, String sourceNick, String sourceLogin, String sourceHostname)
          Called when the user limit is removed for a channel.
protected  void onRemoveInviteOnly(String channel, String sourceNick, String sourceLogin, String sourceHostname)
          Called when a channel has 'invite only' removed.
protected  void onRemoveModerated(String channel, String sourceNick, String sourceLogin, String sourceHostname)
          Called when a channel has moderated mode removed.
protected  void onRemoveNoExternalMessages(String channel, String sourceNick, String sourceLogin, String sourceHostname)
          Called when a channel is set to allow messages from any user, even if they are not actually in the channel.
protected  void onRemovePrivate(String channel, String sourceNick, String sourceLogin, String sourceHostname)
          Called when a channel is marked as not being in private mode.
protected  void onRemoveSecret(String channel, String sourceNick, String sourceLogin, String sourceHostname)
          Called when a channel has 'secret' mode removed.
protected  void onRemoveTopicProtection(String channel, String sourceNick, String sourceLogin, String sourceHostname)
          Called when topic protection is removed for a channel.
protected  void onServerPing(String response)
          The actions to perform when a PING request comes from the server.
protected  void onServerResponse(int code, String response)
          This method is called when we receive a numeric response from the IRC server.
protected  void onSetChannelBan(String channel, String sourceNick, String sourceLogin, String sourceHostname, String hostmask)
          Called when a user (possibly us) gets banned from a channel.
protected  void onSetChannelKey(String channel, String sourceNick, String sourceLogin, String sourceHostname, String key)
          Called when a channel key is set.
protected  void onSetChannelLimit(String channel, String sourceNick, String sourceLogin, String sourceHostname, int limit)
          Called when a user limit is set for a channel.
protected  void onSetInviteOnly(String channel, String sourceNick, String sourceLogin, String sourceHostname)
          Called when a channel is set to 'invite only' mode.
protected  void onSetModerated(String channel, String sourceNick, String sourceLogin, String sourceHostname)
          Called when a channel is set to 'moderated' mode.
protected  void onSetNoExternalMessages(String channel, String sourceNick, String sourceLogin, String sourceHostname)
          Called when a channel is set to only allow messages from users that are in the channel.
protected  void onSetPrivate(String channel, String sourceNick, String sourceLogin, String sourceHostname)
          Called when a channel is marked as being in private mode.
protected  void onSetSecret(String channel, String sourceNick, String sourceLogin, String sourceHostname)
          Called when a channel is set to be in 'secret' mode.
protected  void onSetTopicProtection(String channel, String sourceNick, String sourceLogin, String sourceHostname)
          Called when topic protection is enabled for a channel.
protected  void onTime(String sourceNick, String sourceLogin, String sourceHostname, String target)
          This method is called whenever we receive a TIME request.
protected  void onTopic(String channel, String topic)
          Deprecated. As of 1.2.0, replaced by onTopic(String,String,String,long,boolean)
protected  void onTopic(String channel, String topic, String setBy, long date, boolean changed)
          This method is called whenever a user sets the topic, or when PircBot joins a new channel and discovers its topic.
protected  void onUnknown(String line)
          This method is called whenever we receive a line from the server that the PircBot has not been programmed to recognise.
protected  void onUserList(String channel, User[] users)
          This method is called when we receive a user list from the server after joining a channel.
protected  void onUserMode(String targetNick, String sourceNick, String sourceLogin, String sourceHostname, String mode)
          Called when the mode of a user is set.
protected  void onVersion(String sourceNick, String sourceLogin, String sourceHostname, String target)
          This method is called whenever we receive a VERSION request.
protected  void onVoice(String channel, String sourceNick, String sourceLogin, String sourceHostname, String recipient)
          Called when a user (possibly us) gets voice status granted in a channel.
 void op(String channel, String nick)
          Grants operator privilidges to a user on a channel.
 void partChannel(String channel)
          Parts a channel.
 void partChannel(String channel, String reason)
          Parts a channel, giving a reason.
 void quitServer()
          Quits from the IRC server.
 void quitServer(String reason)
          Quits from the IRC server with a reason.
 void reconnect()
          Reconnects to the IRC server that we were previously connected to.
 void sendAction(String target, String action)
          Sends an action to the channel or to a user.
 void sendCTCPCommand(String target, String command)
          Sends a CTCP command to a channel or user.
 void sendInvite(String nick, String channel)
          Sends an invitation to join a channel.
 void sendMessage(String target, String message)
          Sends a message to a channel or a private message to a user.
 void sendNotice(String target, String notice)
          Sends a notice to the channel or to a user.
 void sendRawLine(String line)
          Sends a raw line to the IRC server as soon as possible, bypassing the outgoing message queue.
 void sendRawLineViaQueue(String line)
          Sends a raw line through the outgoing message queue.
 void setAutoNickChange(boolean autoNickChange)
          When you connect to a server and your nick is already in use and this is set to true, a new nick will be automatically chosen.
 void setDccInetAddress(InetAddress dccInetAddress)
          Sets the InetAddress to be used when sending DCC chat or file transfers.
 void setDccPorts(int[] ports)
          Sets the choice of port numbers that can be used when sending a DCC chat or file transfer.
 void setEncoding(String charset)
          Sets the encoding charset to be used when sending or receiving lines from the IRC server.
protected  void setFinger(String finger)
          Sets the interal finger message.
protected  void setLogin(String login)
          Sets the internal login of the Bot.
 void setMessageDelay(long delay)
          Sets the number of milliseconds to delay between consecutive messages when there are multiple messages waiting in the outgoing message queue.
 void setMode(String channel, String mode)
          Set the mode of a channel.
protected  void setName(String name)
          Sets the name of the bot, which will be used as its nick when it tries to join an IRC server.
 void setTopic(String channel, String topic)
          Set the topic for a channel.
 void setVerbose(boolean verbose)
          Sets the verbose mode.
protected  void setVersion(String version)
          Sets the internal version of the Bot.
 void startIdentServer()
          Starts an ident server (Identification Protocol Server, RFC 1413).
 String toString()
          Returns a String representation of this object.
 void unBan(String channel, String hostmask)
          Unbans a user from a channel.
 void voice(String channel, String nick)
          Grants voice privilidges to a user on a channel.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

VERSION

public static final String VERSION
The definitive version number of this release of PircBot. (Note: Change this before automatically building releases)

See Also:
Constant Field Values
Constructor Detail

PircBot

public PircBot()
Constructs a PircBot with the default settings. Your own constructors in classes which extend the PircBot abstract class should be responsible for changing the default settings if required.

Method Detail

connect

public final void connect(String hostname)
                   throws IOException,
                          IrcException,
                          NickAlreadyInUseException
Attempt to connect to the specified IRC server. The onConnect method is called upon success.

Parameters:
hostname - The hostname of the server to connect to.
Throws:
IOException - if it was not possible to connect to the server.
IrcException - if the server would not let us join it.
NickAlreadyInUseException - if our nick is already in use on the server.

connect

public final void connect(String hostname,
                          int port)
                   throws IOException,
                          IrcException,
                          NickAlreadyInUseException
Attempt to connect to the specified IRC server and port number. The onConnect method is called upon success.

Parameters:
hostname - The hostname of the server to connect to.
port - The port number to connect to on the server.
Throws:
IOException - if it was not possible to connect to the server.
IrcException - if the server would not let us join it.
NickAlreadyInUseException - if our nick is already in use on the server.

connect

public final void connect(String hostname,
                          int port,
                          String password)
                   throws IOException,
                          IrcException,
                          NickAlreadyInUseException
Attempt to connect to the specified IRC server using the supplied password. The onConnect method is called upon success.

Parameters:
hostname - The hostname of the server to connect to.
port - The port number to connect to on the server.
password - The password to use to join the server.
Throws:
IOException - if it was not possible to connect to the server.
IrcException - if the server would not let us join it.
NickAlreadyInUseException - if our nick is already in use on the server.

reconnect

public final void reconnect()
                     throws IOException,
                            IrcException,
                            NickAlreadyInUseException
Reconnects to the IRC server that we were previously connected to. If necessary, the appropriate port number and password will be used. This method will throw an IrcException if we have never connected to an IRC server previously.

Throws:
IOException - if it was not possible to connect to the server.
IrcException - if the server would not let us join it.
NickAlreadyInUseException - if our nick is already in use on the server.
Since:
PircBot 0.9.9

disconnect

public final void disconnect()
This method disconnects from the server cleanly by calling the quitServer() method. Providing the PircBot was connected to an IRC server, the onDisconnect() will be called as soon as the disconnection is made by the server.

See Also:
quitServer, quitServer

setAutoNickChange

public void setAutoNickChange(boolean autoNickChange)
When you connect to a server and your nick is already in use and this is set to true, a new nick will be automatically chosen. This is done by adding numbers to the end of the nick until an available nick is found.

Parameters:
autoNickChange - Set to true if you want automatic nick changes during connection.

startIdentServer

public final void startIdentServer()
Starts an ident server (Identification Protocol Server, RFC 1413).

Most IRC servers attempt to contact the ident server on connecting hosts in order to determine the user's identity. A few IRC servers will not allow you to connect unless this information is provided.

So when a PircBot is run on a machine that does not run an ident server, it may be necessary to call this method to start one up.

Calling this method starts up an ident server which will respond with the login provided by calling getLogin() and then shut down immediately. It will also be shut down if it has not been contacted within 60 seconds of creation.

If you require an ident response, then the correct procedure is to start the ident server and then connect to the IRC server. The IRC server may then contact the ident server to get the information it needs.

The ident server will fail to start if there is already an ident server running on port 113, or if you are running as an unprivileged user who is unable to create a server socket on that port number.

If it is essential for you to use an ident server when connecting to an IRC server, then make sure that port 113 on your machine is visible to the IRC server so that it may contact the ident server.

Since:
PircBot 0.9c

joinChannel

public final void joinChannel(String channel)
Joins a channel.

Parameters:
channel - The name of the channel to join (eg "#cs").

joinChannel

public final void joinChannel(String channel,
                              String key)
Joins a channel with a key.

Parameters:
channel - The name of the channel to join (eg "#cs").
key - The key that will be used to join the channel.

partChannel

public final void partChannel(String channel)
Parts a channel.

Parameters:
channel - The name of the channel to leave.

partChannel

public final void partChannel(String channel,
                              String reason)
Parts a channel, giving a reason.

Parameters:
channel - The name of the channel to leave.
reason - The reason for parting the channel.

quitServer

public final void quitServer()
Quits from the IRC server. Providing we are actually connected to an IRC server, the onDisconnect() method will be called as soon as the IRC server disconnects us.


quitServer

public final void quitServer(String reason)
Quits from the IRC server with a reason. Providing we are actually connected to an IRC server, the onDisconnect() method will be called as soon as the IRC server disconnects us.

Parameters:
reason - The reason for quitting the server.

sendRawLine

public final void sendRawLine(String line)
Sends a raw line to the IRC server as soon as possible, bypassing the outgoing message queue.

Parameters:
line - The raw line to send to the IRC server.

sendRawLineViaQueue

public final void sendRawLineViaQueue(String line)
Sends a raw line through the outgoing message queue.

Parameters:
line - The raw line to send to the IRC server.

sendMessage