MUCRoom.java 42.7 KB
Newer Older
1 2 3 4 5
/**
 * $RCSfile$
 * $Revision: 2979 $
 * $Date: 2005-10-18 19:46:58 -0300 (Tue, 18 Oct 2005) $
 *
6
 * Copyright (C) 2004-2008 Jive Software. All rights reserved.
7
 *
8 9 10 11 12 13 14 15 16 17 18
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
19 20
 */

21
package org.jivesoftware.openfire.muc;
22 23

import org.dom4j.Element;
24 25
import org.jivesoftware.database.JiveID;
import org.jivesoftware.openfire.auth.UnauthorizedException;
26 27
import org.jivesoftware.openfire.muc.spi.IQAdminHandler;
import org.jivesoftware.openfire.muc.spi.IQOwnerHandler;
28 29
import org.jivesoftware.openfire.muc.spi.LocalMUCRole;
import org.jivesoftware.openfire.muc.spi.LocalMUCUser;
30 31
import org.jivesoftware.openfire.user.UserAlreadyExistsException;
import org.jivesoftware.openfire.user.UserNotFoundException;
32 33
import org.jivesoftware.util.JiveConstants;
import org.jivesoftware.util.NotFoundException;
34
import org.xmpp.packet.JID;
35
import org.xmpp.packet.Message;
36
import org.xmpp.packet.Packet;
37
import org.xmpp.packet.Presence;
38
import org.xmpp.resultsetmanagement.Result;
39 40 41 42 43

import java.io.Externalizable;
import java.util.Collection;
import java.util.Date;
import java.util.List;
44 45 46 47 48 49 50 51 52


/**
 * A chat room on the chat server manages its users, and
 * enforces it's own security rules.
 *
 * @author Gaston Dombiak
 */
@JiveID(JiveConstants.MUC_ROOM)
53
public interface MUCRoom extends Externalizable, Result {
54 55 56 57 58 59 60 61

    /**
     * Get the name of this room.
     *
     * @return The name for this room
     */
    String getName();

62 63 64 65 66 67 68
    /**
     * Get the full JID of this room.
     *
     * @return the JID for this room.
     */
    JID getJID();

69 70 71 72 73 74 75 76 77 78 79 80 81
    /**
     * Obtain a unique numerical id for this room. Useful for storing rooms in databases. If the 
     * room is persistent or is logging the conversation then the returned ID won't be -1.
     *
     * @return The unique id for this room or -1 if the room is temporary and is not logging the
     * conversation.
     */
    long getID();

    /**
     * Sets a new room ID if the room has just been saved to the database or sets the saved ID of
     * the room in the database while loading the room. 
     * 
82
     * @param roomID the saved ID of the room in the DB or a new one if the room is being saved to the DB.
83 84 85
     */
    void setID(long roomID);

86 87 88 89 90 91 92 93 94 95
    /**
     * Get the multi user chat service the room is attached to.
     *
     * @return the MultiUserChatService instance that the room is attached to.
     */
    MultiUserChatService getMUCService();

    /**
     * Sets the multi user chat service the room is attached to.
     *
96
     * @param service The MultiUserChatService that the room is attached to (cannot be <tt>null</tt>).
97 98 99
     */
    void setMUCService(MultiUserChatService service);

100 101 102 103 104 105 106 107 108 109
    /**
     * Returns the date when the room was created.
     *
     * @return the date when the room was created.
     */
    Date getCreationDate();

    /**
     * Sets the date when the room was created.
     *
110
     * @param creationDate the date when the room was created (cannot be <tt>null</tt>).
111 112 113 114 115 116 117 118 119 120 121 122 123 124 125
     */
    void setCreationDate(Date creationDate);

    /**
     * Returns the last date when the room's configuration was modified. If the room's configuration
     * was never modified then the creation date will be returned.
     *
     * @return the last date when the room's configuration was modified.
     */
    Date getModificationDate();

    /**
     * Sets the last date when the room's configuration was modified. If the room's configuration
     * was never modified then the initial value will be the same as the creation date.
     *
126
     * @param modificationDate the last date when the room's configuration was modified (cannot be <tt>null</tt>).
127 128 129 130 131 132 133
     */
    void setModificationDate(Date modificationDate);

    /**
     * Sets the date when the last occupant left the room. A null value means that there are
     * occupants in the room at the moment.
     *
134
     * @param emptyDate the date when the last occupant left the room or null if there are occupants in the room (can be <tt>null</tt>).
135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154
     */
    void setEmptyDate(Date emptyDate);

    /**
     * Returns the date when the last occupant left the room. A null value means that there are
     * occupants in the room at the moment.
     *
     * @return the date when the last occupant left the room or null if there are occupants in the
     *         room at the moment.
     */
    Date getEmptyDate();

    /**
     * Obtain the role of the chat server (mainly for addressing messages and presence).
     *
     * @return The role for the chat room itself
     */
    MUCRole getRole();

    /**
155
     * Obtain the first role of a given user by nickname.
156
     *
157
     * @param nickname The nickname of the user you'd like to obtain (cannot be <tt>null</tt>)
158 159
     * @return The user's role in the room
     * @throws UserNotFoundException If there is no user with the given nickname
160
     * @deprecated Prefer {@link #getOccupantsByNickname(String)} instead (a user may be connected more than once)
161 162 163
     */
    MUCRole getOccupant(String nickname) throws UserNotFoundException;

164 165 166 167 168 169 170 171 172
    /**
     * Obtain the roles of a given user by nickname. A user can be connected to a room more than once.
     *
     * @param nickname The nickname of the user you'd like to obtain (cannot be <tt>null</tt>)
     * @return The user's role in the room
     * @throws UserNotFoundException If there is no user with the given nickname
     */
    List<MUCRole> getOccupantsByNickname(String nickname) throws UserNotFoundException;

173 174 175 176
    /**
     * Obtain the roles of a given user in the room by his bare JID. A user can have several roles,
     * one for each client resource from which the user has joined the room. 
     *
177
     * @param jid The bare jid of the user you'd like to obtain  (cannot be <tt>null</tt>).
178 179 180
     * @return The user's roles in the room
     * @throws UserNotFoundException If there is no user with the given nickname
     */
181
    List<MUCRole> getOccupantsByBareJID(JID jid) throws UserNotFoundException;
182 183

    /**
184 185
     * Returns the role of a given user in the room by his full JID or <tt>null</tt>
     * if no role was found for the specified user.
186
     *
187
     * @param jid The full jid of the user you'd like to obtain  (cannot be <tt>null</tt>).
188
     * @return The user's role in the room or null if not found.
189
     */
190
    MUCRole getOccupantByFullJID(JID jid);
191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208

    /**
     * Obtain the roles of all users in the chatroom.
     *
     * @return a collection with all users in the chatroom
     */
    Collection<MUCRole> getOccupants();

    /**
     * Returns the number of occupants in the chatroom at the moment.
     *
     * @return int the number of occupants in the chatroom at the moment.
     */
    int getOccupantsCount();

    /**
     * Determine if a given nickname is taken.
     *
209
     * @param nickname The nickname of the user you'd like to obtain  (cannot be <tt>null</tt>).
210 211 212 213 214 215 216
     * @return True if a nickname is taken
     */
    boolean hasOccupant(String nickname);

    /**
     * Returns the reserved room nickname for the bare JID or null if none.
     * 
217
     * @param jid The bare jid of the user of which you'd like to obtain his reserved nickname (cannot be <tt>null</tt>).
218 219
     * @return the reserved room nickname for the bare JID or null if none.
     */
220
    String getReservedNickname(JID jid);
221 222 223 224 225 226 227

    /**
     * Returns the affiliation state of the user in the room. Possible affiliations are 
     * MUCRole.OWNER, MUCRole.ADMINISTRATOR, MUCRole.MEMBER, MUCRole.OUTCAST and MUCRole.NONE.<p>
     * 
     * Note: Prerequisite - A lock must already be obtained before sending this message.
     *  
228
     * @param bareJID The bare jid of the user of which you'd like to obtain his affiliation (cannot be <tt>null</tt>).
229 230
     * @return the affiliation state of the user in the room.
     */
231
    MUCRole.Affiliation getAffiliation(JID bareJID);
232 233 234 235

    /**
     * Joins the room using the given nickname.
     *
236
     * @param nickname       The nickname the user wants to use in the chatroom  (cannot be <tt>null</tt>).
237 238
     * @param password       The password provided by the user to enter the chatroom or null if none.
     * @param historyRequest The amount of history that the user request or null meaning default.
239 240
     * @param user           The user joining (cannot be <tt>null</tt>).
     * @param presence       The presence sent by the user to join the room (cannot be <tt>null</tt>).
241
     * @return The role created for the user.
242
     * @throws UnauthorizedException         If the user doesn't have permission to join the room.
243 244 245 246 247 248 249 250 251 252 253
     * @throws UserAlreadyExistsException    If the nickname is already taken.
     * @throws RoomLockedException           If the user is trying to join a locked room.
     * @throws ForbiddenException            If the user is an outcast.
     * @throws RegistrationRequiredException If the user is not a member of a members-only room.
     * @throws ConflictException             If another user attempts to join the room with a
     *                                       nickname reserved by the first user.
     * @throws ServiceUnavailableException   If the user cannot join the room since the max number
     *                                       of users has been reached.
     * @throws NotAcceptableException       If the registered user is trying to join with a
     *                                      nickname different than the reserved nickname.
     */
254
    LocalMUCRole joinRoom(String nickname, String password, HistoryRequest historyRequest, LocalMUCUser user,
255 256 257 258 259 260 261
            Presence presence) throws UnauthorizedException, UserAlreadyExistsException,
            RoomLockedException, ForbiddenException, RegistrationRequiredException,
            ConflictException, ServiceUnavailableException, NotAcceptableException;

    /**
     * Remove a member from the chat room.
     *
262
     * @param leaveRole room occupant that left the room  (cannot be <tt>null</tt>).
263
     */
264
    void leaveRoom(MUCRole leaveRole);
265 266 267 268 269 270

    /**
     * Destroys the room. Each occupant will be removed and will receive a presence stanza of type
     * "unavailable" whose "from" attribute will be the occupant's nickname that the user knows he 
     * or she has been removed from the room.
     * 
271 272
     * @param alternateJID an optional alternate JID. Commonly used to provide a replacement room. (can be <tt>null</tt>)
     * @param reason an optional reason why the room was destroyed (can be <tt>null</tt>).
273
     */
274
    void destroyRoom(JID alternateJID, String reason);
275 276 277 278

    /**
     * Create a new presence in this room for the given role.
     *
279
     * @param type Type of presence to create (cannot be <tt>null</tt>).
280 281 282 283 284 285 286 287 288
     * @return The new presence
     * @throws UnauthorizedException If the user doesn't have permission to leave the room
     */
    Presence createPresence(Presence.Type type) throws UnauthorizedException;

    /**
     * Broadcast a given message to all members of this chat room. The sender is always set to 
     * be the chatroom.
     *
289
     * @param msg The message to broadcast (cannot be <tt>null</tt>)
290 291 292 293 294 295 296 297 298 299 300 301 302
     */
    void serverBroadcast(String msg);
    
    /**
     * Returns the total length of the chat session.
     * 
     * @return length of chat session in milliseconds.
     */
    public long getChatLength();

    /**
     * Adds a new user to the list of owners. The user is the actual creator of the room. Only the
     * MultiUserChatServer should use this method. Regular owners list maintenance MUST be done
303
     * through {@link #addOwner(JID jid,MUCRole)}.
304
     * 
305
     * @param bareJID The bare JID of the user to add as owner (cannot be <tt>null</tt>).
306
     */
307
    public void addFirstOwner(JID bareJID);
308

309 310 311
    /**
     * Adds a new user to the list of owners.
     * 
312 313
     * @param jid The JID of the user to add as owner (cannot be <tt>null</tt>).
     * @param senderRole the role of the user that is trying to modify the owners list (cannot be <tt>null</tt>).
314 315 316 317 318 319
     * @return the list of updated presences of all the client resources that the client used to
     *         join the room.
     * @throws ForbiddenException If the user is not allowed to modify the owner list.
     */
    public List<Presence> addOwner(JID jid, MUCRole senderRole) throws ForbiddenException;

320 321 322
    /**
     * Adds a list of users to the list of owners.
     *
323 324
     * @param newOwners the list of bare JIDs of the users to add to the list of existing owners (cannot be <tt>null</tt>).
     * @param senderRole the role of the user that is trying to modify the owners list (cannot be <tt>null</tt>).
325 326 327 328
     * @return the list of updated presences of all the clients resources that the clients used to
     *         join the room.
     * @throws ForbiddenException If the user is not allowed to modify the owner list.
     */
329
    public List<Presence> addOwners(List<JID> newOwners, MUCRole senderRole)
330 331 332 333 334
            throws ForbiddenException;

    /**
     * Adds a list of users to the list of admins.
     *
335 336
     * @param newAdmins the list of bare JIDs of the users to add to the list of existing admins (cannot be <tt>null</tt>).
     * @param senderRole the role of the user that is trying to modify the admins list (cannot be <tt>null</tt>).
337 338 339 340 341
     * @return the list of updated presences of all the clients resources that the clients used to
     *         join the room.
     * @throws ForbiddenException If the user is not allowed to modify the admin list.
     * @throws ConflictException If the room was going to lose all its owners.
     */
342
    public List<Presence> addAdmins(List<JID> newAdmins, MUCRole senderRole)
343 344
            throws ForbiddenException, ConflictException;

345 346 347
    /**
     * Adds a new user to the list of admins.
     * 
348 349
     * @param jid The JID of the user to add as admin (cannot be <tt>null</tt>).
     * @param senderRole The role of the user that is trying to modify the admins list (cannot be <tt>null</tt>).
350 351 352 353 354 355 356
     * @return the list of updated presences of all the client resources that the client used to
     *         join the room.
     * @throws ForbiddenException If the user is not allowed to modify the admin list.
     * @throws ConflictException If the room was going to lose all its owners.
     */
    public List<Presence> addAdmin(JID jid, MUCRole senderRole) throws ForbiddenException,
            ConflictException;
357

358 359 360
    /**
     * Adds a new user to the list of members.
     * 
361
     * @param jid The JID of the user to add as a member (cannot be <tt>null</tt>).
362
     * @param nickname The reserved nickname of the member for the room or null if none.
363
     * @param senderRole the role of the user that is trying to modify the members list (cannot be <tt>null</tt>).
364 365 366 367 368 369 370 371 372 373 374 375
     * @return the list of updated presences of all the client resources that the client used to
     *         join the room.
     * @throws ForbiddenException If the user is not allowed to modify the members list.
     * @throws ConflictException If the desired room nickname is already reserved for the room or if
     *             the room was going to lose all its owners.
     */
    public List<Presence> addMember(JID jid, String nickname, MUCRole senderRole)
            throws ForbiddenException, ConflictException;

    /**
     * Adds a new user to the list of outcast users.
     * 
376 377 378
     * @param jid The JID of the user to add as an outcast (cannot be <tt>null</tt>).
     * @param reason an optional reason why the user was banned (can be <tt>null</tt>).
     * @param senderRole The role of the user that initiated the ban (cannot be <tt>null</tt>).
379 380 381 382 383 384 385 386 387 388 389 390
     * @return the list of updated presences of all the client resources that the client used to
     *         join the room.
     * @throws NotAllowedException Thrown if trying to ban an owner or an administrator.
     * @throws ForbiddenException If the user is not allowed to modify the outcast list.
     * @throws ConflictException If the room was going to lose all its owners.
     */
    public List<Presence> addOutcast(JID jid, String reason, MUCRole senderRole)
            throws NotAllowedException, ForbiddenException, ConflictException;

    /**
     * Removes the user from all the other affiliation list thus giving the user a NONE affiliation.
     * 
391 392
     * @param jid The JID of the user to keep with a NONE affiliation (cannot be <tt>null</tt>).
     * @param senderRole The role of the user that set the affiliation to none (cannot be <tt>null</tt>).
393 394 395 396 397 398 399 400
     * @return the list of updated presences of all the client resources that the client used to
     *         join the room or null if none was updated.
     * @throws ForbiddenException If the user is not allowed to modify the none list.
     * @throws ConflictException If the room was going to lose all its owners.
     */
    public List<Presence> addNone(JID jid, MUCRole senderRole) throws ForbiddenException,
            ConflictException;

401 402 403 404
    /**
     * Changes the role of the user within the room to moderator. A moderator is allowed to kick
     * occupants as well as granting/revoking voice from occupants.
     *
405 406
     * @param fullJID The full JID of the occupant to give moderator privileges (cannot be <tt>null</tt>).
     * @param senderRole The role of the user that is granting moderator privileges to an occupant (cannot be <tt>null</tt>).
407 408 409 410 411 412 413 414 415 416
     * @return the updated presence of the occupant or <tt>null</tt> if the JID does not belong to
     *         an existing occupant.
     * @throws ForbiddenException If the user is not allowed to grant moderator privileges.
     */
    public Presence addModerator(JID fullJID, MUCRole senderRole) throws ForbiddenException;

    /**
     * Changes the role of the user within the room to participant. A participant is allowed to send
     * messages to the room (i.e. has voice) and may change the room's subject.
     *
417
     * @param fullJID The full JID of the occupant to give participant privileges (cannot be <tt>null</tt>).
418 419
     * @param reason The reason why participant privileges were gave to the user or <tt>null</tt>
     *        if none.
420
     * @param senderRole The role of the user that is granting participant privileges to an occupant (cannot be <tt>null</tt>).
421 422 423 424 425 426 427 428 429 430 431 432 433
     * @return the updated presence of the occupant or <tt>null</tt> if the JID does not belong to
     *         an existing occupant.
     * @throws NotAllowedException If trying to change the moderator role to an owner or an admin.
     * @throws ForbiddenException If the user is not allowed to grant participant privileges.
     */
    public Presence addParticipant(JID fullJID, String reason, MUCRole senderRole)
            throws NotAllowedException, ForbiddenException;

    /**
     * Changes the role of the user within the room to visitor. A visitor can receive messages but
     * is not allowed to send messages to the room (i.e. does not has voice) and may invite others
     * to the room.
     *
434 435
     * @param jid the full JID of the occupant to change to visitor (cannot be <tt>null</tt>).
     * @param senderRole the role of the user that is changing the role to visitor (cannot be <tt>null</tt>).
436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461
     * @return the updated presence of the occupant or <tt>null</tt> if the JID does not belong to
     *         an existing occupant.
     * @throws NotAllowedException if trying to change the moderator role to an owner or an admin.
     * @throws ForbiddenException if the user is not a moderator.
     */
    public Presence addVisitor(JID jid, MUCRole senderRole) throws NotAllowedException,
            ForbiddenException;

    /**
     * Returns true if the room is locked. The lock will persist for a defined period of time. If 
     * the room owner does not configure the room within the timeout period, the room owner is 
     * assumed to have accepted the default configuration.
     * 
     * @return true if the room is locked. 
     */
    public boolean isLocked();

    /**
     * Returns true if the room is locked and it was locked by a room owner after the room was
     * initially configured.
     *
     * @return true if the room is locked and it was locked by a room owner after the room was
     *         initially configured.
     */
    public boolean isManuallyLocked();

462 463 464
    /**
     * An event callback fired whenever an occupant updated his presence in the chatroom.
     *
465 466
     * @param occupantRole occupant that changed his presence in the room (cannot be <tt>null</tt>).
     * @param newPresence presence sent by the occupant (cannot be <tt>null</tt>).
467 468 469
     */
    public void presenceUpdated(MUCRole occupantRole, Presence newPresence);

470 471
    /**
     * An event callback fired whenever an occupant changes his nickname within the chatroom.
472
     *
473 474 475 476
     * @param occupantRole occupant that changed his nickname in the room (cannot be <tt>null</tt>).
     * @param newPresence presence sent by the occupant with the new nickname (cannot be <tt>null</tt>).
     * @param oldNick old nickname within the room (cannot be <tt>null</tt>).
     * @param newNick new nickname within the room (cannot be <tt>null</tt>).
477
     */
478
    public void nicknameChanged(MUCRole occupantRole, Presence newPresence, String oldNick, String newNick);
479 480 481 482 483 484 485 486
    
    /**
     * Changes the room's subject if the occupant has enough permissions. The occupant must be
     * a moderator or the room must be configured so that anyone can change its subject. Otherwise
     * a forbidden exception will be thrown.<p>
     * 
     * The new subject will be added to the history of the room.
     *  
487 488
     * @param packet the sent packet to change the room's subject (cannot be <tt>null</tt>).
     * @param role the role of the user that is trying to change the subject (cannot be <tt>null</tt>).
489 490 491 492 493 494 495 496 497 498 499 500 501 502 503
     * @throws ForbiddenException If the user is not allowed to change the subject.
     */
    public void changeSubject(Message packet, MUCRole role) throws ForbiddenException;

    /**
     * Returns the last subject that some occupant set to the room.
     * 
     * @return the last subject that some occupant set to the room.
     */
    public String getSubject();

    /**
     * Sets the last subject that some occupant set to the room. This message will only be used
     * when loading a room from the database. 
     * 
504
     * @param subject the last known subject of the room (cannot be <tt>null</tt>).
505 506 507 508 509 510 511 512
     */
    public void setSubject(String subject);

    /**
     * Sends a message to the all the occupants. In a moderated room, this privilege is restricted
     * to occupants with a role of participant or higher. In an unmoderated room, any occupant can
     * send a message to all other occupants.
     * 
513 514
     * @param message The message to send (cannot be <tt>null</tt>).
     * @param senderRole the role of the user that is trying to send a public message (cannot be <tt>null</tt>).
515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534
     * @throws ForbiddenException If the user is not allowed to send a public message (i.e. does not
     *             have voice in the room).
     */
    public void sendPublicMessage(Message message, MUCRole senderRole) throws ForbiddenException;

    /**
     * Sends a private packet to a selected occupant. The packet can be a Message for private
     * conversation between room occupants or IQ packets when an occupant wants to send IQ packets
     * to other room occupants.
     * 
     * @param packet The packet to send.
     * @param senderRole the role of the user that is trying to send a public message.
     * @throws NotFoundException If the user is sending a packet to a room JID that does not exist.
     */
    public void sendPrivatePacket(Packet packet, MUCRole senderRole) throws NotFoundException;

    /**
     * Kicks a user from the room. If the user was in the room, the returned updated presence will
     * be sent to the remaining occupants. 
     * 
535 536 537
     * @param fullJID The full JID of the kicked user  (cannot be <tt>null</tt>).
     * @param actorJID The JID of the actor that initiated the kick (cannot be <tt>null</tt>).
     * @param reason An optional reason why the user was kicked (can be <tt>null</tt>).
538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560
     * @return the updated presence of the kicked user or null if the user was not in the room.
     * @throws NotAllowedException Thrown if trying to ban an owner or an administrator.
     */
    public Presence kickOccupant(JID fullJID, JID actorJID, String reason)
            throws NotAllowedException;

    public IQOwnerHandler getIQOwnerHandler();

    public IQAdminHandler getIQAdminHandler();

    /**
     * Returns the history of the room which includes chat transcripts.
     *
     * @return the history of the room which includes chat transcripts.
     */
    public MUCRoomHistory getRoomHistory();

    /**
     * Returns a collection with the current list of owners. The collection contains the bareJID of
     * the users with owner affiliation.
     *
     * @return a collection with the current list of owners.
     */
561
    public Collection<JID> getOwners();
562 563 564 565 566 567 568

    /**
     * Returns a collection with the current list of admins. The collection contains the bareJID of
     * the users with admin affiliation.
     *
     * @return a collection with the current list of admins.
     */
569
    public Collection<JID> getAdmins();
570 571 572 573 574 575 576 577 578

    /**
     * Returns a collection with the current list of room members. The collection contains the
     * bareJID of the users with member affiliation. If the room is not members-only then the list
     * will contain the users that registered with the room and therefore they may have reserved a
     * nickname.
     *
     * @return a collection with the current list of members.
     */
579
    public Collection<JID> getMembers();
580 581 582 583 584 585 586 587

    /**
     * Returns a collection with the current list of outcast users. An outcast user is not allowed
     * to join the room again. The collection contains the bareJID of the users with outcast
     * affiliation.
     *
     * @return a collection with the current list of outcast users.
     */
588
    public Collection<JID> getOutcasts();
589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952

    /**
     * Returns a collection with the current list of room moderators. The collection contains the
     * MUCRole of the occupants with moderator role.
     *
     * @return a collection with the current list of moderators.
     */
    public Collection<MUCRole> getModerators();

    /**
     * Returns a collection with the current list of room participants. The collection contains the
     * MUCRole of the occupants with participant role.
     *
     * @return a collection with the current list of moderators.
     */
    public Collection<MUCRole> getParticipants();

    /**
     * Returns true if every presence packet will include the JID of every occupant. This
     * configuration can be modified by the owner while editing the room's configuration.
     *
     * @return true if every presence packet will include the JID of every occupant.
     */
    public boolean canAnyoneDiscoverJID();

    /**
     * Sets if every presence packet will include the JID of every occupant. This
     * configuration can be modified by the owner while editing the room's configuration.
     *
     * @param canAnyoneDiscoverJID boolean that specifies if every presence packet will include the
     *        JID of every occupant.
     */
    public void setCanAnyoneDiscoverJID(boolean canAnyoneDiscoverJID);

    /**
     * Returns true if participants are allowed to change the room's subject.
     *
     * @return true if participants are allowed to change the room's subject.
     */
    public boolean canOccupantsChangeSubject();

    /**
     * Sets if participants are allowed to change the room's subject.
     *
     * @param canOccupantsChangeSubject boolean that specifies if participants are allowed to
     *        change the room's subject.
     */
    public void setCanOccupantsChangeSubject(boolean canOccupantsChangeSubject);

    /**
     * Returns true if occupants can invite other users to the room. If the room does not require an
     * invitation to enter (i.e. is not members-only) then any occupant can send invitations. On
     * the other hand, if the room is members-only and occupants cannot send invitation then only
     * the room owners and admins are allowed to send invitations.
     *
     * @return true if occupants can invite other users to the room.
     */
    public boolean canOccupantsInvite();

    /**
     * Sets if occupants can invite other users to the room. If the room does not require an
     * invitation to enter (i.e. is not members-only) then any occupant can send invitations. On
     * the other hand, if the room is members-only and occupants cannot send invitation then only
     * the room owners and admins are allowed to send invitations.
     *
     * @param canOccupantsInvite boolean that specified in any occupant can invite other users to
     *        the room.
     */
    public void setCanOccupantsInvite(boolean canOccupantsInvite);

    /**
     * Returns the natural language name of the room. This name can only be modified by room owners.
     * It's mainly used for users while discovering rooms hosted by the Multi-User Chat service.
     *
     * @return the natural language name of the room.
     */
    public String getNaturalLanguageName();

    /**
     * Sets the natural language name of the room. This name can only be modified by room owners.
     * It's mainly used for users while discovering rooms hosted by the Multi-User Chat service.
     *
     * @param naturalLanguageName the natural language name of the room.
     */
    public void setNaturalLanguageName(String naturalLanguageName);

    /**
     * Returns a description set by the room's owners about the room. This information will be used
     * when discovering extended information about the room.
     *
     * @return a description set by the room's owners about the room.
     */
    public String getDescription();

    /**
     * Sets a description set by the room's owners about the room. This information will be used
     * when discovering extended information about the room.
     *
     * @param description a description set by the room's owners about the room.
     */
    public void setDescription(String description);

    /**
     * Returns true if the room requires an invitation to enter. That is if the room is
     * members-only.
     *
     * @return true if the room requires an invitation to enter.
     */
    public boolean isMembersOnly();

    /**
     * Sets if the room requires an invitation to enter. That is if the room is members-only.
     *
     * @param membersOnly if true then the room is members-only.
     * @return the list of updated presences of all the occupants that aren't members of the room if
     *         the room is now members-only.
     */
    public List<Presence> setMembersOnly(boolean membersOnly);

    /**
     * Returns true if the room's conversation is being logged. If logging is activated the room
     * conversation will be saved to the database every couple of minutes. The saving frequency is
     * the same for all the rooms and can be configured by changing the property
     * "xmpp.muc.tasks.log.timeout" of MultiUserChatServerImpl.
     *
     * @return true if the room's conversation is being logged.
     */
    public boolean isLogEnabled();

    /**
     * Sets if the room's conversation is being logged. If logging is activated the room
     * conversation will be saved to the database every couple of minutes. The saving frequency is
     * the same for all the rooms and can be configured by changing the property
     * "xmpp.muc.tasks.log.timeout" of MultiUserChatServerImpl.
     *
     * @param logEnabled boolean that specified if the room's conversation must be logged.
     */
    public void setLogEnabled(boolean logEnabled);

    /**
     * Returns true if registered users can only join the room using their registered nickname. By
     * default, registered users can join the room using any nickname. A not_acceptable error
     * will be returned if the user tries to join the room with a nickname different than the
     * reserved nickname.
     *
     * @return true if registered users can only join the room using their registered nickname.
     */
    public boolean isLoginRestrictedToNickname();

    /**
     * Sets if registered users can only join the room using their registered nickname. A
     * not_acceptable error will be returned if the user tries to join the room with a nickname
     * different than the reserved nickname.
     *
     * @param restricted if registered users can only join the room using their registered nickname.
     */
    public void setLoginRestrictedToNickname(boolean restricted);

    /**
     * Returns true if room occupants are allowed to change their nicknames in the room. By
     * default, occupants are allowed to change their nicknames. A not_acceptable error will be
     * returned if an occupant tries to change his nickname and this feature is not enabled.<p>
     *
     * Notice that this feature is not supported by the MUC spec so answering a not_acceptable
     * error may break some cliens.
     *
     * @return true if room occupants are allowed to change their nicknames in the room.
     */
    public boolean canChangeNickname();

    /**
     * Sets if room occupants are allowed to change their nicknames in the room. By default,
     * occupants are allowed to change their nicknames. A not_acceptable error will be returned if
     * an occupant tries to change his nickname and this feature is not enabled.<p>
     *
     * Notice that this feature is not supported by the MUC spec so answering a not_acceptable
     * error may break some cliens. 
     *
     * @param canChange if room occupants are allowed to change their nicknames in the room.
     */
    public void setChangeNickname(boolean canChange);

    /**
     * Returns true if users are allowed to register with the room. By default, room registration
     * is enabled. A not_allowed error will be returned if a user tries to register with the room
     * and this feature is disabled.
     *
     * @return true if users are allowed to register with the room.
     */
    public boolean isRegistrationEnabled();

    /**
     * Sets if users are allowed to register with the room. By default, room registration
     * is enabled. A not_allowed error will be returned if a user tries to register with the room
     * and this feature is disabled.
     *
     * @param registrationEnabled if users are allowed to register with the room.
     */
    public void setRegistrationEnabled(boolean registrationEnabled);

    /**
     * Returns the maximum number of occupants that can be simultaneously in the room. If the number
     * is zero then there is no limit.
     *
     * @return the maximum number of occupants that can be simultaneously in the room. Zero means
     *         unlimited number of occupants.
     */
    public int getMaxUsers();

    /**
     * Sets the maximum number of occupants that can be simultaneously in the room. If the number
     * is zero then there is no limit.
     *
     * @param maxUsers the maximum number of occupants that can be simultaneously in the room. Zero
     *        means unlimited number of occupants.
     */
    public void setMaxUsers(int maxUsers);

    /**
     * Returns if the room in which only those with "voice" may send messages to all occupants.
     *
     * @return if the room in which only those with "voice" may send messages to all occupants.
     */
    public boolean isModerated();

    /**
     * Sets if the room in which only those with "voice" may send messages to all occupants.
     *
     * @param moderated if the room in which only those with "voice" may send messages to all
     *        occupants.
     */
    public void setModerated(boolean moderated);

    /**
     * Returns true if a user cannot enter without first providing the correct password.
     *
     * @return true if a user cannot enter without first providing the correct password.
     */
    public boolean isPasswordProtected();

    /**
     * Returns the password that the user must provide to enter the room.
     *
     * @return the password that the user must provide to enter the room.
     */
    public String getPassword();

    /**
     * Sets the password that the user must provide to enter the room.
     *
     * @param password the password that the user must provide to enter the room.
     */
    public void setPassword(String password);

    /**
     * Returns true if the room is not destroyed if the last occupant exits. Persistent rooms are
     * saved to the database to make their configurations persistent together with the affiliation
     * of the users.
     *
     * @return true if the room is not destroyed if the last occupant exits.
     */
    public boolean isPersistent();

    /**
     * Sets if the room is not destroyed if the last occupant exits. Persistent rooms are
     * saved to the database to make their configurations persistent together with the affiliation
     * of the users.
     *
     * @param persistent if the room is not destroyed if the last occupant exits.
     */
    public void setPersistent(boolean persistent);

    /**
     * Returns true if the room has already been made persistent. If the room is temporary the 
     * answer will always be false.
     * 
     * @return true if the room has already been made persistent.
     */
    public boolean wasSavedToDB();

    /**
     * Sets if the room has already been made persistent.
     * 
     * @param saved boolean that indicates if the room was saved to the database.
     */
    public void setSavedToDB(boolean saved);

    /**
     * Saves the room configuration to the DB. After the room has been saved to the DB it will
     * become persistent. 
     */
    public void saveToDB();

    /**
     * Returns true if the room is searchable and visible through service discovery. 
     * 
     * @return true if the room is searchable and visible through service discovery.
     */
    public boolean isPublicRoom();

    /**
     * Sets if the room is searchable and visible through service discovery.
     * 
     * @param publicRoom if the room is searchable and visible through service discovery.
     */
    public void setPublicRoom(boolean publicRoom);

    /**
     * Returns the list of roles of which presence will be broadcasted to the rest of the occupants.
     * This feature is useful for implementing "invisible" occupants.
     * 
     * @return the list of roles of which presence will be broadcasted to the rest of the occupants.
     */
    public List<String> getRolesToBroadcastPresence();

    /**
     * Sets the list of roles of which presence will be broadcasted to the rest of the occupants.
     * This feature is useful for implementing "invisible" occupants.
     * 
     * @param rolesToBroadcastPresence the list of roles of which presence will be broadcasted to 
     * the rest of the occupants.
     */
    public void setRolesToBroadcastPresence(List<String> rolesToBroadcastPresence);

    /**
     * Returns true if the presences of the requested role will be broadcasted.
     * 
     * @param roleToBroadcast the role to check if its presences will be broadcasted.
     * @return true if the presences of the requested role will be broadcasted.
     */
    public boolean canBroadcastPresence(String roleToBroadcast);

    /**
     * Locks the room so that users cannot join the room. Only the owner of the room can lock/unlock
     * the room.
     *
     * @param senderRole the role of the occupant that locked the room.
     * @throws ForbiddenException If the user is not an owner of the room.
     */
    public void lock(MUCRole senderRole) throws ForbiddenException;

    /**
     * Unlocks the room so that users can join the room. The room is locked when created and only
     * the owner of the room can unlock it by sending the configuration form to the Multi-User Chat
     * service.
     *
     * @param senderRole the role of the occupant that unlocked the room.
     * @throws ForbiddenException If the user is not an owner of the room.
     */
    public void unlock(MUCRole senderRole) throws ForbiddenException;

    /**
     * Sends an invitation to a user. The invitation will be sent as if the room is inviting the 
     * user. The invitation will include the original occupant the sent the invitation together with
     * the reason for the invitation if any. Since the invitee could be offline at the moment we 
     * need the originating session so that the offline strategy could potentially bounce the 
     * message with the invitation.
     * 
     * @param to the JID of the user that is being invited.
     * @param reason the reason of the invitation or null if none.
     * @param role the role of the occupant that sent the invitation.
     * @param extensions the list of extensions sent with the original message invitation or null 
     *        if none.
     * @throws ForbiddenException If the user is not allowed to send the invitation.
953
     * @throws CannotBeInvitedException (Optionally) If the user being invited does not have access to the room
954 955
     */
    public void sendInvitation(JID to, String reason, MUCRole role, List<Element> extensions)
956
            throws ForbiddenException, CannotBeInvitedException;
957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977

    /**
     * Sends the rejection to the inviter. The rejection will be sent as if the room is rejecting 
     * the invitation is named of the invitee. The rejection will include the address of the invitee
     * together with the reason for the rejection if any. Since the inviter could be offline at the 
     * moment we need the originating session so that the offline strategy could potentially bounce 
     * the message with the rejection.
     * 
     * @param to the JID of the user that is originated the invitation.
     * @param reason the reason for the rejection or null if none.
     * @param from the JID of the invitee that is rejecting the invitation.
     */
    public void sendInvitationRejection(JID to, String reason, JID from);

    /**
     * Sends a packet to the user.
     *
     * @param packet The packet to send
     */
    public void send(Packet packet);
}