com.zion.jbuddy.bots
Class BotUser

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

public class BotUser
extends Object

Represents a bot user session.

The engine responds to user input events (such as messages and presence changes) with outgoing gateway commands and engine events. To create or retrieve a BotUser instance, call getUser on a BotClient. This is done automatically by the default gateways, and doesn't have to be done explicity unless a custom gateway implementation is needed.

See Also:

BotClient, BotGateway, processMessage(com.zion.jbuddy.bots.BotMessage), processPresence()

Method Summary

boolean	equals(Object object)
BotClient	getClient() Returns the client this user is associated with.
long	getCreationTime() Returns the system time when this user was created.
Object	getCustomProperty(String name) Returns a custom property value.
String	getDisplayName() Returns this user's display name.
BotEventHandlerSet	getEventHandlers() Returns this user's event handlers.
String	getName() Returns this user's unique name.
String	getStatus() Returns this user's status.
String	getStatusMessage() Returns this user's status message.
BotTargetSet	getTargets() Returns this user's targets.
long	getUpdateTime() Returns the system time when this user was last updated.
int	hashCode()
boolean	processMessage(BotMessage message) Processes an incoming message from this user.
boolean	processPresence() Processes a presence change from this user.
void	processXML(Document document) Processes Bot Definition XML.
void	processXML(InputSource inputSource) Processes Bot Definition XML.
Object	setCustomProperty(String name, Object value) Sets a custom property value.
void	setDisplayName(String displayName) Sets this user's display name.
void	setStatus(String status, String message) Sets this user's status.
String	toString()

Methods inherited from class java.lang.Object

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

Method Detail

getClient

public BotClient getClient()

Returns the client this user is associated with.

getName

public String getName()

Returns this user's unique name.

The content variable ${name} is replaced with this value. For example, the following target can be used to display a greeting to users:

<target default="true"> <content>Hello there, ${name}!</content> </target>

getDisplayName

public String getDisplayName()

Returns this user's display name.

The content variable ${displayName} is replaced with this value. For example, the following target can be used to display a greeting to users:

<target default="true"> <content>Hello there, ${displayName}!</content> </target>

setDisplayName

public void setDisplayName(String displayName)

Sets this user's display name.

Parameters:

displayName - the display name. If null or empty, the user's name will be used as its display name.

getStatus

public String getStatus()

Returns this user's status.

getStatusMessage

public String getStatusMessage()

Returns this user's status message.

setStatus

public void setStatus(String status,
                      String message)

Sets this user's status.

This method does not automatically process presence event handlers. To process event handlers, call processPresence.

Parameters:

status - the status

message - the status message

getTargets

public BotTargetSet getTargets()

Returns this user's targets.

The first time this method is called, the bot engine's targets are copied into this user instance. This allows this user's targets to be modified separately from the bot engine's. This can be used, for example, to create a target or menu for this user only, instead of for all users.

getEventHandlers

public BotEventHandlerSet getEventHandlers()

Returns this user's event handlers.

The first time this method is called, the bot engine's event handlers are copied into this user instance. This allows this user's event handlers to be modified separately from the bot engine's. This can be used, for example, to create an event handler for this user only, instead of for all users.

getCreationTime

public long getCreationTime()

Returns the system time when this user was created.

getUpdateTime

public long getUpdateTime()

Returns the system time when this user was last updated.

A user is updated when input or messages are received from it, or the engine uses it for some other reason (such as when the engine triggers an event handler associated with the user).

processMessage

public boolean processMessage(BotMessage message)
                       throws Exception

Processes an incoming message from this user.

The BotEngine processes this message, and triggers any associated targets or event handlers.

If this message has type IM or null, it is processed as a user command. Any targets with the associated command are triggered. For example, an IM type message with the body gettime would trigger a target having the command gettime.

Returns:

true if the engine processed the message successfully

Throws:

Exception - if a problem occurs, such as the bot engine not being started before attempting to process input

processPresence

public boolean processPresence()
                        throws Exception

Processes a presence change from this user.

The BotEngine processes this presence change, and triggers any associated event handlers. This method should be called after setting presence-related values, such as the status or status message.

Returns:

true if the engine processed the presence successfully

Throws:

Exception - if a problem occurs, such as the bot engine not being started before attempting to process input

processXML

public void processXML(Document document)
                throws Exception

Processes Bot Definition XML. The XML is parsed dynamically into a BotCall and presented to the user as if it was part of the original Bot Definition.

Parameters:

document - the XML document

Throws:

Exception

processXML

public void processXML(InputSource inputSource)
                throws Exception

Processes Bot Definition XML. The XML is parsed dynamically into a BotCall and presented to the user as if it was part of the original Bot Definition.

Parameters:

inputSource - the XML input source

Throws:

Exception

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 user 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

hashCode

public int hashCode()

Overrides:

hashCode in class Object

equals

public boolean equals(Object object)

Overrides:

equals in class Object

toString

public String toString()

Overrides:

toString in class Object