MUCRoom.java 35.1 KB
Newer Older
Matt Tucker's avatar
Matt Tucker committed
1 2 3 4 5
/**
 * $RCSfile$
 * $Revision$
 * $Date$
 *
Matt Tucker's avatar
Matt Tucker committed
6
 * Copyright (C) 2004 Jive Software. All rights reserved.
Matt Tucker's avatar
Matt Tucker committed
7
 *
Matt Tucker's avatar
Matt Tucker committed
8 9
 * This software is published under the terms of the GNU Public License (GPL),
 * a copy of which is included in this distribution.
Matt Tucker's avatar
Matt Tucker committed
10 11 12 13 14
 */

package org.jivesoftware.messenger.muc;

import java.util.List;
15
import java.util.Date;
16
import java.util.Collection;
Matt Tucker's avatar
Matt Tucker committed
17

18
import org.dom4j.Element;
Matt Tucker's avatar
Matt Tucker committed
19 20 21
import org.jivesoftware.messenger.muc.spi.IQAdminHandler;
import org.jivesoftware.messenger.muc.spi.IQOwnerHandler;
import org.jivesoftware.util.NotFoundException;
Andrew Wright's avatar
Andrew Wright committed
22
import org.jivesoftware.util.JiveConstants;
Matt Tucker's avatar
Matt Tucker committed
23 24 25
import org.jivesoftware.messenger.auth.UnauthorizedException;
import org.jivesoftware.messenger.user.UserAlreadyExistsException;
import org.jivesoftware.messenger.user.UserNotFoundException;
Andrew Wright's avatar
Andrew Wright committed
26
import org.jivesoftware.database.JiveID;
27 28 29
import org.xmpp.packet.Presence;
import org.xmpp.packet.Message;
import org.xmpp.packet.JID;
Matt Tucker's avatar
Matt Tucker committed
30
import org.xmpp.packet.Packet;
Matt Tucker's avatar
Matt Tucker committed
31 32 33 34 35 36 37 38


/**
 * A chat room on the chat server manages its users, and
 * enforces it's own security rules.
 *
 * @author Gaston Dombiak
 */
Andrew Wright's avatar
Andrew Wright committed
39
@JiveID(JiveConstants.MUC_ROOM)
Matt Tucker's avatar
Matt Tucker committed
40
public interface MUCRoom {
Matt Tucker's avatar
Matt Tucker committed
41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66

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

    /**
     * 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. 
     * 
     * @param roomID the saved ID of the room in the DB or a new one if the room is being saved to 
     * the DB.
     */
    void setID(long roomID);

67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96
    /**
     * 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.
     *
     * @param creationDate the date when the room was created.
     */
    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.
     *
     * @param modificationDate the last date when the room's configuration was modified.
     */
    void setModificationDate(Date modificationDate);

Matt Tucker's avatar
Matt Tucker committed
97
    /**
98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115
     * Sets the date when the last occupant left the room. A null value means that there are
     * occupants in the room at the moment.
     *
     * @param emptyDate the date when the last occupant left the room or null if there are occupants
     *        in the room.
     */
    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();

    /**
Matt Tucker's avatar
Matt Tucker committed
116 117 118 119
     * Obtain the role of the chat server (mainly for addressing messages and presence).
     *
     * @return The role for the chat room itself
     */
120
    MUCRole getRole();
Matt Tucker's avatar
Matt Tucker committed
121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152

    /**
     * Obtain the role of a given user by nickname.
     *
     * @param nickname The nickname of the user you'd like to obtain
     * @return The user's role in the room
     * @throws UserNotFoundException If there is no user with the given nickname
     */
    MUCRole getOccupant(String nickname) throws UserNotFoundException;

    /**
     * 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. 
     *
     * @param jid The bare jid of the user you'd like to obtain
     * @return The user's roles in the room
     * @throws UserNotFoundException If there is no user with the given nickname
     */
    List<MUCRole> getOccupantsByBareJID(String jid) throws UserNotFoundException;

    /**
     * Obtain the role of a given user in the room by his full JID.
     *
     * @param jid The full jid of the user you'd like to obtain
     * @return The user's role in the room
     * @throws UserNotFoundException If there is no user with the given nickname
     */
    MUCRole getOccupantByFullJID(String jid) throws UserNotFoundException;

    /**
     * Obtain the roles of all users in the chatroom.
     *
153
     * @return a collection with all users in the chatroom
Matt Tucker's avatar
Matt Tucker committed
154
     */
155
    Collection<MUCRole> getOccupants();
Matt Tucker's avatar
Matt Tucker committed
156 157 158 159 160 161 162 163 164 165 166 167 168 169

    /**
     * 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.
     *
     * @param nickname The nickname of the user you'd like to obtain
     * @return True if a nickname is taken
     */
170
    boolean hasOccupant(String nickname);
Matt Tucker's avatar
Matt Tucker committed
171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188

    /**
     * Returns the reserved room nickname for the bare JID or null if none.
     * 
     * @param bareJID The bare jid of the user of which you'd like to obtain his reserved nickname.
     * @return the reserved room nickname for the bare JID or null if none.
     */
    String getReservedNickname(String bareJID);

    /**
     * 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.
     *  
     * @param bareJID The bare jid of the user of which you'd like to obtain his affiliation.
     * @return the affiliation state of the user in the room.
     */
Matt Tucker's avatar
Matt Tucker committed
189
    MUCRole.Affiliation getAffiliation(String bareJID);
Matt Tucker's avatar
Matt Tucker committed
190 191 192

    /**
     * Joins the room using the given nickname.
193 194 195
     *
     * @param nickname       The nickname the user wants to use in the chatroom.
     * @param password       The password provided by the user to enter the chatroom or null if none.
Matt Tucker's avatar
Matt Tucker committed
196
     * @param historyRequest The amount of history that the user request or null meaning default.
197 198
     * @param user           The user joining.
     * @param presence       The presence sent by the user to join the room.
Matt Tucker's avatar
Matt Tucker committed
199
     * @return The role created for the user.
200 201 202 203
     * @throws UnauthorizedException         If the user doesn't have permision to join the room.
     * @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.
Matt Tucker's avatar
Matt Tucker committed
204
     * @throws RegistrationRequiredException If the user is not a member of a members-only room.
205 206 207 208
     * @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.
Matt Tucker's avatar
Matt Tucker committed
209
     */
210 211 212
    MUCRole joinRoom(String nickname, String password, HistoryRequest historyRequest, MUCUser user,
            Presence presence) throws UnauthorizedException, UserAlreadyExistsException,
            RoomLockedException, ForbiddenException, RegistrationRequiredException,
213
            ConflictException, ServiceUnavailableException;
Matt Tucker's avatar
Matt Tucker committed
214 215 216 217 218 219 220

    /**
     * Remove a member from the chat room.
     *
     * @param nickname The user to remove
     * @throws UserNotFoundException If the nickname is not found.
     */
221
    void leaveRoom(String nickname) throws UserNotFoundException;
Matt Tucker's avatar
Matt Tucker committed
222 223 224 225 226 227 228 229 230

    /**
     * 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.
     * 
     * @param alternateJID the alternate JID. Commonly used to provide a replacement room.
     * @param reason the reason why the room was destroyed.
     */
231
    void destroyRoom(String alternateJID, String reason);
Matt Tucker's avatar
Matt Tucker committed
232 233 234 235 236 237 238

    /**
     * Create a new presence in this room for the given role.
     *
     * @return The new presence
     * @throws UnauthorizedException If the user doesn't have permission to leave the room
     */
239
    Presence createPresence(Presence.Type type) throws UnauthorizedException;
Matt Tucker's avatar
Matt Tucker committed
240 241 242 243 244 245 246

    /**
     * Broadcast a given message to all members of this chat room. The sender is always set to 
     * be the chatroom.
     *
     * @param msg The message to broadcast
     */
247
    void serverBroadcast(String msg);
Matt Tucker's avatar
Matt Tucker committed
248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268
    
    /**
     * 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
     * through {@link #addOwner(String,MUCRole)}.
     * 
     * @param bareJID The bare JID of the user to add as owner.
     */
    public void addFirstOwner(String bareJID);

    /**
     * Adds a new user to the list of owners.
     * 
     * @param bareJID The bare JID of the user to add as owner.
Gaston Dombiak's avatar
Gaston Dombiak committed
269
     * @param senderRole the role of the user that is trying to modify the owners list.
Matt Tucker's avatar
Matt Tucker committed
270 271 272 273
     * @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.
     */
274
    public List<Presence> addOwner(String bareJID, MUCRole senderRole) throws ForbiddenException;
Gaston Dombiak's avatar
Gaston Dombiak committed
275 276 277 278 279 280 281 282 283 284

    /**
     * Adds a list of users to the list of owners.
     *
     * @param newOwners the list of bare JIDs of the users to add to the list of existing owners.
     * @param senderRole the role of the user that is trying to modify the owners list.
     * @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.
     */
285 286
    public List<Presence> addOwners(List<String> newOwners, MUCRole senderRole)
            throws ForbiddenException;
Gaston Dombiak's avatar
Gaston Dombiak committed
287 288 289 290 291 292 293 294 295 296 297

    /**
     * Adds a list of users to the list of admins.
     *
     * @param newAdmins the list of bare JIDs of the users to add to the list of existing admins.
     * @param senderRole the role of the user that is trying to modify the admins list.
     * @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.
     */
298 299
    public List<Presence> addAdmins(List<String> newAdmins, MUCRole senderRole)
            throws ForbiddenException, ConflictException;
Matt Tucker's avatar
Matt Tucker committed
300 301 302 303 304

    /**
     * Adds a new user to the list of admins.
     * 
     * @param bareJID The bare JID of the user to add as admin.
Gaston Dombiak's avatar
Gaston Dombiak committed
305
     * @param senderRole The role of the user that is trying to modify the admins list.
Matt Tucker's avatar
Matt Tucker committed
306 307 308 309 310
     * @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.
     */
311
    public List<Presence> addAdmin(String bareJID, MUCRole senderRole) throws ForbiddenException,
Matt Tucker's avatar
Matt Tucker committed
312 313 314 315 316 317 318
            ConflictException;

    /**
     * Adds a new user to the list of members.
     * 
     * @param bareJID The bare JID of the user to add as a member.
     * @param nickname The reserved nickname of the member for the room or null if none.
Gaston Dombiak's avatar
Gaston Dombiak committed
319
     * @param senderRole the role of the user that is trying to modify the members list.
Matt Tucker's avatar
Matt Tucker committed
320 321 322 323 324 325
     * @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.
     */
326
    public List<Presence> addMember(String bareJID, String nickname, MUCRole senderRole)
Matt Tucker's avatar
Matt Tucker committed
327 328 329 330 331 332 333
            throws ForbiddenException, ConflictException;

    /**
     * Adds a new user to the list of outcast users.
     * 
     * @param bareJID The bare JID of the user to add as an outcast.
     * @param reason The reason why the user was banned.
Gaston Dombiak's avatar
Gaston Dombiak committed
334
     * @param senderRole The role of the user that initiated the ban.
Matt Tucker's avatar
Matt Tucker committed
335 336 337 338 339 340
     * @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.
     */
341
    public List<Presence> addOutcast(String bareJID, String reason, MUCRole senderRole)
Matt Tucker's avatar
Matt Tucker committed
342 343 344 345 346 347
            throws NotAllowedException, ForbiddenException, ConflictException;

    /**
     * Removes the user from all the other affiliation list thus giving the user a NONE affiliation.
     * 
     * @param bareJID The bare JID of the user to keep with a NONE affiliation.
Gaston Dombiak's avatar
Gaston Dombiak committed
348
     * @param senderRole The role of the user that set the affiliation to none.
Matt Tucker's avatar
Matt Tucker committed
349 350 351 352 353
     * @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.
     */
354
    public List<Presence> addNone(String bareJID, MUCRole senderRole) throws ForbiddenException,
Matt Tucker's avatar
Matt Tucker committed
355 356
            ConflictException;

Gaston Dombiak's avatar
Gaston Dombiak committed
357 358 359 360 361 362 363 364 365 366
    /**
     * 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.
     *
     * @param fullJID The full JID of the occupant to give moderator privileges.
     * @param senderRole The role of the user that is granting moderator privileges to an occupant.
     * @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.
     */
367
    public Presence addModerator(JID fullJID, MUCRole senderRole) throws ForbiddenException;
Gaston Dombiak's avatar
Gaston Dombiak committed
368 369 370 371 372 373 374 375 376 377 378 379 380 381

    /**
     * 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.
     *
     * @param fullJID The full JID of the occupant to give participant privileges.
     * @param reason The reason why participant privileges were gave to the user or <tt>null</tt>
     *        if none.
     * @param senderRole The role of the user that is granting participant privileges to an occupant.
     * @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.
     */
382
    public Presence addParticipant(JID fullJID, String reason, MUCRole senderRole)
Gaston Dombiak's avatar
Gaston Dombiak committed
383 384 385 386 387 388 389
            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.
     *
390 391
     * @param jid the full JID of the occupant to change to visitor.
     * @param senderRole the role of the user that is changing the role to visitor.
Gaston Dombiak's avatar
Gaston Dombiak committed
392 393
     * @return the updated presence of the occupant or <tt>null</tt> if the JID does not belong to
     *         an existing occupant.
394 395
     * @throws NotAllowedException if trying to change the moderator role to an owner or an admin.
     * @throws ForbiddenException if the user is not a moderator.
Gaston Dombiak's avatar
Gaston Dombiak committed
396
     */
397
    public Presence addVisitor(JID jid, MUCRole senderRole) throws NotAllowedException,
Gaston Dombiak's avatar
Gaston Dombiak committed
398 399
            ForbiddenException;

Matt Tucker's avatar
Matt Tucker committed
400 401 402 403 404 405 406 407 408
    /**
     * 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();

409 410 411 412 413 414 415 416 417
    /**
     * 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();

Matt Tucker's avatar
Matt Tucker committed
418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436
    /**
     * An event callback fired whenever an occupant changes his nickname within the chatroom.
     *  
     * @param oldNick old nickname within the room.
     * @param newNick new nickname within the room.
     */
    public void nicknameChanged(String oldNick, String newNick);
    
    /**
     * 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.
     *  
     * @param packet the sent packet to change the room's subject.
     * @param role the role of the user that is trying to change the subject.
     * @throws ForbiddenException If the user is not allowed to change the subject.
     */
437
    public void changeSubject(Message packet, MUCRole role) throws ForbiddenException;
Matt Tucker's avatar
Matt Tucker committed
438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463

    /**
     * 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. 
     * 
     * @param subject the last known subject of the room.
     */
    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.
     * 
     * @param message The message to send.
     * @param senderRole the role of the user that is trying to send a public message.
     * @throws ForbiddenException If the user is not allowed to send a public message (i.e. does not
     *             have voice in the room).
     */
464
    public void sendPublicMessage(Message message, MUCRole senderRole) throws ForbiddenException;
Matt Tucker's avatar
Matt Tucker committed
465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484

    /**
     * Sends a private message to a selected occupant. 
     * 
     * @param message The message 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 message to a room JID that does not exist.
     */
    public void sendPrivateMessage(Message message, 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. 
     * 
     * @param fullJID The full JID of the kicked user.
     * @param actorJID The JID of the actor that initiated the kick.
     * @param reason The reason why the user was kicked.
     * @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.
     */
485
    public Presence kickOccupant(JID fullJID, JID actorJID, String reason)
Matt Tucker's avatar
Matt Tucker committed
486 487 488 489 490 491
            throws NotAllowedException;

    public IQOwnerHandler getIQOwnerHandler();

    public IQAdminHandler getIQAdminHandler();

492 493 494 495 496 497 498
    /**
     * Returns the history of the room which includes chat transcripts.
     *
     * @return the history of the room which includes chat transcripts.
     */
    public MUCRoomHistory getRoomHistory();

Gaston Dombiak's avatar
Gaston Dombiak committed
499
    /**
500 501
     * Returns a collection with the current list of owners. The collection contains the bareJID of
     * the users with owner affiliation.
Gaston Dombiak's avatar
Gaston Dombiak committed
502
     *
503
     * @return a collection with the current list of owners.
Gaston Dombiak's avatar
Gaston Dombiak committed
504
     */
505
    public Collection<String> getOwners();
Matt Tucker's avatar
Matt Tucker committed
506

Gaston Dombiak's avatar
Gaston Dombiak committed
507
    /**
508 509
     * Returns a collection with the current list of admins. The collection contains the bareJID of
     * the users with admin affiliation.
Gaston Dombiak's avatar
Gaston Dombiak committed
510
     *
511
     * @return a collection with the current list of admins.
Gaston Dombiak's avatar
Gaston Dombiak committed
512
     */
513
    public Collection<String> getAdmins();
Matt Tucker's avatar
Matt Tucker committed
514

Gaston Dombiak's avatar
Gaston Dombiak committed
515
    /**
516 517 518
     * 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
Gaston Dombiak's avatar
Gaston Dombiak committed
519 520
     * nickname.
     *
521
     * @return a collection with the current list of members.
Gaston Dombiak's avatar
Gaston Dombiak committed
522
     */
523
    public Collection<String> getMembers();
Matt Tucker's avatar
Matt Tucker committed
524

Gaston Dombiak's avatar
Gaston Dombiak committed
525
    /**
526 527 528
     * 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.
Gaston Dombiak's avatar
Gaston Dombiak committed
529
     *
530
     * @return a collection with the current list of outcast users.
Gaston Dombiak's avatar
Gaston Dombiak committed
531
     */
532
    public Collection<String> getOutcasts();
Matt Tucker's avatar
Matt Tucker committed
533

Gaston Dombiak's avatar
Gaston Dombiak committed
534
    /**
535
     * Returns a collection with the current list of room moderators. The collection contains the
Gaston Dombiak's avatar
Gaston Dombiak committed
536 537
     * MUCRole of the occupants with moderator role.
     *
538
     * @return a collection with the current list of moderators.
Gaston Dombiak's avatar
Gaston Dombiak committed
539
     */
540
    public Collection<MUCRole> getModerators();
Matt Tucker's avatar
Matt Tucker committed
541

Gaston Dombiak's avatar
Gaston Dombiak committed
542
    /**
543
     * Returns a collection with the current list of room participants. The collection contains the
Gaston Dombiak's avatar
Gaston Dombiak committed
544 545
     * MUCRole of the occupants with participant role.
     *
546
     * @return a collection with the current list of moderators.
Gaston Dombiak's avatar
Gaston Dombiak committed
547
     */
548
    public Collection<MUCRole> getParticipants();
Matt Tucker's avatar
Matt Tucker committed
549

Gaston Dombiak's avatar
Gaston Dombiak committed
550 551 552 553 554 555
    /**
     * 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.
     */
Matt Tucker's avatar
Matt Tucker committed
556 557
    public boolean canAnyoneDiscoverJID();

Gaston Dombiak's avatar
Gaston Dombiak committed
558 559 560 561 562 563 564
    /**
     * 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.
     */
Matt Tucker's avatar
Matt Tucker committed
565 566
    public void setCanAnyoneDiscoverJID(boolean canAnyoneDiscoverJID);

Gaston Dombiak's avatar
Gaston Dombiak committed
567 568 569 570 571
    /**
     * Returns true if participants are allowed to change the room's subject.
     *
     * @return true if participants are allowed to change the room's subject.
     */
Matt Tucker's avatar
Matt Tucker committed
572 573
    public boolean canOccupantsChangeSubject();

Gaston Dombiak's avatar
Gaston Dombiak committed
574 575 576 577 578 579
    /**
     * 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.
     */
Matt Tucker's avatar
Matt Tucker committed
580 581
    public void setCanOccupantsChangeSubject(boolean canOccupantsChangeSubject);

Gaston Dombiak's avatar
Gaston Dombiak committed
582 583 584 585 586 587 588 589
    /**
     * 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.
     */
Matt Tucker's avatar
Matt Tucker committed
590 591
    public boolean canOccupantsInvite();

Gaston Dombiak's avatar
Gaston Dombiak committed
592 593 594 595 596 597 598 599 600
    /**
     * 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.
     */
Matt Tucker's avatar
Matt Tucker committed
601 602
    public void setCanOccupantsInvite(boolean canOccupantsInvite);

Gaston Dombiak's avatar
Gaston Dombiak committed
603 604 605 606 607 608
    /**
     * 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.
     */
609 610
    public String getNaturalLanguageName();

Gaston Dombiak's avatar
Gaston Dombiak committed
611 612 613 614 615 616
    /**
     * 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.
     */
617 618
    public void setNaturalLanguageName(String naturalLanguageName);

Gaston Dombiak's avatar
Gaston Dombiak committed
619 620 621 622 623 624
    /**
     * 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.
     */
Matt Tucker's avatar
Matt Tucker committed
625 626
    public String getDescription();

Gaston Dombiak's avatar
Gaston Dombiak committed
627 628 629 630 631 632
    /**
     * 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.
     */
Matt Tucker's avatar
Matt Tucker committed
633 634
    public void setDescription(String description);

Gaston Dombiak's avatar
Gaston Dombiak committed
635
    /**
636 637
     * Returns true if the room requires an invitation to enter. That is if the room is
     * members-only.
Gaston Dombiak's avatar
Gaston Dombiak committed
638 639 640
     *
     * @return true if the room requires an invitation to enter.
     */
641
    public boolean isMembersOnly();
Matt Tucker's avatar
Matt Tucker committed
642

Gaston Dombiak's avatar
Gaston Dombiak committed
643
    /**
644
     * Sets if the room requires an invitation to enter. That is if the room is members-only.
Gaston Dombiak's avatar
Gaston Dombiak committed
645
     *
646
     * @param membersOnly if true then the room is members-only.
647 648
     * @return the list of updated presences of all the occupants that aren't members of the room if
     *         the room is now members-only.
Gaston Dombiak's avatar
Gaston Dombiak committed
649
     */
650
    public List<Presence> setMembersOnly(boolean membersOnly);
Matt Tucker's avatar
Matt Tucker committed
651

Gaston Dombiak's avatar
Gaston Dombiak committed
652 653 654 655 656 657 658 659
    /**
     * 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.
     */
Matt Tucker's avatar
Matt Tucker committed
660 661
    public boolean isLogEnabled();

Gaston Dombiak's avatar
Gaston Dombiak committed
662 663 664 665 666 667 668 669
    /**
     * 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.
     */
Matt Tucker's avatar
Matt Tucker committed
670 671
    public void setLogEnabled(boolean logEnabled);

Gaston Dombiak's avatar
Gaston Dombiak committed
672 673 674 675 676 677 678
    /**
     * 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.
     */
Matt Tucker's avatar
Matt Tucker committed
679 680
    public int getMaxUsers();

Gaston Dombiak's avatar
Gaston Dombiak committed
681 682 683 684 685 686 687
    /**
     * 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.
     */
Matt Tucker's avatar
Matt Tucker committed
688 689
    public void setMaxUsers(int maxUsers);

Gaston Dombiak's avatar
Gaston Dombiak committed
690 691 692 693 694
    /**
     * 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.
     */
Matt Tucker's avatar
Matt Tucker committed
695 696
    public boolean isModerated();

Gaston Dombiak's avatar
Gaston Dombiak committed
697 698 699 700 701 702
    /**
     * 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.
     */
Matt Tucker's avatar
Matt Tucker committed
703 704
    public void setModerated(boolean moderated);

Gaston Dombiak's avatar
Gaston Dombiak committed
705 706 707 708 709 710 711 712 713 714 715 716
    /**
     * 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.
     */
Matt Tucker's avatar
Matt Tucker committed
717 718
    public String getPassword();

Gaston Dombiak's avatar
Gaston Dombiak committed
719 720 721 722 723
    /**
     * 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.
     */
Matt Tucker's avatar
Matt Tucker committed
724 725
    public void setPassword(String password);

Gaston Dombiak's avatar
Gaston Dombiak committed
726 727 728 729 730 731 732
    /**
     * 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.
     */
Matt Tucker's avatar
Matt Tucker committed
733 734
    public boolean isPersistent();

Gaston Dombiak's avatar
Gaston Dombiak committed
735 736 737 738 739 740 741
    /**
     * 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.
     */
Matt Tucker's avatar
Matt Tucker committed
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
    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.
     */
785
    public List<String> getRolesToBroadcastPresence();
Matt Tucker's avatar
Matt Tucker committed
786 787 788 789 790 791 792 793

    /**
     * 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.
     */
794
    public void setRolesToBroadcastPresence(List<String> rolesToBroadcastPresence);
Matt Tucker's avatar
Matt Tucker committed
795 796 797 798 799 800 801 802 803

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

804 805 806 807 808 809 810 811 812
    /**
     * 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;

Matt Tucker's avatar
Matt Tucker committed
813 814 815 816
    /**
     * 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.
817
     *
Gaston Dombiak's avatar
Gaston Dombiak committed
818
     * @param senderRole the role of the occupant that unlocked the room.
819
     * @throws ForbiddenException If the user is not an owner of the room.
Matt Tucker's avatar
Matt Tucker committed
820
     */
821
    public void unlock(MUCRole senderRole) throws ForbiddenException;
Matt Tucker's avatar
Matt Tucker committed
822 823 824 825 826 827 828 829

    /**
     * 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.
     * 
830
     * @param to the JID of the user that is being invited.
Matt Tucker's avatar
Matt Tucker committed
831 832
     * @param reason the reason of the invitation or null if none.
     * @param role the role of the occupant that sent the invitation.
833 834
     * @param extensions the list of extensions sent with the original message invitation or null 
     *        if none.
Matt Tucker's avatar
Matt Tucker committed
835 836
     * @throws ForbiddenException If the user is not allowed to send the invitation.
     */
837
    public void sendInvitation(JID to, String reason, MUCRole role, List<Element> extensions)
Matt Tucker's avatar
Matt Tucker committed
838 839 840 841 842 843 844 845 846
            throws ForbiddenException;

    /**
     * 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.
     * 
847
     * @param to the JID of the user that is originated the invitation.
Matt Tucker's avatar
Matt Tucker committed
848
     * @param reason the reason for the rejection or null if none.
849
     * @param from the JID of the invitee that is rejecting the invitation.
Matt Tucker's avatar
Matt Tucker committed
850
     */
851
    public void sendInvitationRejection(JID to, String reason, JID from);
Matt Tucker's avatar
Matt Tucker committed
852 853 854 855 856 857 858

    /**
     * Sends a packet to the user.
     *
     * @param packet The packet to send
     */
    public void send(Packet packet);
Matt Tucker's avatar
Matt Tucker committed
859
}