MUCRoom.java 43.7 KB
Newer Older
1
/**
2
 * Copyright (C) 2004-2008 Jive Software. All rights reserved.
3
 *
4 5 6 7 8 9 10 11 12 13 14
 * 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.
15 16
 */

17
package org.jivesoftware.openfire.muc;
18 19

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

import java.io.Externalizable;
import java.util.Collection;
import java.util.Date;
import java.util.List;
40 41 42 43 44 45 46 47 48


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

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

58 59 60 61 62 63 64
    /**
     * Get the full JID of this room.
     *
     * @return the JID for this room.
     */
    JID getJID();

65 66 67 68 69 70 71 72 73 74 75 76 77
    /**
     * 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. 
     * 
78
     * @param roomID the saved ID of the room in the DB or a new one if the room is being saved to the DB.
79 80 81
     */
    void setID(long roomID);

82 83 84 85 86 87 88 89 90 91
    /**
     * 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.
     *
92
     * @param service The MultiUserChatService that the room is attached to (cannot be <tt>null</tt>).
93 94 95
     */
    void setMUCService(MultiUserChatService service);

96 97 98 99 100 101 102 103 104 105
    /**
     * 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.
     *
106
     * @param creationDate the date when the room was created (cannot be <tt>null</tt>).
107 108 109 110 111 112 113 114 115 116 117 118 119 120 121
     */
    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.
     *
122
     * @param modificationDate the last date when the room's configuration was modified (cannot be <tt>null</tt>).
123 124 125 126 127 128 129
     */
    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.
     *
130
     * @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>).
131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150
     */
    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();

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

160 161 162 163 164 165 166 167 168
    /**
     * 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;

169 170 171 172
    /**
     * 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. 
     *
173
     * @param jid The bare jid of the user you'd like to obtain  (cannot be <tt>null</tt>).
174 175 176
     * @return The user's roles in the room
     * @throws UserNotFoundException If there is no user with the given nickname
     */
177
    List<MUCRole> getOccupantsByBareJID(JID jid) throws UserNotFoundException;
178 179

    /**
180 181
     * 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.
182
     *
183
     * @param jid The full jid of the user you'd like to obtain  (cannot be <tt>null</tt>).
184
     * @return The user's role in the room or null if not found.
185
     */
186
    MUCRole getOccupantByFullJID(JID jid);
187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204

    /**
     * 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.
     *
205
     * @param nickname The nickname of the user you'd like to obtain  (cannot be <tt>null</tt>).
206 207 208 209 210 211 212
     * @return True if a nickname is taken
     */
    boolean hasOccupant(String nickname);

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

    /**
     * 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.
     *  
224
     * @param bareJID The bare jid of the user of which you'd like to obtain his affiliation (cannot be <tt>null</tt>).
225 226
     * @return the affiliation state of the user in the room.
     */
227
    MUCRole.Affiliation getAffiliation(JID bareJID);
228 229 230 231

    /**
     * Joins the room using the given nickname.
     *
232
     * @param nickname       The nickname the user wants to use in the chatroom  (cannot be <tt>null</tt>).
233 234
     * @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.
235 236
     * @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>).
237
     * @return The role created for the user.
238
     * @throws UnauthorizedException         If the user doesn't have permission to join the room.
239 240 241 242 243 244 245 246 247 248 249
     * @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.
     */
250
    LocalMUCRole joinRoom(String nickname, String password, HistoryRequest historyRequest, LocalMUCUser user,
251 252 253 254 255 256 257
            Presence presence) throws UnauthorizedException, UserAlreadyExistsException,
            RoomLockedException, ForbiddenException, RegistrationRequiredException,
            ConflictException, ServiceUnavailableException, NotAcceptableException;

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

    /**
     * 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.
     * 
267 268
     * @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>).
269
     */
270
    void destroyRoom(JID alternateJID, String reason);
271 272 273 274

    /**
     * Create a new presence in this room for the given role.
     *
275
     * @param type Type of presence to create (cannot be <tt>null</tt>).
276 277 278 279 280 281 282 283 284
     * @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.
     *
285
     * @param msg The message to broadcast (cannot be <tt>null</tt>)
286 287 288 289 290 291 292 293 294 295 296 297 298
     */
    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
299
     * through {@link #addOwner(JID jid,MUCRole)}.
300
     * 
301
     * @param bareJID The bare JID of the user to add as owner (cannot be <tt>null</tt>).
302
     */
303
    public void addFirstOwner(JID bareJID);
304

305 306 307
    /**
     * Adds a new user to the list of owners.
     * 
308 309
     * @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>).
310 311 312 313 314 315
     * @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;

316 317 318
    /**
     * Adds a list of users to the list of owners.
     *
319 320
     * @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>).
321 322 323 324
     * @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.
     */
325
    public List<Presence> addOwners(List<JID> newOwners, MUCRole senderRole)
326 327 328 329 330
            throws ForbiddenException;

    /**
     * Adds a list of users to the list of admins.
     *
331 332
     * @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>).
333 334 335 336 337
     * @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.
     */
338
    public List<Presence> addAdmins(List<JID> newAdmins, MUCRole senderRole)
339 340
            throws ForbiddenException, ConflictException;

341 342 343
    /**
     * Adds a new user to the list of admins.
     * 
344 345
     * @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>).
346 347 348 349 350 351 352
     * @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;
353

354 355 356
    /**
     * Adds a new user to the list of members.
     * 
357
     * @param jid The JID of the user to add as a member (cannot be <tt>null</tt>).
358
     * @param nickname The reserved nickname of the member for the room or null if none.
359
     * @param senderRole the role of the user that is trying to modify the members list (cannot be <tt>null</tt>).
360 361 362 363 364 365 366 367 368 369 370 371
     * @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.
     * 
372 373 374
     * @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>).
375 376 377 378 379 380 381 382 383 384 385 386
     * @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.
     * 
387 388
     * @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>).
389 390 391 392 393 394 395 396
     * @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;

397 398 399 400
    /**
     * 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.
     *
401 402
     * @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>).
403 404 405 406 407 408 409 410 411 412
     * @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.
     *
413
     * @param fullJID The full JID of the occupant to give participant privileges (cannot be <tt>null</tt>).
414 415
     * @param reason The reason why participant privileges were gave to the user or <tt>null</tt>
     *        if none.
416
     * @param senderRole The role of the user that is granting participant privileges to an occupant (cannot be <tt>null</tt>).
417 418 419 420 421 422 423 424 425 426 427 428 429
     * @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.
     *
430 431
     * @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>).
432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457
     * @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();

458 459 460
    /**
     * An event callback fired whenever an occupant updated his presence in the chatroom.
     *
461 462
     * @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>).
463 464 465
     */
    public void presenceUpdated(MUCRole occupantRole, Presence newPresence);

466 467
    /**
     * An event callback fired whenever an occupant changes his nickname within the chatroom.
468
     *
469 470 471 472
     * @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>).
473
     */
474
    public void nicknameChanged(MUCRole occupantRole, Presence newPresence, String oldNick, String newNick);
475 476 477 478 479 480 481 482
    
    /**
     * 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.
     *  
483 484
     * @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>).
485 486 487 488 489 490 491 492 493 494 495 496 497 498 499
     * @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. 
     * 
500
     * @param subject the last known subject of the room (cannot be <tt>null</tt>).
501 502 503 504 505 506 507 508
     */
    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.
     * 
509 510
     * @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>).
511 512 513 514 515 516 517 518 519 520 521 522 523
     * @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.
524
     * @throws ForbiddenException If a user of this role is not permitted to send private messages in this room.
525
     */
526
    public void sendPrivatePacket(Packet packet, MUCRole senderRole) throws NotFoundException, ForbiddenException;
527 528 529

    /**
     * Kicks a user from the room. If the user was in the room, the returned updated presence will
530 531 532 533 534 535
     * be sent to the remaining occupants.
     *
     * @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 actorNickname The actor nickname.
     * @param reason        An optional reason why the user was kicked (can be <tt>null</tt>).
536 537 538
     * @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.
     */
539
    public Presence kickOccupant(JID fullJID, JID actorJID, String actorNickname, String reason)
540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558
            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.
     */
559
    public Collection<JID> getOwners();
560 561 562 563 564 565 566

    /**
     * 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.
     */
567
    public Collection<JID> getAdmins();
568 569 570 571 572 573 574 575 576

    /**
     * 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.
     */
577
    public Collection<JID> getMembers();
578 579 580 581 582 583 584 585

    /**
     * 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.
     */
586
    public Collection<JID> getOutcasts();
587 588 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

    /**
     * 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);

621 622 623 624 625 626 627 628 629 630 631 632
    /**
     * Returns the minimal role of persons that are allowed to send private messages in the room. The returned value is
     * any one of: "anyone", "moderators", "participants", "none".
     *
     * @return The minimal role of persons that are allowed to send private messages in the room (never null).
     */
    public String canSendPrivateMessage();

    /**
     * Sets the minimal role of persons that are allowed to send private messages in the room. The provided value is
     * any one of: "anyone", "moderators", "participants", "none". If another value is set, "anyone" is used instead.
     *
633
     * @param role The minimal role of persons that are allowed to send private messages in the room (never null).
634 635 636
     */
    public void setCanSendPrivateMessage(String role);

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 953 954 955 956 957 958 959 960 961 962 963 964 965 966
    /**
     * 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.
967
     * @throws CannotBeInvitedException (Optionally) If the user being invited does not have access to the room
968 969
     */
    public void sendInvitation(JID to, String reason, MUCRole role, List<Element> extensions)
970
            throws ForbiddenException, CannotBeInvitedException;
971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990

    /**
     * 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);
991
}