com.zion.jbuddy.bots
Class BotClient

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

public class BotClient
extends Object

Used by the bot engine to communicate with external networks.

A client can be specified in the Bot Definition File, or can be created manually and added to a BotEngine by calling addClient.

Constructor Summary

BotClient(String protocol, String name)
Creates a bot client.

Method Summary

void	addBuddy(String name, String displayName, String group) Adds a user to the client's buddy list.
void	addDeny(String name) Adds a user to the client's deny list.
void	addPermit(String name) Adds a user to the client's permit list.
void	connect() Connects this client to an external network.
void	disconnect() Disconnects this client from the external network.
boolean	equals(BotClient client) Returns true if this client is equal to the specified client.
boolean	equals(Object object)
long	getConnectTimeout() Returns this client's connect timeout value, in milliseconds.
Object	getCustomProperty(String name) Returns a custom property value.
String	getDescription() Returns this client's description.
String	getDisplayName() Returns this client's display name.
BotEngine	getEngine() Returns the engine this client is associated with.
Class	getGatewayClass() Returns this client's BotGateway class.
String	getHost() Returns this client's host address.
String	getID() Returns this client's identifier.
IClient	getJBuddyClient() Returns the JBuddy SDK client being used.
String	getName() Returns this client's unique name.
String	getPassword() Returns this client's password.
String	getPermitMode() Returns the client's permit mode.
int	getPort() Returns this client's port.
Properties	getProperties() Returns system properties that pertain to this client.
String	getProtocol() Returns this client's protocol.
BotStatistics	getStatistics() Returns this client's statistics.
String	getStatus() Returns this client's status.
String	getStatusMessage() Returns this client's status message.
BotUser	getUser(String name) Returns the user session with the specified name.
int	hashCode()
boolean	isConnected() Returns whether this client is connected to an external network.
boolean	isConnecting() Returns whether this client is in the process of connecting.
boolean	isPasswordEncrypted() Returns whether the password is encrypted.
void	removeBuddy(String name) Removes a user from the client's buddy list.
void	removeBuddy(String name, String group) Removes a user from the client's buddy list.
void	removeDeny(String name) Removes a user from the client's deny list.
void	removePermit(String name) Removes a user from the client's permit list.
void	sendFile(String userName, BotFile file) Sends a file to this user.
void	sendMessage(String userName, BotMessage message) Sends a message to a user.
void	setConnectTimeout(long connectTimeout) Sets this client's connect timeout value, in milliseconds.
Object	setCustomProperty(String name, Object value) Sets a custom property value.
void	setDescription(String description) Sets this client's description.
void	setDisplayName(String displayName) Sets this client's display name.
void	setGatewayClass(Class gatewayClass) Sets this client's BotGateway class.
void	setHost(String host) Sets this client's host address.
void	setID(String id) Sets this client's identifier, which can be used to reference this client.
void	setPassword(String password) Sets this client's password.
void	setPasswordEncrypted(boolean passwordEncrypted) Sets whether the password is encrypted.
void	setPermitMode(String permitMode) Sets this client's permit mode.
void	setPort(int port) Sets this client's port.
void	setStatus(String status, String message) Sets this client's status.
String	toString()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

BotClient

public BotClient(String protocol,
                 String name)

Creates a bot client.

Parameters:

protocol - the client's protocol

name - the client's unique name

Method Detail

getEngine

public BotEngine getEngine()

Returns the engine this client is associated with.

Returns:

the engine, or null (if this client was not added to an engine)

getProtocol

public String getProtocol()

Returns this client's protocol.

getName

public String getName()

Returns this client's unique name.

getID

public String getID()

Returns this client's identifier.

setID

public void setID(String id)

Sets this client's identifier, which can be used to reference this client.

If not specified, the default value is name#protocol. For example, if a client's name is somebot and its protocol is AIM, its default identifier is somebot#AIM.

Client identifiers are used with routes to reference sender clients.

getConnectTimeout

public long getConnectTimeout()

Returns this client's connect timeout value, in milliseconds.

setConnectTimeout

public void setConnectTimeout(long connectTimeout)

Sets this client's connect timeout value, in milliseconds.

If a client's gateway takes longer than its specified timeout to connect successfully, the connection attempt is canceled, and the gateway is disconnected. If a timeout is not specified (connectTimeout <= 0), the gateway is allowed to take any amount of time to complete.

The default value is 0.

getDescription

public String getDescription()

Returns this client's description.

setDescription

public void setDescription(String description)

Sets this client's description.

This is an informational value, and is not used by the bot engine.

getDisplayName

public String getDisplayName()

Returns this client's display name.

setDisplayName

public void setDisplayName(String displayName)

Sets this client's display name.

This is normally visible to other users in messages or their buddy lists.

getGatewayClass

public Class getGatewayClass()

Returns this client's BotGateway class.

setGatewayClass

public void setGatewayClass(Class gatewayClass)

Sets this client's BotGateway class. The value must be the class of a BotGateway implementation.

If not specified, gateway support is provided internally by the JBuddy SDK. A custom gateway implementation should be provided if necessary features are not already provided by the default gateway (such as custom protocols, message types, or status types).

getHost

public String getHost()

Returns this client's host address.

setHost

public void setHost(String host)

Sets this client's host address.

This is the address of the server the client should connect to.

getPort

public int getPort()

Returns this client's port.

setPort

public void setPort(int port)

Sets this client's port.

This is the port number of the server the client should connect to.

getPassword

public String getPassword()

Returns this client's password.

setPassword

public void setPassword(String password)

Sets this client's password.

If passwordEncrypted is true, this value must be the encrypted password string, obtained from the EncryptPassword utility included with the framework.

isPasswordEncrypted

public boolean isPasswordEncrypted()

Returns whether the password is encrypted.

setPasswordEncrypted

public void setPasswordEncrypted(boolean passwordEncrypted)

Sets whether the password is encrypted.

If true, the password value must be the encrypted password string, obtained from the EncryptPassword utility included with the framework.

getProperties

public Properties getProperties()

Returns system properties that pertain to this client.

These properties are loaded into the Java system properties when this client gateway is in the process of connecting to its host. After connecting, the previous values of any system properties that were modified are restored.

See Also:

System.setProperty(java.lang.String, java.lang.String)

getStatistics

public BotStatistics getStatistics()

Returns this client's statistics.

getUser

public BotUser getUser(String name)

Returns the user session with the specified name.

If the session already exists, it is returned. Otherwise, a new user session is created and returned.

This method must be called each time user input is to be processed. User session references should not be kept for longer than necessary, as the bot engine manages and removes sessions automatically, and references may become stale after some time.

getCustomProperty

public Object getCustomProperty(String name)

Returns a custom property value.

Parameters:

name - the property's name

setCustomProperty

public Object setCustomProperty(String name,
                                Object value)

Sets a custom property value.

Custom properties can be attached to this client instance by an application using the bot framework, for convenience. They are not used by the engine itself.

Parameters:

name - the property's name

value - the property's value (if null, the property is removed)

Returns:

the property's previous value, or null

isConnecting

public boolean isConnecting()

Returns whether this client is in the process of connecting.

isConnected

public boolean isConnected()

Returns whether this client is connected to an external network.

connect

public void connect()
             throws Exception

Connects this client to an external network.

When connecting, a BotGateway is instantiated for this client, according to its gateway class. The gateway uses this client's properties and information (such as the protocol, name, password, host, and port values) to set up a connection.

Once the client has connected successfully, isConnected will return true, and a connected event will be fired. Otherwise, if the connection attempt fails for some reason, a couldNotConnect event will be fired.

Throws:

Exception

See Also:

BotClientConnectionListener

disconnect

public void disconnect()

Disconnects this client from the external network.

getJBuddyClient

public IClient getJBuddyClient()

Returns the JBuddy SDK client being used.

This call is equivalent to:

(IClient)getCustomProperty("com.zion.jbuddy.IClient")

Returns:

the JBuddy client, or null (if this client is not connected, or the JBuddy SDK is not being used)

sendMessage

public void sendMessage(String userName,
                        BotMessage message)
                 throws Exception

Sends a message to a user.

The message is sent using the associated gateway. A sendMessage event is also fired.

Parameters:

userName - the name of the user to send to

message - the message

Throws:

Exception - if this client is not currently connected

sendFile

public void sendFile(String userName,
                     BotFile file)
              throws Exception

Sends a file to this user.

The file is sent using the associated gateway. A sendFile event is also fired.

Parameters:

userName - the name of the user to send to

file - the file

Throws:

Exception - if this client is not currently connected

getStatus

public String getStatus()

Returns this client's status.

getStatusMessage

public String getStatusMessage()

Returns this client's status message.

setStatus

public void setStatus(String status,
                      String message)
               throws Exception

Sets this client's status.

The status is set using the associated gateway. A setStatus event is also fired.

Parameters:

status - the status

message - the status message

Throws:

Exception - if this client is not currently connected

addBuddy

public void addBuddy(String name,
                     String displayName,
                     String group)
              throws Exception

Adds a user to the client's buddy list.

The buddy is added using the associated gateway. A addBuddy event is also fired.

Parameters:

name - the user's name

displayName - the user's display name

group - the group to add the user to

Throws:

Exception - if this client is not currently connected

removeBuddy

public void removeBuddy(String name)
                 throws Exception

Removes a user from the client's buddy list.

The buddy is removed using the associated gateway. A removeBuddy event is also fired.

Parameters:

name - the user's name

Throws:

Exception - if this client is not currently connected

removeBuddy

public void removeBuddy(String name,
                        String group)
                 throws Exception

Removes a user from the client's buddy list.

The buddy is removed using the associated gateway. A removeBuddy event is also fired.

Parameters:

name - the user's name

group - the group to remove the user from; if a group is not specified, the user is removed from all groups

Throws:

Exception - if this client is not currently connected

getPermitMode

public String getPermitMode()

Returns the client's permit mode.

setPermitMode

public void setPermitMode(String permitMode)
                   throws Exception

Sets this client's permit mode.

The permit mode is set using the associated gateway. A setPermitMode event is also fired.

Parameters:

permitMode - the permitMode

Throws:

Exception - if this client is not currently connected

addDeny

public void addDeny(String name)
             throws Exception

Adds a user to the client's deny list.

The user is added using the associated gateway. A addDeny event is also fired.

Parameters:

name - the user's name

Throws:

Exception - if this client is not currently connected

removeDeny

public void removeDeny(String name)
                throws Exception

Removes a user from the client's deny list.

The user is removed using the associated gateway. A removeDeny event is also fired.

Parameters:

name - the user's name

Throws:

Exception - if this client is not currently connected

addPermit

public void addPermit(String name)
               throws Exception

Adds a user to the client's permit list.

The user is added using the associated gateway. A addPermit event is also fired.

Parameters:

name - the user's name

Throws:

Exception - if this client is not currently connected

removePermit

public void removePermit(String name)
                  throws Exception

Removes a user from the client's permit list.

The user is removed using the associated gateway. A removePermit event is also fired.

Parameters:

name - the user's name

Throws:

Exception - if this client is not currently connected

equals

public boolean equals(BotClient client)

Returns true if this client is equal to the specified client. Clients are equal if their various properties are also equal. Custom property values are not considered when comparing clients for equality.

equals

public boolean equals(Object object)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

toString

public String toString()

Overrides:

toString in class Object