org.jivesoftware.smackx.workgroup.agent
Class WorkgroupSession

java.lang.Object
  org.jivesoftware.smackx.workgroup.agent.WorkgroupSession

public class WorkgroupSession
extends Object

This class embodies the agent's active presence within a given workgroup. The application should have N instances of this class, where N is the number of workgroups to which the owning agent of the application belongs. This class provides all functionality that a session within a given workgroup is expected to have from an agent's perspective -- setting the status, tracking the status of queues to which the agent belongs within the workgroup, and dequeuing customers.

Author:

Matt Tucker

Constructor Summary

WorkgroupSession(String workgroupName, XMPPConnection connection)
Creates a new agent session instance.

Method Summary

void	addInvitationListener(PacketListener invitationListener) Adds an invitation listener.
void	addOfferListener(OfferListener offerListener) Adds an offer listener.
void	addQueueAgentsListener(QueueAgentsListener listener)
void	addQueueUsersListener(QueueUsersListener listener)
void	dequeueUser(String userID) Removes a user from the workgroup queue.
int	getCurrentChats() Returns the current number of chats the agent is in.
int	getMaxChats() Returns the maximum number of chats the agent can participate in.
String	getMetaData(String key) Allows the retrieval of meta data for a specified key.
Presence.Mode	getPresenceMode() Returns the agent's current presence mode.
WorkgroupQueue	getQueue(String queueName)
Iterator	getQueues()
String	getWorkgroupName()
boolean	isOnline() Returns true if the agent is online with the workgroup.
void	removeMetaData(String key) Allows the removal of data from the agent's meta data, if the key represents existing data, the revised meta data will be rebroadcast in an agent's presence broadcast.
void	removeOfferListener(OfferListener offerListener) Removes an offer listener.
void	removeQueueAgentsListener(QueueAgentsListener listener)
void	removeQueueUsersListener(QueueUsersListener listener)
void	setMetaData(String key, String val) Allows the addition of a new key-value pair to the agent's meta data, if the value is new data, the revised meta data will be rebroadcast in an agent's presence broadcast.
void	setOnline(boolean online) Sets whether the agent is online with the workgroup.
void	setStatus(Presence.Mode presenceMode, int currentChats, int maxChats) Sets the agent's current status with the workgroup.
void	setStatus(Presence.Mode presenceMode, int currentChats, int maxChats, String status) Sets the agent's current status with the workgroup.

Methods inherited from class java.lang.Object

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

Constructor Detail

WorkgroupSession

public WorkgroupSession(String workgroupName,
                        XMPPConnection connection)

Creates a new agent session instance.

Parameters:

connection - a connection instance which must have already gone through authentication.

workgroupName - the fully qualified name of the workgroup.

Method Detail

getPresenceMode

public Presence.Mode getPresenceMode()

Returns the agent's current presence mode.

Returns:

the agent's current presence mode.

getCurrentChats

public int getCurrentChats()

Returns the current number of chats the agent is in.

Returns:

the current number of chats the agent is in.

getMaxChats

public int getMaxChats()

Returns the maximum number of chats the agent can participate in.

Returns:

the maximum number of chats the agent can participate in.

isOnline

public boolean isOnline()

Returns true if the agent is online with the workgroup.

Returns:

true if the agent is online with the workgroup.

setMetaData

public void setMetaData(String key,
                        String val)
                 throws XMPPException

Allows the addition of a new key-value pair to the agent's meta data, if the value is new data, the revised meta data will be rebroadcast in an agent's presence broadcast.

Parameters:

key - the meta data key

val - the non-null meta data value

Throws:

XMPPException

removeMetaData

public void removeMetaData(String key)
                    throws XMPPException

Allows the removal of data from the agent's meta data, if the key represents existing data, the revised meta data will be rebroadcast in an agent's presence broadcast.

Parameters:

key - the meta data key

Throws:

XMPPException

getMetaData

public String getMetaData(String key)

Allows the retrieval of meta data for a specified key.

Parameters:

key - the meta data key

Returns:

the meta data value associated with the key or null if the meta-data doesn't exist..

setOnline

public void setOnline(boolean online)
               throws XMPPException

Sets whether the agent is online with the workgroup. If the user tries to go online with the workgroup but is not allowed to be an agent, an XMPPError with error code 401 will be thrown.

Parameters:

online - true to set the agent as online with the workgroup.

Throws:

XMPPException - if an error occurs setting the online status.

setStatus

public void setStatus(Presence.Mode presenceMode,
                      int currentChats,
                      int maxChats)
               throws XMPPException

Sets the agent's current status with the workgroup. The presence mode affects how offers are routed to the agent. The possible presence modes with their meanings are as follows:

• Presence.Mode.AVAILABLE -- (Default) the agent is available for more chats (equivalent to Presence.Mode.CHAT).
• Presence.Mode.DO_NOT_DISTURB -– the agent is busy and should not be disturbed. However, special case, or extreme urgency chats may still be offered to the agent.
• Presence.Mode.AWAY -- the agent is not available and should not have a chat routed to them (equivalent to Presence.Mode.EXTENDED_AWAY).

The current chats value indicates how many chats the agent is currently in. Because the agent is responsible for reporting the current chats value to the server, this value must be set every time it changes.

The max chats value is the maximum number of chats the agent is willing to have routed to them at once. Some servers may be configured to only accept max chat values in a certain range; for example, between two and five. In that case, the maxChats value the agent sends may be adjusted by the server to a value within that range.

Parameters:

presenceMode - the presence mode of the agent.

currentChats - the current number of chats the agent is in.

maxChats - the maximum number of chats the agent is willing to accept.

Throws:

XMPPException - if an error occurs setting the agent status.

IllegalStateException - if the agent is not online with the workgroup.

setStatus

public void setStatus(Presence.Mode presenceMode,
                      int currentChats,
                      int maxChats,
                      String status)
               throws XMPPException

Sets the agent's current status with the workgroup. The presence mode affects how offers are routed to the agent. The possible presence modes with their meanings are as follows:

• Presence.Mode.AVAILABLE -- (Default) the agent is available for more chats (equivalent to Presence.Mode.CHAT).
• Presence.Mode.DO_NOT_DISTURB -– the agent is busy and should not be disturbed. However, special case, or extreme urgency chats may still be offered to the agent.
• Presence.Mode.AWAY -- the agent is not available and should not have a chat routed to them (equivalent to Presence.Mode.EXTENDED_AWAY).

The current chats value indicates how many chats the agent is currently in. Because the agent is responsible for reporting the current chats value to the server, this value must be set every time it changes.

The max chats value is the maximum number of chats the agent is willing to have routed to them at once. Some servers may be configured to only accept max chat values in a certain range; for example, between two and five. In that case, the maxChats value the agent sends may be adjusted by the server to a value within that range.

Parameters:

presenceMode - the presence mode of the agent.

currentChats - the current number of chats the agent is in.

maxChats - the maximum number of chats the agent is willing to accept.

status - sets the status message of the presence update.

Throws:

XMPPException - if an error occurs setting the agent status.

IllegalStateException - if the agent is not online with the workgroup.

dequeueUser

public void dequeueUser(String userID)
                 throws XMPPException

Removes a user from the workgroup queue. This is an administrative action that the The agent is not guaranteed of having privileges to perform this action; an exception denying the request may be thrown.

Throws:

XMPPException

getWorkgroupName

public String getWorkgroupName()

Returns:

the fully-qualified name of the workgroup for which this session exists

getQueue

public WorkgroupQueue getQueue(String queueName)

Parameters:

queueName - the name of the queue

Returns:

an instance of WorkgroupQueue for the argument queue name, or null if none exists

getQueues

public Iterator getQueues()

addQueueUsersListener

public void addQueueUsersListener(QueueUsersListener listener)

removeQueueUsersListener

public void removeQueueUsersListener(QueueUsersListener listener)

addQueueAgentsListener

public void addQueueAgentsListener(QueueAgentsListener listener)

removeQueueAgentsListener

public void removeQueueAgentsListener(QueueAgentsListener listener)

addOfferListener

public void addOfferListener(OfferListener offerListener)

Adds an offer listener.

Parameters:

offerListener - the offer listener.

removeOfferListener

public void removeOfferListener(OfferListener offerListener)

Removes an offer listener.

Parameters:

offerListener - the offer listener.

addInvitationListener

public void addInvitationListener(PacketListener invitationListener)

Adds an invitation listener.

Parameters:

invitationListener - the invitation listener.