org.jivesoftware.openfire.muc.MUCRoom Maven / Gradle / Ivy
/*
* Copyright (C) 2004-2008 Jive Software. All rights reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.jivesoftware.openfire.muc;
import org.dom4j.Element;
import org.jivesoftware.database.JiveID;
import org.jivesoftware.openfire.auth.UnauthorizedException;
import org.jivesoftware.openfire.muc.spi.IQAdminHandler;
import org.jivesoftware.openfire.muc.spi.IQOwnerHandler;
import org.jivesoftware.openfire.muc.spi.LocalMUCRole;
import org.jivesoftware.openfire.muc.spi.LocalMUCUser;
import org.jivesoftware.openfire.user.UserAlreadyExistsException;
import org.jivesoftware.openfire.user.UserNotFoundException;
import org.jivesoftware.util.JiveConstants;
import org.jivesoftware.util.NotFoundException;
import org.xmpp.packet.JID;
import org.xmpp.packet.Message;
import org.xmpp.packet.Packet;
import org.xmpp.packet.Presence;
import org.xmpp.resultsetmanagement.Result;
import java.io.Externalizable;
import java.util.Collection;
import java.util.Date;
import java.util.List;
/**
* A chat room on the chat server manages its users, and
* enforces it's own security rules.
*
* @author Gaston Dombiak
*/
@JiveID(JiveConstants.MUC_ROOM)
public interface MUCRoom extends Externalizable, Result {
/**
* Get the name of this room.
*
* @return The name for this room
*/
String getName();
/**
* Get the full JID of this room.
*
* @return the JID for this room.
*/
JID getJID();
/**
* 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);
/**
* 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.
*
* @param service The MultiUserChatService that the room is attached to (cannot be null).
*/
void setMUCService(MultiUserChatService service);
/**
* 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 (cannot be null).
*/
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 (cannot be null).
*/
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.
*
* @param emptyDate the date when the last occupant left the room or null if there are occupants in the room (can be null).
*/
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();
/**
* Obtain the first role of a given user by nickname.
*
* @param nickname The nickname of the user you'd like to obtain (cannot be null)
* @return The user's role in the room
* @throws UserNotFoundException If there is no user with the given nickname
* @deprecated Prefer {@link #getOccupantsByNickname(String)} instead (a user may be connected more than once)
*/
MUCRole getOccupant(String nickname) throws UserNotFoundException;
/**
* 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 null)
* @return The user's role in the room
* @throws UserNotFoundException If there is no user with the given nickname
*/
List getOccupantsByNickname(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 (cannot be null).
* @return The user's roles in the room
* @throws UserNotFoundException If there is no user with the given nickname
*/
List getOccupantsByBareJID(JID jid) throws UserNotFoundException;
/**
* Returns the role of a given user in the room by his full JID or null
* if no role was found for the specified user.
*
* @param jid The full jid of the user you'd like to obtain (cannot be null).
* @return The user's role in the room or null if not found.
*/
MUCRole getOccupantByFullJID(JID jid);
/**
* Obtain the roles of all users in the chatroom.
*
* @return a collection with all users in the chatroom
*/
Collection 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.
*
* @param nickname The nickname of the user you'd like to obtain (cannot be null).
* @return True if a nickname is taken
*/
boolean hasOccupant(String nickname);
/**
* Returns the reserved room nickname for the bare JID or null if none.
*
* @param jid The bare jid of the user of which you'd like to obtain his reserved nickname (cannot be null).
* @return the reserved room nickname for the bare JID or null if none.
*/
String getReservedNickname(JID jid);
/**
* Returns the affiliation state of the user in the room. Possible affiliations are
* MUCRole.OWNER, MUCRole.ADMINISTRATOR, MUCRole.MEMBER, MUCRole.OUTCAST and MUCRole.NONE.
*
* 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 (cannot be null).
* @return the affiliation state of the user in the room.
*/
MUCRole.Affiliation getAffiliation(JID bareJID);
/**
* Joins the room using the given nickname.
*
* @param nickname The nickname the user wants to use in the chatroom (cannot be null).
* @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.
* @param user The user joining (cannot be null).
* @param presence The presence sent by the user to join the room (cannot be null).
* @return The role created for the user.
* @throws UnauthorizedException If the user doesn't have permission 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.
* @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.
*/
LocalMUCRole joinRoom(String nickname, String password, HistoryRequest historyRequest, LocalMUCUser user,
Presence presence) throws UnauthorizedException, UserAlreadyExistsException,
RoomLockedException, ForbiddenException, RegistrationRequiredException,
ConflictException, ServiceUnavailableException, NotAcceptableException;
/**
* Remove a member from the chat room.
*
* @param leaveRole room occupant that left the room (cannot be null).
*/
void leaveRoom(MUCRole leaveRole);
/**
* 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 an optional alternate JID. Commonly used to provide a replacement room. (can be null)
* @param reason an optional reason why the room was destroyed (can be null).
*/
void destroyRoom(JID alternateJID, String reason);
/**
* Create a new presence in this room for the given role.
*
* @param type Type of presence to create (cannot be null).
* @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.
*
* @param msg The message to broadcast (cannot be null)
*/
void serverBroadcast(String msg);
/**
* Returns the total length of the chat session.
*
* @return length of chat session in milliseconds.
*/
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(JID jid,MUCRole)}.
*
* @param bareJID The bare JID of the user to add as owner (cannot be null).
*/
void addFirstOwner( JID bareJID );
/**
* Adds a new user to the list of owners.
*
* @param jid The JID of the user to add as owner (cannot be null).
* @param senderRole the role of the user that is trying to modify the owners list (cannot be null).
* @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.
*/
List addOwner( JID jid, MUCRole senderRole ) throws ForbiddenException;
/**
* 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 (cannot be null).
* @param senderRole the role of the user that is trying to modify the owners list (cannot be null).
* @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.
*/
List addOwners( List newOwners, MUCRole senderRole )
throws ForbiddenException;
/**
* 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 (cannot be null).
* @param senderRole the role of the user that is trying to modify the admins list (cannot be null).
* @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.
*/
List addAdmins( List newAdmins, MUCRole senderRole )
throws ForbiddenException, ConflictException;
/**
* Adds a new user to the list of admins.
*
* @param jid The JID of the user to add as admin (cannot be null).
* @param senderRole The role of the user that is trying to modify the admins list (cannot be null).
* @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.
*/
List addAdmin( JID jid, MUCRole senderRole ) throws ForbiddenException,
ConflictException;
/**
* Adds a new user to the list of members.
*
* @param jid The JID of the user to add as a member (cannot be null).
* @param nickname The reserved nickname of the member for the room or null if none.
* @param senderRole the role of the user that is trying to modify the members list (cannot be null).
* @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.
*/
List addMember( JID jid, String nickname, MUCRole senderRole )
throws ForbiddenException, ConflictException;
/**
* Adds a new user to the list of outcast users.
*
* @param jid The JID of the user to add as an outcast (cannot be null).
* @param reason an optional reason why the user was banned (can be null).
* @param senderRole The role of the user that initiated the ban (cannot be null).
* @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.
*/
List 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.
*
* @param jid The JID of the user to keep with a NONE affiliation (cannot be null).
* @param senderRole The role of the user that set the affiliation to none (cannot be null).
* @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.
*/
List addNone( JID jid, MUCRole senderRole ) throws ForbiddenException,
ConflictException;
/**
* 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 (cannot be null).
* @param senderRole The role of the user that is granting moderator privileges to an occupant (cannot be null).
* @return the updated presence of the occupant or null if the JID does not belong to
* an existing occupant.
* @throws ForbiddenException If the user is not allowed to grant moderator privileges.
*/
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.
*
* @param fullJID The full JID of the occupant to give participant privileges (cannot be null).
* @param reason The reason why participant privileges were gave to the user or null
* if none.
* @param senderRole The role of the user that is granting participant privileges to an occupant (cannot be null).
* @return the updated presence of the occupant or null 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.
*/
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.
*
* @param jid the full JID of the occupant to change to visitor (cannot be null).
* @param senderRole the role of the user that is changing the role to visitor (cannot be null).
* @return the updated presence of the occupant or null 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.
*/
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.
*/
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.
*/
boolean isManuallyLocked();
/**
* An event callback fired whenever an occupant updated his presence in the chatroom.
*
* @param occupantRole occupant that changed his presence in the room (cannot be null).
* @param newPresence presence sent by the occupant (cannot be null).
*/
void presenceUpdated( MUCRole occupantRole, Presence newPresence );
/**
* An event callback fired whenever an occupant changes his nickname within the chatroom.
*
* @param occupantRole occupant that changed his nickname in the room (cannot be null).
* @param newPresence presence sent by the occupant with the new nickname (cannot be null).
* @param oldNick old nickname within the room (cannot be null).
* @param newNick new nickname within the room (cannot be null).
*/
void nicknameChanged( MUCRole occupantRole, Presence newPresence, 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.
*
* The new subject will be added to the history of the room.
*
* @param packet the sent packet to change the room's subject (cannot be null).
* @param role the role of the user that is trying to change the subject (cannot be null).
* @throws ForbiddenException If the user is not allowed to change the subject.
*/
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.
*/
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 (cannot be null).
*/
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 (cannot be null).
* @param senderRole the role of the user that is trying to send a public message (cannot be null).
* @throws ForbiddenException If the user is not allowed to send a public message (i.e. does not
* have voice in the room).
*/
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.
* @throws ForbiddenException If a user of this role is not permitted to send private messages in this room.
*/
void sendPrivatePacket( Packet packet, MUCRole senderRole ) throws NotFoundException, ForbiddenException;
/**
* 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 (cannot be null).
* @param actorJID The JID of the actor that initiated the kick (cannot be null).
* @param actorNickname The actor nickname.
* @param reason An optional reason why the user was kicked (can be null).
* @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.
*/
Presence kickOccupant( JID fullJID, JID actorJID, String actorNickname, String reason )
throws NotAllowedException;
IQOwnerHandler getIQOwnerHandler();
IQAdminHandler getIQAdminHandler();
/**
* Returns the history of the room which includes chat transcripts.
*
* @return the history of the room which includes chat transcripts.
*/
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.
*/
Collection getOwners();
/**
* 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.
*/
Collection getAdmins();
/**
* 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.
*/
Collection getMembers();
/**
* 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.
*/
Collection getOutcasts();
/**
* 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.
*/
Collection 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.
*/
Collection 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.
*/
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.
*/
void setCanAnyoneDiscoverJID( boolean canAnyoneDiscoverJID );
/**
* 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).
*/
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.
*
* @param role The minimal role of persons that are allowed to send private messages in the room (never null).
*/
void setCanSendPrivateMessage( String role );
/**
* Returns true if participants are allowed to change the room's subject.
*
* @return true if participants are allowed to change the room's subject.
*/
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.
*/
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.
*/
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.
*/
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.
*/
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.
*/
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.
*/
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.
*/
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.
*/
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.
*/
List 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.
*/
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.
*/
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.
*/
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.
*/
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.
*
* 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.
*/
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.
*
* 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.
*/
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.
*/
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.
*/
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.
*/
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.
*/
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.
*/
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.
*/
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.
*/
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.
*/
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.
*/
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.
*/
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.
*/
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.
*/
boolean wasSavedToDB();
/**
* Sets if the room has already been made persistent.
*
* @param saved boolean that indicates if the room was saved to the database.
*/
void setSavedToDB( boolean saved );
/**
* Saves the room configuration to the DB. After the room has been saved to the DB it will
* become persistent.
*/
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.
*/
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.
*/
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.
*/
List 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.
*/
void setRolesToBroadcastPresence( List 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.
*/
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.
*/
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.
*/
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.
* @throws CannotBeInvitedException (Optionally) If the user being invited does not have access to the room
*/
void sendInvitation( JID to, String reason, MUCRole role, List extensions )
throws ForbiddenException, CannotBeInvitedException;
/**
* 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.
*/
void sendInvitationRejection( JID to, String reason, JID from );
/**
* Sends a packet to the user.
*
* @param packet The packet to send
*/
void send( Packet packet );
}