com.zion.jbuddy.bots
Class BotGateway

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

public abstract class BotGateway
extends Object

Provides functionality to a bot via an external network or source. A gateway can give a bot the ability to send or receive messages, send files, or support various instant messaging and presence features.

By default, the JBuddy Bot Framework uses the JBuddy SDK to connect to various popular instant messaging networks (all available gateway methods and features are currently supported by JBuddy). This class allows other mediums to potentially be supported, such as an SMS (Short Message Service) gateway.

The following example (fictional) XML snippet might be used to add SMS client support to a Bot Definition File:

<client protocol="SMS" gatewayClass="com.acme.bots.SMSGateway"> <property name="shortCode" value="12345"/> </client>

A BotGateway is associated with a single BotClient, and exists for only as long as the client is connected. Instances of this class are not reused between multiple connections.

For more information, see the User's Guide.

Constructor Summary

protected

BotGateway()

Method Summary

protected void	addBuddy(BotAddBuddyEvent event) Adds a user to the client's Buddy List.
protected void	addDeny(BotAddDenyEvent event) Adds a user to the client's Deny List.
protected void	addPermit(BotAddPermitEvent event) Adds a user to the client's Permit List.
protected abstract void	connect() Connects this gateway.
protected abstract void	disconnect() Disconnects this gateway.
protected void	dispose() Disposes of resources used by this gateway.
protected BotClient	getClient() Returns the client this gateway is associated with.
protected long	getReconnectDelay() Returns the amount of time the engine must wait before reconnecting this gateway (after disconnecting or a connection attempt fails).
protected void	notifyConnected() Notifies the BotEngine that this gateway has been successfully connected.
protected void	notifyCouldNotConnect(Exception exception, boolean canReconnect) Notifies the BotEngine that this gateway could not be connected.
protected void	notifyDisconnected(Exception exception, boolean canReconnect) Notifies the BotEngine that this gateway's connection has been closed or severed unexpectedly.
protected void	receiveMessage(String userName, BotMessage message) Notifies the BotEngine that a message has been received.
protected void	removeBuddy(BotRemoveBuddyEvent event) Removes a user from the client's Buddy List.
protected void	removeDeny(BotRemoveDenyEvent event) Removes a user from the client's Deny List.
protected void	removePermit(BotRemovePermitEvent event) Removes a user from the client's Permit List.
protected void	sendFile(BotSendFileEvent event) Sends a file to a user.
protected abstract void	sendMessage(BotSendMessageEvent event) Overridden to send an outgoing message.
protected void	setPermitMode(BotSetPermitModeEvent event) Sets the client's Permit Mode.
protected void	setReconnectDelay(long reconnectDelay) Sets the amount of time the engine must wait before reconnecting this gateway (after disconnecting or a connection attempt fails).
protected void	setStatus(BotSetStatusEvent event) Sets the client's status.

Methods inherited from class java.lang.Object

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

Constructor Detail

BotGateway

protected BotGateway()

Method Detail

getClient

protected final BotClient getClient()

Returns the client this gateway is associated with.

getReconnectDelay

protected final long getReconnectDelay()

Returns the amount of time the engine must wait before reconnecting this gateway (after disconnecting or a connection attempt fails).

setReconnectDelay

protected final void setReconnectDelay(long reconnectDelay)

Sets the amount of time the engine must wait before reconnecting this gateway (after disconnecting or a connection attempt fails).

If a delay is not specified (reconnectDelay <= 0), the default behavior is used (for the first reconnect attempt, no delay occurs; subsequent failed attempts add a delay of one minute, up to a total delay of 20 minutes; a successful connection resets the delay time to zero).

connect

protected abstract void connect()

Connects this gateway. This must be overridden to do whatever is necessary to connect (which may include opening socket connections, for example).

The connection attempt may occur either asynchronously (in a separate thread) or synchronously (within this method). If the attempt is successful, the BotEngine must be notified by calling notifyConnected. Otherwise, if the gateway could not be connected, the engine must be notified by calling notifyCouldNotConnect.

See Also:

notifyConnected(), notifyCouldNotConnect(java.lang.Exception, boolean)

notifyConnected

protected final void notifyConnected()
                              throws IllegalStateException

Notifies the BotEngine that this gateway has been successfully connected.

Throws:

IllegalStateException - if this gateway is not currently connecting

See Also:

connect()

notifyCouldNotConnect

protected final void notifyCouldNotConnect(Exception exception,
                                           boolean canReconnect)
                                    throws IllegalStateException

Notifies the BotEngine that this gateway could not be connected.

Parameters:

exception - the exception that occurred, if any

canReconnect - whether the engine is allowed to try to connect this gateway again (this should be false if the gateway could not connect due to an invalid password, to avoid successive failed attempts)

Throws:

IllegalStateException - if this gateway is not currently connecting

See Also:

connect()

disconnect

protected abstract void disconnect()

Disconnects this gateway. This must be overridden to do whatever is necessary to disconnect (which may include closing socket connections, for example).

Unlike connect, the BotEngine does not have to be notified that this has been called; notifyDisconnected is only called when the connection has been closed unexpectedly.

notifyDisconnected

protected final void notifyDisconnected(Exception exception,
                                        boolean canReconnect)
                                 throws IllegalStateException

Notifies the BotEngine that this gateway's connection has been closed or severed unexpectedly. This may occur if a network socket connection has been closed by a remote server, for example.

Parameters:

exception - the exception that occurred, if any

canReconnect - whether the engine is allowed to try to connect this gateway again

Throws:

IllegalStateException - if this gateway is not currently in a connected state

sendMessage

protected abstract void sendMessage(BotSendMessageEvent event)
                             throws Exception

Overridden to send an outgoing message.

Parameters:

event - contains properties describing the message

Throws:

Exception

receiveMessage

protected final void receiveMessage(String userName,
                                    BotMessage message)
                             throws Exception

Notifies the BotEngine that a message has been received.

This is a convenience method, which creates a BotUser session and calls processMessage on that user.

Parameters:

userName - the unique name of the user that sent the message

message - the message

Throws:

Exception - if something goes wrong

addBuddy

protected void addBuddy(BotAddBuddyEvent event)
                 throws Exception

Adds a user to the client's Buddy List.

By default, an UnsupportedOperationException is thrown, indicating that this method is not implemented. Subclasses should override this to do something useful.

Parameters:

event - contains properties describing the user

Throws:

Exception

removeBuddy

protected void removeBuddy(BotRemoveBuddyEvent event)
                    throws Exception

Removes a user from the client's Buddy List.

By default, an UnsupportedOperationException is thrown, indicating that this method is not implemented. Subclasses should override this to do something useful.

Parameters:

event - contains properties describing the user

Throws:

Exception

addDeny

protected void addDeny(BotAddDenyEvent event)
                throws Exception

Adds a user to the client's Deny List.

By default, an UnsupportedOperationException is thrown, indicating that this method is not implemented. Subclasses should override this to do something useful.

Parameters:

event - contains properties describing the user

Throws:

Exception

removeDeny

protected void removeDeny(BotRemoveDenyEvent event)
                   throws Exception

Removes a user from the client's Deny List.

By default, an UnsupportedOperationException is thrown, indicating that this method is not implemented. Subclasses should override this to do something useful.

Parameters:

event - contains properties describing the user

Throws:

Exception

addPermit

protected void addPermit(BotAddPermitEvent event)
                  throws Exception

Adds a user to the client's Permit List.

By default, an UnsupportedOperationException is thrown, indicating that this method is not implemented. Subclasses should override this to do something useful.

Parameters:

event - contains properties describing the user

Throws:

Exception

removePermit

protected void removePermit(BotRemovePermitEvent event)
                     throws Exception

Removes a user from the client's Permit List.

By default, an UnsupportedOperationException is thrown, indicating that this method is not implemented. Subclasses should override this to do something useful.

Parameters:

event - contains properties describing the user

Throws:

Exception

sendFile

protected void sendFile(BotSendFileEvent event)
                 throws Exception

Sends a file to a user.

By default, an UnsupportedOperationException is thrown, indicating that this method is not implemented. Subclasses should override this to do something useful.

Parameters:

event - contains properties describing the file

Throws:

Exception

setPermitMode

protected void setPermitMode(BotSetPermitModeEvent event)
                      throws Exception

Sets the client's Permit Mode.

By default, an UnsupportedOperationException is thrown, indicating that this method is not implemented. Subclasses should override this to do something useful.

Parameters:

event - contains properties describing the Permit Mode change

Throws:

Exception

setStatus

protected void setStatus(BotSetStatusEvent event)
                  throws Exception

Sets the client's status.

By default, an UnsupportedOperationException is thrown, indicating that this method is not implemented. Subclasses should override this to do something useful.

Parameters:

event - contains properties describing the status change

Throws:

Exception

dispose

protected void dispose()

Disposes of resources used by this gateway.

This method is automatically called when this gateway is no longer being used by the BotEngine. Subclasses should override this to do something useful.