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 users perspective into a workgroup and is not intended for use by agents.

Constructor Summary

Constructors

Constructor and Description
Workgroup(EntityBareJid workgroupJID, XMPPConnection connection) Creates a new workgroup instance using the specified workgroup JID (eg support@workgroup.example.com) and XMPP connection.

Method Summary

Modifier and Type	Method and Description
void	addInvitationListener(WorkgroupInvitationListener invitationListener) 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.
ChatSetting	getChatSetting(String key) Returns a single chat setting based on it's identified key.
ChatSettings	getChatSettings() Returns all ChatSettings.
ChatSettings	getChatSettings(int type) Returns ChatSettings based on type.
OfflineSettings	getOfflineSettings() Asks the workgroup for it's Offline Settings.
int	getQueuePosition() Returns the users 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.
SoundSettings	getSoundSettings() Asks the workgroup for it's Sound Settings.
Form	getWorkgroupForm() Returns the Form to use for all clients of a workgroup.
EntityBareJid	getWorkgroupJID() Returns the name of this workgroup (eg support@example.com).
WorkgroupProperties	getWorkgroupProperties() Asks the workgroup for it's Properties.
WorkgroupProperties	getWorkgroupProperties(String jid) Asks the workgroup for it's Properties.
boolean	isAvailable() Returns true if the workgroup is available for receiving new requests.
boolean	isEmailAvailable() The workgroup service may be configured to send email.
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(Form answerForm) Joins the workgroup queue to wait to be routed to an agent.
void	joinQueue(Form answerForm, Jid userID) Joins the workgroup queue to wait to be routed to an agent.
void	joinQueue(Map<String,Object> metadata, Jid userID) Joins the workgroup queue to wait to be routed to an agent.
void	removeQueueListener(QueueListener queueListener) Removes a queue listener.
void	removeQueueListener(WorkgroupInvitationListener invitationListener) Removes an invitation listener.

Methods inherited from class java.lang.Object

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

Constructor Detail

Workgroup

public Workgroup(EntityBareJid workgroupJID,
                 XMPPConnection connection)

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

Parameters:

workgroupJID - the JID of the workgroup.

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

Method Detail

getWorkgroupJID

public EntityBareJid getWorkgroupJID()

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.

isAvailable

public boolean isAvailable()
                    throws SmackException.NoResponseException,
                           XMPPException.XMPPErrorException,
                           SmackException.NotConnectedException,
                           InterruptedException

Returns true if the workgroup is available for receiving new requests. The workgroup will be available only when agents are available for this workgroup.

Returns:

true if the workgroup is available for receiving new requests.

Throws:

XMPPException.XMPPErrorException

SmackException.NoResponseException

SmackException.NotConnectedException

InterruptedException

getQueuePosition

public int getQueuePosition()

Returns the users 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 workgroup, or no queue position information is available, -1 will be returned.

Returns:

the user's current position in the workgroup 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 workgroup queue, or -1 if time information isn't available or if the user isn't int the queue.

joinQueue

public void joinQueue()
               throws XMPPException,
                      SmackException,
                      InterruptedException

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 can 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 throw an IllegalStateException 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(Form) method should be used instead of this method so that meta-data may be passed in.

The server tracks the conversations that a user has with agents over time. By default, that tracking is done using the user's JID. However, this is not always possible. For example, when the user is logged in anonymously using a web client. In that case the user ID might be a randomly generated value put into a persistent cookie or a username obtained via the session. A userID can be explicitly passed in by using the joinQueue(Form, Jid) method. When specified, that userID will be used instead of the user's JID to track conversations. The server will ignore a manually specified userID if the user's connection to the server is not anonymous.

Throws:

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

SmackException

InterruptedException

joinQueue

public void joinQueue(Form answerForm)
               throws XMPPException,
                      SmackException,
                      InterruptedException

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 can 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 throw an IllegalStateException if the user is already in the queue.

Some servers may be configured to require certain meta-data in order to join the queue.

The server tracks the conversations that a user has with agents over time. By default, that tracking is done using the user's JID. However, this is not always possible. For example, when the user is logged in anonymously using a web client. In that case the user ID might be a randomly generated value put into a persistent cookie or a username obtained via the session. A userID can be explicitly passed in by using the joinQueue(Form, Jid) method. When specified, that userID will be used instead of the user's JID to track conversations. The server will ignore a manually specified userID if the user's connection to the server is not anonymous.

Parameters:

answerForm - the completed form the send for the join request.

Throws:

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

SmackException

InterruptedException

joinQueue

public void joinQueue(Form answerForm,
                      Jid userID)
               throws SmackException.NoResponseException,
                      XMPPException.XMPPErrorException,
                      SmackException.NotConnectedException,
                      InterruptedException

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 can 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 throw an IllegalStateException if the user is already in the queue.

Some servers may be configured to require certain meta-data in order to join the queue.

The server tracks the conversations that a user has with agents over time. By default, that tracking is done using the user's JID. However, this is not always possible. For example, when the user is logged in anonymously using a web client. In that case the user ID might be a randomly generated value put into a persistent cookie or a username obtained via the session. When specified, that userID will be used instead of the user's JID to track conversations. The server will ignore a manually specified userID if the user's connection to the server is not anonymous.

Parameters:

answerForm - the completed form associated with the join request.

userID - String that represents the ID of the user when using anonymous sessions or null if a userID should not be used.

Throws:

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

SmackException.NoResponseException

SmackException.NotConnectedException

InterruptedException

joinQueue

public void joinQueue(Map<String,Object> metadata,
                      Jid userID)
               throws XMPPException,
                      SmackException,
                      InterruptedException

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 can 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 throw an IllegalStateException if the user is already in the queue.

Some servers may be configured to require certain meta-data in order to join the queue.

The server tracks the conversations that a user has with agents over time. By default, that tracking is done using the user's JID. However, this is not always possible. For example, when the user is logged in anonymously using a web client. In that case the user ID might be a randomly generated value put into a persistent cookie or a username obtained via the session. When specified, that userID will be used instead of the user's JID to track conversations. The server will ignore a manually specified userID if the user's connection to the server is not anonymous.

Parameters:

metadata - metadata to create a dataform from.

userID - String that represents the ID of the user when using anonymous sessions or null if a userID should not be used.

Throws:

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

SmackException

InterruptedException

departQueue

public void departQueue()
                 throws SmackException.NoResponseException,
                        XMPPException.XMPPErrorException,
                        SmackException.NotConnectedException,
                        InterruptedException

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.XMPPErrorException - if an error occurred trying to send the depart queue request to the server.

SmackException.NoResponseException

SmackException.NotConnectedException

InterruptedException

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(WorkgroupInvitationListener invitationListener)

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

Parameters:

invitationListener - the invitation listener.

removeQueueListener

public void removeQueueListener(WorkgroupInvitationListener invitationListener)

Removes an invitation listener.

Parameters:

invitationListener - the invitation listener.

getChatSetting

public ChatSetting getChatSetting(String key)
                           throws XMPPException,
                                  SmackException,
                                  InterruptedException

Returns a single chat setting based on it's identified key.

Parameters:

key - the key to find.

Returns:

the ChatSetting if found, otherwise false.

Throws:

XMPPException - if an error occurs while getting information from the server.

SmackException

InterruptedException

getChatSettings

public ChatSettings getChatSettings(int type)
                             throws XMPPException,
                                    SmackException,
                                    InterruptedException

Returns ChatSettings based on type.

Parameters:

type - the type of ChatSettings to return.

Returns:

the ChatSettings of given type, otherwise null.

Throws:

XMPPException - if an error occurs while getting information from the server.

SmackException

InterruptedException

getChatSettings

public ChatSettings getChatSettings()
                             throws XMPPException,
                                    SmackException,
                                    InterruptedException

Returns all ChatSettings.

Returns:

all ChatSettings of a given workgroup.

Throws:

XMPPException - if an error occurs while getting information from the server.

SmackException

InterruptedException

isEmailAvailable

public boolean isEmailAvailable()
                         throws SmackException,
                                InterruptedException

The workgroup service may be configured to send email. This queries the Workgroup Service to see if the email service has been configured and is available.

Returns:

true if the email service is available, otherwise return false.

Throws:

SmackException

InterruptedException

getOfflineSettings

public OfflineSettings getOfflineSettings()
                                   throws SmackException.NoResponseException,
                                          XMPPException.XMPPErrorException,
                                          SmackException.NotConnectedException,
                                          InterruptedException

Asks the workgroup for it's Offline Settings.

Returns:

offlineSettings the offline settings for this workgroup.

Throws:

XMPPException.XMPPErrorException

SmackException.NoResponseException

SmackException.NotConnectedException

InterruptedException

getSoundSettings

public SoundSettings getSoundSettings()
                               throws SmackException.NoResponseException,
                                      XMPPException.XMPPErrorException,
                                      SmackException.NotConnectedException,
                                      InterruptedException

Asks the workgroup for it's Sound Settings.

Returns:

soundSettings the sound settings for the specified workgroup.

Throws:

XMPPException.XMPPErrorException

SmackException.NoResponseException

SmackException.NotConnectedException

InterruptedException

getWorkgroupProperties

public WorkgroupProperties getWorkgroupProperties()
                                           throws SmackException.NoResponseException,
                                                  XMPPException.XMPPErrorException,
                                                  SmackException.NotConnectedException,
                                                  InterruptedException

Asks the workgroup for it's Properties.

Returns:

the WorkgroupProperties for the specified workgroup.

Throws:

XMPPException.XMPPErrorException

SmackException.NoResponseException

SmackException.NotConnectedException

InterruptedException

getWorkgroupProperties

public WorkgroupProperties getWorkgroupProperties(String jid)
                                           throws SmackException.NoResponseException,
                                                  XMPPException.XMPPErrorException,
                                                  SmackException.NotConnectedException,
                                                  InterruptedException

Asks the workgroup for it's Properties.

Parameters:

jid - the jid of the user who's information you would like the workgroup to retreive.

Returns:

the WorkgroupProperties for the specified workgroup.

Throws:

XMPPException.XMPPErrorException

SmackException.NoResponseException

SmackException.NotConnectedException

InterruptedException

getWorkgroupForm

public Form getWorkgroupForm()
                      throws SmackException.NoResponseException,
                             XMPPException.XMPPErrorException,
                             SmackException.NotConnectedException,
                             InterruptedException

Returns the Form to use for all clients of a workgroup. It is unlikely that the server will change the form (without a restart) so it is safe to keep the returned form for future submissions.

Returns:

the Form to use for searching transcripts.

Throws:

XMPPException.XMPPErrorException

SmackException.NoResponseException

SmackException.NotConnectedException

InterruptedException