org.jivesoftware.smackx.workgroup.user
Class Workgroup

java.lang.Object
  org.jivesoftware.smackx.workgroup.user.Workgroup

public class Workgroup
extends Object

Provides workgroup services for users. Users can join the workgroup queue, depart the queue, find status information about their placement in the queue, and register to be notified when they are routed to an agent.

This class only provides a user's perspective into a workgroup and is not intended for use by agents.

Author:

Matt Tucker

Constructor Summary

Workgroup(String workgroupName, XMPPConnection connection)
Creates a new workgroup instance using the specified workgroup name (eg support@example.com) and XMPP connection.

Method Summary

void	addInvitationListener(PacketListener packetListener) Adds an invitation listener that will be notified of groupchat invitations from the workgroup for the the user that created this Workgroup instance.
void	addQueueListener(QueueListener queueListener) Adds a queue listener that will be notified of queue events for the user that created this Workgroup instance.
void	departQueue() Departs the workgroup queue.
protected void	finalize()
int	getQueuePosition() Returns the user's current position in the workgroup queue.
int	getQueueRemainingTime() Returns the estimated time (in seconds) that the user has to left wait in the workgroup queue before being routed.
String	getWorkgroupName() Returns the name of this workgroup (eg support@example.com).
boolean	isInQueue() Returns true if the user is currently waiting in the workgroup queue.
void	joinQueue() Joins the workgroup queue to wait to be routed to an agent.
void	joinQueue(Map metaData) Joins the workgroup queue to wait to be routed to an agent.
void	removeQueueListener(QueueListener queueListener) Removes a queue listener.

Methods inherited from class java.lang.Object

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

Constructor Detail

Workgroup

public Workgroup(String workgroupName,
                 XMPPConnection connection)

Creates a new workgroup instance using the specified workgroup name (eg support@example.com) and XMPP connection. The connection must have undergone a successful login before being used to construct an instance of this class.

Parameters:

workgroupName - the fully qualified name of the workgroup.

connection - an XMPP connection which must have already undergone a successful login.

Method Detail

getWorkgroupName

public String getWorkgroupName()

Returns the name of this workgroup (eg support@example.com).

Returns:

the name of the workgroup.

isInQueue

public boolean isInQueue()

Returns true if the user is currently waiting in the workgroup queue.

Returns:

true if currently waiting in the queue.

getQueuePosition

public int getQueuePosition()

Returns the user's current position in the workgroup queue. A value of 0 means the user is next in line to be routed; therefore, if the queue position is being displayed to the end user it is usually a good idea to add 1 to the value this method returns before display. If the user is not currently waiting in the workgorup, or no queue position information is available, -1 will be returned.

Returns:

the user's current position in the workgorup queue, or -1 if the position isn't available or if the user isn't in the queue.

getQueueRemainingTime

public int getQueueRemainingTime()

Returns the estimated time (in seconds) that the user has to left wait in the workgroup queue before being routed. If the user is not currently waiting int he workgroup, or no queue time information is available, -1 will be returned.

Returns:

the estimated time remaining (in seconds) that the user has to wait in the workgropu queue, or -1 if time information isn't available or if the user isn't int the queue.

joinQueue

public void joinQueue()
               throws XMPPException

Joins the workgroup queue to wait to be routed to an agent. After joining the queue, queue status events will be sent to indicate the user's position and estimated time left in the queue. Once joining the queue, there are three ways the user will leave the queue:

• The user is routed to an agent, which triggers a groupchat invitation.
• The user asks to leave the queue by calling the departQueue() method.
• A server error occurs, or an administrator explicitly removes the user from the queue.

A user cannot request to join the queue again if already in the queue. Therefore, this method will do nothing if the user is already in the queue.

Some servers may be configured to require certain meta-data in order to join the queue. In that case, the joinQueue(Map) method should be used instead of this method so that meta-data may be passed in.

Throws:

XMPPException - if an error occured joining the queue. An error may indicate that a connection failure occured or that the server explicitly rejected the request to join the queue.

joinQueue

public void joinQueue(Map metaData)
               throws XMPPException

Joins the workgroup queue to wait to be routed to an agent. After joining the queue, queue status events will be sent to indicate the user's position and estimated time left in the queue. Once joining the queue, there are three ways the user will leave the queue:

• The user is routed to an agent, which triggers a groupchat invitation.
• The user asks to leave the queue by calling the departQueue() method.
• A server error occurs, or an administrator explicitly removes the user from the queue.

A user cannot request to join the queue again if already in the queue. Therefore, this method will do nothing if the user is already in the queue.

Arbitrary meta-data can be passed in with the queue join request in order to assist the server in routing the user to an agent and to provide information about the user to the agent. Some servers may be configured to require certain meta-data in order to join the queue.

The server may reject the join queue request, which will cause an XMPPException to be thrown. The error codes for specific cases are as follows:

• 503 -- the workgroup is closed or otherwise unavailable to take new chat requests.

Parameters:

metaData - the metaData for the join request.

Throws:

XMPPException - if an error occured joining the queue. An error may indicate that a connection failure occured or that the server explicitly rejected the request to join the queue (error code 503). The error code should be checked to determine the specific error.

departQueue

public void departQueue()
                 throws XMPPException

Departs the workgroup queue. If the user is not currently in the queue, this method will do nothing.

Normally, the user would not manually leave the queue. However, they may wish to under certain circumstances -- for example, if they no longer wish to be routed to an agent because they've been waiting too long.

Throws:

XMPPException - if an error occured trying to send the depart queue request to the server.

addQueueListener

public void addQueueListener(QueueListener queueListener)

Adds a queue listener that will be notified of queue events for the user that created this Workgroup instance.

Parameters:

queueListener - the queue listener.

removeQueueListener

public void removeQueueListener(QueueListener queueListener)

Removes a queue listener.

Parameters:

queueListener - the queue listener.

addInvitationListener

public void addInvitationListener(PacketListener packetListener)

Adds an invitation listener that will be notified of groupchat invitations from the workgroup for the the user that created this Workgroup instance.

Parameters:

packetListener - the invitation listener.

finalize

protected void finalize()
                 throws Throwable

Overrides:

finalize in class Object

Throws:

Throwable