/**
* 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.
*
* @return the Form to use for searching transcripts.
* @throws XMPPException if an error occurs while sending the request to the server.
*/
public Form getWorkgroupForm() throws XMPPException {
WorkgroupForm workgroupForm = new WorkgroupForm();
workgroupForm.setType(IQ.Type.GET);
workgroupForm.setTo(workgroupJID);
WorkgroupForm response =
(WorkgroupForm) connection.createPacketCollectorAndSend(workgroupForm).nextResultOrThrow();
return Form.getFormFrom(response);
}
/**
* Asks the workgroup for it's Properties
*
* @return the WorkgroupProperties for the specified workgroup.
* @throws XMPPException if an error occurs while getting information from the server.
*/
public WorkgroupProperties getWorkgroupProperties() throws XMPPException {
WorkgroupProperties request = new WorkgroupProperties();
request.setType(IQ.Type.GET);
request.setTo(workgroupJID);
WorkgroupProperties response =
(WorkgroupProperties) connection.createPacketCollectorAndSend(request).nextResultOrThrow();
return response;
}
/**
* Asks the workgroup for it's Sound Settings.
*
* @return soundSettings the sound settings for the specified workgroup.
* @throws XMPPException if an error occurs while getting information from the server.
*/
public SoundSettings getSoundSettings() throws XMPPException {
SoundSettings request = new SoundSettings();
request.setType(IQ.Type.GET);
request.setTo(workgroupJID);
SoundSettings response =
(SoundSettings) connection.createPacketCollectorAndSend(request).nextResultOrThrow();
return response;
}
/**
* Departs the workgroup queue. If the user is not currently in the queue, this method will do
* nothing.
*
* <p>
*
* <p>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.
*/
public void departQueue() throws XMPPException {
// If not in the queue ignore the depart request.
if (!inQueue) {
return;
}
DepartQueuePacket departPacket = new DepartQueuePacket(this.workgroupJID);
connection.createPacketCollectorAndSend(departPacket).nextResultOrThrow();
// Notify listeners that we're no longer in the queue.
fireQueueDepartedEvent();
}
/**
* 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:
*
* <ul>
* <p>
* <li>The user is routed to an agent, which triggers a GroupChat invitation.
* <li>The user asks to leave the queue by calling the {@link #departQueue} method.
* <li>A server error occurs, or an administrator explicitly removes the user from the queue.
* </ul>
*
* <p>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.
*
* <p>
*
* <p>Some servers may be configured to require certain meta-data in order to join the queue.
*
* <p>
*
* <p>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.
*
* @param answerForm the completed form associated with the join reqest.
* @param userID String that represents the ID of the user when using anonymous sessions or
* <tt>null</tt> if a userID should not be used.
* @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.
*/
public void joinQueue(Form answerForm, String userID) throws XMPPException {
// If already in the queue ignore the join request.
if (inQueue) {
throw new IllegalStateException("Already in queue " + workgroupJID);
}
JoinQueuePacket joinPacket = new JoinQueuePacket(workgroupJID, answerForm, userID);
connection.createPacketCollectorAndSend(joinPacket).nextResultOrThrow();
// Notify listeners that we've joined the queue.
fireQueueJoinedEvent();
}
/**
* Asks the workgroup for it's Chat Settings.
*
* @return key specify a key to retrieve only that settings. Otherwise for all settings, key
* should be null.
* @throws XMPPException if an error occurs while getting information from the server.
*/
private ChatSettings getChatSettings(String key, int type) throws XMPPException {
ChatSettings request = new ChatSettings();
if (key != null) {
request.setKey(key);
}
if (type != -1) {
request.setType(type);
}
request.setType(IQ.Type.GET);
request.setTo(workgroupJID);
ChatSettings response =
(ChatSettings) connection.createPacketCollectorAndSend(request).nextResultOrThrow();
return response;
}