/*
* Created on 15.11.2005 by jawe
* $Id$
*/
/*
* This file is part of scriptbot.
*
* scriptbot is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*
* scriptbot is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with ScriptBot; if not, write to the Free Software
* Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
*/
package net.jawe.scriptbot;
import java.net.InetAddress;
import java.util.Collection;
import java.util.Map;
import java.util.Set;
import org.apache.commons.logging.Log;
import org.jibble.pircbot.DccChat;
import org.jibble.pircbot.User;
import net.jawe.scriptbot.users.BotUser;
/**
* Main interface for the bot. Contains methods to setup the bot and to
* interact with IRC.
* @author jawe
*/
public interface Bot extends Runnable {
/**
* The bot's configuration. Set by spring.
* @return Returns the _config.
*/
public Config getConfig();
/**
* Indicates wether the bot is shutting down and should not try to reconnect.
* @return Returns the _shutdownInProgress.
*/
public boolean isShutdownInProgress();
/**
* Set the shutdown status, which indicates that the bot should not try to
* reconnect.
* @param shutdownInProgress
* The _shutdownInProgress to set.
*/
public void setShutdownInProgress(boolean shutdownInProgress);
/**
* Indicates that the bot main program should be restarted after shutdown.
* @return restarting flag
*/
public boolean isRestarting();
/**
* Indicates that the bot main program should be restarted after shutdown.
* @param restarting restarting flag
*/
public void setRestarting(boolean restarting);
/**
* Indicates wether the bot is jumping to another server.
* @return Returns the jumping.
*/
public boolean isJumping();
/**
* All registered commands.
*
* @return Returns the commands.
*/
public Collection<Command> getCommands();
/**
* All registered commands as an array. Convenience method for use by
* scripts.
* @return the commands.
*/
public Command[] getCommandsArray();
/**
* The commands of a specific module
*
* @param moduleName
* the module's name.
* @return the module's commands
*/
public Set<Command> getCommands(String moduleName);
/**
* The commands of a specific module as an array. Convenience method for
* use by scripts.
* @param module the module's name.
* @return the module's commands.
*/
public Command[] getCommandsArray(String module);
/**
* Get the module with the specified name.
* @param name the module name.
* @return the module with the specified name.
*/
public Module getModule(String name);
/**
* All registered module names.
*
* @return the module names.
*/
public Set<String> getModules();
/**
* All registered module names as an array. Convenience method for use
* by scripts.
* @return the module names.
*/
public String[] getModulesArray();
/**
* Loads the module by executing the specified script.
* @param moduleScript the module script.
* @return the loaded module or null if loading failed
*/
public Module loadModule(String moduleScript);
/**
* Unloads the specified module.
* @param module the module name.
* @return the unloaded module or null if unloading failed
*/
public Module unloadModule(String module);
/**
* Reloads the specified module. Same as calling <tt>unloadModule()</tt>
* and <tt>loadModule()</tt>
* @param moduleName the module name
* @return the reloaded module or null if reloading failed
*/
public Module reloadModule(String moduleName);
/**
*
* @see org.jibble.pircbot.PircBot#log(java.lang.String)
*/
public void log(String line);
/**
* Set an IRC user mode on the bot.
* @param flags the user modes, eg. "+iw"
*/
public void setMode(String flags);
/**
* Registers a new command, overwriting any exisiting commands with the same
* name.
* @param command the command.
* @return the previously registered command or null.
*/
public Command registerCommand(Command command);
/**
* Unregisters a command.
* @param command the command.
* @return the unregistered command or null.
*/
public Command unregisterCommand(Command command);
/**
* Registers an event handler.
* @param event the event name.
* @param module the module the event handler belongs to.
* @param scriptfile the script to execute when the event fires.
* @return true if the event handler was successfully registered, eg. not
* already registered.
*/
public boolean registerEventHandler(String event, Module module,
String scriptfile);
/**
* Registers an event handler.
* @param event the event name.
* @param module the module the event handler belongs to.
* @param scriptfile the script to execute when the event fires.
* @param async wether the script should be executed asynchronously by default.
* @return true if the event handler was successfully registered, eg. not
* already registered.
*/
public boolean registerEventHandler(String event, Module module,
String scriptfile, boolean async);
/**
* Unregisters an event handler.
* @param event the event name.
* @param module the module the event handler belongs to.
* @param script the event handling script.
* @return true if the event handler was successfully registered, eg.
* previously registered.
*/
public boolean unregisterEventHandler(String event, Module module,
Script script);
/**
* Jump to the next configured server.
* @return true if connecting to the new server succeeded.
*/
public boolean jump();
/**
* Jump to the specified server in the list of configured servers.
* @param hostname the server's hostname or IP.
* @param port the server's port.
* @param reason the quit message.
* @return true if connecting to the new server succeeded.
*/
public boolean jump(String hostname, int port, String reason);
/**
* Jump to the specified server in the list of configured servers.
* @param serverIndex the server's index in the list of configured servers.
* @param reason the quit message.
* @return true if connecting to the new server succeeded.
*/
public boolean jump(int serverIndex, String reason);
/**
* Jump to a new server.
* @param hostname the server's hostname.
* @param port the server's port
* @param password the server's password.
* @return true if connecting to the new server succeeded.
*/
public boolean jumpNew(String hostname, int port, String password);
/**
* Connect to the next configured server.
* @return true if connecting succeeded.
*/
public boolean connect();
/**
* Execute the given script.
*
* @param filename
* the script file to execute, relative to the scripts directory.
* @return wether executing succeeded.
*/
public boolean execScript(String filename);
/**
* Execute the given script.
*
* @param module the module the script belongs to.
* @param filename the script file to execute, relative to the module directory.
* @return whether executing succeeded.
*/
public boolean execScript(String module, String filename);
/**
* Execute the given script and provide it with the supplied params
* as intrinsic objects.
* @param filename
* the script file to execute, relative to the scripts directory.
* @param params additional params passed to the script.
* @return whether executing succeeded.
*/
public boolean execScript(String filename,
Map<String, ? extends Object> params);
/**
* Execute the given script and provide it with the supplied params
* as intrinsic objects.
* @param module the module the script belongs to.
* @param filename the script file to execute, relative to the module directory.
* @param params additional params passed to the script.
* @return whether executing succeeded.
*/
public boolean execScript(String module, String filename,
Map<String, ? extends Object> params);
/**
* Reloads the bot config.
*/
public boolean reload();
/**
* Is the user in a channel the bot is in?
*
* @param nick
* the user's nick.
* @return true if the user is in a channel the bot is in too.
*/
public boolean isUserInBotChannel(String nick);
/**
*
* @see org.jibble.pircbot.PircBot#dispose()
*/
public void dispose();
/**
*
* @see org.jibble.pircbot.PircBot#getDccInetAddress()
*/
public InetAddress getDccInetAddress();
/**
*
* @see org.jibble.pircbot.PircBot#getDccPorts()
*/
public int[] getDccPorts();
/**
*
* @see org.jibble.pircbot.PircBot#getEncoding()
*/
public String getEncoding();
/**
*
* @see org.jibble.pircbot.PircBot#getInetAddress()
*/
public InetAddress getInetAddress();
/**
*
* @see org.jibble.pircbot.PircBot#getNick()
*/
public String getNick();
/**
*
* @see org.jibble.pircbot.PircBot#joinChannel(java.lang.String)
*/
public void joinChannel(String channel);
/**
*
* @see org.jibble.pircbot.PircBot#joinChannel(java.lang.String,
* java.lang.String)
*/
public void joinChannel(String channel, String key);
/**
*
* @see org.jibble.pircbot.PircBot#partChannel(java.lang.String)
*/
public void partChannel(String channel);
/**
*
* @see org.jibble.pircbot.PircBot#partChannel(java.lang.String,
* java.lang.String)
*/
public void partChannel(String channel, String reason);
/**
*
* @see org.jibble.pircbot.PircBot#quitServer()
*/
public void quitServer();
/**
*
* @see org.jibble.pircbot.PircBot#quitServer(java.lang.String)
*/
public void quitServer(String reason);
/**
*
* @see org.jibble.pircbot.PircBot#sendRawLine(java.lang.String)
*/
public void sendRawLine(String line);
/**
*
* @see org.jibble.pircbot.PircBot#sendRawLineViaQueue(java.lang.String)
*/
public void sendRawLineViaQueue(String line);
/**
*
* @see org.jibble.pircbot.PircBot#sendMessage(java.lang.String,
* java.lang.String)
*/
public void sendMessage(String target, String message);
/**
*
* @see org.jibble.pircbot.PircBot#sendAction(java.lang.String,
* java.lang.String)
*/
public void sendAction(String target, String action);
/**
*
* @see org.jibble.pircbot.PircBot#sendNotice(java.lang.String,
* java.lang.String)
*/
public void sendNotice(String target, String notice);
/**
*
* @see org.jibble.pircbot.PircBot#sendCTCPCommand(java.lang.String,
* java.lang.String)
*/
public void sendCTCPCommand(String target, String command);
/**
*
* @see org.jibble.pircbot.PircBot#changeNick(java.lang.String)
*/
public void changeNick(String newNick);
/**
*
* @see org.jibble.pircbot.PircBot#setMode(java.lang.String,
* java.lang.String)
*/
public void setMode(String channel, String mode);
/**
*
* @see org.jibble.pircbot.PircBot#sendInvite(java.lang.String,
* java.lang.String)
*/
public void sendInvite(String nick, String channel);
/**
*
* @see org.jibble.pircbot.PircBot#ban(java.lang.String,
* java.lang.String)
*/
public void ban(String channel, String hostmask);
/**
*
* @see org.jibble.pircbot.PircBot#unBan(java.lang.String,
* java.lang.String)
*/
public void unBan(String channel, String hostmask);
/**
*
* @see org.jibble.pircbot.PircBot#op(java.lang.String,
* java.lang.String)
*/
public void op(String channel, String nick);
/**
*
* @see org.jibble.pircbot.PircBot#deOp(java.lang.String,
* java.lang.String)
*/
public void deOp(String channel, String nick);
/**
*
* @see org.jibble.pircbot.PircBot#voice(java.lang.String,
* java.lang.String)
*/
public void voice(String channel, String nick);
/**
*
* @see org.jibble.pircbot.PircBot#deVoice(java.lang.String,
* java.lang.String)
*/
public void deVoice(String channel, String nick);
/**
*
* @see org.jibble.pircbot.PircBot#setTopic(java.lang.String,
* java.lang.String)
*/
public void setTopic(String channel, String topic);
/**
*
* @see org.jibble.pircbot.PircBot#kick(java.lang.String,
* java.lang.String)
*/
public void kick(String channel, String nick);
/**
*
* @see org.jibble.pircbot.PircBot#kick(java.lang.String,
* java.lang.String, java.lang.String)
*/
public void kick(String channel, String nick, String reason);
/**
*
* @see org.jibble.pircbot.PircBot#listChannels()
*/
public void listChannels();
/**
*
* @see org.jibble.pircbot.PircBot#listChannels(java.lang.String)
*/
public void listChannels(String parameters);
/**
*
* @see org.jibble.pircbot.PircBot#getName()
*/
public String getName();
/**
*
* @see org.jibble.pircbot.PircBot#getLogin()
*/
public String getLogin();
/**
*
* @see org.jibble.pircbot.PircBot#getVersion()
*/
public String getVersion();
/**
*
* @see org.jibble.pircbot.PircBot#getFinger()
*/
public String getFinger();
/**
*
* @see org.jibble.pircbot.PircBot#isConnected()
*/
public boolean isConnected();
/**
*
* @see org.jibble.pircbot.PircBot#setMessageDelay(long)
*/
public void setMessageDelay(long delay);
/**
*
* @see org.jibble.pircbot.PircBot#getMessageDelay()
*/
public long getMessageDelay();
/**
*
* @see org.jibble.pircbot.PircBot#getMaxLineLength()
*/
public int getMaxLineLength();
/**
*
* @see org.jibble.pircbot.PircBot#getOutgoingQueueSize()
*/
public int getOutgoingQueueSize();
/**
*
* @see org.jibble.pircbot.PircBot#getServer()
*/
public String getServer();
/**
*
* @see org.jibble.pircbot.PircBot#getPort()
*/
public int getPort();
/**
*
* @see org.jibble.pircbot.PircBot#getPassword()
*/
public String getPassword();
/**
*
* @see org.jibble.pircbot.PircBot#getUsers(java.lang.String)
*/
public User[] getUsers(String channel);
/**
*
* @see org.jibble.pircbot.PircBot#getChannels()
*/
public String[] getChannels();
/**
* Process a message as if it would have come from a user.
* @param nick TODO
* @param login TODO
* @param hostname TODO
* @param channel TODO
* @param message TODO
*/
public void processMessage(String nick, String login, String hostname,
String channel, String message);
/**
* Process a private message as if it would have come from a user.
* @param nick TODO
* @param login TODO
* @param hostname TODO
* @param message TODO
*/
public void processPrivateMessage(String nick, String login,
String hostname, String message);
/**
* Process an action as if it would have come from a user.
* @param nick TODO
* @param login TODO
* @param hostname TODO
* @param channel TODO
* @param message TODO
*/
public void processAction(String nick, String login, String hostname,
String channel, String message);
/**
* Process a message as if it would have come from a user.
* @param sender TODO
* @param target TODO
* @param message TODO
*/
public void processDccMessage(DccChat sender, DccChat target, String message);
/**
* Process a notice as if it would have come from a user.
* @param sourceNick TODO
* @param sourceLogin TODO
* @param sourceHostname TODO
* @param target TODO
* @param notice TODO
*/
public void processNotice(String sourceNick, String sourceLogin,
String sourceHostname, String target, String notice);
/**
* Retrieve an object from the cache.
* @param module the name of the module the cache entry belongs to, or <tt>null</tt>.
* @param key the cache key.
* @return the cached object.
*/
public Object getFromCache(String module, String key);
/**
* Put an object into the cache.
* @param module the name of the module the cache entry belongs to, or <tt>null</tt>.
* @param key the cache key.
* @param object the object to cache.
* @return any object previously registered under that key.
*/
public Object putInCache(String module, String key, Object object);
/**
* Should be called whenever a user successfully logs in to the bot.
* In the default configuration this is done in the
* <tt>scripts/irc/commands/auth.js</tt> script.
* @param user the user that just logged in.
*/
public void onLogin(BotUser user);
/**
* Should be called whenever a user logs out of the bot.
* In the default configuration this is done in the
* <tt>scripts/irc/commands/logout.js</tt> script.
* @param user the user that just logged out.
*/
public void onLogout(BotUser user);
/**
* The log to use for PircBot IRC logging.
* @param log the log
*/
public void setIrcLog(Log log);
/**
* The log used for PircBot IRC logging.
* @return the log
*/
public Log getIrcLog();
}
