* A MultiUserChat is a conversation that takes place among many users in a virtual * room. A room could have many occupants with different affiliation and roles. * Possible affiliations are "owner", "admin", "member", and "outcast". Possible roles * are "moderator", "participant", and "visitor". Each role and affiliation guarantees * different privileges (e.g. Send messages to all occupants, Kick participants and visitors, * Grant voice, Edit member list, etc.). *
** Note: Make sure to leave the MUC ({@link #leave()}) when you don't need it anymore or * otherwise you may leak the instance. *
* * @author Gaston Dombiak * @author Larry Kirschner * @author Florian Schmaus */ public class MultiUserChat { private static final Logger LOGGER = Logger.getLogger(MultiUserChat.class.getName()); private static final ExpirationCache* To create an "Instant Room", that means a room with some default configuration that is * available for immediate access, the room's owner should send an empty form after creating the * room. Simply call {@link MucCreateConfigFormHandle#makeInstant()} on the returned {@link MucCreateConfigFormHandle}. *
** To create a "Reserved Room", that means a room manually configured by the room creator before * anyone is allowed to enter, the room's owner should complete and send a form after creating * the room. Once the completed configuration form is sent to the server, the server will unlock * the room. You can use the returned {@link MucCreateConfigFormHandle} to configure the room. *
* * @param nickname the nickname to use. * @return a handle to the MUC create configuration form API. * @throws XMPPErrorException if the room couldn't be created for some reason (e.g. 405 error if * the user is not allowed to create the room) * @throws NoResponseException if there was no response from the server. * @throws InterruptedException * @throws NotConnectedException * @throws MucAlreadyJoinedException * @throws MissingMucCreationAcknowledgeException * @throws NotAMucServiceException */ public synchronized MucCreateConfigFormHandle create(Resourcepart nickname) throws NoResponseException, XMPPErrorException, InterruptedException, MucAlreadyJoinedException, NotConnectedException, MissingMucCreationAcknowledgeException, NotAMucServiceException { if (joined) { throw new MucAlreadyJoinedException(); } MucCreateConfigFormHandle mucCreateConfigFormHandle = createOrJoin(nickname); if (mucCreateConfigFormHandle != null) { // We successfully created a new room return mucCreateConfigFormHandle; } // We need to leave the room since it seems that the room already existed leave(); throw new MissingMucCreationAcknowledgeException(); } /** * Create or join the MUC room with the given nickname. * * @param nickname the nickname to use in the MUC room. * @return A {@link MucCreateConfigFormHandle} if the room was created while joining, or {@code null} if the room was just joined. * @throws NoResponseException * @throws XMPPErrorException * @throws InterruptedException * @throws NotConnectedException * @throws MucAlreadyJoinedException * @throws NotAMucServiceException */ public synchronized MucCreateConfigFormHandle createOrJoin(Resourcepart nickname) throws NoResponseException, XMPPErrorException, InterruptedException, MucAlreadyJoinedException, NotConnectedException, NotAMucServiceException { MucEnterConfiguration mucEnterConfiguration = getEnterConfigurationBuilder(nickname).build(); return createOrJoin(mucEnterConfiguration); } /** * Like {@link #create(Resourcepart)}, but will return true if the room creation was acknowledged by * the service (with an 201 status code). It's up to the caller to decide, based on the return * value, if he needs to continue sending the room configuration. If false is returned, the room * already existed and the user is able to join right away, without sending a form. * * @param nickname the nickname to use. * @param password the password to use. * @param history the amount of discussion history to receive while joining a room. * @param timeout the amount of time to wait for a reply from the MUC service(in milliseconds). * @return A {@link MucCreateConfigFormHandle} if the room was created while joining, or {@code null} if the room was just joined. * @throws XMPPErrorException if the room couldn't be created for some reason (e.g. 405 error if * the user is not allowed to create the room) * @throws NoResponseException if there was no response from the server. * @throws InterruptedException * @throws MucAlreadyJoinedException if the MUC is already joined * @throws NotConnectedException * @throws NotAMucServiceException * @deprecated use {@link #createOrJoin(MucEnterConfiguration)} instead. */ @Deprecated public MucCreateConfigFormHandle createOrJoin(Resourcepart nickname, String password, DiscussionHistory history, long timeout) throws NoResponseException, XMPPErrorException, InterruptedException, MucAlreadyJoinedException, NotConnectedException, NotAMucServiceException { MucEnterConfiguration.Builder builder = getEnterConfigurationBuilder(nickname).withPassword( password).timeoutAfter(timeout); return createOrJoin(builder.build()); } /** * Like {@link #create(Resourcepart)}, but will return a {@link MucCreateConfigFormHandle} if the room creation was acknowledged by * the service (with an 201 status code). It's up to the caller to decide, based on the return * value, if he needs to continue sending the room configuration. If {@code null} is returned, the room * already existed and the user is able to join right away, without sending a form. * * @param mucEnterConfiguration the configuration used to enter the MUC. * @return A {@link MucCreateConfigFormHandle} if the room was created while joining, or {@code null} if the room was just joined. * @throws XMPPErrorException if the room couldn't be created for some reason (e.g. 405 error if * the user is not allowed to create the room) * @throws NoResponseException if there was no response from the server. * @throws InterruptedException * @throws MucAlreadyJoinedException if the MUC is already joined * @throws NotConnectedException * @throws NotAMucServiceException */ public synchronized MucCreateConfigFormHandle createOrJoin(MucEnterConfiguration mucEnterConfiguration) throws NoResponseException, XMPPErrorException, InterruptedException, MucAlreadyJoinedException, NotConnectedException, NotAMucServiceException { if (joined) { throw new MucAlreadyJoinedException(); } Presence presence = enter(mucEnterConfiguration); // Look for confirmation of room creation from the server MUCUser mucUser = MUCUser.from(presence); if (mucUser != null && mucUser.getStatus().contains(Status.ROOM_CREATED_201)) { // Room was created and the user has joined the room return new MucCreateConfigFormHandle(); } return null; } /** * A handle used to configure a newly created room. As long as the room is not configured it will be locked, which * means that no one is able to join. The room will become unlocked as soon it got configured. In order to create an * instant room, use {@link #makeInstant()}. ** For advanced configuration options, use {@link MultiUserChat#getConfigurationForm()}, get the answer form with * {@link Form#createAnswerForm()}, fill it out and send it back to the room with * {@link MultiUserChat#sendConfigurationForm(Form)}. *
*/ public class MucCreateConfigFormHandle { /** * Create an instant room. The default configuration will be accepted and the room will become unlocked, i.e. * other users are able to join. * * @throws NoResponseException * @throws XMPPErrorException * @throws NotConnectedException * @throws InterruptedException * @see XEP-45 § 10.1.2 Creating an * Instant Room */ public void makeInstant() throws NoResponseException, XMPPErrorException, NotConnectedException, InterruptedException { sendConfigurationForm(new Form(DataForm.Type.submit)); } /** * Alias for {@link MultiUserChat#getConfigFormManager()}. * * @return a MUC configuration form manager for this room. * @throws NoResponseException * @throws XMPPErrorException * @throws NotConnectedException * @throws InterruptedException * @see MultiUserChat#getConfigFormManager() */ public MucConfigFormManager getConfigFormManager() throws NoResponseException, XMPPErrorException, NotConnectedException, InterruptedException { return MultiUserChat.this.getConfigFormManager(); } } /** * Create or join a MUC if it is necessary, i.e. if not the MUC is not already joined. * * @param nickname the required nickname to use. * @param password the optional password required to join * @return A {@link MucCreateConfigFormHandle} if the room was created while joining, or {@code null} if the room was just joined. * @throws NoResponseException * @throws XMPPErrorException * @throws NotConnectedException * @throws InterruptedException * @throws NotAMucServiceException */ public MucCreateConfigFormHandle createOrJoinIfNecessary(Resourcepart nickname, String password) throws NoResponseException, XMPPErrorException, NotConnectedException, InterruptedException, NotAMucServiceException { if (isJoined()) { return null; } MucEnterConfiguration mucEnterConfiguration = getEnterConfigurationBuilder(nickname).withPassword( password).build(); try { return createOrJoin(mucEnterConfiguration); } catch (MucAlreadyJoinedException e) { return null; } } /** * Joins the chat room using the specified nickname. If already joined * using another nickname, this method will first leave the room and then * re-join using the new nickname. The default connection timeout for a reply * from the group chat server that the join succeeded will be used. After * joining the room, the room will decide the amount of history to send. * * @param nickname the nickname to use. * @throws NoResponseException * @throws XMPPErrorException if an error occurs joining the room. In particular, a * 401 error can occur if no password was provided and one is required; or a * 403 error can occur if the user is banned; or a * 404 error can occur if the room does not exist or is locked; or a * 407 error can occur if user is not on the member list; or a * 409 error can occur if someone is already in the group chat with the same nickname. * @throws NoResponseException if there was no response from the server. * @throws NotConnectedException * @throws InterruptedException * @throws NotAMucServiceException */ public void join(Resourcepart nickname) throws NoResponseException, XMPPErrorException, NotConnectedException, InterruptedException, NotAMucServiceException { MucEnterConfiguration.Builder builder = getEnterConfigurationBuilder(nickname); join(builder.build()); } /** * Joins the chat room using the specified nickname and password. If already joined * using another nickname, this method will first leave the room and then * re-join using the new nickname. The default connection timeout for a reply * from the group chat server that the join succeeded will be used. After * joining the room, the room will decide the amount of history to send.* * A password is required when joining password protected rooms. If the room does * not require a password there is no need to provide one. * * @param nickname the nickname to use. * @param password the password to use. * @throws XMPPErrorException if an error occurs joining the room. In particular, a * 401 error can occur if no password was provided and one is required; or a * 403 error can occur if the user is banned; or a * 404 error can occur if the room does not exist or is locked; or a * 407 error can occur if user is not on the member list; or a * 409 error can occur if someone is already in the group chat with the same nickname. * @throws InterruptedException * @throws NotConnectedException * @throws NoResponseException if there was no response from the server. * @throws NotAMucServiceException */ public void join(Resourcepart nickname, String password) throws XMPPErrorException, InterruptedException, NoResponseException, NotConnectedException, NotAMucServiceException { MucEnterConfiguration.Builder builder = getEnterConfigurationBuilder(nickname).withPassword( password); join(builder.build()); } /** * Joins the chat room using the specified nickname and password. If already joined * using another nickname, this method will first leave the room and then * re-join using the new nickname.
* * To control the amount of history to receive while joining a room you will need to provide * a configured DiscussionHistory object.
* * A password is required when joining password protected rooms. If the room does * not require a password there is no need to provide one.
* * If the room does not already exist when the user seeks to enter it, the server will * decide to create a new room or not. * * @param nickname the nickname to use. * @param password the password to use. * @param history the amount of discussion history to receive while joining a room. * @param timeout the amount of time to wait for a reply from the MUC service(in milleseconds). * @throws XMPPErrorException if an error occurs joining the room. In particular, a * 401 error can occur if no password was provided and one is required; or a * 403 error can occur if the user is banned; or a * 404 error can occur if the room does not exist or is locked; or a * 407 error can occur if user is not on the member list; or a * 409 error can occur if someone is already in the group chat with the same nickname. * @throws NoResponseException if there was no response from the server. * @throws NotConnectedException * @throws InterruptedException * @throws NotAMucServiceException * @deprecated use {@link #join(MucEnterConfiguration)} instead. */ @Deprecated public void join( Resourcepart nickname, String password, DiscussionHistory history, long timeout) throws XMPPErrorException, NoResponseException, NotConnectedException, InterruptedException, NotAMucServiceException { MucEnterConfiguration.Builder builder = getEnterConfigurationBuilder(nickname).withPassword( password).timeoutAfter(timeout); join(builder.build()); } /** * Joins the chat room using the specified nickname and password. If already joined * using another nickname, this method will first leave the room and then * re-join using the new nickname.
* * To control the amount of history to receive while joining a room you will need to provide * a configured DiscussionHistory object.
* * A password is required when joining password protected rooms. If the room does * not require a password there is no need to provide one.
* * If the room does not already exist when the user seeks to enter it, the server will * decide to create a new room or not. * * @param mucEnterConfiguration the configuration used to enter the MUC. * @throws XMPPErrorException if an error occurs joining the room. In particular, a * 401 error can occur if no password was provided and one is required; or a * 403 error can occur if the user is banned; or a * 404 error can occur if the room does not exist or is locked; or a * 407 error can occur if user is not on the member list; or a * 409 error can occur if someone is already in the group chat with the same nickname. * @throws NoResponseException if there was no response from the server. * @throws NotConnectedException * @throws InterruptedException * @throws NotAMucServiceException */ public synchronized void join(MucEnterConfiguration mucEnterConfiguration) throws XMPPErrorException, NoResponseException, NotConnectedException, InterruptedException, NotAMucServiceException { // If we've already joined the room, leave it before joining under a new // nickname. if (joined) { leave(); } enter(mucEnterConfiguration); } /** * Returns true if currently in the multi user chat (after calling the {@link * #join(Resourcepart)} method). * * @return true if currently in the multi user chat room. */ public boolean isJoined() { return joined; } /** * Leave the chat room. * @throws NotConnectedException * @throws InterruptedException */ public synchronized void leave() throws NotConnectedException, InterruptedException { // If not joined already, do nothing. if (!joined) { return; } // We leave a room by sending a presence packet where the "to" // field is in the form "roomName@service/nickname" Presence leavePresence = new Presence(Presence.Type.unavailable); leavePresence.setTo(JidCreate.fullFrom(room, nickname)); connection.sendStanza(leavePresence); // Reset occupant information. occupantsMap.clear(); nickname = null; joined = false; userHasLeft(); } /** * Get a {@link MucConfigFormManager} to configure this room. *
* Only room owners are able to configure a room. *
* * @return a MUC configuration form manager for this room. * @throws NoResponseException * @throws XMPPErrorException * @throws NotConnectedException * @throws InterruptedException * @see XEP-45 § 10.2 Subsequent Room Configuration * @since 4.2 */ public MucConfigFormManager getConfigFormManager() throws NoResponseException, XMPPErrorException, NotConnectedException, InterruptedException { return new MucConfigFormManager(this); } /** * Returns the room's configuration form that the room's owner can use or null if * no configuration is possible. The configuration form allows to set the room's language, * enable logging, specify room's type, etc.. * * @return the Form that contains the fields to complete together with the instrucions or * null if no configuration is possible. * @throws XMPPErrorException if an error occurs asking the configuration form for the room. * @throws NoResponseException if there was no response from the server. * @throws NotConnectedException * @throws InterruptedException */ public Form getConfigurationForm() throws NoResponseException, XMPPErrorException, NotConnectedException, InterruptedException { MUCOwner iq = new MUCOwner(); iq.setTo(room); iq.setType(IQ.Type.get); IQ answer = connection.createStanzaCollectorAndSend(iq).nextResultOrThrow(); return Form.getFormFrom(answer); } /** * Sends the completed configuration form to the server. The room will be configured * with the new settings defined in the form. * * @param form the form with the new settings. * @throws XMPPErrorException if an error occurs setting the new rooms' configuration. * @throws NoResponseException if there was no response from the server. * @throws NotConnectedException * @throws InterruptedException */ public void sendConfigurationForm(Form form) throws NoResponseException, XMPPErrorException, NotConnectedException, InterruptedException { MUCOwner iq = new MUCOwner(); iq.setTo(room); iq.setType(IQ.Type.set); iq.addExtension(form.getDataFormToSend()); connection.createStanzaCollectorAndSend(iq).nextResultOrThrow(); } /** * Returns the room's registration form that an unaffiliated user, can use to become a member * of the room or null if no registration is possible. Some rooms may restrict the * privilege to register members and allow only room admins to add new members.* * If the user requesting registration requirements is not allowed to register with the room * (e.g. because that privilege has been restricted), the room will return a "Not Allowed" * error to the user (error code 405). * * @return the registration Form that contains the fields to complete together with the * instrucions or null if no registration is possible. * @throws XMPPErrorException if an error occurs asking the registration form for the room or a * 405 error if the user is not allowed to register with the room. * @throws NoResponseException if there was no response from the server. * @throws NotConnectedException * @throws InterruptedException */ public Form getRegistrationForm() throws NoResponseException, XMPPErrorException, NotConnectedException, InterruptedException { Registration reg = new Registration(); reg.setType(IQ.Type.get); reg.setTo(room); IQ result = connection.createStanzaCollectorAndSend(reg).nextResultOrThrow(); return Form.getFormFrom(result); } /** * Sends the completed registration form to the server. After the user successfully submits * the form, the room may queue the request for review by the room admins or may immediately * add the user to the member list by changing the user's affiliation from "none" to "member.
* * If the desired room nickname is already reserved for that room, the room will return a * "Conflict" error to the user (error code 409). If the room does not support registration, * it will return a "Service Unavailable" error to the user (error code 503). * * @param form the completed registration form. * @throws XMPPErrorException if an error occurs submitting the registration form. In particular, a * 409 error can occur if the desired room nickname is already reserved for that room; * or a 503 error can occur if the room does not support registration. * @throws NoResponseException if there was no response from the server. * @throws NotConnectedException * @throws InterruptedException */ public void sendRegistrationForm(Form form) throws NoResponseException, XMPPErrorException, NotConnectedException, InterruptedException { Registration reg = new Registration(); reg.setType(IQ.Type.set); reg.setTo(room); reg.addExtension(form.getDataFormToSend()); connection.createStanzaCollectorAndSend(reg).nextResultOrThrow(); } /** * Sends a request to the server to destroy the room. The sender of the request * should be the room's owner. If the sender of the destroy request is not the room's owner * then the server will answer a "Forbidden" error (403). * * @param reason the reason for the room destruction. * @param alternateJID the JID of an alternate location. * @throws XMPPErrorException if an error occurs while trying to destroy the room. * An error can occur which will be wrapped by an XMPPException -- * XMPP error code 403. The error code can be used to present more * appropiate error messages to end-users. * @throws NoResponseException if there was no response from the server. * @throws NotConnectedException * @throws InterruptedException */ public void destroy(String reason, EntityBareJid alternateJID) throws NoResponseException, XMPPErrorException, NotConnectedException, InterruptedException { MUCOwner iq = new MUCOwner(); iq.setTo(room); iq.setType(IQ.Type.set); // Create the reason for the room destruction Destroy destroy = new Destroy(alternateJID, reason); iq.setDestroy(destroy); connection.createStanzaCollectorAndSend(iq).nextResultOrThrow(); // Reset occupant information. occupantsMap.clear(); nickname = null; joined = false; userHasLeft(); } /** * Invites another user to the room in which one is an occupant. The invitation * will be sent to the room which in turn will forward the invitation to the invitee.
* * If the room is password-protected, the invitee will receive a password to use to join * the room. If the room is members-only, the the invitee may be added to the member list. * * @param user the user to invite to the room.(e.g. hecate@shakespeare.lit) * @param reason the reason why the user is being invited. * @throws NotConnectedException * @throws InterruptedException */ public void invite(EntityBareJid user, String reason) throws NotConnectedException, InterruptedException { invite(new Message(), user, reason); } /** * Invites another user to the room in which one is an occupant using a given Message. The invitation * will be sent to the room which in turn will forward the invitation to the invitee.
* * If the room is password-protected, the invitee will receive a password to use to join * the room. If the room is members-only, the the invitee may be added to the member list. * * @param message the message to use for sending the invitation. * @param user the user to invite to the room.(e.g. hecate@shakespeare.lit) * @param reason the reason why the user is being invited. * @throws NotConnectedException * @throws InterruptedException */ public void invite(Message message, EntityBareJid user, String reason) throws NotConnectedException, InterruptedException { // TODO listen for 404 error code when inviter supplies a non-existent JID message.setTo(room); // Create the MUCUser packet that will include the invitation MUCUser mucUser = new MUCUser(); MUCUser.Invite invite = new MUCUser.Invite(reason, user); mucUser.setInvite(invite); // Add the MUCUser packet that includes the invitation to the message message.addExtension(mucUser); connection.sendStanza(message); } /** * Adds a listener to invitation rejections notifications. The listener will be fired anytime * an invitation is declined. * * @param listener an invitation rejection listener. * @return true if the listener was not already added. */ public boolean addInvitationRejectionListener(InvitationRejectionListener listener) { return invitationRejectionListeners.add(listener); } /** * Removes a listener from invitation rejections notifications. The listener will be fired * anytime an invitation is declined. * * @param listener an invitation rejection listener. * @return true if the listener was registered and is now removed. */ public boolean removeInvitationRejectionListener(InvitationRejectionListener listener) { return invitationRejectionListeners.remove(listener); } /** * Fires invitation rejection listeners. * * @param invitee the user being invited. * @param reason the reason for the rejection */ private void fireInvitationRejectionListeners(Message message, MUCUser.Decline rejection) { EntityBareJid invitee = rejection.getFrom(); String reason = rejection.getReason(); InvitationRejectionListener[] listeners; synchronized (invitationRejectionListeners) { listeners = new InvitationRejectionListener[invitationRejectionListeners.size()]; invitationRejectionListeners.toArray(listeners); } for (InvitationRejectionListener listener : listeners) { listener.invitationDeclined(invitee, reason, message, rejection); } } /** * Adds a listener to subject change notifications. The listener will be fired anytime * the room's subject changes. * * @param listener a subject updated listener. * @return true if the listener was not already added. */ public boolean addSubjectUpdatedListener(SubjectUpdatedListener listener) { return subjectUpdatedListeners.add(listener); } /** * Removes a listener from subject change notifications. The listener will be fired * anytime the room's subject changes. * * @param listener a subject updated listener. * @return true if the listener was registered and is now removed. */ public boolean removeSubjectUpdatedListener(SubjectUpdatedListener listener) { return subjectUpdatedListeners.remove(listener); } /** * Adds a new {@link StanzaListener} that will be invoked every time a new presence * is going to be sent by this MultiUserChat to the server. Stanza(/Packet) interceptors may * add new extensions to the presence that is going to be sent to the MUC service. * * @param presenceInterceptor the new stanza(/packet) interceptor that will intercept presence packets. */ public void addPresenceInterceptor(PresenceListener presenceInterceptor) { presenceInterceptors.add(presenceInterceptor); } /** * Removes a {@link StanzaListener} that was being invoked every time a new presence * was being sent by this MultiUserChat to the server. Stanza(/Packet) interceptors may * add new extensions to the presence that is going to be sent to the MUC service. * * @param presenceInterceptor the stanza(/packet) interceptor to remove. */ public void removePresenceInterceptor(StanzaListener presenceInterceptor) { presenceInterceptors.remove(presenceInterceptor); } /** * Returns the last known room's subject or null if the user hasn't joined the room * or the room does not have a subject yet. In case the room has a subject, as soon as the * user joins the room a message with the current room's subject will be received.
* * To be notified every time the room's subject change you should add a listener * to this room. {@link #addSubjectUpdatedListener(SubjectUpdatedListener)}
*
* To change the room's subject use {@link #changeSubject(String)}.
*
* @return the room's subject or null if the user hasn't joined the room or the
* room does not have a subject yet.
*/
public String getSubject() {
return subject;
}
/**
* Returns the reserved room nickname for the user in the room. A user may have a reserved
* nickname, for example through explicit room registration or database integration. In such
* cases it may be desirable for the user to discover the reserved nickname before attempting
* to enter the room.
*
* @return the reserved room nickname or null if none.
* @throws SmackException if there was no response from the server.
* @throws InterruptedException
*/
public String getReservedNickname() throws SmackException, InterruptedException {
try {
DiscoverInfo result =
ServiceDiscoveryManager.getInstanceFor(connection).discoverInfo(
room,
"x-roomuser-item");
// Look for an Identity that holds the reserved nickname and return its name
for (DiscoverInfo.Identity identity : result.getIdentities()) {
return identity.getName();
}
}
catch (XMPPException e) {
LOGGER.log(Level.SEVERE, "Error retrieving room nickname", e);
}
// If no Identity was found then the user does not have a reserved room nickname
return null;
}
/**
* Returns the nickname that was used to join the room, or null if not
* currently joined.
*
* @return the nickname currently being used.
*/
public Resourcepart getNickname() {
return nickname;
}
/**
* Changes the occupant's nickname to a new nickname within the room. Each room occupant
* will receive two presence packets. One of type "unavailable" for the old nickname and one
* indicating availability for the new nickname. The unavailable presence will contain the new
* nickname and an appropriate status code (namely 303) as extended presence information. The
* status code 303 indicates that the occupant is changing his/her nickname.
*
* @param nickname the new nickname within the room.
* @throws XMPPErrorException if the new nickname is already in use by another occupant.
* @throws NoResponseException if there was no response from the server.
* @throws NotConnectedException
* @throws InterruptedException
* @throws MucNotJoinedException
*/
public synchronized void changeNickname(Resourcepart nickname) throws NoResponseException, XMPPErrorException, NotConnectedException, InterruptedException, MucNotJoinedException {
StringUtils.requireNotNullOrEmpty(nickname, "Nickname must not be null or blank.");
// Check that we already have joined the room before attempting to change the
// nickname.
if (!joined) {
throw new MucNotJoinedException(this);
}
final EntityFullJid jid = JidCreate.fullFrom(room, nickname);
// We change the nickname by sending a presence packet where the "to"
// field is in the form "roomName@service/nickname"
// We don't have to signal the MUC support again
Presence joinPresence = new Presence(Presence.Type.available);
joinPresence.setTo(jid);
// Wait for a presence packet back from the server.
StanzaFilter responseFilter =
new AndFilter(
FromMatchesFilter.createFull(jid),
new StanzaTypeFilter(Presence.class));
StanzaCollector response = connection.createStanzaCollectorAndSend(responseFilter, joinPresence);
// Wait up to a certain number of seconds for a reply. If there is a negative reply, an
// exception will be thrown
response.nextResultOrThrow();
this.nickname = nickname;
}
/**
* Changes the occupant's availability status within the room. The presence type
* will remain available but with a new status that describes the presence update and
* a new presence mode (e.g. Extended away).
*
* @param status a text message describing the presence update.
* @param mode the mode type for the presence update.
* @throws NotConnectedException
* @throws InterruptedException
* @throws MucNotJoinedException
*/
public void changeAvailabilityStatus(String status, Presence.Mode mode) throws NotConnectedException, InterruptedException, MucNotJoinedException {
StringUtils.requireNotNullOrEmpty(nickname, "Nickname must not be null or blank.");
// Check that we already have joined the room before attempting to change the
// availability status.
if (!joined) {
throw new MucNotJoinedException(this);
}
// We change the availability status by sending a presence packet to the room with the
// new presence status and mode
Presence joinPresence = new Presence(Presence.Type.available);
joinPresence.setStatus(status);
joinPresence.setMode(mode);
joinPresence.setTo(JidCreate.fullFrom(room, nickname));
// Send join packet.
connection.sendStanza(joinPresence);
}
/**
* Kicks a visitor or participant from the room. The kicked occupant will receive a presence
* of type "unavailable" including a status code 307 and optionally along with the reason
* (if provided) and the bare JID of the user who initiated the kick. After the occupant
* was kicked from the room, the rest of the occupants will receive a presence of type
* "unavailable". The presence will include a status code 307 which means that the occupant
* was kicked from the room.
*
* @param nickname the nickname of the participant or visitor to kick from the room
* (e.g. "john").
* @param reason the reason why the participant or visitor is being kicked from the room.
* @throws XMPPErrorException if an error occurs kicking the occupant. In particular, a
* 405 error can occur if a moderator or a user with an affiliation of "owner" or "admin"
* was intended to be kicked (i.e. Not Allowed error); or a
* 403 error can occur if the occupant that intended to kick another occupant does
* not have kicking privileges (i.e. Forbidden error); or a
* 400 error can occur if the provided nickname is not present in the room.
* @throws NoResponseException if there was no response from the server.
* @throws NotConnectedException
* @throws InterruptedException
*/
public void kickParticipant(Resourcepart nickname, String reason) throws XMPPErrorException, NoResponseException, NotConnectedException, InterruptedException {
changeRole(nickname, MUCRole.none, reason);
}
/**
* Sends a voice request to the MUC. The room moderators usually need to approve this request.
*
* @throws NotConnectedException
* @throws InterruptedException
* @see XEP-45 § 7.13 Requesting
* Voice
* @since 4.1
*/
public void requestVoice() throws NotConnectedException, InterruptedException {
DataForm form = new DataForm(DataForm.Type.submit);
FormField formTypeField = new FormField(FormField.FORM_TYPE);
formTypeField.addValue(MUCInitialPresence.NAMESPACE + "#request");
form.addField(formTypeField);
FormField requestVoiceField = new FormField("muc#role");
requestVoiceField.setType(FormField.Type.text_single);
requestVoiceField.setLabel("Requested role");
requestVoiceField.addValue("participant");
form.addField(requestVoiceField);
Message message = new Message(room);
message.addExtension(form);
connection.sendStanza(message);
}
/**
* Grants voice to visitors in the room. In a moderated room, a moderator may want to manage
* who does and does not have "voice" in the room. To have voice means that a room occupant
* is able to send messages to the room occupants.
*
* @param nicknames the nicknames of the visitors to grant voice in the room (e.g. "john").
* @throws XMPPErrorException if an error occurs granting voice to a visitor. In particular, a
* 403 error can occur if the occupant that intended to grant voice is not
* a moderator in this room (i.e. Forbidden error); or a
* 400 error can occur if the provided nickname is not present in the room.
* @throws NoResponseException if there was no response from the server.
* @throws NotConnectedException
* @throws InterruptedException
*/
public void grantVoice(Collection
*
* Note: this value will only be accurate after joining the group chat, and
* may fluctuate over time. If you query this value directly after joining the
* group chat it may not be accurate, as it takes a certain amount of time for
* the server to send all presence packets to this client.
*
* @return the number of occupants in the group chat.
*/
public int getOccupantsCount() {
return occupantsMap.size();
}
/**
* Returns an List for the list of fully qualified occupants
* in the group chat. For example, "conference@chat.jivesoftware.com/SomeUser".
* Typically, a client would only display the nickname of the occupant. To
* get the nickname from the fully qualified name, use the
* {@link org.jxmpp.util.XmppStringUtils#parseResource(String)} method.
* Note: this value will only be accurate after joining the group chat, and may
* fluctuate over time.
*
* @return a List of the occupants in the group chat.
*/
public List
*
* @param user the room occupant to search for his presence. The format of user must
* be: roomName@service/nickname (e.g. darkcave@macbeth.shakespeare.lit/thirdwitch).
* @return the occupant's current presence, or null if the user is unavailable
* or if no presence information is available.
*/
public Presence getOccupantPresence(EntityFullJid user) {
return occupantsMap.get(user);
}
/**
* Returns the Occupant information for a particular occupant, or null if the
* user is not in the room. The Occupant object may include information such as full
* JID of the user as well as the role and affiliation of the user in the room.
*
* @param user the room occupant to search for his presence. The format of user must
* be: roomName@service/nickname (e.g. darkcave@macbeth.shakespeare.lit/thirdwitch).
* @return the Occupant or null if the user is unavailable (i.e. not in the room).
*/
public Occupant getOccupant(EntityFullJid user) {
Presence presence = getOccupantPresence(user);
if (presence != null) {
return new Occupant(presence);
}
return null;
}
/**
* Adds a stanza(/packet) listener that will be notified of any new Presence packets
* sent to the group chat. Using a listener is a suitable way to know when the list
* of occupants should be re-loaded due to any changes.
*
* @param listener a stanza(/packet) listener that will be notified of any presence packets
* sent to the group chat.
* @return true if the listener was not already added.
*/
public boolean addParticipantListener(PresenceListener listener) {
return presenceListeners.add(listener);
}
/**
* Removes a stanza(/packet) listener that was being notified of any new Presence packets
* sent to the group chat.
*
* @param listener a stanza(/packet) listener that was being notified of any presence packets
* sent to the group chat.
* @return true if the listener was removed, otherwise the listener was not added previously.
*/
public boolean removeParticipantListener(PresenceListener listener) {
return presenceListeners.remove(listener);
}
/**
* Returns a list of Affiliate with the room owners.
*
* @return a list of Affiliate with the room owners.
* @throws XMPPErrorException if you don't have enough privileges to get this information.
* @throws NoResponseException if there was no response from the server.
* @throws NotConnectedException
* @throws InterruptedException
*/
public ListAffiliate with the room administrators.
*
* @return a list of Affiliate with the room administrators.
* @throws XMPPErrorException if you don't have enough privileges to get this information.
* @throws NoResponseException if there was no response from the server.
* @throws NotConnectedException
* @throws InterruptedException
*/
public ListAffiliate with the room members.
*
* @return a list of Affiliate with the room members.
* @throws XMPPErrorException if you don't have enough privileges to get this information.
* @throws NoResponseException if there was no response from the server.
* @throws NotConnectedException
* @throws InterruptedException
*/
public ListAffiliate with the room outcasts.
*
* @return a list of Affiliate with the room outcasts.
* @throws XMPPErrorException if you don't have enough privileges to get this information.
* @throws NoResponseException if there was no response from the server.
* @throws NotConnectedException
* @throws InterruptedException
*/
public ListAffiliate that have the specified room affiliation
* sending a request in the admin namespace.
*
* @param affiliation the affiliation of the users in the room.
* @return a collection of Affiliate that have the specified room affiliation.
* @throws XMPPErrorException if you don't have enough privileges to get this information.
* @throws NoResponseException if there was no response from the server.
* @throws NotConnectedException
* @throws InterruptedException
*/
private ListOccupant with the room moderators.
*
* @return a list of Occupant with the room moderators.
* @throws XMPPErrorException if you don't have enough privileges to get this information.
* @throws NoResponseException if there was no response from the server.
* @throws NotConnectedException
* @throws InterruptedException
*/
public ListOccupant with the room participants.
*
* @return a list of Occupant with the room participants.
* @throws XMPPErrorException if you don't have enough privileges to get this information.
* @throws NoResponseException if there was no response from the server.
* @throws NotConnectedException
* @throws InterruptedException
*/
public ListOccupant that have the specified room role.
*
* @param role the role of the occupant in the room.
* @return a list of Occupant that have the specified room role.
* @throws XMPPErrorException if an error occured while performing the request to the server or you
* don't have enough privileges to get this information.
* @throws NoResponseException if there was no response from the server.
* @throws NotConnectedException
* @throws InterruptedException
*/
private ListUserStatusListeners added to this
* MultiUserChat will be fired. On the other hand, if the occupant that changed
* his role is not yours then the ParticipantStatusListeners added to this
* MultiUserChat will be fired. The following table shows the events that will
* be fired depending on the previous and new role of the occupant.
*
*
*
*
*
*
* @param oldRole the previous role of the user in the room before receiving the new presence
* @param newRole the new role of the user in the room after receiving the new presence
* @param isUserModification whether the received presence is about your user in the room or not
* @param from the occupant whose role in the room has changed
* (e.g. room@conference.jabber.org/nick).
*/
private void checkRoleModifications(
MUCRole oldRole,
MUCRole newRole,
boolean isUserModification,
EntityFullJid from) {
// Voice was granted to a visitor
if ((MUCRole.visitor.equals(oldRole) || MUCRole.none.equals(oldRole))
&& MUCRole.participant.equals(newRole)) {
if (isUserModification) {
for (UserStatusListener listener : userStatusListeners) {
listener.voiceGranted();
}
}
else {
for (ParticipantStatusListener listener : participantStatusListeners) {
listener.voiceGranted(from);
}
}
}
// The participant's voice was revoked from the room
else if (
MUCRole.participant.equals(oldRole)
&& (MUCRole.visitor.equals(newRole) || MUCRole.none.equals(newRole))) {
if (isUserModification) {
for (UserStatusListener listener : userStatusListeners) {
listener.voiceRevoked();
}
}
else {
for (ParticipantStatusListener listener : participantStatusListeners) {
listener.voiceRevoked(from);
}
}
}
// Moderator privileges were granted to a participant
if (!MUCRole.moderator.equals(oldRole) && MUCRole.moderator.equals(newRole)) {
if (MUCRole.visitor.equals(oldRole) || MUCRole.none.equals(oldRole)) {
if (isUserModification) {
for (UserStatusListener listener : userStatusListeners) {
listener.voiceGranted();
}
}
else {
for (ParticipantStatusListener listener : participantStatusListeners) {
listener.voiceGranted(from);
}
}
}
if (isUserModification) {
for (UserStatusListener listener : userStatusListeners) {
listener.moderatorGranted();
}
}
else {
for (ParticipantStatusListener listener : participantStatusListeners) {
listener.moderatorGranted(from);
}
}
}
// Moderator privileges were revoked from a participant
else if (MUCRole.moderator.equals(oldRole) && !MUCRole.moderator.equals(newRole)) {
if (MUCRole.visitor.equals(newRole) || MUCRole.none.equals(newRole)) {
if (isUserModification) {
for (UserStatusListener listener : userStatusListeners) {
listener.voiceRevoked();
}
}
else {
for (ParticipantStatusListener listener : participantStatusListeners) {
listener.voiceRevoked(from);
}
}
}
if (isUserModification) {
for (UserStatusListener listener : userStatusListeners) {
listener.moderatorRevoked();
}
}
else {
for (ParticipantStatusListener listener : participantStatusListeners) {
listener.moderatorRevoked(from);
}
}
}
}
/**
* Fires notification events if the affiliation of a room occupant has changed. If the
* occupant that changed his affiliation is your occupant then the
* Old New Events None Visitor -- Visitor Participant voiceGranted Participant Moderator moderatorGranted None Participant voiceGranted None Moderator voiceGranted + moderatorGranted Visitor Moderator voiceGranted + moderatorGranted Moderator Participant moderatorRevoked Participant Visitor voiceRevoked Visitor None kicked Moderator Visitor voiceRevoked + moderatorRevoked Moderator None kicked Participant None kicked UserStatusListeners added to this MultiUserChat will be fired.
* On the other hand, if the occupant that changed his affiliation is not yours then the
* ParticipantStatusListeners added to this MultiUserChat will be
* fired. The following table shows the events that will be fired depending on the previous
* and new affiliation of the occupant.
*
*
*
*
*
*
* @param oldAffiliation the previous affiliation of the user in the room before receiving the
* new presence
* @param newAffiliation the new affiliation of the user in the room after receiving the new
* presence
* @param isUserModification whether the received presence is about your user in the room or not
* @param from the occupant whose role in the room has changed
* (e.g. room@conference.jabber.org/nick).
*/
private void checkAffiliationModifications(
MUCAffiliation oldAffiliation,
MUCAffiliation newAffiliation,
boolean isUserModification,
EntityFullJid from) {
// First check for revoked affiliation and then for granted affiliations. The idea is to
// first fire the "revoke" events and then fire the "grant" events.
// The user's ownership to the room was revoked
if (MUCAffiliation.owner.equals(oldAffiliation) && !MUCAffiliation.owner.equals(newAffiliation)) {
if (isUserModification) {
for (UserStatusListener listener : userStatusListeners) {
listener.ownershipRevoked();
}
}
else {
for (ParticipantStatusListener listener : participantStatusListeners) {
listener.ownershipRevoked(from);
}
}
}
// The user's administrative privileges to the room were revoked
else if (MUCAffiliation.admin.equals(oldAffiliation) && !MUCAffiliation.admin.equals(newAffiliation)) {
if (isUserModification) {
for (UserStatusListener listener : userStatusListeners) {
listener.adminRevoked();
}
}
else {
for (ParticipantStatusListener listener : participantStatusListeners) {
listener.adminRevoked(from);
}
}
}
// The user's membership to the room was revoked
else if (MUCAffiliation.member.equals(oldAffiliation) && !MUCAffiliation.member.equals(newAffiliation)) {
if (isUserModification) {
for (UserStatusListener listener : userStatusListeners) {
listener.membershipRevoked();
}
}
else {
for (ParticipantStatusListener listener : participantStatusListeners) {
listener.membershipRevoked(from);
}
}
}
// The user was granted ownership to the room
if (!MUCAffiliation.owner.equals(oldAffiliation) && MUCAffiliation.owner.equals(newAffiliation)) {
if (isUserModification) {
for (UserStatusListener listener : userStatusListeners) {
listener.ownershipGranted();
}
}
else {
for (ParticipantStatusListener listener : participantStatusListeners) {
listener.ownershipGranted(from);
}
}
}
// The user was granted administrative privileges to the room
else if (!MUCAffiliation.admin.equals(oldAffiliation) && MUCAffiliation.admin.equals(newAffiliation)) {
if (isUserModification) {
for (UserStatusListener listener : userStatusListeners) {
listener.adminGranted();
}
}
else {
for (ParticipantStatusListener listener : participantStatusListeners) {
listener.adminGranted(from);
}
}
}
// The user was granted membership to the room
else if (!MUCAffiliation.member.equals(oldAffiliation) && MUCAffiliation.member.equals(newAffiliation)) {
if (isUserModification) {
for (UserStatusListener listener : userStatusListeners) {
listener.membershipGranted();
}
}
else {
for (ParticipantStatusListener listener : participantStatusListeners) {
listener.membershipGranted(from);
}
}
}
}
/**
* Fires events according to the received presence code.
*
* @param statusCodes
* @param isUserModification
* @param mucUser
* @param from
*/
private void checkPresenceCode(
SetOld New Events None Member membershipGranted Member Admin membershipRevoked + adminGranted Admin Owner adminRevoked + ownershipGranted None Admin adminGranted None Owner ownershipGranted Member Owner membershipRevoked + ownershipGranted Owner Admin ownershipRevoked + adminGranted Admin Member adminRevoked + membershipGranted Member None membershipRevoked Owner Member ownershipRevoked + membershipGranted Owner None ownershipRevoked Admin None adminRevoked Anyone Outcast banned