001/** 002 * 003 * Copyright 2003-2007 Jive Software. 2020-2024 Florian Schmaus 004 * 005 * Licensed under the Apache License, Version 2.0 (the "License"); 006 * you may not use this file except in compliance with the License. 007 * You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017 018package org.jivesoftware.smackx.muc; 019 020import java.util.ArrayList; 021import java.util.Collection; 022import java.util.List; 023import java.util.Map; 024import java.util.Set; 025import java.util.concurrent.ConcurrentHashMap; 026import java.util.concurrent.CopyOnWriteArrayList; 027import java.util.concurrent.CopyOnWriteArraySet; 028import java.util.concurrent.atomic.AtomicInteger; 029import java.util.logging.Level; 030import java.util.logging.Logger; 031 032import org.jivesoftware.smack.MessageListener; 033import org.jivesoftware.smack.PresenceListener; 034import org.jivesoftware.smack.SmackException; 035import org.jivesoftware.smack.SmackException.NoResponseException; 036import org.jivesoftware.smack.SmackException.NotConnectedException; 037import org.jivesoftware.smack.StanzaCollector; 038import org.jivesoftware.smack.StanzaListener; 039import org.jivesoftware.smack.XMPPConnection; 040import org.jivesoftware.smack.XMPPException; 041import org.jivesoftware.smack.XMPPException.XMPPErrorException; 042import org.jivesoftware.smack.chat.ChatMessageListener; 043import org.jivesoftware.smack.filter.AndFilter; 044import org.jivesoftware.smack.filter.FromMatchesFilter; 045import org.jivesoftware.smack.filter.MessageTypeFilter; 046import org.jivesoftware.smack.filter.MessageWithBodiesFilter; 047import org.jivesoftware.smack.filter.MessageWithSubjectFilter; 048import org.jivesoftware.smack.filter.MessageWithThreadFilter; 049import org.jivesoftware.smack.filter.NotFilter; 050import org.jivesoftware.smack.filter.OrFilter; 051import org.jivesoftware.smack.filter.PossibleFromTypeFilter; 052import org.jivesoftware.smack.filter.PresenceTypeFilter; 053import org.jivesoftware.smack.filter.StanzaExtensionFilter; 054import org.jivesoftware.smack.filter.StanzaFilter; 055import org.jivesoftware.smack.filter.StanzaIdFilter; 056import org.jivesoftware.smack.filter.StanzaTypeFilter; 057import org.jivesoftware.smack.filter.ToMatchesFilter; 058import org.jivesoftware.smack.packet.IQ; 059import org.jivesoftware.smack.packet.Message; 060import org.jivesoftware.smack.packet.MessageBuilder; 061import org.jivesoftware.smack.packet.MessageView; 062import org.jivesoftware.smack.packet.Presence; 063import org.jivesoftware.smack.packet.PresenceBuilder; 064import org.jivesoftware.smack.packet.Stanza; 065import org.jivesoftware.smack.util.Consumer; 066import org.jivesoftware.smack.util.Objects; 067 068import org.jivesoftware.smackx.disco.ServiceDiscoveryManager; 069import org.jivesoftware.smackx.disco.packet.DiscoverInfo; 070import org.jivesoftware.smackx.iqregister.packet.Registration; 071import org.jivesoftware.smackx.muc.MultiUserChatException.MissingMucCreationAcknowledgeException; 072import org.jivesoftware.smackx.muc.MultiUserChatException.MucAlreadyJoinedException; 073import org.jivesoftware.smackx.muc.MultiUserChatException.MucNotJoinedException; 074import org.jivesoftware.smackx.muc.MultiUserChatException.NotAMucServiceException; 075import org.jivesoftware.smackx.muc.filter.MUCUserStatusCodeFilter; 076import org.jivesoftware.smackx.muc.packet.Destroy; 077import org.jivesoftware.smackx.muc.packet.GroupChatInvitation; 078import org.jivesoftware.smackx.muc.packet.MUCAdmin; 079import org.jivesoftware.smackx.muc.packet.MUCInitialPresence; 080import org.jivesoftware.smackx.muc.packet.MUCItem; 081import org.jivesoftware.smackx.muc.packet.MUCOwner; 082import org.jivesoftware.smackx.muc.packet.MUCUser; 083import org.jivesoftware.smackx.muc.packet.MUCUser.Status; 084import org.jivesoftware.smackx.xdata.FormField; 085import org.jivesoftware.smackx.xdata.TextSingleFormField; 086import org.jivesoftware.smackx.xdata.form.FillableForm; 087import org.jivesoftware.smackx.xdata.form.Form; 088import org.jivesoftware.smackx.xdata.packet.DataForm; 089 090import org.jxmpp.jid.DomainBareJid; 091import org.jxmpp.jid.EntityBareJid; 092import org.jxmpp.jid.EntityFullJid; 093import org.jxmpp.jid.EntityJid; 094import org.jxmpp.jid.Jid; 095import org.jxmpp.jid.impl.JidCreate; 096import org.jxmpp.jid.parts.Resourcepart; 097 098/** 099 * A MultiUserChat room (XEP-45), created with {@link MultiUserChatManager#getMultiUserChat(EntityBareJid)}. 100 * <p> 101 * A MultiUserChat is a conversation that takes place among many users in a virtual 102 * room. A room could have many occupants with different affiliation and roles. 103 * Possible affiliations are "owner", "admin", "member", and "outcast". Possible roles 104 * are "moderator", "participant", and "visitor". Each role and affiliation guarantees 105 * different privileges (e.g. Send messages to all occupants, Kick participants and visitors, 106 * Grant voice, Edit member list, etc.). 107 * </p> 108 * <p> 109 * <b>Note:</b> Make sure to leave the MUC ({@link #leave()}) when you don't need it anymore or 110 * otherwise you may leak the instance. 111 * </p> 112 * 113 * @author Gaston Dombiak 114 * @author Larry Kirschner 115 * @author Florian Schmaus 116 */ 117public class MultiUserChat { 118 private static final Logger LOGGER = Logger.getLogger(MultiUserChat.class.getName()); 119 120 private final XMPPConnection connection; 121 private final EntityBareJid room; 122 private final MultiUserChatManager multiUserChatManager; 123 private final Map<EntityFullJid, Presence> occupantsMap = new ConcurrentHashMap<>(); 124 125 private final Set<InvitationRejectionListener> invitationRejectionListeners = new CopyOnWriteArraySet<InvitationRejectionListener>(); 126 private final Set<SubjectUpdatedListener> subjectUpdatedListeners = new CopyOnWriteArraySet<SubjectUpdatedListener>(); 127 private final Set<UserStatusListener> userStatusListeners = new CopyOnWriteArraySet<UserStatusListener>(); 128 private final Set<ParticipantStatusListener> participantStatusListeners = new CopyOnWriteArraySet<ParticipantStatusListener>(); 129 private final Set<MessageListener> messageListeners = new CopyOnWriteArraySet<MessageListener>(); 130 private final Set<PresenceListener> presenceListeners = new CopyOnWriteArraySet<PresenceListener>(); 131 private final Set<Consumer<PresenceBuilder>> presenceInterceptors = new CopyOnWriteArraySet<>(); 132 133 /** 134 * This filter will match all stanzas send from the groupchat or from one if 135 * the groupchat participants, i.e. it filters only the bare JID of the from 136 * attribute against the JID of the MUC. 137 */ 138 private final StanzaFilter fromRoomFilter; 139 140 /** 141 * Same as {@link #fromRoomFilter} together with {@link MessageTypeFilter#GROUPCHAT}. 142 */ 143 private final StanzaFilter fromRoomGroupchatFilter; 144 145 private final AtomicInteger presenceInterceptorCount = new AtomicInteger(); 146 // We want to save the presence interceptor in a variable, using a lambda, (and not use a method reference) to be 147 // able to dynamically add and remove it from the connection. 148 @SuppressWarnings("UnnecessaryLambda") 149 private final Consumer<PresenceBuilder> presenceInterceptor = presenceBuilder -> { 150 for (Consumer<PresenceBuilder> interceptor : presenceInterceptors) { 151 interceptor.accept(presenceBuilder); 152 } 153 }; 154 155 private final StanzaListener messageListener; 156 private final StanzaListener presenceListener; 157 private final StanzaListener subjectListener; 158 159 private static final StanzaFilter DECLINE_FILTER = new AndFilter(MessageTypeFilter.NORMAL, 160 new StanzaExtensionFilter(MUCUser.ELEMENT, MUCUser.NAMESPACE)); 161 private final StanzaListener declinesListener; 162 163 private String subject; 164 private EntityFullJid myRoomJid; 165 private StanzaCollector messageCollector; 166 167 private DiscoverInfo mucServiceDiscoInfo; 168 169 /** 170 * Used to signal that the reflected self-presence was received <b>and</b> processed by us. 171 */ 172 private volatile boolean processedReflectedSelfPresence; 173 174 private CopyOnWriteArrayList<MucMessageInterceptor> messageInterceptors; 175 176 MultiUserChat(XMPPConnection connection, EntityBareJid room, MultiUserChatManager multiUserChatManager) { 177 this.connection = connection; 178 this.room = room; 179 this.multiUserChatManager = multiUserChatManager; 180 this.messageInterceptors = MultiUserChatManager.getMessageInterceptors(); 181 182 fromRoomFilter = FromMatchesFilter.create(room); 183 fromRoomGroupchatFilter = new AndFilter(fromRoomFilter, MessageTypeFilter.GROUPCHAT); 184 185 messageListener = new StanzaListener() { 186 @Override 187 public void processStanza(Stanza packet) throws NotConnectedException { 188 final Message message = (Message) packet; 189 190 for (MessageListener listener : messageListeners) { 191 listener.processMessage(message); 192 } 193 } 194 }; 195 196 // Create a listener for subject updates. 197 subjectListener = new StanzaListener() { 198 @Override 199 public void processStanza(Stanza packet) { 200 final Message msg = (Message) packet; 201 final EntityFullJid from = msg.getFrom().asEntityFullJidIfPossible(); 202 // Update the room subject 203 subject = msg.getSubject(); 204 205 // Fire event for subject updated listeners 206 for (SubjectUpdatedListener listener : subjectUpdatedListeners) { 207 listener.subjectUpdated(msg.getSubject(), from); 208 } 209 } 210 }; 211 212 // Create a listener for all presence updates. 213 presenceListener = new StanzaListener() { 214 @Override 215 public void processStanza(final Stanza packet) { 216 final Presence presence = (Presence) packet; 217 final EntityFullJid from = presence.getFrom().asEntityFullJidIfPossible(); 218 if (from == null) { 219 return; 220 } 221 final EntityFullJid myRoomJID = getMyRoomJid(); 222 final boolean isUserStatusModification = presence.getFrom().equals(myRoomJID); 223 final MUCUser mucUser = MUCUser.from(packet); 224 225 switch (presence.getType()) { 226 case available: 227 if (!processedReflectedSelfPresence 228 && mucUser.getStatus().contains(MUCUser.Status.PRESENCE_TO_SELF_110)) { 229 processedReflectedSelfPresence = true; 230 synchronized (this) { 231 notify(); 232 } 233 } 234 235 Presence oldPresence = occupantsMap.put(from, presence); 236 if (oldPresence != null) { 237 // Get the previous occupant's affiliation & role 238 MUCUser mucExtension = MUCUser.from(oldPresence); 239 MUCAffiliation oldAffiliation = mucExtension.getItem().getAffiliation(); 240 MUCRole oldRole = mucExtension.getItem().getRole(); 241 // Get the new occupant's affiliation & role 242 MUCAffiliation newAffiliation = mucUser.getItem().getAffiliation(); 243 MUCRole newRole = mucUser.getItem().getRole(); 244 // Fire role modification events 245 checkRoleModifications(oldRole, newRole, isUserStatusModification, from); 246 // Fire affiliation modification events 247 checkAffiliationModifications( 248 oldAffiliation, 249 newAffiliation, 250 isUserStatusModification, 251 from); 252 } else { 253 // A new occupant has joined the room 254 for (ParticipantStatusListener listener : participantStatusListeners) { 255 listener.joined(from); 256 } 257 } 258 break; 259 case unavailable: 260 occupantsMap.remove(from); 261 Set<Status> status = mucUser.getStatus(); 262 if (mucUser != null && !status.isEmpty()) { 263 if (isUserStatusModification && !status.contains(MUCUser.Status.NEW_NICKNAME_303)) { 264 userHasLeft(); 265 } 266 // Fire events according to the received presence code 267 checkPresenceCode( 268 status, 269 isUserStatusModification, 270 mucUser, 271 from); 272 } else { 273 // An occupant has left the room 274 if (!isUserStatusModification) { 275 for (ParticipantStatusListener listener : participantStatusListeners) { 276 listener.left(from); 277 } 278 } 279 } 280 281 Destroy destroy = mucUser == null ? null : mucUser.getDestroy(); 282 // The room has been destroyed. 283 if (destroy != null) { 284 EntityBareJid alternateMucJid = destroy.getJid(); 285 final MultiUserChat alternateMuc; 286 if (alternateMucJid == null) { 287 alternateMuc = null; 288 } else { 289 alternateMuc = multiUserChatManager.getMultiUserChat(alternateMucJid); 290 } 291 292 for (UserStatusListener listener : userStatusListeners) { 293 listener.roomDestroyed(alternateMuc, destroy.getPassword(), destroy.getReason()); 294 } 295 } 296 297 if (isUserStatusModification) { 298 for (UserStatusListener listener : userStatusListeners) { 299 listener.removed(mucUser, presence); 300 } 301 } else { 302 for (ParticipantStatusListener listener : participantStatusListeners) { 303 listener.parted(from); 304 } 305 } 306 break; 307 default: 308 break; 309 } 310 for (PresenceListener listener : presenceListeners) { 311 listener.processPresence(presence); 312 } 313 } 314 }; 315 316 // Listens for all messages that include a MUCUser extension and fire the invitation 317 // rejection listeners if the message includes an invitation rejection. 318 declinesListener = new StanzaListener() { 319 @Override 320 public void processStanza(Stanza packet) { 321 Message message = (Message) packet; 322 // Get the MUC User extension 323 MUCUser mucUser = MUCUser.from(packet); 324 MUCUser.Decline rejection = mucUser.getDecline(); 325 // Check if the MUCUser informs that the invitee has declined the invitation 326 if (rejection == null) { 327 return; 328 } 329 // Fire event for invitation rejection listeners 330 fireInvitationRejectionListeners(message, rejection); 331 } 332 }; 333 } 334 335 336 /** 337 * Returns the name of the room this MultiUserChat object represents. 338 * 339 * @return the multi user chat room name. 340 */ 341 public EntityBareJid getRoom() { 342 return room; 343 } 344 345 /** 346 * Enter a room, as described in XEP-45 7.2. 347 * 348 * @param conf the configuration used to enter the room. 349 * @return the returned presence by the service after the client send the initial presence in order to enter the room. 350 * @throws NotConnectedException if the XMPP connection is not connected. 351 * @throws NoResponseException if there was no response from the remote entity. 352 * @throws XMPPErrorException if there was an XMPP error returned. 353 * @throws InterruptedException if the calling thread was interrupted. 354 * @throws NotAMucServiceException if the entity is not a MUC serivce. 355 * @see <a href="http://xmpp.org/extensions/xep-0045.html#enter">XEP-45 7.2 Entering a Room</a> 356 */ 357 private Presence enter(MucEnterConfiguration conf) throws NotConnectedException, NoResponseException, 358 XMPPErrorException, InterruptedException, NotAMucServiceException { 359 final DomainBareJid mucService = room.asDomainBareJid(); 360 mucServiceDiscoInfo = multiUserChatManager.getMucServiceDiscoInfo(mucService); 361 if (mucServiceDiscoInfo == null) { 362 throw new NotAMucServiceException(this); 363 } 364 // We enter a room by sending a presence packet where the "to" 365 // field is in the form "roomName@service/nickname" 366 Presence joinPresence = conf.getJoinPresence(this); 367 368 // Setup the messageListeners and presenceListeners *before* the join presence is send. 369 connection.addStanzaListener(messageListener, fromRoomGroupchatFilter); 370 StanzaFilter presenceFromRoomFilter = new AndFilter(fromRoomFilter, 371 StanzaTypeFilter.PRESENCE, 372 PossibleFromTypeFilter.ENTITY_FULL_JID); 373 connection.addStanzaListener(presenceListener, presenceFromRoomFilter); 374 // @formatter:off 375 connection.addStanzaListener(subjectListener, 376 new AndFilter(fromRoomFilter, 377 MessageWithSubjectFilter.INSTANCE, 378 new NotFilter(MessageTypeFilter.ERROR), 379 // According to XEP-0045 § 8.1 "A message with a <subject/> and a <body/> or a <subject/> and a <thread/> is a 380 // legitimate message, but it SHALL NOT be interpreted as a subject change." 381 new NotFilter(MessageWithBodiesFilter.INSTANCE), 382 new NotFilter(MessageWithThreadFilter.INSTANCE)) 383 ); 384 // @formatter:on 385 connection.addStanzaListener(declinesListener, new AndFilter(fromRoomFilter, DECLINE_FILTER)); 386 messageCollector = connection.createStanzaCollector(fromRoomGroupchatFilter); 387 388 // Wait for a presence packet back from the server. 389 // @formatter:off 390 StanzaFilter responseFilter = new AndFilter(StanzaTypeFilter.PRESENCE, 391 new OrFilter( 392 // We use a bare JID filter for positive responses, since the MUC service/room may rewrite the nickname. 393 new AndFilter(FromMatchesFilter.createBare(getRoom()), MUCUserStatusCodeFilter.STATUS_110_PRESENCE_TO_SELF), 394 // In case there is an error reply, we match on an error presence with the same stanza id and from the full 395 // JID we send the join presence to. 396 new AndFilter(FromMatchesFilter.createFull(joinPresence.getTo()), new StanzaIdFilter(joinPresence), PresenceTypeFilter.ERROR) 397 ) 398 ); 399 // @formatter:on 400 processedReflectedSelfPresence = false; 401 StanzaCollector presenceStanzaCollector = null; 402 final Presence reflectedSelfPresence; 403 try { 404 // This stanza collector will collect the final self presence from the MUC, which also signals that we have successful entered the MUC. 405 StanzaCollector selfPresenceCollector = connection.createStanzaCollectorAndSend(responseFilter, joinPresence); 406 StanzaCollector.Configuration presenceStanzaCollectorConfguration = StanzaCollector.newConfiguration().setCollectorToReset( 407 selfPresenceCollector).setStanzaFilter(presenceFromRoomFilter); 408 // This stanza collector is used to reset the timeout of the selfPresenceCollector. 409 presenceStanzaCollector = connection.createStanzaCollector(presenceStanzaCollectorConfguration); 410 reflectedSelfPresence = selfPresenceCollector.nextResultOrThrow(conf.getTimeout()); 411 } 412 catch (NotConnectedException | InterruptedException | NoResponseException | XMPPErrorException e) { 413 // Ensure that all callbacks are removed if there is an exception 414 removeConnectionCallbacks(); 415 throw e; 416 } 417 finally { 418 if (presenceStanzaCollector != null) { 419 presenceStanzaCollector.cancel(); 420 } 421 } 422 423 synchronized (presenceListener) { 424 // Only continue after we have received *and* processed the reflected self-presence. Since presences are 425 // handled in an extra listener, we may return from enter() without having processed all presences of the 426 // participants, resulting in a e.g. to low participant counter after enter(). Hence we wait here until the 427 // processing is done. 428 while (!processedReflectedSelfPresence) { 429 presenceListener.wait(); 430 } 431 } 432 433 // This presence must be send from a full JID. We use the resourcepart of this JID as nick, since the room may 434 // performed roomnick rewriting 435 Resourcepart receivedNickname = reflectedSelfPresence.getFrom().getResourceOrThrow(); 436 setNickname(receivedNickname); 437 438 // Update the list of joined rooms 439 multiUserChatManager.addJoinedRoom(room); 440 return reflectedSelfPresence; 441 } 442 443 private void setNickname(Resourcepart nickname) { 444 this.myRoomJid = JidCreate.entityFullFrom(room, nickname); 445 } 446 447 /** 448 * Get a new MUC enter configuration builder. 449 * 450 * @param nickname the nickname used when entering the MUC room. 451 * @return a new MUC enter configuration builder. 452 * @since 4.2 453 */ 454 public MucEnterConfiguration.Builder getEnterConfigurationBuilder(Resourcepart nickname) { 455 return new MucEnterConfiguration.Builder(nickname, connection); 456 } 457 458 /** 459 * Creates the room according to some default configuration, assign the requesting user as the 460 * room owner, and add the owner to the room but not allow anyone else to enter the room 461 * (effectively "locking" the room). The requesting user will join the room under the specified 462 * nickname as soon as the room has been created. 463 * <p> 464 * To create an "Instant Room", that means a room with some default configuration that is 465 * available for immediate access, the room's owner should send an empty form after creating the 466 * room. Simply call {@link MucCreateConfigFormHandle#makeInstant()} on the returned {@link MucCreateConfigFormHandle}. 467 * </p> 468 * <p> 469 * To create a "Reserved Room", that means a room manually configured by the room creator before 470 * anyone is allowed to enter, the room's owner should complete and send a form after creating 471 * the room. Once the completed configuration form is sent to the server, the server will unlock 472 * the room. You can use the returned {@link MucCreateConfigFormHandle} to configure the room. 473 * </p> 474 * 475 * @param nickname the nickname to use. 476 * @return a handle to the MUC create configuration form API. 477 * @throws XMPPErrorException if the room couldn't be created for some reason (e.g. 405 error if 478 * the user is not allowed to create the room) 479 * @throws NoResponseException if there was no response from the server. 480 * @throws InterruptedException if the calling thread was interrupted. 481 * @throws NotConnectedException if the XMPP connection is not connected. 482 * @throws MucAlreadyJoinedException if already joined the Multi-User Chat.7y 483 * @throws MissingMucCreationAcknowledgeException if there MUC creation was not acknowledged by the service. 484 * @throws NotAMucServiceException if the entity is not a MUC serivce. 485 */ 486 public synchronized MucCreateConfigFormHandle create(Resourcepart nickname) throws NoResponseException, 487 XMPPErrorException, InterruptedException, MucAlreadyJoinedException, 488 NotConnectedException, MissingMucCreationAcknowledgeException, NotAMucServiceException { 489 if (isJoined()) { 490 throw new MucAlreadyJoinedException(); 491 } 492 493 MucCreateConfigFormHandle mucCreateConfigFormHandle = createOrJoin(nickname); 494 if (mucCreateConfigFormHandle != null) { 495 // We successfully created a new room 496 return mucCreateConfigFormHandle; 497 } 498 // We need to leave the room since it seems that the room already existed 499 try { 500 leave(); 501 } 502 catch (MucNotJoinedException e) { 503 LOGGER.log(Level.INFO, "Unexpected MucNotJoinedException", e); 504 } 505 throw new MissingMucCreationAcknowledgeException(); 506 } 507 508 /** 509 * Create or join the MUC room with the given nickname. 510 * 511 * @param nickname the nickname to use in the MUC room. 512 * @return A {@link MucCreateConfigFormHandle} if the room was created while joining, or {@code null} if the room was just joined. 513 * @throws NoResponseException if there was no response from the remote entity. 514 * @throws XMPPErrorException if there was an XMPP error returned. 515 * @throws InterruptedException if the calling thread was interrupted. 516 * @throws NotConnectedException if the XMPP connection is not connected. 517 * @throws MucAlreadyJoinedException if already joined the Multi-User Chat.7y 518 * @throws NotAMucServiceException if the entity is not a MUC serivce. 519 */ 520 public synchronized MucCreateConfigFormHandle createOrJoin(Resourcepart nickname) throws NoResponseException, XMPPErrorException, 521 InterruptedException, MucAlreadyJoinedException, NotConnectedException, NotAMucServiceException { 522 MucEnterConfiguration mucEnterConfiguration = getEnterConfigurationBuilder(nickname).build(); 523 return createOrJoin(mucEnterConfiguration); 524 } 525 526 /** 527 * Like {@link #create(Resourcepart)}, but will return a {@link MucCreateConfigFormHandle} if the room creation was acknowledged by 528 * the service (with an 201 status code). It's up to the caller to decide, based on the return 529 * value, if he needs to continue sending the room configuration. If {@code null} is returned, the room 530 * already existed and the user is able to join right away, without sending a form. 531 * 532 * @param mucEnterConfiguration the configuration used to enter the MUC. 533 * @return A {@link MucCreateConfigFormHandle} if the room was created while joining, or {@code null} if the room was just joined. 534 * @throws XMPPErrorException if the room couldn't be created for some reason (e.g. 405 error if 535 * the user is not allowed to create the room) 536 * @throws NoResponseException if there was no response from the server. 537 * @throws InterruptedException if the calling thread was interrupted. 538 * @throws MucAlreadyJoinedException if the MUC is already joined 539 * @throws NotConnectedException if the XMPP connection is not connected. 540 * @throws NotAMucServiceException if the entity is not a MUC serivce. 541 */ 542 public synchronized MucCreateConfigFormHandle createOrJoin(MucEnterConfiguration mucEnterConfiguration) 543 throws NoResponseException, XMPPErrorException, InterruptedException, MucAlreadyJoinedException, NotConnectedException, NotAMucServiceException { 544 if (isJoined()) { 545 throw new MucAlreadyJoinedException(); 546 } 547 548 Presence presence = enter(mucEnterConfiguration); 549 550 // Look for confirmation of room creation from the server 551 MUCUser mucUser = MUCUser.from(presence); 552 if (mucUser != null && mucUser.getStatus().contains(Status.ROOM_CREATED_201)) { 553 // Room was created and the user has joined the room 554 return new MucCreateConfigFormHandle(); 555 } 556 return null; 557 } 558 559 /** 560 * A handle used to configure a newly created room. As long as the room is not configured it will be locked, which 561 * means that no one is able to join. The room will become unlocked as soon it got configured. In order to create an 562 * instant room, use {@link #makeInstant()}. 563 * <p> 564 * For advanced configuration options, use {@link MultiUserChat#getConfigurationForm()}, get the answer form with 565 * {@link Form#getFillableForm()}, fill it out and send it back to the room with 566 * {@link MultiUserChat#sendConfigurationForm(FillableForm)}. 567 * </p> 568 */ 569 public class MucCreateConfigFormHandle { 570 571 /** 572 * Create an instant room. The default configuration will be accepted and the room will become unlocked, i.e. 573 * other users are able to join. 574 * 575 * @throws NoResponseException if there was no response from the remote entity. 576 * @throws XMPPErrorException if there was an XMPP error returned. 577 * @throws NotConnectedException if the XMPP connection is not connected. 578 * @throws InterruptedException if the calling thread was interrupted. 579 * @see <a href="http://www.xmpp.org/extensions/xep-0045.html#createroom-instant">XEP-45 § 10.1.2 Creating an 580 * Instant Room</a> 581 */ 582 public void makeInstant() throws NoResponseException, XMPPErrorException, NotConnectedException, 583 InterruptedException { 584 sendConfigurationForm(null); 585 } 586 587 /** 588 * Alias for {@link MultiUserChat#getConfigFormManager()}. 589 * 590 * @return a MUC configuration form manager for this room. 591 * @throws NoResponseException if there was no response from the remote entity. 592 * @throws XMPPErrorException if there was an XMPP error returned. 593 * @throws NotConnectedException if the XMPP connection is not connected. 594 * @throws InterruptedException if the calling thread was interrupted. 595 * @see MultiUserChat#getConfigFormManager() 596 */ 597 public MucConfigFormManager getConfigFormManager() throws NoResponseException, 598 XMPPErrorException, NotConnectedException, InterruptedException { 599 return MultiUserChat.this.getConfigFormManager(); 600 } 601 } 602 603 /** 604 * Create or join a MUC if it is necessary, i.e. if not the MUC is not already joined. 605 * 606 * @param nickname the required nickname to use. 607 * @param password the optional password required to join 608 * @return A {@link MucCreateConfigFormHandle} if the room was created while joining, or {@code null} if the room was just joined. 609 * @throws NoResponseException if there was no response from the remote entity. 610 * @throws XMPPErrorException if there was an XMPP error returned. 611 * @throws NotConnectedException if the XMPP connection is not connected. 612 * @throws InterruptedException if the calling thread was interrupted. 613 * @throws NotAMucServiceException if the entity is not a MUC serivce. 614 */ 615 public MucCreateConfigFormHandle createOrJoinIfNecessary(Resourcepart nickname, String password) throws NoResponseException, 616 XMPPErrorException, NotConnectedException, InterruptedException, NotAMucServiceException { 617 if (isJoined()) { 618 return null; 619 } 620 MucEnterConfiguration mucEnterConfiguration = getEnterConfigurationBuilder(nickname).withPassword( 621 password).build(); 622 try { 623 return createOrJoin(mucEnterConfiguration); 624 } 625 catch (MucAlreadyJoinedException e) { 626 return null; 627 } 628 } 629 630 /** 631 * Joins the chat room using the specified nickname. If already joined 632 * using another nickname, this method will first leave the room and then 633 * re-join using the new nickname. The default connection timeout for a reply 634 * from the group chat server that the join succeeded will be used. After 635 * joining the room, the room will decide the amount of history to send. 636 * 637 * @param nickname the nickname to use. 638 * @return the leave self-presence as reflected by the MUC. 639 * @throws NoResponseException if there was no response from the remote entity. 640 * @throws XMPPErrorException if an error occurs joining the room. In particular, a 641 * 401 error can occur if no password was provided and one is required; or a 642 * 403 error can occur if the user is banned; or a 643 * 404 error can occur if the room does not exist or is locked; or a 644 * 407 error can occur if user is not on the member list; or a 645 * 409 error can occur if someone is already in the group chat with the same nickname. 646 * @throws NoResponseException if there was no response from the server. 647 * @throws NotConnectedException if the XMPP connection is not connected. 648 * @throws InterruptedException if the calling thread was interrupted. 649 * @throws NotAMucServiceException if the entity is not a MUC serivce. 650 */ 651 public Presence join(Resourcepart nickname) throws NoResponseException, XMPPErrorException, 652 NotConnectedException, InterruptedException, NotAMucServiceException { 653 MucEnterConfiguration.Builder builder = getEnterConfigurationBuilder(nickname); 654 Presence reflectedJoinPresence = join(builder.build()); 655 return reflectedJoinPresence; 656 } 657 658 /** 659 * Joins the chat room using the specified nickname and password. If already joined 660 * using another nickname, this method will first leave the room and then 661 * re-join using the new nickname. The default connection timeout for a reply 662 * from the group chat server that the join succeeded will be used. After 663 * joining the room, the room will decide the amount of history to send.<p> 664 * 665 * A password is required when joining password protected rooms. If the room does 666 * not require a password there is no need to provide one. 667 * 668 * @param nickname the nickname to use. 669 * @param password the password to use. 670 * @throws XMPPErrorException if an error occurs joining the room. In particular, a 671 * 401 error can occur if no password was provided and one is required; or a 672 * 403 error can occur if the user is banned; or a 673 * 404 error can occur if the room does not exist or is locked; or a 674 * 407 error can occur if user is not on the member list; or a 675 * 409 error can occur if someone is already in the group chat with the same nickname. 676 * @throws InterruptedException if the calling thread was interrupted. 677 * @throws NotConnectedException if the XMPP connection is not connected. 678 * @throws NoResponseException if there was no response from the server. 679 * @throws NotAMucServiceException if the entity is not a MUC serivce. 680 */ 681 public void join(Resourcepart nickname, String password) throws XMPPErrorException, InterruptedException, NoResponseException, NotConnectedException, NotAMucServiceException { 682 MucEnterConfiguration.Builder builder = getEnterConfigurationBuilder(nickname).withPassword( 683 password); 684 join(builder.build()); 685 } 686 687 /** 688 * Joins the chat room using the specified nickname and password. If already joined 689 * using another nickname, this method will first leave the room and then 690 * re-join using the new nickname.<p> 691 * 692 * To control the amount of history to receive while joining a room you will need to provide 693 * a configured DiscussionHistory object.<p> 694 * 695 * A password is required when joining password protected rooms. If the room does 696 * not require a password there is no need to provide one.<p> 697 * 698 * If the room does not already exist when the user seeks to enter it, the server will 699 * decide to create a new room or not. 700 * 701 * @param mucEnterConfiguration the configuration used to enter the MUC. 702 * @return the join self-presence as reflected by the MUC. 703 * @throws XMPPErrorException if an error occurs joining the room. In particular, a 704 * 401 error can occur if no password was provided and one is required; or a 705 * 403 error can occur if the user is banned; or a 706 * 404 error can occur if the room does not exist or is locked; or a 707 * 407 error can occur if user is not on the member list; or a 708 * 409 error can occur if someone is already in the group chat with the same nickname. 709 * @throws NoResponseException if there was no response from the server. 710 * @throws NotConnectedException if the XMPP connection is not connected. 711 * @throws InterruptedException if the calling thread was interrupted. 712 * @throws NotAMucServiceException if the entity is not a MUC serivce. 713 */ 714 public synchronized Presence join(MucEnterConfiguration mucEnterConfiguration) 715 throws XMPPErrorException, NoResponseException, NotConnectedException, InterruptedException, NotAMucServiceException { 716 // If we've already joined the room, leave it before joining under a new 717 // nickname. 718 if (isJoined()) { 719 try { 720 leaveSync(); 721 } 722 catch (XMPPErrorException | NoResponseException | MucNotJoinedException e) { 723 LOGGER.log(Level.WARNING, "Could not leave MUC prior joining, assuming we are not joined", e); 724 } 725 } 726 Presence reflectedJoinPresence = enter(mucEnterConfiguration); 727 return reflectedJoinPresence; 728 } 729 730 /** 731 * Returns true if currently in the multi user chat (after calling the {@link 732 * #join(Resourcepart)} method). 733 * 734 * @return true if currently in the multi user chat room. 735 */ 736 public boolean isJoined() { 737 return getMyRoomJid() != null; 738 } 739 740 /** 741 * Leave the chat room. 742 * 743 * @return the leave presence as reflected by the MUC. 744 * @throws NotConnectedException if the XMPP connection is not connected. 745 * @throws InterruptedException if the calling thread was interrupted. 746 * @throws XMPPErrorException if there was an XMPP error returned. 747 * @throws NoResponseException if there was no response from the remote entity. 748 * @throws MucNotJoinedException if not joined to the Multi-User Chat. 749 * @deprecated use {@link #leave()} instead. 750 */ 751 @Deprecated 752 // TODO: Remove in Smack 4.5. 753 public synchronized Presence leaveSync() throws NotConnectedException, InterruptedException, MucNotJoinedException, NoResponseException, XMPPErrorException { 754 return leave(); 755 } 756 757 /** 758 * Leave the chat room. 759 * 760 * @return the leave presence as reflected by the MUC. 761 * @throws NotConnectedException if the XMPP connection is not connected. 762 * @throws InterruptedException if the calling thread was interrupted. 763 * @throws XMPPErrorException if there was an XMPP error returned. 764 * @throws NoResponseException if there was no response from the remote entity. 765 * @throws MucNotJoinedException if not joined to the Multi-User Chat. 766 */ 767 public synchronized Presence leave() 768 throws NotConnectedException, InterruptedException, NoResponseException, XMPPErrorException, MucNotJoinedException { 769 // Note that this method is intentionally not guarded by 770 // "if (!joined) return" because it should be always be possible to leave the room in case the instance's 771 // state does not reflect the actual state. 772 773 final EntityFullJid myRoomJid = getMyRoomJid(); 774 if (myRoomJid == null) { 775 throw new MucNotJoinedException(this); 776 } 777 778 // TODO: Consider adding a origin-id to the presence, once it is moved form smack-experimental into 779 // smack-extensions, in case the MUC service does not support stable IDs, and modify 780 // reflectedLeavePresenceFilters accordingly. 781 782 // We leave a room by sending a presence packet where the "to" 783 // field is in the form "roomName@service/nickname" 784 Presence leavePresence = connection.getStanzaFactory().buildPresenceStanza() 785 .ofType(Presence.Type.unavailable) 786 .to(myRoomJid) 787 .build(); 788 789 List<StanzaFilter> reflectedLeavePresenceFilters = new ArrayList<>(3); 790 reflectedLeavePresenceFilters.add(StanzaTypeFilter.PRESENCE); 791 reflectedLeavePresenceFilters.add(new OrFilter( 792 new AndFilter(FromMatchesFilter.createFull(myRoomJid), PresenceTypeFilter.UNAVAILABLE, 793 MUCUserStatusCodeFilter.STATUS_110_PRESENCE_TO_SELF), 794 new AndFilter(fromRoomFilter, PresenceTypeFilter.ERROR))); 795 796 if (serviceSupportsStableIds()) { 797 reflectedLeavePresenceFilters.add(new StanzaIdFilter(leavePresence)); 798 } 799 800 StanzaFilter reflectedLeavePresenceFilter = new AndFilter(reflectedLeavePresenceFilters); 801 802 Presence reflectedLeavePresence; 803 try { 804 reflectedLeavePresence = connection.createStanzaCollectorAndSend(reflectedLeavePresenceFilter, leavePresence).nextResultOrThrow(); 805 } finally { 806 // Reset occupant information after we send the leave presence. This ensures that we only call userHasLeft() 807 // and reset the local MUC state after we successfully left the MUC (or if an exception occurred). 808 userHasLeft(); 809 } 810 811 return reflectedLeavePresence; 812 } 813 814 /** 815 * Get a {@link MucConfigFormManager} to configure this room. 816 * <p> 817 * Only room owners are able to configure a room. 818 * </p> 819 * 820 * @return a MUC configuration form manager for this room. 821 * @throws NoResponseException if there was no response from the remote entity. 822 * @throws XMPPErrorException if there was an XMPP error returned. 823 * @throws NotConnectedException if the XMPP connection is not connected. 824 * @throws InterruptedException if the calling thread was interrupted. 825 * @see <a href="http://xmpp.org/extensions/xep-0045.html#roomconfig">XEP-45 § 10.2 Subsequent Room Configuration</a> 826 * @since 4.2 827 */ 828 public MucConfigFormManager getConfigFormManager() throws NoResponseException, 829 XMPPErrorException, NotConnectedException, InterruptedException { 830 return new MucConfigFormManager(this); 831 } 832 833 /** 834 * Returns the room's configuration form that the room's owner can use. 835 * The configuration form allows to set the room's language, 836 * enable logging, specify room's type, etc.. 837 * 838 * @return the Form that contains the fields to complete together with the instrucions or 839 * <code>null</code> if no configuration is possible. 840 * @throws XMPPErrorException if an error occurs asking the configuration form for the room. 841 * @throws NoResponseException if there was no response from the server. 842 * @throws NotConnectedException if the XMPP connection is not connected. 843 * @throws InterruptedException if the calling thread was interrupted. 844 */ 845 public Form getConfigurationForm() throws NoResponseException, XMPPErrorException, NotConnectedException, InterruptedException { 846 MUCOwner iq = new MUCOwner(); 847 iq.setTo(room); 848 iq.setType(IQ.Type.get); 849 850 IQ answer = connection.sendIqRequestAndWaitForResponse(iq); 851 DataForm dataForm = DataForm.from(answer, MucConfigFormManager.FORM_TYPE); 852 return new Form(dataForm); 853 } 854 855 /** 856 * Sends the completed configuration form to the server. The room will be configured 857 * with the new settings defined in the form. 858 * 859 * @param form the form with the new settings. 860 * @throws XMPPErrorException if an error occurs setting the new rooms' configuration. 861 * @throws NoResponseException if there was no response from the server. 862 * @throws NotConnectedException if the XMPP connection is not connected. 863 * @throws InterruptedException if the calling thread was interrupted. 864 */ 865 public void sendConfigurationForm(FillableForm form) throws NoResponseException, XMPPErrorException, NotConnectedException, InterruptedException { 866 final DataForm dataForm; 867 if (form != null) { 868 dataForm = form.getDataFormToSubmit(); 869 } else { 870 // Instant room, cf. XEP-0045 § 10.1.2 871 dataForm = DataForm.builder().build(); 872 } 873 874 MUCOwner iq = new MUCOwner(); 875 iq.setTo(room); 876 iq.setType(IQ.Type.set); 877 iq.addExtension(dataForm); 878 879 connection.sendIqRequestAndWaitForResponse(iq); 880 } 881 882 /** 883 * Returns the room's registration form that an unaffiliated user, can use to become a member 884 * of the room or <code>null</code> if no registration is possible. Some rooms may restrict the 885 * privilege to register members and allow only room admins to add new members.<p> 886 * 887 * If the user requesting registration requirements is not allowed to register with the room 888 * (e.g. because that privilege has been restricted), the room will return a "Not Allowed" 889 * error to the user (error code 405). 890 * 891 * @return the registration Form that contains the fields to complete together with the 892 * instrucions or <code>null</code> if no registration is possible. 893 * @throws XMPPErrorException if an error occurs asking the registration form for the room or a 894 * 405 error if the user is not allowed to register with the room. 895 * @throws NoResponseException if there was no response from the server. 896 * @throws NotConnectedException if the XMPP connection is not connected. 897 * @throws InterruptedException if the calling thread was interrupted. 898 */ 899 public Form getRegistrationForm() throws NoResponseException, XMPPErrorException, NotConnectedException, InterruptedException { 900 Registration reg = new Registration(); 901 reg.setType(IQ.Type.get); 902 reg.setTo(room); 903 904 IQ result = connection.sendIqRequestAndWaitForResponse(reg); 905 DataForm dataForm = DataForm.from(result); 906 return new Form(dataForm); 907 } 908 909 /** 910 * Sends the completed registration form to the server. After the user successfully submits 911 * the form, the room may queue the request for review by the room admins or may immediately 912 * add the user to the member list by changing the user's affiliation from "none" to "member.<p> 913 * 914 * If the desired room nickname is already reserved for that room, the room will return a 915 * "Conflict" error to the user (error code 409). If the room does not support registration, 916 * it will return a "Service Unavailable" error to the user (error code 503). 917 * 918 * @param form the completed registration form. 919 * @throws XMPPErrorException if an error occurs submitting the registration form. In particular, a 920 * 409 error can occur if the desired room nickname is already reserved for that room; 921 * or a 503 error can occur if the room does not support registration. 922 * @throws NoResponseException if there was no response from the server. 923 * @throws NotConnectedException if the XMPP connection is not connected. 924 * @throws InterruptedException if the calling thread was interrupted. 925 */ 926 public void sendRegistrationForm(FillableForm form) throws NoResponseException, XMPPErrorException, NotConnectedException, InterruptedException { 927 Registration reg = new Registration(); 928 reg.setType(IQ.Type.set); 929 reg.setTo(room); 930 reg.addExtension(form.getDataFormToSubmit()); 931 932 connection.sendIqRequestAndWaitForResponse(reg); 933 } 934 935 /** 936 * Sends a request to destroy the room. 937 * 938 * @throws XMPPErrorException if an error occurs while trying to destroy the room. 939 * An error can occur which will be wrapped by an XMPPException -- 940 * XMPP error code 403. The error code can be used to present more 941 * appropriate error messages to end-users. 942 * @throws NoResponseException if there was no response from the server. 943 * @throws NotConnectedException if the XMPP connection is not connected. 944 * @throws InterruptedException if the calling thread was interrupted. 945 * @see #destroy(String, EntityBareJid) 946 * @since 4.5 947 */ 948 public void destroy() throws NoResponseException, XMPPErrorException, NotConnectedException, InterruptedException { 949 destroy(null, null); 950 } 951 952 /** 953 * Sends a request to the server to destroy the room. The sender of the request 954 * should be the room's owner. If the sender of the destroy request is not the room's owner 955 * then the server will answer a "Forbidden" error (403). 956 * 957 * @param reason an optional reason for the room destruction. 958 * @param alternateJID an optional JID of an alternate location. 959 * @throws XMPPErrorException if an error occurs while trying to destroy the room. 960 * An error can occur which will be wrapped by an XMPPException -- 961 * XMPP error code 403. The error code can be used to present more 962 * appropriate error messages to end-users. 963 * @throws NoResponseException if there was no response from the server. 964 * @throws NotConnectedException if the XMPP connection is not connected. 965 * @throws InterruptedException if the calling thread was interrupted. 966 */ 967 public void destroy(String reason, EntityBareJid alternateJID) throws NoResponseException, XMPPErrorException, NotConnectedException, InterruptedException { 968 destroy(reason, alternateJID, null); 969 } 970 971 /** 972 * Sends a request to the server to destroy the room. The sender of the request 973 * should be the room's owner. If the sender of the destroy request is not the room's owner 974 * then the server will answer a "Forbidden" error (403). 975 * 976 * @param reason an optional reason for the room destruction. 977 * @param alternateJID an optional JID of an alternate location. 978 * @param password an optional password for the alternate location 979 * @throws XMPPErrorException if an error occurs while trying to destroy the room. 980 * An error can occur which will be wrapped by an XMPPException -- 981 * XMPP error code 403. The error code can be used to present more 982 * appropriate error messages to end-users. 983 * @throws NoResponseException if there was no response from the server. 984 * @throws NotConnectedException if the XMPP connection is not connected. 985 * @throws InterruptedException if the calling thread was interrupted. 986 */ 987 public void destroy(String reason, EntityBareJid alternateJID, String password) throws NoResponseException, XMPPErrorException, NotConnectedException, InterruptedException { 988 MUCOwner iq = new MUCOwner(); 989 iq.setTo(room); 990 iq.setType(IQ.Type.set); 991 992 // Create the reason for the room destruction 993 Destroy destroy = new Destroy(alternateJID, password, reason); 994 iq.setDestroy(destroy); 995 996 try { 997 connection.sendIqRequestAndWaitForResponse(iq); 998 } 999 catch (XMPPErrorException e) { 1000 // Note that we do not call userHasLeft() here because an XMPPErrorException would usually indicate that the 1001 // room was not destroyed and we therefore we also did not leave the room. 1002 throw e; 1003 } 1004 catch (NoResponseException | NotConnectedException | InterruptedException e) { 1005 // Reset occupant information. 1006 userHasLeft(); 1007 throw e; 1008 } 1009 1010 // Reset occupant information. 1011 userHasLeft(); 1012 } 1013 1014 /** 1015 * Invites another user to the room in which one is an occupant. The invitation 1016 * will be sent to the room which in turn will forward the invitation to the invitee.<p> 1017 * 1018 * If the room is password-protected, the invitee will receive a password to use to join 1019 * the room. If the room is members-only, the invitee may be added to the member list. 1020 * 1021 * @param user the user to invite to the room.(e.g. hecate@shakespeare.lit) 1022 * @param reason the reason why the user is being invited. 1023 * @throws NotConnectedException if the XMPP connection is not connected. 1024 * @throws InterruptedException if the calling thread was interrupted. 1025 */ 1026 public void invite(EntityBareJid user, String reason) throws NotConnectedException, InterruptedException { 1027 invite(connection.getStanzaFactory().buildMessageStanza(), user, reason); 1028 } 1029 1030 /** 1031 * Invites another user to the room in which one is an occupant using a given Message. The invitation 1032 * will be sent to the room which in turn will forward the invitation to the invitee.<p> 1033 * 1034 * If the room is password-protected, the invitee will receive a password to use to join 1035 * the room. If the room is members-only, the invitee may be added to the member list. 1036 * 1037 * @param message the message to use for sending the invitation. 1038 * @param user the user to invite to the room.(e.g. hecate@shakespeare.lit) 1039 * @param reason the reason why the user is being invited. 1040 * @throws NotConnectedException if the XMPP connection is not connected. 1041 * @throws InterruptedException if the calling thread was interrupted. 1042 * @deprecated use {@link #invite(MessageBuilder, EntityBareJid, String)} instead. 1043 */ 1044 @Deprecated 1045 // TODO: Remove in Smack 4.5. 1046 public void invite(Message message, EntityBareJid user, String reason) throws NotConnectedException, InterruptedException { 1047 // TODO listen for 404 error code when inviter supplies a non-existent JID 1048 message.setTo(room); 1049 1050 // Create the MUCUser packet that will include the invitation 1051 MUCUser mucUser = new MUCUser(); 1052 MUCUser.Invite invite = new MUCUser.Invite(reason, user); 1053 mucUser.setInvite(invite); 1054 // Add the MUCUser packet that includes the invitation to the message 1055 message.addExtension(mucUser); 1056 1057 connection.sendStanza(message); 1058 } 1059 1060 /** 1061 * Invites another user to the room in which one is an occupant using a given Message. The invitation 1062 * will be sent to the room which in turn will forward the invitation to the invitee.<p> 1063 * 1064 * If the room is password-protected, the invitee will receive a password to use to join 1065 * the room. If the room is members-only, the invitee may be added to the member list. 1066 * 1067 * @param messageBuilder the message to use for sending the invitation. 1068 * @param user the user to invite to the room.(e.g. hecate@shakespeare.lit) 1069 * @param reason the reason why the user is being invited. 1070 * @throws NotConnectedException if the XMPP connection is not connected. 1071 * @throws InterruptedException if the calling thread was interrupted. 1072 */ 1073 public void invite(MessageBuilder messageBuilder, EntityBareJid user, String reason) throws NotConnectedException, InterruptedException { 1074 // TODO listen for 404 error code when inviter supplies a non-existent JID 1075 messageBuilder.to(room); 1076 1077 // Create the MUCUser packet that will include the invitation 1078 MUCUser mucUser = new MUCUser(); 1079 MUCUser.Invite invite = new MUCUser.Invite(reason, user); 1080 mucUser.setInvite(invite); 1081 // Add the MUCUser packet that includes the invitation to the message 1082 messageBuilder.addExtension(mucUser); 1083 1084 Message message = messageBuilder.build(); 1085 connection.sendStanza(message); 1086 } 1087 1088 /** 1089 * Invites another user to the room in which one is an occupant. In contrast 1090 * to the method "invite", the invitation is sent directly to the user rather 1091 * than via the chat room. This is useful when the user being invited is 1092 * offline, as otherwise the invitation would be dropped. 1093 * 1094 * @param address the user to send the invitation to 1095 * @throws NotConnectedException if the XMPP connection is not connected. 1096 * @throws InterruptedException if the calling thread was interrupted. 1097 */ 1098 public void inviteDirectly(EntityBareJid address) throws NotConnectedException, InterruptedException { 1099 inviteDirectly(address, null, null, false, null); 1100 } 1101 1102 /** 1103 * Invites another user to the room in which one is an occupant. In contrast 1104 * to the method "invite", the invitation is sent directly to the user rather 1105 * than via the chat room. This is useful when the user being invited is 1106 * offline, as otherwise the invitation would be dropped. 1107 * 1108 * @param address the user to send the invitation to 1109 * @param reason the purpose for the invitation 1110 * @param password specifies a password needed for entry 1111 * @param continueAsOneToOneChat specifies if the groupchat room continues a one-to-one chat having the designated thread 1112 * @param thread the thread to continue 1113 * @throws NotConnectedException if the XMPP connection is not connected. 1114 * @throws InterruptedException if the calling thread was interrupted. 1115 */ 1116 public void inviteDirectly(EntityBareJid address, String reason, String password, boolean continueAsOneToOneChat, String thread) 1117 throws NotConnectedException, InterruptedException { 1118 // Add the extension for direct invitation 1119 GroupChatInvitation invitationExt = new GroupChatInvitation(room, 1120 reason, 1121 password, 1122 continueAsOneToOneChat, 1123 thread); 1124 1125 Message message = connection.getStanzaFactory().buildMessageStanza() 1126 .to(address) 1127 .addExtension(invitationExt) 1128 .build(); 1129 1130 connection.sendStanza(message); 1131 } 1132 1133 /** 1134 * Adds a listener to invitation rejections notifications. The listener will be fired anytime 1135 * an invitation is declined. 1136 * 1137 * @param listener an invitation rejection listener. 1138 * @return true if the listener was not already added. 1139 */ 1140 public boolean addInvitationRejectionListener(InvitationRejectionListener listener) { 1141 return invitationRejectionListeners.add(listener); 1142 } 1143 1144 /** 1145 * Removes a listener from invitation rejections notifications. The listener will be fired 1146 * anytime an invitation is declined. 1147 * 1148 * @param listener an invitation rejection listener. 1149 * @return true if the listener was registered and is now removed. 1150 */ 1151 public boolean removeInvitationRejectionListener(InvitationRejectionListener listener) { 1152 return invitationRejectionListeners.remove(listener); 1153 } 1154 1155 /** 1156 * Fires invitation rejection listeners. 1157 * 1158 * @param message the message. 1159 * @param rejection the information about the rejection. 1160 */ 1161 private void fireInvitationRejectionListeners(Message message, MUCUser.Decline rejection) { 1162 EntityBareJid invitee = rejection.getFrom(); 1163 String reason = rejection.getReason(); 1164 InvitationRejectionListener[] listeners; 1165 synchronized (invitationRejectionListeners) { 1166 listeners = new InvitationRejectionListener[invitationRejectionListeners.size()]; 1167 invitationRejectionListeners.toArray(listeners); 1168 } 1169 for (InvitationRejectionListener listener : listeners) { 1170 listener.invitationDeclined(invitee, reason, message, rejection); 1171 } 1172 } 1173 1174 /** 1175 * Adds a listener to subject change notifications. The listener will be fired anytime 1176 * the room's subject changes. 1177 * 1178 * @param listener a subject updated listener. 1179 * @return true if the listener was not already added. 1180 */ 1181 public boolean addSubjectUpdatedListener(SubjectUpdatedListener listener) { 1182 return subjectUpdatedListeners.add(listener); 1183 } 1184 1185 /** 1186 * Removes a listener from subject change notifications. The listener will be fired 1187 * anytime the room's subject changes. 1188 * 1189 * @param listener a subject updated listener. 1190 * @return true if the listener was registered and is now removed. 1191 */ 1192 public boolean removeSubjectUpdatedListener(SubjectUpdatedListener listener) { 1193 return subjectUpdatedListeners.remove(listener); 1194 } 1195 1196 /** 1197 * Adds a new {@link StanzaListener} that will be invoked every time a new presence 1198 * is going to be sent by this MultiUserChat to the server. Stanza interceptors may 1199 * add new extensions to the presence that is going to be sent to the MUC service. 1200 * 1201 * @param presenceInterceptor the new stanza interceptor that will intercept presence packets. 1202 */ 1203 public void addPresenceInterceptor(Consumer<PresenceBuilder> presenceInterceptor) { 1204 boolean added = presenceInterceptors.add(presenceInterceptor); 1205 if (!added) return; 1206 int currentCount = presenceInterceptorCount.incrementAndGet(); 1207 if (currentCount == 1) { 1208 connection.addPresenceInterceptor(this.presenceInterceptor, ToMatchesFilter.create(room).asPredicate(Presence.class)); 1209 } 1210 } 1211 1212 /** 1213 * Removes a {@link StanzaListener} that was being invoked every time a new presence 1214 * was being sent by this MultiUserChat to the server. Stanza interceptors may 1215 * add new extensions to the presence that is going to be sent to the MUC service. 1216 * 1217 * @param presenceInterceptor the stanza interceptor to remove. 1218 */ 1219 public void removePresenceInterceptor(Consumer<PresenceBuilder> presenceInterceptor) { 1220 boolean removed = presenceInterceptors.remove(presenceInterceptor); 1221 if (!removed) return; 1222 int currentCount = presenceInterceptorCount.decrementAndGet(); 1223 if (currentCount == 0) { 1224 connection.removePresenceInterceptor(this.presenceInterceptor); 1225 } 1226 } 1227 1228 /** 1229 * Returns the last known room's subject or <code>null</code> if the user hasn't joined the room 1230 * or the room does not have a subject yet. In case the room has a subject, as soon as the 1231 * user joins the room a message with the current room's subject will be received.<p> 1232 * 1233 * To be notified every time the room's subject change you should add a listener 1234 * to this room. {@link #addSubjectUpdatedListener(SubjectUpdatedListener)}<p> 1235 * 1236 * To change the room's subject use {@link #changeSubject(String)}. 1237 * 1238 * @return the room's subject or <code>null</code> if the user hasn't joined the room or the 1239 * room does not have a subject yet. 1240 */ 1241 public String getSubject() { 1242 return subject; 1243 } 1244 1245 /** 1246 * Returns the reserved room nickname for the user in the room. A user may have a reserved 1247 * nickname, for example through explicit room registration or database integration. In such 1248 * cases it may be desirable for the user to discover the reserved nickname before attempting 1249 * to enter the room. 1250 * 1251 * @return the reserved room nickname or <code>null</code> if none. 1252 * @throws SmackException if there was no response from the server. 1253 * @throws InterruptedException if the calling thread was interrupted. 1254 */ 1255 public String getReservedNickname() throws SmackException, InterruptedException { 1256 try { 1257 DiscoverInfo result = 1258 ServiceDiscoveryManager.getInstanceFor(connection).discoverInfo( 1259 room, 1260 "x-roomuser-item"); 1261 // Look for an Identity that holds the reserved nickname and return its name 1262 for (DiscoverInfo.Identity identity : result.getIdentities()) { 1263 return identity.getName(); 1264 } 1265 } 1266 catch (XMPPException e) { 1267 LOGGER.log(Level.SEVERE, "Error retrieving room nickname", e); 1268 } 1269 // If no Identity was found then the user does not have a reserved room nickname 1270 return null; 1271 } 1272 1273 /** 1274 * Returns the nickname that was used to join the room, or <code>null</code> if not 1275 * currently joined. 1276 * 1277 * @return the nickname currently being used. 1278 */ 1279 public Resourcepart getNickname() { 1280 final EntityFullJid myRoomJid = getMyRoomJid(); 1281 if (myRoomJid == null) { 1282 return null; 1283 } 1284 return myRoomJid.getResourcepart(); 1285 } 1286 1287 /** 1288 * Return the full JID of the user in the room, or <code>null</code> if the room is not joined. 1289 * 1290 * @return the full JID of the user in the room, or <code>null</code>. 1291 * @since 4.5.0 1292 */ 1293 public EntityFullJid getMyRoomJid() { 1294 return myRoomJid; 1295 } 1296 1297 private static final Object changeNicknameLock = new Object(); 1298 1299 /** 1300 * Changes the occupant's nickname to a new nickname within the room. Each room occupant 1301 * will receive two presence packets. One of type "unavailable" for the old nickname and one 1302 * indicating availability for the new nickname. The unavailable presence will contain the new 1303 * nickname and an appropriate status code (namely 303) as extended presence information. The 1304 * status code 303 indicates that the occupant is changing his/her nickname. 1305 * 1306 * @param nickname the new nickname within the room. 1307 * @throws XMPPErrorException if the new nickname is already in use by another occupant. 1308 * @throws NoResponseException if there was no response from the server. 1309 * @throws NotConnectedException if the XMPP connection is not connected. 1310 * @throws InterruptedException if the calling thread was interrupted. 1311 * @throws MucNotJoinedException if not joined to the Multi-User Chat. 1312 */ 1313 public void changeNickname(Resourcepart nickname) throws NoResponseException, XMPPErrorException, NotConnectedException, InterruptedException, MucNotJoinedException { 1314 Objects.requireNonNull(nickname, "Nickname must not be null or blank."); 1315 // Check that we already have joined the room before attempting to change the 1316 // nickname. 1317 if (!isJoined()) { 1318 throw new MucNotJoinedException(this); 1319 } 1320 final EntityFullJid jid = JidCreate.entityFullFrom(room, nickname); 1321 // We change the nickname by sending a presence packet where the "to" 1322 // field is in the form "roomName@service/nickname" 1323 // We don't have to signal the MUC support again 1324 Presence joinPresence = connection.getStanzaFactory().buildPresenceStanza() 1325 .to(jid) 1326 .ofType(Presence.Type.available) 1327 .build(); 1328 1329 synchronized (changeNicknameLock) { 1330 // Wait for a presence packet back from the server. 1331 StanzaFilter responseFilter = 1332 new AndFilter( 1333 FromMatchesFilter.createFull(jid), 1334 new StanzaTypeFilter(Presence.class)); 1335 StanzaCollector response = connection.createStanzaCollectorAndSend(responseFilter, joinPresence); 1336 // Wait up to a certain number of seconds for a reply. If there is a negative reply, an 1337 // exception will be thrown 1338 response.nextResultOrThrow(); 1339 1340 // TODO: Shouldn't this handle nickname rewriting by the MUC service? 1341 setNickname(nickname); 1342 } 1343 } 1344 1345 /** 1346 * Changes the occupant's availability status within the room. The presence type 1347 * will remain available but with a new status that describes the presence update and 1348 * a new presence mode (e.g. Extended away). 1349 * 1350 * @param status a text message describing the presence update. 1351 * @param mode the mode type for the presence update. 1352 * @throws NotConnectedException if the XMPP connection is not connected. 1353 * @throws InterruptedException if the calling thread was interrupted. 1354 * @throws MucNotJoinedException if not joined to the Multi-User Chat. 1355 */ 1356 public void changeAvailabilityStatus(String status, Presence.Mode mode) throws NotConnectedException, InterruptedException, MucNotJoinedException { 1357 final EntityFullJid myRoomJid = getMyRoomJid(); 1358 if (myRoomJid == null) { 1359 throw new MucNotJoinedException(this); 1360 } 1361 1362 // We change the availability status by sending a presence packet to the room with the 1363 // new presence status and mode 1364 Presence joinPresence = connection.getStanzaFactory().buildPresenceStanza() 1365 .to(myRoomJid) 1366 .ofType(Presence.Type.available) 1367 .setStatus(status) 1368 .setMode(mode) 1369 .build(); 1370 1371 // Send join packet. 1372 connection.sendStanza(joinPresence); 1373 } 1374 1375 /** 1376 * Kicks a visitor or participant from the room. The kicked occupant will receive a presence 1377 * of type "unavailable" including a status code 307 and optionally along with the reason 1378 * (if provided) and the bare JID of the user who initiated the kick. After the occupant 1379 * was kicked from the room, the rest of the occupants will receive a presence of type 1380 * "unavailable". The presence will include a status code 307 which means that the occupant 1381 * was kicked from the room. 1382 * 1383 * @param nickname the nickname of the participant or visitor to kick from the room 1384 * (e.g. "john"). 1385 * @param reason the reason why the participant or visitor is being kicked from the room. 1386 * @throws XMPPErrorException if an error occurs kicking the occupant. In particular, a 1387 * 405 error can occur if a moderator or a user with an affiliation of "owner" or "admin" 1388 * was intended to be kicked (i.e. Not Allowed error); or a 1389 * 403 error can occur if the occupant that intended to kick another occupant does 1390 * not have kicking privileges (i.e. Forbidden error); or a 1391 * 400 error can occur if the provided nickname is not present in the room. 1392 * @throws NoResponseException if there was no response from the server. 1393 * @throws NotConnectedException if the XMPP connection is not connected. 1394 * @throws InterruptedException if the calling thread was interrupted. 1395 */ 1396 public void kickParticipant(Resourcepart nickname, String reason) throws XMPPErrorException, NoResponseException, NotConnectedException, InterruptedException { 1397 changeRole(nickname, MUCRole.none, reason); 1398 } 1399 1400 /** 1401 * Sends a voice request to the MUC. The room moderators usually need to approve this request. 1402 * 1403 * @throws NotConnectedException if the XMPP connection is not connected. 1404 * @throws InterruptedException if the calling thread was interrupted. 1405 * @see <a href="http://xmpp.org/extensions/xep-0045.html#requestvoice">XEP-45 § 7.13 Requesting 1406 * Voice</a> 1407 * @since 4.1 1408 */ 1409 public void requestVoice() throws NotConnectedException, InterruptedException { 1410 DataForm.Builder form = DataForm.builder() 1411 .setFormType(MUCInitialPresence.NAMESPACE + "#request"); 1412 1413 TextSingleFormField.Builder requestVoiceField = FormField.textSingleBuilder("muc#role"); 1414 requestVoiceField.setLabel("Requested role"); 1415 requestVoiceField.setValue("participant"); 1416 form.addField(requestVoiceField.build()); 1417 1418 Message message = connection.getStanzaFactory().buildMessageStanza() 1419 .to(room) 1420 .addExtension(form.build()) 1421 .build(); 1422 connection.sendStanza(message); 1423 } 1424 1425 /** 1426 * Grants voice to visitors in the room. In a moderated room, a moderator may want to manage 1427 * who does and does not have "voice" in the room. To have voice means that a room occupant 1428 * is able to send messages to the room occupants. 1429 * 1430 * @param nicknames the nicknames of the visitors to grant voice in the room (e.g. "john"). 1431 * @throws XMPPErrorException if an error occurs granting voice to a visitor. In particular, a 1432 * 403 error can occur if the occupant that intended to grant voice is not 1433 * a moderator in this room (i.e. Forbidden error); or a 1434 * 400 error can occur if the provided nickname is not present in the room. 1435 * @throws NoResponseException if there was no response from the server. 1436 * @throws NotConnectedException if the XMPP connection is not connected. 1437 * @throws InterruptedException if the calling thread was interrupted. 1438 */ 1439 public void grantVoice(Collection<Resourcepart> nicknames) throws XMPPErrorException, NoResponseException, NotConnectedException, InterruptedException { 1440 changeRole(nicknames, MUCRole.participant); 1441 } 1442 1443 /** 1444 * Grants voice to a visitor in the room. In a moderated room, a moderator may want to manage 1445 * who does and does not have "voice" in the room. To have voice means that a room occupant 1446 * is able to send messages to the room occupants. 1447 * 1448 * @param nickname the nickname of the visitor to grant voice in the room (e.g. "john"). 1449 * @throws XMPPErrorException if an error occurs granting voice to a visitor. In particular, a 1450 * 403 error can occur if the occupant that intended to grant voice is not 1451 * a moderator in this room (i.e. Forbidden error); or a 1452 * 400 error can occur if the provided nickname is not present in the room. 1453 * @throws NoResponseException if there was no response from the server. 1454 * @throws NotConnectedException if the XMPP connection is not connected. 1455 * @throws InterruptedException if the calling thread was interrupted. 1456 */ 1457 public void grantVoice(Resourcepart nickname) throws XMPPErrorException, NoResponseException, NotConnectedException, InterruptedException { 1458 changeRole(nickname, MUCRole.participant, null); 1459 } 1460 1461 /** 1462 * Revokes voice from participants in the room. In a moderated room, a moderator may want to 1463 * revoke an occupant's privileges to speak. To have voice means that a room occupant 1464 * is able to send messages to the room occupants. 1465 * 1466 * @param nicknames the nicknames of the participants to revoke voice (e.g. "john"). 1467 * @throws XMPPErrorException if an error occurs revoking voice from a participant. In particular, a 1468 * 405 error can occur if a moderator or a user with an affiliation of "owner" or "admin" 1469 * was tried to revoke his voice (i.e. Not Allowed error); or a 1470 * 400 error can occur if the provided nickname is not present in the room. 1471 * @throws NoResponseException if there was no response from the server. 1472 * @throws NotConnectedException if the XMPP connection is not connected. 1473 * @throws InterruptedException if the calling thread was interrupted. 1474 */ 1475 public void revokeVoice(Collection<Resourcepart> nicknames) throws XMPPErrorException, NoResponseException, NotConnectedException, InterruptedException { 1476 changeRole(nicknames, MUCRole.visitor); 1477 } 1478 1479 /** 1480 * Revokes voice from a participant in the room. In a moderated room, a moderator may want to 1481 * revoke an occupant's privileges to speak. To have voice means that a room occupant 1482 * is able to send messages to the room occupants. 1483 * 1484 * @param nickname the nickname of the participant to revoke voice (e.g. "john"). 1485 * @throws XMPPErrorException if an error occurs revoking voice from a participant. In particular, a 1486 * 405 error can occur if a moderator or a user with an affiliation of "owner" or "admin" 1487 * was tried to revoke his voice (i.e. Not Allowed error); or a 1488 * 400 error can occur if the provided nickname is not present in the room. 1489 * @throws NoResponseException if there was no response from the server. 1490 * @throws NotConnectedException if the XMPP connection is not connected. 1491 * @throws InterruptedException if the calling thread was interrupted. 1492 */ 1493 public void revokeVoice(Resourcepart nickname) throws XMPPErrorException, NoResponseException, NotConnectedException, InterruptedException { 1494 changeRole(nickname, MUCRole.visitor, null); 1495 } 1496 1497 /** 1498 * Bans users from the room. An admin or owner of the room can ban users from a room. This 1499 * means that the banned user will no longer be able to join the room unless the ban has been 1500 * removed. If the banned user was present in the room then he/she will be removed from the 1501 * room and notified that he/she was banned along with the reason (if provided) and the bare 1502 * XMPP user ID of the user who initiated the ban. 1503 * 1504 * @param jids the bare XMPP user IDs of the users to ban. 1505 * @throws XMPPErrorException if an error occurs banning a user. In particular, a 1506 * 405 error can occur if a moderator or a user with an affiliation of "owner" or "admin" 1507 * was tried to be banned (i.e. Not Allowed error). 1508 * @throws NoResponseException if there was no response from the server. 1509 * @throws NotConnectedException if the XMPP connection is not connected. 1510 * @throws InterruptedException if the calling thread was interrupted. 1511 */ 1512 public void banUsers(Collection<? extends Jid> jids) throws XMPPErrorException, NoResponseException, NotConnectedException, InterruptedException { 1513 changeAffiliationByAdmin(jids, MUCAffiliation.outcast); 1514 } 1515 1516 /** 1517 * Bans a user from the room. An admin or owner of the room can ban users from a room. This 1518 * means that the banned user will no longer be able to join the room unless the ban has been 1519 * removed. If the banned user was present in the room then he/she will be removed from the 1520 * room and notified that he/she was banned along with the reason (if provided) and the bare 1521 * XMPP user ID of the user who initiated the ban. 1522 * 1523 * @param jid the bare XMPP user ID of the user to ban (e.g. "user@host.org"). 1524 * @param reason the optional reason why the user was banned. 1525 * @throws XMPPErrorException if an error occurs banning a user. In particular, a 1526 * 405 error can occur if a moderator or a user with an affiliation of "owner" or "admin" 1527 * was tried to be banned (i.e. Not Allowed error). 1528 * @throws NoResponseException if there was no response from the server. 1529 * @throws NotConnectedException if the XMPP connection is not connected. 1530 * @throws InterruptedException if the calling thread was interrupted. 1531 */ 1532 public void banUser(Jid jid, String reason) throws XMPPErrorException, NoResponseException, NotConnectedException, InterruptedException { 1533 changeAffiliationByAdmin(jid, MUCAffiliation.outcast, reason); 1534 } 1535 1536 /** 1537 * Grants membership to other users. Only administrators are able to grant membership. A user 1538 * that becomes a room member will be able to enter a room of type Members-Only (i.e. a room 1539 * that a user cannot enter without being on the member list). 1540 * 1541 * @param jids the XMPP user IDs of the users to grant membership. 1542 * @throws XMPPErrorException if an error occurs granting membership to a user. 1543 * @throws NoResponseException if there was no response from the server. 1544 * @throws NotConnectedException if the XMPP connection is not connected. 1545 * @throws InterruptedException if the calling thread was interrupted. 1546 */ 1547 public void grantMembership(Collection<? extends Jid> jids) throws XMPPErrorException, NoResponseException, NotConnectedException, InterruptedException { 1548 changeAffiliationByAdmin(jids, MUCAffiliation.member); 1549 } 1550 1551 /** 1552 * Grants membership to a user. Only administrators are able to grant membership. A user 1553 * that becomes a room member will be able to enter a room of type Members-Only (i.e. a room 1554 * that a user cannot enter without being on the member list). 1555 * 1556 * @param jid the XMPP user ID of the user to grant membership (e.g. "user@host.org"). 1557 * @throws XMPPErrorException if an error occurs granting membership to a user. 1558 * @throws NoResponseException if there was no response from the server. 1559 * @throws NotConnectedException if the XMPP connection is not connected. 1560 * @throws InterruptedException if the calling thread was interrupted. 1561 */ 1562 public void grantMembership(Jid jid) throws XMPPErrorException, NoResponseException, NotConnectedException, InterruptedException { 1563 changeAffiliationByAdmin(jid, MUCAffiliation.member, null); 1564 } 1565 1566 /** 1567 * Revokes users' membership. Only administrators are able to revoke membership. A user 1568 * that becomes a room member will be able to enter a room of type Members-Only (i.e. a room 1569 * that a user cannot enter without being on the member list). If the user is in the room and 1570 * the room is of type members-only then the user will be removed from the room. 1571 * 1572 * @param jids the bare XMPP user IDs of the users to revoke membership. 1573 * @throws XMPPErrorException if an error occurs revoking membership to a user. 1574 * @throws NoResponseException if there was no response from the server. 1575 * @throws NotConnectedException if the XMPP connection is not connected. 1576 * @throws InterruptedException if the calling thread was interrupted. 1577 */ 1578 public void revokeMembership(Collection<? extends Jid> jids) throws XMPPErrorException, NoResponseException, NotConnectedException, InterruptedException { 1579 changeAffiliationByAdmin(jids, MUCAffiliation.none); 1580 } 1581 1582 /** 1583 * Revokes a user's membership. Only administrators are able to revoke membership. A user 1584 * that becomes a room member will be able to enter a room of type Members-Only (i.e. a room 1585 * that a user cannot enter without being on the member list). If the user is in the room and 1586 * the room is of type members-only then the user will be removed from the room. 1587 * 1588 * @param jid the bare XMPP user ID of the user to revoke membership (e.g. "user@host.org"). 1589 * @throws XMPPErrorException if an error occurs revoking membership to a user. 1590 * @throws NoResponseException if there was no response from the server. 1591 * @throws NotConnectedException if the XMPP connection is not connected. 1592 * @throws InterruptedException if the calling thread was interrupted. 1593 */ 1594 public void revokeMembership(Jid jid) throws XMPPErrorException, NoResponseException, NotConnectedException, InterruptedException { 1595 changeAffiliationByAdmin(jid, MUCAffiliation.none, null); 1596 } 1597 1598 /** 1599 * Grants moderator privileges to participants or visitors. Room administrators may grant 1600 * moderator privileges. A moderator is allowed to kick users, grant and revoke voice, invite 1601 * other users, modify room's subject plus all the partcipants privileges. 1602 * 1603 * @param nicknames the nicknames of the occupants to grant moderator privileges. 1604 * @throws XMPPErrorException if an error occurs granting moderator privileges to a user. 1605 * @throws NoResponseException if there was no response from the server. 1606 * @throws NotConnectedException if the XMPP connection is not connected. 1607 * @throws InterruptedException if the calling thread was interrupted. 1608 */ 1609 public void grantModerator(Collection<Resourcepart> nicknames) throws XMPPErrorException, NoResponseException, NotConnectedException, InterruptedException { 1610 changeRole(nicknames, MUCRole.moderator); 1611 } 1612 1613 /** 1614 * Grants moderator privileges to a participant or visitor. Room administrators may grant 1615 * moderator privileges. A moderator is allowed to kick users, grant and revoke voice, invite 1616 * other users, modify room's subject plus all the partcipants privileges. 1617 * 1618 * @param nickname the nickname of the occupant to grant moderator privileges. 1619 * @throws XMPPErrorException if an error occurs granting moderator privileges to a user. 1620 * @throws NoResponseException if there was no response from the server. 1621 * @throws NotConnectedException if the XMPP connection is not connected. 1622 * @throws InterruptedException if the calling thread was interrupted. 1623 */ 1624 public void grantModerator(Resourcepart nickname) throws XMPPErrorException, NoResponseException, NotConnectedException, InterruptedException { 1625 changeRole(nickname, MUCRole.moderator, null); 1626 } 1627 1628 /** 1629 * Revokes moderator privileges from other users. The occupant that loses moderator 1630 * privileges will become a participant. Room administrators may revoke moderator privileges 1631 * only to occupants whose affiliation is member or none. This means that an administrator is 1632 * not allowed to revoke moderator privileges from other room administrators or owners. 1633 * 1634 * @param nicknames the nicknames of the occupants to revoke moderator privileges. 1635 * @throws XMPPErrorException if an error occurs revoking moderator privileges from a user. 1636 * @throws NoResponseException if there was no response from the server. 1637 * @throws NotConnectedException if the XMPP connection is not connected. 1638 * @throws InterruptedException if the calling thread was interrupted. 1639 */ 1640 public void revokeModerator(Collection<Resourcepart> nicknames) throws XMPPErrorException, NoResponseException, NotConnectedException, InterruptedException { 1641 changeRole(nicknames, MUCRole.participant); 1642 } 1643 1644 /** 1645 * Revokes moderator privileges from another user. The occupant that loses moderator 1646 * privileges will become a participant. Room administrators may revoke moderator privileges 1647 * only to occupants whose affiliation is member or none. This means that an administrator is 1648 * not allowed to revoke moderator privileges from other room administrators or owners. 1649 * 1650 * @param nickname the nickname of the occupant to revoke moderator privileges. 1651 * @throws XMPPErrorException if an error occurs revoking moderator privileges from a user. 1652 * @throws NoResponseException if there was no response from the server. 1653 * @throws NotConnectedException if the XMPP connection is not connected. 1654 * @throws InterruptedException if the calling thread was interrupted. 1655 */ 1656 public void revokeModerator(Resourcepart nickname) throws XMPPErrorException, NoResponseException, NotConnectedException, InterruptedException { 1657 changeRole(nickname, MUCRole.participant, null); 1658 } 1659 1660 /** 1661 * Grants ownership privileges to other users. Room owners may grant ownership privileges. 1662 * Some room implementations will not allow to grant ownership privileges to other users. 1663 * An owner is allowed to change defining room features as well as perform all administrative 1664 * functions. 1665 * 1666 * @param jids the collection of bare XMPP user IDs of the users to grant ownership. 1667 * @throws XMPPErrorException if an error occurs granting ownership privileges to a user. 1668 * @throws NoResponseException if there was no response from the server. 1669 * @throws NotConnectedException if the XMPP connection is not connected. 1670 * @throws InterruptedException if the calling thread was interrupted. 1671 */ 1672 public void grantOwnership(Collection<? extends Jid> jids) throws XMPPErrorException, NoResponseException, NotConnectedException, InterruptedException { 1673 changeAffiliationByAdmin(jids, MUCAffiliation.owner); 1674 } 1675 1676 /** 1677 * Grants ownership privileges to another user. Room owners may grant ownership privileges. 1678 * Some room implementations will not allow to grant ownership privileges to other users. 1679 * An owner is allowed to change defining room features as well as perform all administrative 1680 * functions. 1681 * 1682 * @param jid the bare XMPP user ID of the user to grant ownership (e.g. "user@host.org"). 1683 * @throws XMPPErrorException if an error occurs granting ownership privileges to a user. 1684 * @throws NoResponseException if there was no response from the server. 1685 * @throws NotConnectedException if the XMPP connection is not connected. 1686 * @throws InterruptedException if the calling thread was interrupted. 1687 */ 1688 public void grantOwnership(Jid jid) throws XMPPErrorException, NoResponseException, NotConnectedException, InterruptedException { 1689 changeAffiliationByAdmin(jid, MUCAffiliation.owner, null); 1690 } 1691 1692 /** 1693 * Revokes ownership privileges from other users. The occupant that loses ownership 1694 * privileges will become an administrator. Room owners may revoke ownership privileges. 1695 * Some room implementations will not allow to grant ownership privileges to other users. 1696 * 1697 * @param jids the bare XMPP user IDs of the users to revoke ownership. 1698 * @throws XMPPErrorException if an error occurs revoking ownership privileges from a user. 1699 * @throws NoResponseException if there was no response from the server. 1700 * @throws NotConnectedException if the XMPP connection is not connected. 1701 * @throws InterruptedException if the calling thread was interrupted. 1702 */ 1703 public void revokeOwnership(Collection<? extends Jid> jids) throws XMPPErrorException, NoResponseException, NotConnectedException, InterruptedException { 1704 changeAffiliationByAdmin(jids, MUCAffiliation.admin); 1705 } 1706 1707 /** 1708 * Revokes ownership privileges from another user. The occupant that loses ownership 1709 * privileges will become an administrator. Room owners may revoke ownership privileges. 1710 * Some room implementations will not allow to grant ownership privileges to other users. 1711 * 1712 * @param jid the bare XMPP user ID of the user to revoke ownership (e.g. "user@host.org"). 1713 * @throws XMPPErrorException if an error occurs revoking ownership privileges from a user. 1714 * @throws NoResponseException if there was no response from the server. 1715 * @throws NotConnectedException if the XMPP connection is not connected. 1716 * @throws InterruptedException if the calling thread was interrupted. 1717 */ 1718 public void revokeOwnership(Jid jid) throws XMPPErrorException, NoResponseException, NotConnectedException, InterruptedException { 1719 changeAffiliationByAdmin(jid, MUCAffiliation.admin, null); 1720 } 1721 1722 /** 1723 * Grants administrator privileges to other users. Room owners may grant administrator 1724 * privileges to a member or unaffiliated user. An administrator is allowed to perform 1725 * administrative functions such as banning users and edit moderator list. 1726 * 1727 * @param jids the bare XMPP user IDs of the users to grant administrator privileges. 1728 * @throws XMPPErrorException if an error occurs granting administrator privileges to a user. 1729 * @throws NoResponseException if there was no response from the server. 1730 * @throws NotConnectedException if the XMPP connection is not connected. 1731 * @throws InterruptedException if the calling thread was interrupted. 1732 */ 1733 public void grantAdmin(Collection<? extends Jid> jids) throws XMPPErrorException, NoResponseException, NotConnectedException, InterruptedException { 1734 changeAffiliationByAdmin(jids, MUCAffiliation.admin); 1735 } 1736 1737 /** 1738 * Grants administrator privileges to another user. Room owners may grant administrator 1739 * privileges to a member or unaffiliated user. An administrator is allowed to perform 1740 * administrative functions such as banning users and edit moderator list. 1741 * 1742 * @param jid the bare XMPP user ID of the user to grant administrator privileges 1743 * (e.g. "user@host.org"). 1744 * @throws XMPPErrorException if an error occurs granting administrator privileges to a user. 1745 * @throws NoResponseException if there was no response from the server. 1746 * @throws NotConnectedException if the XMPP connection is not connected. 1747 * @throws InterruptedException if the calling thread was interrupted. 1748 */ 1749 public void grantAdmin(Jid jid) throws XMPPErrorException, NoResponseException, NotConnectedException, InterruptedException { 1750 changeAffiliationByAdmin(jid, MUCAffiliation.admin); 1751 } 1752 1753 /** 1754 * Revokes administrator privileges from users. The occupant that loses administrator 1755 * privileges will become a member. Room owners may revoke administrator privileges from 1756 * a member or unaffiliated user. 1757 * 1758 * @param jids the bare XMPP user IDs of the user to revoke administrator privileges. 1759 * @throws XMPPErrorException if an error occurs revoking administrator privileges from a user. 1760 * @throws NoResponseException if there was no response from the server. 1761 * @throws NotConnectedException if the XMPP connection is not connected. 1762 * @throws InterruptedException if the calling thread was interrupted. 1763 */ 1764 public void revokeAdmin(Collection<? extends Jid> jids) throws XMPPErrorException, NoResponseException, NotConnectedException, InterruptedException { 1765 changeAffiliationByAdmin(jids, MUCAffiliation.admin); 1766 } 1767 1768 /** 1769 * Revokes administrator privileges from a user. The occupant that loses administrator 1770 * privileges will become a member. Room owners may revoke administrator privileges from 1771 * a member or unaffiliated user. 1772 * 1773 * @param jid the bare XMPP user ID of the user to revoke administrator privileges 1774 * (e.g. "user@host.org"). 1775 * @throws XMPPErrorException if an error occurs revoking administrator privileges from a user. 1776 * @throws NoResponseException if there was no response from the server. 1777 * @throws NotConnectedException if the XMPP connection is not connected. 1778 * @throws InterruptedException if the calling thread was interrupted. 1779 */ 1780 public void revokeAdmin(EntityJid jid) throws XMPPErrorException, NoResponseException, NotConnectedException, InterruptedException { 1781 changeAffiliationByAdmin(jid, MUCAffiliation.member); 1782 } 1783 1784 /** 1785 * Tries to change the affiliation with an 'muc#admin' namespace 1786 * 1787 * @param jid TODO javadoc me please 1788 * @param affiliation TODO javadoc me please 1789 * @throws XMPPErrorException if there was an XMPP error returned. 1790 * @throws NoResponseException if there was no response from the remote entity. 1791 * @throws NotConnectedException if the XMPP connection is not connected. 1792 * @throws InterruptedException if the calling thread was interrupted. 1793 */ 1794 private void changeAffiliationByAdmin(Jid jid, MUCAffiliation affiliation) 1795 throws NoResponseException, XMPPErrorException, 1796 NotConnectedException, InterruptedException { 1797 changeAffiliationByAdmin(jid, affiliation, null); 1798 } 1799 1800 /** 1801 * Tries to change the affiliation with an 'muc#admin' namespace 1802 * 1803 * @param jid TODO javadoc me please 1804 * @param affiliation TODO javadoc me please 1805 * @param reason the reason for the affiliation change (optional) 1806 * @throws XMPPErrorException if there was an XMPP error returned. 1807 * @throws NoResponseException if there was no response from the remote entity. 1808 * @throws NotConnectedException if the XMPP connection is not connected. 1809 * @throws InterruptedException if the calling thread was interrupted. 1810 */ 1811 private void changeAffiliationByAdmin(Jid jid, MUCAffiliation affiliation, String reason) throws NoResponseException, XMPPErrorException, NotConnectedException, InterruptedException { 1812 MUCAdmin iq = new MUCAdmin(); 1813 iq.setTo(room); 1814 iq.setType(IQ.Type.set); 1815 // Set the new affiliation. 1816 MUCItem item = new MUCItem(affiliation, jid, reason); 1817 iq.addItem(item); 1818 1819 connection.sendIqRequestAndWaitForResponse(iq); 1820 } 1821 1822 private void changeAffiliationByAdmin(Collection<? extends Jid> jids, MUCAffiliation affiliation) 1823 throws NoResponseException, XMPPErrorException, NotConnectedException, InterruptedException { 1824 MUCAdmin iq = new MUCAdmin(); 1825 iq.setTo(room); 1826 iq.setType(IQ.Type.set); 1827 for (Jid jid : jids) { 1828 // Set the new affiliation. 1829 MUCItem item = new MUCItem(affiliation, jid); 1830 iq.addItem(item); 1831 } 1832 1833 connection.sendIqRequestAndWaitForResponse(iq); 1834 } 1835 1836 private void changeRole(Resourcepart nickname, MUCRole role, String reason) throws NoResponseException, XMPPErrorException, NotConnectedException, InterruptedException { 1837 MUCAdmin iq = new MUCAdmin(); 1838 iq.setTo(room); 1839 iq.setType(IQ.Type.set); 1840 // Set the new role. 1841 MUCItem item = new MUCItem(role, nickname, reason); 1842 iq.addItem(item); 1843 1844 connection.sendIqRequestAndWaitForResponse(iq); 1845 } 1846 1847 private void changeRole(Collection<Resourcepart> nicknames, MUCRole role) throws NoResponseException, XMPPErrorException, NotConnectedException, InterruptedException { 1848 MUCAdmin iq = new MUCAdmin(); 1849 iq.setTo(room); 1850 iq.setType(IQ.Type.set); 1851 for (Resourcepart nickname : nicknames) { 1852 // Set the new role. 1853 MUCItem item = new MUCItem(role, nickname); 1854 iq.addItem(item); 1855 } 1856 1857 connection.sendIqRequestAndWaitForResponse(iq); 1858 } 1859 1860 /** 1861 * Returns the number of occupants in the group chat.<p> 1862 * 1863 * Note: this value will only be accurate after joining the group chat, and 1864 * may fluctuate over time. If you query this value directly after joining the 1865 * group chat it may not be accurate, as it takes a certain amount of time for 1866 * the server to send all presence packets to this client. 1867 * 1868 * @return the number of occupants in the group chat. 1869 */ 1870 public int getOccupantsCount() { 1871 return occupantsMap.size(); 1872 } 1873 1874 /** 1875 * Returns an List for the list of fully qualified occupants 1876 * in the group chat. For example, "conference@chat.jivesoftware.com/SomeUser". 1877 * Typically, a client would only display the nickname of the occupant. To 1878 * get the nickname from the fully qualified name, use the 1879 * {@link org.jxmpp.util.XmppStringUtils#parseResource(String)} method. 1880 * Note: this value will only be accurate after joining the group chat, and may 1881 * fluctuate over time. 1882 * 1883 * @return a List of the occupants in the group chat. 1884 */ 1885 public List<EntityFullJid> getOccupants() { 1886 return new ArrayList<>(occupantsMap.keySet()); 1887 } 1888 1889 /** 1890 * Returns the presence info for a particular user, or <code>null</code> if the user 1891 * is not in the room.<p> 1892 * 1893 * @param user the room occupant to search for his presence. The format of user must 1894 * be: roomName@service/nickname (e.g. darkcave@macbeth.shakespeare.lit/thirdwitch). 1895 * @return the occupant's current presence, or <code>null</code> if the user is unavailable 1896 * or if no presence information is available. 1897 */ 1898 public Presence getOccupantPresence(EntityFullJid user) { 1899 return occupantsMap.get(user); 1900 } 1901 1902 /** 1903 * Returns the Occupant information for a particular occupant, or <code>null</code> if the 1904 * user is not in the room. The Occupant object may include information such as full 1905 * JID of the user as well as the role and affiliation of the user in the room.<p> 1906 * 1907 * @param user the room occupant to search for his presence. The format of user must 1908 * be: roomName@service/nickname (e.g. darkcave@macbeth.shakespeare.lit/thirdwitch). 1909 * @return the Occupant or <code>null</code> if the user is unavailable (i.e. not in the room). 1910 */ 1911 public Occupant getOccupant(EntityFullJid user) { 1912 Presence presence = getOccupantPresence(user); 1913 if (presence != null) { 1914 return new Occupant(presence); 1915 } 1916 return null; 1917 } 1918 1919 /** 1920 * Adds a stanza listener that will be notified of any new Presence packets 1921 * sent to the group chat. Using a listener is a suitable way to know when the list 1922 * of occupants should be re-loaded due to any changes. 1923 * 1924 * @param listener a stanza listener that will be notified of any presence packets 1925 * sent to the group chat. 1926 * @return true if the listener was not already added. 1927 */ 1928 public boolean addParticipantListener(PresenceListener listener) { 1929 return presenceListeners.add(listener); 1930 } 1931 1932 /** 1933 * Removes a stanza listener that was being notified of any new Presence packets 1934 * sent to the group chat. 1935 * 1936 * @param listener a stanza listener that was being notified of any presence packets 1937 * sent to the group chat. 1938 * @return true if the listener was removed, otherwise the listener was not added previously. 1939 */ 1940 public boolean removeParticipantListener(PresenceListener listener) { 1941 return presenceListeners.remove(listener); 1942 } 1943 1944 /** 1945 * Returns a list of <code>Affiliate</code> with the room owners. 1946 * 1947 * @return a list of <code>Affiliate</code> with the room owners. 1948 * @throws XMPPErrorException if you don't have enough privileges to get this information. 1949 * @throws NoResponseException if there was no response from the server. 1950 * @throws NotConnectedException if the XMPP connection is not connected. 1951 * @throws InterruptedException if the calling thread was interrupted. 1952 */ 1953 public List<Affiliate> getOwners() throws NoResponseException, XMPPErrorException, NotConnectedException, InterruptedException { 1954 return getAffiliatesByAdmin(MUCAffiliation.owner); 1955 } 1956 1957 /** 1958 * Returns a list of <code>Affiliate</code> with the room administrators. 1959 * 1960 * @return a list of <code>Affiliate</code> with the room administrators. 1961 * @throws XMPPErrorException if you don't have enough privileges to get this information. 1962 * @throws NoResponseException if there was no response from the server. 1963 * @throws NotConnectedException if the XMPP connection is not connected. 1964 * @throws InterruptedException if the calling thread was interrupted. 1965 */ 1966 public List<Affiliate> getAdmins() throws NoResponseException, XMPPErrorException, NotConnectedException, InterruptedException { 1967 return getAffiliatesByAdmin(MUCAffiliation.admin); 1968 } 1969 1970 /** 1971 * Returns a list of <code>Affiliate</code> with the room members. 1972 * 1973 * @return a list of <code>Affiliate</code> with the room members. 1974 * @throws XMPPErrorException if you don't have enough privileges to get this information. 1975 * @throws NoResponseException if there was no response from the server. 1976 * @throws NotConnectedException if the XMPP connection is not connected. 1977 * @throws InterruptedException if the calling thread was interrupted. 1978 */ 1979 public List<Affiliate> getMembers() throws NoResponseException, XMPPErrorException, NotConnectedException, InterruptedException { 1980 return getAffiliatesByAdmin(MUCAffiliation.member); 1981 } 1982 1983 /** 1984 * Returns a list of <code>Affiliate</code> with the room outcasts. 1985 * 1986 * @return a list of <code>Affiliate</code> with the room outcasts. 1987 * @throws XMPPErrorException if you don't have enough privileges to get this information. 1988 * @throws NoResponseException if there was no response from the server. 1989 * @throws NotConnectedException if the XMPP connection is not connected. 1990 * @throws InterruptedException if the calling thread was interrupted. 1991 */ 1992 public List<Affiliate> getOutcasts() throws NoResponseException, XMPPErrorException, NotConnectedException, InterruptedException { 1993 return getAffiliatesByAdmin(MUCAffiliation.outcast); 1994 } 1995 1996 /** 1997 * Returns a collection of <code>Affiliate</code> that have the specified room affiliation 1998 * sending a request in the admin namespace. 1999 * 2000 * @param affiliation the affiliation of the users in the room. 2001 * @return a collection of <code>Affiliate</code> that have the specified room affiliation. 2002 * @throws XMPPErrorException if you don't have enough privileges to get this information. 2003 * @throws NoResponseException if there was no response from the server. 2004 * @throws NotConnectedException if the XMPP connection is not connected. 2005 * @throws InterruptedException if the calling thread was interrupted. 2006 */ 2007 private List<Affiliate> getAffiliatesByAdmin(MUCAffiliation affiliation) throws NoResponseException, XMPPErrorException, NotConnectedException, InterruptedException { 2008 MUCAdmin iq = new MUCAdmin(); 2009 iq.setTo(room); 2010 iq.setType(IQ.Type.get); 2011 // Set the specified affiliation. This may request the list of owners/admins/members/outcasts. 2012 MUCItem item = new MUCItem(affiliation); 2013 iq.addItem(item); 2014 2015 MUCAdmin answer = (MUCAdmin) connection.sendIqRequestAndWaitForResponse(iq); 2016 2017 // Get the list of affiliates from the server's answer 2018 List<Affiliate> affiliates = new ArrayList<Affiliate>(); 2019 for (MUCItem mucadminItem : answer.getItems()) { 2020 affiliates.add(new Affiliate(mucadminItem)); 2021 } 2022 return affiliates; 2023 } 2024 2025 /** 2026 * Returns a list of <code>Occupant</code> with the room moderators. 2027 * 2028 * @return a list of <code>Occupant</code> with the room moderators. 2029 * @throws XMPPErrorException if you don't have enough privileges to get this information. 2030 * @throws NoResponseException if there was no response from the server. 2031 * @throws NotConnectedException if the XMPP connection is not connected. 2032 * @throws InterruptedException if the calling thread was interrupted. 2033 */ 2034 public List<Occupant> getModerators() throws NoResponseException, XMPPErrorException, NotConnectedException, InterruptedException { 2035 return getOccupants(MUCRole.moderator); 2036 } 2037 2038 /** 2039 * Returns a list of <code>Occupant</code> with the room participants. 2040 * 2041 * @return a list of <code>Occupant</code> with the room participants. 2042 * @throws XMPPErrorException if you don't have enough privileges to get this information. 2043 * @throws NoResponseException if there was no response from the server. 2044 * @throws NotConnectedException if the XMPP connection is not connected. 2045 * @throws InterruptedException if the calling thread was interrupted. 2046 */ 2047 public List<Occupant> getParticipants() throws NoResponseException, XMPPErrorException, NotConnectedException, InterruptedException { 2048 return getOccupants(MUCRole.participant); 2049 } 2050 2051 /** 2052 * Returns a list of <code>Occupant</code> that have the specified room role. 2053 * 2054 * @param role the role of the occupant in the room. 2055 * @return a list of <code>Occupant</code> that have the specified room role. 2056 * @throws XMPPErrorException if an error occurred while performing the request to the server or you 2057 * don't have enough privileges to get this information. 2058 * @throws NoResponseException if there was no response from the server. 2059 * @throws NotConnectedException if the XMPP connection is not connected. 2060 * @throws InterruptedException if the calling thread was interrupted. 2061 */ 2062 private List<Occupant> getOccupants(MUCRole role) throws NoResponseException, XMPPErrorException, NotConnectedException, InterruptedException { 2063 MUCAdmin iq = new MUCAdmin(); 2064 iq.setTo(room); 2065 iq.setType(IQ.Type.get); 2066 // Set the specified role. This may request the list of moderators/participants. 2067 MUCItem item = new MUCItem(role); 2068 iq.addItem(item); 2069 2070 MUCAdmin answer = (MUCAdmin) connection.sendIqRequestAndWaitForResponse(iq); 2071 // Get the list of participants from the server's answer 2072 List<Occupant> participants = new ArrayList<Occupant>(); 2073 for (MUCItem mucadminItem : answer.getItems()) { 2074 participants.add(new Occupant(mucadminItem)); 2075 } 2076 return participants; 2077 } 2078 2079 /** 2080 * Sends a message to the chat room. 2081 * 2082 * @param text the text of the message to send. 2083 * @throws NotConnectedException if the XMPP connection is not connected. 2084 * @throws InterruptedException if the calling thread was interrupted. 2085 */ 2086 public void sendMessage(String text) throws NotConnectedException, InterruptedException { 2087 Message message = buildMessage() 2088 .setBody(text) 2089 .build(); 2090 connection.sendStanza(message); 2091 } 2092 2093 /** 2094 * Returns a new Chat for sending private messages to a given room occupant. 2095 * The Chat's occupant address is the room's JID (i.e. roomName@service/nick). The server 2096 * service will change the 'from' address to the sender's room JID and delivering the message 2097 * to the intended recipient's full JID. 2098 * 2099 * @param occupant occupant unique room JID (e.g. 'darkcave@macbeth.shakespeare.lit/Paul'). 2100 * @param listener the listener is a message listener that will handle messages for the newly 2101 * created chat. 2102 * @return new Chat for sending private messages to a given room occupant. 2103 */ 2104 // TODO This should be made new not using chat.Chat. Private MUC chats are different from XMPP-IM 1:1 chats in to many ways. 2105 // API sketch: PrivateMucChat createPrivateChat(Resourcepart nick) 2106 @SuppressWarnings("deprecation") 2107 public org.jivesoftware.smack.chat.Chat createPrivateChat(EntityFullJid occupant, ChatMessageListener listener) { 2108 return org.jivesoftware.smack.chat.ChatManager.getInstanceFor(connection).createChat(occupant, listener); 2109 } 2110 2111 /** 2112 * Creates a new Message to send to the chat room. 2113 * 2114 * @return a new Message addressed to the chat room. 2115 * @deprecated use {@link #buildMessage()} instead. 2116 */ 2117 @Deprecated 2118 // TODO: Remove when stanza builder is ready. 2119 public Message createMessage() { 2120 return connection.getStanzaFactory().buildMessageStanza() 2121 .ofType(Message.Type.groupchat) 2122 .to(room) 2123 .build(); 2124 } 2125 2126 /** 2127 * Constructs a new message builder for messages send to this MUC room. 2128 * 2129 * @return a new message builder. 2130 */ 2131 public MessageBuilder buildMessage() { 2132 return connection.getStanzaFactory() 2133 .buildMessageStanza() 2134 .ofType(Message.Type.groupchat) 2135 .to(room) 2136 ; 2137 } 2138 2139 /** 2140 * Sends a Message to the chat room. 2141 * 2142 * @param message the message. 2143 * @throws NotConnectedException if the XMPP connection is not connected. 2144 * @throws InterruptedException if the calling thread was interrupted. 2145 * @deprecated use {@link #sendMessage(MessageBuilder)} instead. 2146 */ 2147 @Deprecated 2148 // TODO: Remove in Smack 4.5. 2149 public void sendMessage(Message message) throws NotConnectedException, InterruptedException { 2150 sendMessage(message.asBuilder()); 2151 } 2152 2153 /** 2154 * Sends a Message to the chat room. 2155 * 2156 * @param messageBuilder the message. 2157 * @return a read-only view of the send message. 2158 * @throws NotConnectedException if the XMPP connection is not connected. 2159 * @throws InterruptedException if the calling thread was interrupted. 2160 */ 2161 public MessageView sendMessage(MessageBuilder messageBuilder) throws NotConnectedException, InterruptedException { 2162 for (MucMessageInterceptor interceptor : messageInterceptors) { 2163 interceptor.intercept(messageBuilder, this); 2164 } 2165 2166 Message message = messageBuilder.to(room).ofType(Message.Type.groupchat).build(); 2167 connection.sendStanza(message); 2168 return message; 2169 } 2170 2171 /** 2172 * Polls for and returns the next message, or <code>null</code> if there isn't 2173 * a message immediately available. This method provides significantly different 2174 * functionalty than the {@link #nextMessage()} method since it's non-blocking. 2175 * In other words, the method call will always return immediately, whereas the 2176 * nextMessage method will return only when a message is available (or after 2177 * a specific timeout). 2178 * 2179 * @return the next message if one is immediately available and 2180 * <code>null</code> otherwise. 2181 * @throws MucNotJoinedException if not joined to the Multi-User Chat. 2182 */ 2183 public Message pollMessage() throws MucNotJoinedException { 2184 if (messageCollector == null) { 2185 throw new MucNotJoinedException(this); 2186 } 2187 return messageCollector.pollResult(); 2188 } 2189 2190 /** 2191 * Returns the next available message in the chat. The method call will block 2192 * (not return) until a message is available. 2193 * 2194 * @return the next message. 2195 * @throws MucNotJoinedException if not joined to the Multi-User Chat. 2196 * @throws InterruptedException if the calling thread was interrupted. 2197 */ 2198 public Message nextMessage() throws MucNotJoinedException, InterruptedException { 2199 if (messageCollector == null) { 2200 throw new MucNotJoinedException(this); 2201 } 2202 return messageCollector.nextResultBlockForever(); 2203 } 2204 2205 /** 2206 * Returns the next available message in the chat. The method call will block 2207 * (not return) until a stanza is available or the <code>timeout</code> has elapased. 2208 * If the timeout elapses without a result, <code>null</code> will be returned. 2209 * 2210 * @param timeout the maximum amount of time to wait for the next message. 2211 * @return the next message, or <code>null</code> if the timeout elapses without a 2212 * message becoming available. 2213 * @throws MucNotJoinedException if not joined to the Multi-User Chat. 2214 * @throws InterruptedException if the calling thread was interrupted. 2215 */ 2216 public Message nextMessage(long timeout) throws MucNotJoinedException, InterruptedException { 2217 if (messageCollector == null) { 2218 throw new MucNotJoinedException(this); 2219 } 2220 return messageCollector.nextResult(timeout); 2221 } 2222 2223 /** 2224 * Adds a stanza listener that will be notified of any new messages in the 2225 * group chat. Only "group chat" messages addressed to this group chat will 2226 * be delivered to the listener. If you wish to listen for other packets 2227 * that may be associated with this group chat, you should register a 2228 * PacketListener directly with the XMPPConnection with the appropriate 2229 * PacketListener. 2230 * 2231 * @param listener a stanza listener. 2232 * @return true if the listener was not already added. 2233 */ 2234 public boolean addMessageListener(MessageListener listener) { 2235 return messageListeners.add(listener); 2236 } 2237 2238 /** 2239 * Removes a stanza listener that was being notified of any new messages in the 2240 * multi user chat. Only "group chat" messages addressed to this multi user chat were 2241 * being delivered to the listener. 2242 * 2243 * @param listener a stanza listener. 2244 * @return true if the listener was removed, otherwise the listener was not added previously. 2245 */ 2246 public boolean removeMessageListener(MessageListener listener) { 2247 return messageListeners.remove(listener); 2248 } 2249 2250 public boolean addMessageInterceptor(MucMessageInterceptor interceptor) { 2251 return messageInterceptors.add(interceptor); 2252 } 2253 2254 public boolean removeMessageInterceptor(MucMessageInterceptor interceptor) { 2255 return messageInterceptors.remove(interceptor); 2256 } 2257 2258 /** 2259 * Changes the subject within the room. As a default, only users with a role of "moderator" 2260 * are allowed to change the subject in a room. Although some rooms may be configured to 2261 * allow a mere participant or even a visitor to change the subject. 2262 * 2263 * @param subject the new room's subject to set. 2264 * @throws XMPPErrorException if someone without appropriate privileges attempts to change the 2265 * room subject will throw an error with code 403 (i.e. Forbidden) 2266 * @throws NoResponseException if there was no response from the server. 2267 * @throws NotConnectedException if the XMPP connection is not connected. 2268 * @throws InterruptedException if the calling thread was interrupted. 2269 */ 2270 public void changeSubject(final String subject) throws NoResponseException, XMPPErrorException, NotConnectedException, InterruptedException { 2271 Message message = buildMessage() 2272 .setSubject(subject) 2273 .build(); 2274 // Wait for an error or confirmation message back from the server. 2275 StanzaFilter successFilter = new AndFilter(fromRoomGroupchatFilter, new StanzaFilter() { 2276 @Override 2277 public boolean accept(Stanza packet) { 2278 Message msg = (Message) packet; 2279 return subject.equals(msg.getSubject()); 2280 } 2281 }); 2282 StanzaFilter errorFilter = new AndFilter(fromRoomFilter, new StanzaIdFilter(message), MessageTypeFilter.ERROR); 2283 StanzaFilter responseFilter = new OrFilter(successFilter, errorFilter); 2284 StanzaCollector response = connection.createStanzaCollectorAndSend(responseFilter, message); 2285 // Wait up to a certain number of seconds for a reply. 2286 response.nextResultOrThrow(); 2287 } 2288 2289 /** 2290 * Remove the connection callbacks (PacketListener, PacketInterceptor, StanzaCollector) used by this MUC from the 2291 * connection. 2292 */ 2293 private void removeConnectionCallbacks() { 2294 connection.removeStanzaListener(messageListener); 2295 connection.removeStanzaListener(presenceListener); 2296 connection.removeStanzaListener(subjectListener); 2297 connection.removeStanzaListener(declinesListener); 2298 connection.removePresenceInterceptor(presenceInterceptor); 2299 if (messageCollector != null) { 2300 messageCollector.cancel(); 2301 messageCollector = null; 2302 } 2303 } 2304 2305 /** 2306 * Remove all callbacks and resources necessary when the user has left the room for some reason. 2307 */ 2308 private synchronized void userHasLeft() { 2309 occupantsMap.clear(); 2310 myRoomJid = null; 2311 // Update the list of joined rooms 2312 multiUserChatManager.removeJoinedRoom(room); 2313 removeConnectionCallbacks(); 2314 } 2315 2316 /** 2317 * Adds a listener that will be notified of changes in your status in the room 2318 * such as the user being kicked, banned, or granted admin permissions. 2319 * 2320 * @param listener a user status listener. 2321 * @return true if the user status listener was not already added. 2322 */ 2323 public boolean addUserStatusListener(UserStatusListener listener) { 2324 return userStatusListeners.add(listener); 2325 } 2326 2327 /** 2328 * Removes a listener that was being notified of changes in your status in the room 2329 * such as the user being kicked, banned, or granted admin permissions. 2330 * 2331 * @param listener a user status listener. 2332 * @return true if the listener was registered and is now removed. 2333 */ 2334 public boolean removeUserStatusListener(UserStatusListener listener) { 2335 return userStatusListeners.remove(listener); 2336 } 2337 2338 /** 2339 * Adds a listener that will be notified of changes in occupants status in the room 2340 * such as the user being kicked, banned, or granted admin permissions. 2341 * 2342 * @param listener a participant status listener. 2343 * @return true if the listener was not already added. 2344 */ 2345 public boolean addParticipantStatusListener(ParticipantStatusListener listener) { 2346 return participantStatusListeners.add(listener); 2347 } 2348 2349 /** 2350 * Removes a listener that was being notified of changes in occupants status in the room 2351 * such as the user being kicked, banned, or granted admin permissions. 2352 * 2353 * @param listener a participant status listener. 2354 * @return true if the listener was registered and is now removed. 2355 */ 2356 public boolean removeParticipantStatusListener(ParticipantStatusListener listener) { 2357 return participantStatusListeners.remove(listener); 2358 } 2359 2360 /** 2361 * Fires notification events if the role of a room occupant has changed. If the occupant that 2362 * changed his role is your occupant then the <code>UserStatusListeners</code> added to this 2363 * <code>MultiUserChat</code> will be fired. On the other hand, if the occupant that changed 2364 * his role is not yours then the <code>ParticipantStatusListeners</code> added to this 2365 * <code>MultiUserChat</code> will be fired. The following table shows the events that will 2366 * be fired depending on the previous and new role of the occupant. 2367 * 2368 * <pre> 2369 * <table border="1"> 2370 * <tr><td><b>Old</b></td><td><b>New</b></td><td><b>Events</b></td></tr> 2371 * 2372 * <tr><td>None</td><td>Visitor</td><td>--</td></tr> 2373 * <tr><td>Visitor</td><td>Participant</td><td>voiceGranted</td></tr> 2374 * <tr><td>Participant</td><td>Moderator</td><td>moderatorGranted</td></tr> 2375 * 2376 * <tr><td>None</td><td>Participant</td><td>voiceGranted</td></tr> 2377 * <tr><td>None</td><td>Moderator</td><td>voiceGranted + moderatorGranted</td></tr> 2378 * <tr><td>Visitor</td><td>Moderator</td><td>voiceGranted + moderatorGranted</td></tr> 2379 * 2380 * <tr><td>Moderator</td><td>Participant</td><td>moderatorRevoked</td></tr> 2381 * <tr><td>Participant</td><td>Visitor</td><td>voiceRevoked</td></tr> 2382 * <tr><td>Visitor</td><td>None</td><td>kicked</td></tr> 2383 * 2384 * <tr><td>Moderator</td><td>Visitor</td><td>voiceRevoked + moderatorRevoked</td></tr> 2385 * <tr><td>Moderator</td><td>None</td><td>kicked</td></tr> 2386 * <tr><td>Participant</td><td>None</td><td>kicked</td></tr> 2387 * </table> 2388 * </pre> 2389 * 2390 * @param oldRole the previous role of the user in the room before receiving the new presence 2391 * @param newRole the new role of the user in the room after receiving the new presence 2392 * @param isUserModification whether the received presence is about your user in the room or not 2393 * @param from the occupant whose role in the room has changed 2394 * (e.g. room@conference.jabber.org/nick). 2395 */ 2396 private void checkRoleModifications( 2397 MUCRole oldRole, 2398 MUCRole newRole, 2399 boolean isUserModification, 2400 EntityFullJid from) { 2401 // Voice was granted to a visitor 2402 if ((MUCRole.visitor.equals(oldRole) || MUCRole.none.equals(oldRole)) 2403 && MUCRole.participant.equals(newRole)) { 2404 if (isUserModification) { 2405 for (UserStatusListener listener : userStatusListeners) { 2406 listener.voiceGranted(); 2407 } 2408 } 2409 else { 2410 for (ParticipantStatusListener listener : participantStatusListeners) { 2411 listener.voiceGranted(from); 2412 } 2413 } 2414 } 2415 // The participant's voice was revoked from the room 2416 else if ( 2417 MUCRole.participant.equals(oldRole) 2418 && (MUCRole.visitor.equals(newRole) || MUCRole.none.equals(newRole))) { 2419 if (isUserModification) { 2420 for (UserStatusListener listener : userStatusListeners) { 2421 listener.voiceRevoked(); 2422 } 2423 } 2424 else { 2425 for (ParticipantStatusListener listener : participantStatusListeners) { 2426 listener.voiceRevoked(from); 2427 } 2428 } 2429 } 2430 // Moderator privileges were granted to a participant 2431 if (!MUCRole.moderator.equals(oldRole) && MUCRole.moderator.equals(newRole)) { 2432 if (MUCRole.visitor.equals(oldRole) || MUCRole.none.equals(oldRole)) { 2433 if (isUserModification) { 2434 for (UserStatusListener listener : userStatusListeners) { 2435 listener.voiceGranted(); 2436 } 2437 } 2438 else { 2439 for (ParticipantStatusListener listener : participantStatusListeners) { 2440 listener.voiceGranted(from); 2441 } 2442 } 2443 } 2444 if (isUserModification) { 2445 for (UserStatusListener listener : userStatusListeners) { 2446 listener.moderatorGranted(); 2447 } 2448 } 2449 else { 2450 for (ParticipantStatusListener listener : participantStatusListeners) { 2451 listener.moderatorGranted(from); 2452 } 2453 } 2454 } 2455 // Moderator privileges were revoked from a participant 2456 else if (MUCRole.moderator.equals(oldRole) && !MUCRole.moderator.equals(newRole)) { 2457 if (MUCRole.visitor.equals(newRole) || MUCRole.none.equals(newRole)) { 2458 if (isUserModification) { 2459 for (UserStatusListener listener : userStatusListeners) { 2460 listener.voiceRevoked(); 2461 } 2462 } 2463 else { 2464 for (ParticipantStatusListener listener : participantStatusListeners) { 2465 listener.voiceRevoked(from); 2466 } 2467 } 2468 } 2469 if (isUserModification) { 2470 for (UserStatusListener listener : userStatusListeners) { 2471 listener.moderatorRevoked(); 2472 } 2473 } 2474 else { 2475 for (ParticipantStatusListener listener : participantStatusListeners) { 2476 listener.moderatorRevoked(from); 2477 } 2478 } 2479 } 2480 } 2481 2482 /** 2483 * Fires notification events if the affiliation of a room occupant has changed. If the 2484 * occupant that changed his affiliation is your occupant then the 2485 * <code>UserStatusListeners</code> added to this <code>MultiUserChat</code> will be fired. 2486 * On the other hand, if the occupant that changed his affiliation is not yours then the 2487 * <code>ParticipantStatusListeners</code> added to this <code>MultiUserChat</code> will be 2488 * fired. The following table shows the events that will be fired depending on the previous 2489 * and new affiliation of the occupant. 2490 * 2491 * <pre> 2492 * <table border="1"> 2493 * <tr><td><b>Old</b></td><td><b>New</b></td><td><b>Events</b></td></tr> 2494 * 2495 * <tr><td>None</td><td>Member</td><td>membershipGranted</td></tr> 2496 * <tr><td>Member</td><td>Admin</td><td>membershipRevoked + adminGranted</td></tr> 2497 * <tr><td>Admin</td><td>Owner</td><td>adminRevoked + ownershipGranted</td></tr> 2498 * 2499 * <tr><td>None</td><td>Admin</td><td>adminGranted</td></tr> 2500 * <tr><td>None</td><td>Owner</td><td>ownershipGranted</td></tr> 2501 * <tr><td>Member</td><td>Owner</td><td>membershipRevoked + ownershipGranted</td></tr> 2502 * 2503 * <tr><td>Owner</td><td>Admin</td><td>ownershipRevoked + adminGranted</td></tr> 2504 * <tr><td>Admin</td><td>Member</td><td>adminRevoked + membershipGranted</td></tr> 2505 * <tr><td>Member</td><td>None</td><td>membershipRevoked</td></tr> 2506 * 2507 * <tr><td>Owner</td><td>Member</td><td>ownershipRevoked + membershipGranted</td></tr> 2508 * <tr><td>Owner</td><td>None</td><td>ownershipRevoked</td></tr> 2509 * <tr><td>Admin</td><td>None</td><td>adminRevoked</td></tr> 2510 * <tr><td><i>Anyone</i></td><td>Outcast</td><td>banned</td></tr> 2511 * </table> 2512 * </pre> 2513 * 2514 * @param oldAffiliation the previous affiliation of the user in the room before receiving the 2515 * new presence 2516 * @param newAffiliation the new affiliation of the user in the room after receiving the new 2517 * presence 2518 * @param isUserModification whether the received presence is about your user in the room or not 2519 * @param from the occupant whose role in the room has changed 2520 * (e.g. room@conference.jabber.org/nick). 2521 */ 2522 private void checkAffiliationModifications( 2523 MUCAffiliation oldAffiliation, 2524 MUCAffiliation newAffiliation, 2525 boolean isUserModification, 2526 EntityFullJid from) { 2527 // First check for revoked affiliation and then for granted affiliations. The idea is to 2528 // first fire the "revoke" events and then fire the "grant" events. 2529 2530 // The user's ownership to the room was revoked 2531 if (MUCAffiliation.owner.equals(oldAffiliation) && !MUCAffiliation.owner.equals(newAffiliation)) { 2532 if (isUserModification) { 2533 for (UserStatusListener listener : userStatusListeners) { 2534 listener.ownershipRevoked(); 2535 } 2536 } 2537 else { 2538 for (ParticipantStatusListener listener : participantStatusListeners) { 2539 listener.ownershipRevoked(from); 2540 } 2541 } 2542 } 2543 // The user's administrative privileges to the room were revoked 2544 else if (MUCAffiliation.admin.equals(oldAffiliation) && !MUCAffiliation.admin.equals(newAffiliation)) { 2545 if (isUserModification) { 2546 for (UserStatusListener listener : userStatusListeners) { 2547 listener.adminRevoked(); 2548 } 2549 } 2550 else { 2551 for (ParticipantStatusListener listener : participantStatusListeners) { 2552 listener.adminRevoked(from); 2553 } 2554 } 2555 } 2556 // The user's membership to the room was revoked 2557 else if (MUCAffiliation.member.equals(oldAffiliation) && !MUCAffiliation.member.equals(newAffiliation)) { 2558 if (isUserModification) { 2559 for (UserStatusListener listener : userStatusListeners) { 2560 listener.membershipRevoked(); 2561 } 2562 } 2563 else { 2564 for (ParticipantStatusListener listener : participantStatusListeners) { 2565 listener.membershipRevoked(from); 2566 } 2567 } 2568 } 2569 2570 // The user was granted ownership to the room 2571 if (!MUCAffiliation.owner.equals(oldAffiliation) && MUCAffiliation.owner.equals(newAffiliation)) { 2572 if (isUserModification) { 2573 for (UserStatusListener listener : userStatusListeners) { 2574 listener.ownershipGranted(); 2575 } 2576 } 2577 else { 2578 for (ParticipantStatusListener listener : participantStatusListeners) { 2579 listener.ownershipGranted(from); 2580 } 2581 } 2582 } 2583 // The user was granted administrative privileges to the room 2584 else if (!MUCAffiliation.admin.equals(oldAffiliation) && MUCAffiliation.admin.equals(newAffiliation)) { 2585 if (isUserModification) { 2586 for (UserStatusListener listener : userStatusListeners) { 2587 listener.adminGranted(); 2588 } 2589 } 2590 else { 2591 for (ParticipantStatusListener listener : participantStatusListeners) { 2592 listener.adminGranted(from); 2593 } 2594 } 2595 } 2596 // The user was granted membership to the room 2597 else if (!MUCAffiliation.member.equals(oldAffiliation) && MUCAffiliation.member.equals(newAffiliation)) { 2598 if (isUserModification) { 2599 for (UserStatusListener listener : userStatusListeners) { 2600 listener.membershipGranted(); 2601 } 2602 } 2603 else { 2604 for (ParticipantStatusListener listener : participantStatusListeners) { 2605 listener.membershipGranted(from); 2606 } 2607 } 2608 } 2609 } 2610 2611 /** 2612 * Fires events according to the received presence code. 2613 * 2614 * @param statusCodes TODO javadoc me please 2615 * @param isUserModification TODO javadoc me please 2616 * @param mucUser TODO javadoc me please 2617 * @param from TODO javadoc me please 2618 */ 2619 private void checkPresenceCode( 2620 Set<Status> statusCodes, 2621 boolean isUserModification, 2622 MUCUser mucUser, 2623 EntityFullJid from) { 2624 // Check if an occupant was kicked from the room 2625 if (statusCodes.contains(Status.KICKED_307)) { 2626 // Check if this occupant was kicked 2627 if (isUserModification) { 2628 for (UserStatusListener listener : userStatusListeners) { 2629 listener.kicked(mucUser.getItem().getActor(), mucUser.getItem().getReason()); 2630 } 2631 } 2632 else { 2633 for (ParticipantStatusListener listener : participantStatusListeners) { 2634 listener.kicked(from, mucUser.getItem().getActor(), mucUser.getItem().getReason()); 2635 } 2636 } 2637 } 2638 // A user was banned from the room 2639 if (statusCodes.contains(Status.BANNED_301)) { 2640 // Check if this occupant was banned 2641 if (isUserModification) { 2642 for (UserStatusListener listener : userStatusListeners) { 2643 listener.banned(mucUser.getItem().getActor(), mucUser.getItem().getReason()); 2644 } 2645 } 2646 else { 2647 for (ParticipantStatusListener listener : participantStatusListeners) { 2648 listener.banned(from, mucUser.getItem().getActor(), mucUser.getItem().getReason()); 2649 } 2650 } 2651 } 2652 // A user's membership was revoked from the room 2653 if (statusCodes.contains(Status.REMOVED_AFFIL_CHANGE_321)) { 2654 // Check if this occupant's membership was revoked 2655 if (isUserModification) { 2656 for (UserStatusListener listener : userStatusListeners) { 2657 listener.membershipRevoked(); 2658 } 2659 } else { 2660 for (ParticipantStatusListener listener : participantStatusListeners) { 2661 listener.membershipRevoked(from); 2662 } 2663 } 2664 } 2665 // A occupant has changed his nickname in the room 2666 if (statusCodes.contains(Status.NEW_NICKNAME_303)) { 2667 for (ParticipantStatusListener listener : participantStatusListeners) { 2668 listener.nicknameChanged(from, mucUser.getItem().getNick()); 2669 } 2670 } 2671 } 2672 2673 /** 2674 * Get the XMPP connection associated with this chat instance. 2675 * 2676 * @return the associated XMPP connection. 2677 * @since 4.3.0 2678 */ 2679 public XMPPConnection getXmppConnection() { 2680 return connection; 2681 } 2682 2683 public boolean serviceSupportsStableIds() { 2684 return DiscoverInfo.nullSafeContainsFeature(mucServiceDiscoInfo, MultiUserChatConstants.STABLE_ID_FEATURE); 2685 } 2686 2687 @Override 2688 public String toString() { 2689 return "MUC: " + room + "(" + connection.getUser() + ")"; 2690 } 2691}