/** * * Copyright 2003-2007 Jive Software. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package org.jivesoftware.smackx.muc; import java.util.ArrayList; import java.util.Collection; import java.util.Collections; import java.util.List; import java.util.Locale; import java.util.Map; import java.util.Set; import java.util.concurrent.ConcurrentHashMap; import java.util.concurrent.CopyOnWriteArraySet; import java.util.logging.Level; import java.util.logging.Logger; import org.jivesoftware.smack.Chat; import org.jivesoftware.smack.ChatManager; import org.jivesoftware.smack.ChatMessageListener; import org.jivesoftware.smack.MessageListener; import org.jivesoftware.smack.PacketCollector; import org.jivesoftware.smack.PacketListener; import org.jivesoftware.smack.PresenceListener; import org.jivesoftware.smack.SmackException; import org.jivesoftware.smack.SmackException.NoResponseException; import org.jivesoftware.smack.SmackException.NotConnectedException; import org.jivesoftware.smack.XMPPConnection; import org.jivesoftware.smack.XMPPException; import org.jivesoftware.smack.XMPPException.XMPPErrorException; import org.jivesoftware.smack.filter.AndFilter; import org.jivesoftware.smack.filter.FromMatchesFilter; import org.jivesoftware.smack.filter.MessageTypeFilter; import org.jivesoftware.smack.filter.MessageWithSubjectFilter; import org.jivesoftware.smack.filter.NotFilter; import org.jivesoftware.smack.filter.PacketExtensionFilter; import org.jivesoftware.smack.filter.PacketFilter; import org.jivesoftware.smack.filter.PacketTypeFilter; import org.jivesoftware.smack.filter.ToFilter; import org.jivesoftware.smack.packet.IQ; import org.jivesoftware.smack.packet.Message; import org.jivesoftware.smack.packet.Packet; import org.jivesoftware.smack.packet.Presence; import org.jivesoftware.smack.util.StringUtils; import org.jivesoftware.smackx.disco.ServiceDiscoveryManager; import org.jivesoftware.smackx.disco.packet.DiscoverInfo; import org.jivesoftware.smackx.iqregister.packet.Registration; import org.jivesoftware.smackx.muc.packet.Destroy; import org.jivesoftware.smackx.muc.packet.MUCAdmin; import org.jivesoftware.smackx.muc.packet.MUCInitialPresence; import org.jivesoftware.smackx.muc.packet.MUCItem; import org.jivesoftware.smackx.muc.packet.MUCOwner; import org.jivesoftware.smackx.muc.packet.MUCUser; import org.jivesoftware.smackx.muc.packet.MUCUser.Status; import org.jivesoftware.smackx.xdata.Form; /** * 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()}) before you drop the reference to * it, or otherwise you may leak the instance. *
* * @author Gaston Dombiak, Larry Kirschner */ public class MultiUserChat { private static final Logger LOGGER = Logger.getLogger(MultiUserChat.class.getName()); private final XMPPConnection connection; private final String room; private final MultiUserChatManager multiUserChatManager; private final Map* 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. {@link #sendConfigurationForm(Form)} *
* 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. {@link #sendConfigurationForm(Form)} * * @param nickname the nickname to use. * @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 SmackException If the creation failed because of a missing acknowledge from the * server, e.g. because the room already existed. */ public synchronized void create(String nickname) throws NoResponseException, XMPPErrorException, SmackException { if (joined) { throw new IllegalStateException("Creation failed - User already joined the room."); } if (createOrJoin(nickname)) { // We successfully created a new room return; } // We need to leave the room since it seems that the room already existed leave(); throw new SmackException("Creation failed - Missing acknowledge of room creation."); } /** * Like {@link #create(String)}, 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. * @return true if the room creation was acknowledged by the service, false otherwise. * @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. */ public synchronized boolean createOrJoin(String nickname) throws NoResponseException, XMPPErrorException, SmackException { if (joined) { throw new IllegalStateException("Creation failed - User already joined the room."); } Presence presence = enter(nickname, null, null, connection.getPacketReplyTimeout()); // 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 true; } return false; } /** * 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 */ public void join(String nickname) throws NoResponseException, XMPPErrorException, NotConnectedException { join(nickname, null, null, connection.getPacketReplyTimeout()); } /** * 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 SmackException if there was no response from the server. */ public void join(String nickname, String password) throws XMPPErrorException, SmackException { join(nickname, password, null, connection.getPacketReplyTimeout()); } /** * 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 */ public synchronized void join( String nickname, String password, DiscussionHistory history, long timeout) throws XMPPErrorException, NoResponseException, NotConnectedException { // If we've already joined the room, leave it before joining under a new // nickname. if (joined) { leave(); } enter(nickname, password, history, timeout); } /** * Returns true if currently in the multi user chat (after calling the {@link * #join(String)} method). * * @return true if currently in the multi user chat room. */ public boolean isJoined() { return joined; } /** * Leave the chat room. * @throws NotConnectedException */ public synchronized void leave() throws NotConnectedException { // 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(room + "/" + nickname); connection.sendPacket(leavePresence); // Reset occupant information. occupantsMap.clear(); nickname = null; joined = false; userHasLeft(); } /** * 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 */ public Form getConfigurationForm() throws NoResponseException, XMPPErrorException, NotConnectedException { MUCOwner iq = new MUCOwner(); iq.setTo(room); iq.setType(IQ.Type.get); IQ answer = connection.createPacketCollectorAndSend(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. If the form is empty then the server * will create an instant room (will use default configuration). * * @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 */ public void sendConfigurationForm(Form form) throws NoResponseException, XMPPErrorException, NotConnectedException { MUCOwner iq = new MUCOwner(); iq.setTo(room); iq.setType(IQ.Type.set); iq.addExtension(form.getDataFormToSend()); connection.createPacketCollectorAndSend(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 */ public Form getRegistrationForm() throws NoResponseException, XMPPErrorException, NotConnectedException { Registration reg = new Registration(); reg.setType(IQ.Type.get); reg.setTo(room); IQ result = connection.createPacketCollectorAndSend(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 */ public void sendRegistrationForm(Form form) throws NoResponseException, XMPPErrorException, NotConnectedException { Registration reg = new Registration(); reg.setType(IQ.Type.set); reg.setTo(room); reg.addExtension(form.getDataFormToSend()); connection.createPacketCollectorAndSend(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 */ public void destroy(String reason, String alternateJID) throws NoResponseException, XMPPErrorException, NotConnectedException { MUCOwner iq = new MUCOwner(); iq.setTo(room); iq.setType(IQ.Type.set); // Create the reason for the room destruction Destroy destroy = new Destroy(); destroy.setReason(reason); destroy.setJid(alternateJID); iq.setDestroy(destroy); connection.createPacketCollectorAndSend(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 */ public void invite(String user, String reason) throws NotConnectedException { 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 */ public void invite(Message message, String user, String reason) throws NotConnectedException { // 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(); invite.setTo(user); invite.setReason(reason); mucUser.setInvite(invite); // Add the MUCUser packet that includes the invitation to the message message.addExtension(mucUser); connection.sendPacket(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(String invitee, String reason) { InvitationRejectionListener[] listeners; synchronized (invitationRejectionListeners) { listeners = new InvitationRejectionListener[invitationRejectionListeners.size()]; invitationRejectionListeners.toArray(listeners); } for (InvitationRejectionListener listener : listeners) { listener.invitationDeclined(invitee, reason); } } /** * 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 PacketListener} that will be invoked every time a new presence * is going to be sent by this MultiUserChat to the server. Packet interceptors may * add new extensions to the presence that is going to be sent to the MUC service. * * @param presenceInterceptor the new packet interceptor that will intercept presence packets. */ public void addPresenceInterceptor(PresenceListener presenceInterceptor) { presenceInterceptors.add(presenceInterceptor); } /** * Removes a {@link PacketListener} that was being invoked every time a new presence * was being sent by this MultiUserChat to the server. Packet interceptors may * add new extensions to the presence that is going to be sent to the MUC service. * * @param presenceInterceptor the packet interceptor to remove. */ public void removePresenceInterceptor(PacketListener 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.
*/
public String getReservedNickname() throws SmackException {
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 String 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
*/
public void changeNickname(String nickname) throws NoResponseException, XMPPErrorException, NotConnectedException {
if (StringUtils.isNullOrEmpty(nickname)) {
throw new IllegalArgumentException("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 IllegalStateException("Must be logged into the room to change 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(room + "/" + nickname);
// Wait for a presence packet back from the server.
PacketFilter responseFilter =
new AndFilter(
FromMatchesFilter.createFull(room + "/" + nickname),
new PacketTypeFilter(Presence.class));
PacketCollector response = connection.createPacketCollectorAndSend(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
*/
public void changeAvailabilityStatus(String status, Presence.Mode mode) throws NotConnectedException {
if (StringUtils.isNullOrEmpty(nickname)) {
throw new IllegalArgumentException("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 IllegalStateException(
"Must be logged into the room to change the " + "availability status.");
}
// 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(room + "/" + nickname);
// Send join packet.
connection.sendPacket(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
*/
public void kickParticipant(String nickname, String reason) throws XMPPErrorException, NoResponseException, NotConnectedException {
changeRole(nickname, MUCRole.none, reason);
}
/**
* 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
*/
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 Iterator (of Strings) 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(String 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(String user) {
Presence presence = occupantsMap.get(user);
if (presence != null) {
return new Occupant(presence);
}
return null;
}
/**
* Adds a 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 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 packet listener that was being notified of any new Presence packets
* sent to the group chat.
*
* @param listener a 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
*/
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
*/
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
*/
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
*/
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
*/
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
*/
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
*/
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
*/
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,
String from) {
// Voice was granted to a visitor
if (("visitor".equals(oldRole) || "none".equals(oldRole))
&& "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 (
"participant".equals(oldRole)
&& ("visitor".equals(newRole) || "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 (!"moderator".equals(oldRole) && "moderator".equals(newRole)) {
if ("visitor".equals(oldRole) || "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 ("moderator".equals(oldRole) && !"moderator".equals(newRole)) {
if ("visitor".equals(newRole) || "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,
String 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 ("owner".equals(oldAffiliation) && !"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 ("admin".equals(oldAffiliation) && !"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 ("member".equals(oldAffiliation) && !"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 (!"owner".equals(oldAffiliation) && "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 (!"admin".equals(oldAffiliation) && "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 (!"member".equals(oldAffiliation) && "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(
Set
*
* Old 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