com.zion.jbuddy.bots
Class BotEngine

java.lang.Object
  com.zion.jbuddy.bots.BotEngine

public class BotEngine
extends Object

Acts as a bot, processing user input and generating responses.

The engine can load bot logic from a Bot Definition File. Its logic can also be set programmatically via this API.

Using the engine typically requires the following steps:

• load a Bot Definition (see loadDefinition)
• register event listeners to receive events from the engine (optional, see addListener)
• start the engine (see start)

The engine responds to user input events (such as messages and presence changes) with outgoing gateway commands and engine events.

The framework includes Run and Test utilities, which are complete implementations of this engine, utilizing the JBuddy SDK for client and gateway support. An engine does not have to be explicity created, unless a custom implementation is needed.

Constructor Summary

BotEngine()
Creates a bot engine.

Method Summary

void	addClient(BotClient client) Adds a client to this engine.
BotClient	addClient(String protocol, String name) Adds a client to this engine.
void	addClientConnectionListener(BotClientConnectionListener listener) Registers a listener to receive client connection events from this engine.
void	addListener(BotEngineListener listener) Registers a listener to receive events from this engine.
protected ClassLoader	createClassLoader() Returns the class loader used by this engine to load resources, such as action tasks, resource bundles, and XSL transformations.
static String	encryptPassword(String password, String passKey) Encrypts a password for use in a Bot Definition File.
List	getClients() Returns a List of clients in this engine.
BotEventHandlerSet	getEventHandlers() Returns this engine's event handlers.
BotLogLevel	getLogLevel() Returns this engine's log level.
PrintStream	getLogOutput() Returns this engine's log output.
int	getMenuHistorySize() Returns the user menu history size.
String	getPassKey() Returns this engine's pass key.
ResourceBundle	getResourceBundle() Returns this engine's resource bundle.
BotStatistics	getStatistics() Returns this engine's statistics.
BotTargetSet	getTargets() Returns this engine's targets.
int	getThreadPoolSize() Returns the size of the internal thread pool this bot engine uses to process requests.
long	getUserTimeout() Returns the amount of time, in milliseconds, before idle user sessions are timed-out.
boolean	isAutomaticallyConnectClients() Returns whether this engine automatically connects clients.
boolean	isRunning() Returns true if this engine is running (has been started).
void	loadDefinition(InputSource source) Loads Bot Definition XML from the specified input source.
void	loadDefinition(InputStream inputStream) Loads Bot Definition XML from the specified input stream.
void	loadDefinition(String path) Loads Bot Definition XML from the specified path.
void	removeClient(BotClient client) Removes a client from this engine.
void	removeClientConnectionListener(BotClientConnectionListener listener) Stops a listener from receiving client connection events from this engine.
void	removeListener(BotEngineListener listener) Stops a listener from receiving events from this engine.
void	setAutomaticallyConnectClients(boolean automaticallyConnectClients) Sets whether this engine automatically connects clients.
void	setLogLevel(BotLogLevel logLevel) Sets this engine's log level.
void	setLogOutput(PrintStream output) Sets this engine's log output.
void	setMenuHistorySize(int menuHistorySize) Sets the user menu history size.
void	setPassKey(String passKey) Sets this engine's pass key.
void	setResourceBundle(ResourceBundle resourceBundle) Sets this engine's resource bundle.
void	setThreadPoolSize(int size) Sets the size of the internal thread pool this bot engine uses to process requests.
void	setUserTimeout(long userTimeout) Sets the amount of time, in milliseconds, before idle user sessions are timed-out.
void	start() Starts this engine.
void	stop() Stops this engine.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BotEngine

public BotEngine()

Creates a bot engine.

Method Detail

encryptPassword

public static String encryptPassword(String password,
                                     String passKey)

Encrypts a password for use in a Bot Definition File.

Parameters:

password - the password

passKey - the optional pass key (may be null)

Returns:

the encrypted password string

addListener

public void addListener(BotEngineListener listener)

Registers a listener to receive events from this engine.

removeListener

public void removeListener(BotEngineListener listener)

Stops a listener from receiving events from this engine.

addClientConnectionListener

public void addClientConnectionListener(BotClientConnectionListener listener)

Registers a listener to receive client connection events from this engine.

removeClientConnectionListener

public void removeClientConnectionListener(BotClientConnectionListener listener)

Stops a listener from receiving client connection events from this engine.

loadDefinition

public void loadDefinition(InputSource source)
                    throws Exception

Loads Bot Definition XML from the specified input source.

Existing clients, targets, menus, and event handlers in this engine are removed, and replaced by those in the Bot Definition, if any. Other properties of this engine may also be modified by the Bot Definition, depending on any attributes that are set.

For more information on the XML format, consult the XML Schema Documentation included with the framework.

Throws:

Exception - if something goes wrong loading the Bot Definition (such as an XML error)

loadDefinition

public void loadDefinition(InputStream inputStream)
                    throws Exception

Loads Bot Definition XML from the specified input stream.

Existing clients, targets, menus, and event handlers in this engine are removed, and replaced by those in the Bot Definition, if any. Other properties of this engine may also be modified by the Bot Definition, depending on any attributes that are set.

For more information on the XML format, consult the XML Schema Documentation included with the framework.

Throws:

Exception - if something goes wrong loading the Bot Definition (such as an XML error)

loadDefinition

public void loadDefinition(String path)
                    throws Exception

Loads Bot Definition XML from the specified path. The path may be a fully-qualified URL, or a relative path to a Bot Definition File.

Existing clients, targets, menus, and event handlers in this engine are removed, and replaced by those in the Bot Definition, if any. Other properties of this engine may also be modified by the Bot Definition, depending on any attributes that are set.

For more information on the XML format, consult the XML Schema Documentation included with the framework.

Throws:

Exception - if something goes wrong loading the Bot Definition (such as an XML error)

isRunning

public boolean isRunning()

Returns true if this engine is running (has been started).

start

public void start()

Starts this engine.

Statistics compiled since the engine last started are reset. If automaticallyConnectClients is true, clients are connected (if they are not already connected).

This method must be called before any user input can be processed. An exception is thrown if attempting to send input to a user whose associated engine hasn't been started.

See Also:

setAutomaticallyConnectClients(boolean)

stop

public void stop()

Stops this engine. All clients are disconnected.

isAutomaticallyConnectClients

public boolean isAutomaticallyConnectClients()

Returns whether this engine automatically connects clients.

setAutomaticallyConnectClients

public void setAutomaticallyConnectClients(boolean automaticallyConnectClients)

Sets whether this engine automatically connects clients.

If true, while this engine is running, it will automatically manage client connections; when a new definition is loaded, new clients will be connected, removed clients will be disconnected, and unchanged client connections will be preserved.

If false, client connections will not be automatically managed (though clients can always be connected manually).

getLogLevel

public BotLogLevel getLogLevel()

Returns this engine's log level.

setLogLevel

public void setLogLevel(BotLogLevel logLevel)

Sets this engine's log level.

getLogOutput

public PrintStream getLogOutput()

Returns this engine's log output.

setLogOutput

public void setLogOutput(PrintStream output)

Sets this engine's log output.

By default, the engine prints log output to System.out.

getMenuHistorySize

public int getMenuHistorySize()

Returns the user menu history size.

setMenuHistorySize

public void setMenuHistorySize(int menuHistorySize)

Sets the user menu history size.

If a user visits a menu that would cause the associated menu history to grow larger than this size, the oldest menu is removed from the history.

If menuHistorySize < 0, the history may contain an infinite number of menus (not recommended).

The default value is 10.

getPassKey

public String getPassKey()

Returns this engine's pass key.

setPassKey

public void setPassKey(String passKey)

Sets this engine's pass key.

The pass key is used to decrypt encrypted client passwords in the Bot Definition. To encrypt client passwords, use the EncryptPassword utility included with the framework.

getResourceBundle

public ResourceBundle getResourceBundle()

Returns this engine's resource bundle.

setResourceBundle

public void setResourceBundle(ResourceBundle resourceBundle)

Sets this engine's resource bundle.

The engine normally loads string constants from its built-in resource bundle. The constants can be overridden here. To see the available constants, consult the Bots.properties file included with the framework.

getThreadPoolSize

public int getThreadPoolSize()

Returns the size of the internal thread pool this bot engine uses to process requests.

setThreadPoolSize

public void setThreadPoolSize(int size)

Sets the size of the internal thread pool this bot engine uses to process requests.

The default value is 5.

getUserTimeout

public long getUserTimeout()

Returns the amount of time, in milliseconds, before idle user sessions are timed-out.

setUserTimeout

public void setUserTimeout(long userTimeout)

Sets the amount of time, in milliseconds, before idle user sessions are timed-out.

If no input is sent by a user for longer than this amount of time, the user's session is considered inactive and is removed from the engine. Further input from the user would then create a new session.

If userTimeout < 1, user sessions will never time out (not recommended).

The default value is 900000 (60s * 15min * 1000ms = 15 minutes).

getStatistics

public BotStatistics getStatistics()

Returns this engine's statistics.

getTargets

public BotTargetSet getTargets()

Returns this engine's targets.

getEventHandlers

public BotEventHandlerSet getEventHandlers()

Returns this engine's event handlers.

addClient

public void addClient(BotClient client)
               throws Exception

Adds a client to this engine.

Throws:

Exception - if a similar client already exists

addClient

public BotClient addClient(String protocol,
                           String name)

Adds a client to this engine.

If a similar client already exists, it is returned. Otherwise, a new client is created and returned.

Parameters:

protocol - the client's protocol

name - the client's unique name

Returns:

the client

getClients

public List getClients()

Returns a List of clients in this engine.

removeClient

public void removeClient(BotClient client)

Removes a client from this engine. The client is also disconnected.

createClassLoader

protected ClassLoader createClassLoader()

Returns the class loader used by this engine to load resources, such as action tasks, resource bundles, and XSL transformations.

This should be overridden if a custom implementation is required.

Returns:

the class loader