MUCRoom


1   /**
2    * $RCSfile: MUCRoom.java,v $
3    * $Revision: 1.22 $
4    * $Date: 2005/07/12 21:40:16 $
5    *
6    * Copyright (C) 2004 Jive Software. All rights reserved.
7    *
8    * This software is published under the terms of the GNU Public License (GPL),
9    * a copy of which is included in this distribution.
10   */
11  
12  package org.jivesoftware.messenger.muc;
13  
14  import java.util.List  ;
15  import java.util.Date  ;
16  import java.util.Collection  ;
17  
18  import org.dom4j.Element;
19  import org.jivesoftware.messenger.muc.spi.IQAdminHandler;
20  import org.jivesoftware.messenger.muc.spi.IQOwnerHandler;
21  import org.jivesoftware.util.NotFoundException;
22  import org.jivesoftware.util.JiveConstants;
23  import org.jivesoftware.messenger.auth.UnauthorizedException;
24  import org.jivesoftware.messenger.user.UserAlreadyExistsException;
25  import org.jivesoftware.messenger.user.UserNotFoundException;
26  import org.jivesoftware.database.JiveID;
27  import org.xmpp.packet.Presence;
28  import org.xmpp.packet.Message;
29  import org.xmpp.packet.JID;
30  import org.xmpp.packet.Packet;
31  
32  
33  /**
34   * A chat room on the chat server manages its users, and
35   * enforces it's own security rules.
36   *
37   * @author Gaston Dombiak
38   */
39  @JiveID(JiveConstants.MUC_ROOM)
40  public interface MUCRoom {
41  
42      /**
43       * Get the name of this room.
44       *
45       * @return The name for this room
46       */
47      String   getName();
48  
49      /**
50       * Obtain a unique numerical id for this room. Useful for storing rooms in databases. If the 
51       * room is persistent or is logging the conversation then the returned ID won't be -1.
52       *
53       * @return The unique id for this room or -1 if the room is temporary and is not logging the
54       * conversation.
55       */
56      long getID();
57  
58      /**
59       * Sets a new room ID if the room has just been saved to the database or sets the saved ID of
60       * the room in the database while loading the room. 
61       * 
62       * @param roomID the saved ID of the room in the DB or a new one if the room is being saved to 
63       * the DB.
64       */
65      void setID(long roomID);
66  
67      /**
68       * Returns the date when the room was created.
69       *
70       * @return the date when the room was created.
71       */
72      Date   getCreationDate();
73  
74      /**
75       * Sets the date when the room was created.
76       *
77       * @param creationDate the date when the room was created.
78       */
79      void setCreationDate(Date   creationDate);
80  
81      /**
82       * Returns the last date when the room's configuration was modified. If the room's configuration
83       * was never modified then the creation date will be returned.
84       *
85       * @return the last date when the room's configuration was modified.
86       */
87      Date   getModificationDate();
88  
89      /**
90       * Sets the last date when the room's configuration was modified. If the room's configuration
91       * was never modified then the initial value will be the same as the creation date.
92       *
93       * @param modificationDate the last date when the room's configuration was modified.
94       */
95      void setModificationDate(Date   modificationDate);
96  
97      /**
98       * Sets the date when the last occupant left the room. A null value means that there are
99       * occupants in the room at the moment.
100      *
101      * @param emptyDate the date when the last occupant left the room or null if there are occupants
102      *        in the room.
103      */
104     void setEmptyDate(Date   emptyDate);
105 
106     /**
107      * Returns the date when the last occupant left the room. A null value means that there are
108      * occupants in the room at the moment.
109      *
110      * @return the date when the last occupant left the room or null if there are occupants in the
111      *         room at the moment.
112      */
113     Date   getEmptyDate();
114 
115     /**
116      * Obtain the role of the chat server (mainly for addressing messages and presence).
117      *
118      * @return The role for the chat room itself
119      */
120     MUCRole getRole();
121 
122     /**
123      * Obtain the role of a given user by nickname.
124      *
125      * @param nickname The nickname of the user you'd like to obtain
126      * @return The user's role in the room
127      * @throws UserNotFoundException If there is no user with the given nickname
128      */
129     MUCRole getOccupant(String   nickname) throws UserNotFoundException;
130 
131     /**
132      * Obtain the roles of a given user in the room by his bare JID. A user can have several roles,
133      * one for each client resource from which the user has joined the room. 
134      *
135      * @param jid The bare jid of the user you'd like to obtain
136      * @return The user's roles in the room
137      * @throws UserNotFoundException If there is no user with the given nickname
138      */
139     List  <MUCRole> getOccupantsByBareJID(String   jid) throws UserNotFoundException;
140 
141     /**
142      * Obtain the role of a given user in the room by his full JID.
143      *
144      * @param jid The full jid of the user you'd like to obtain
145      * @return The user's role in the room
146      * @throws UserNotFoundException If there is no user with the given nickname
147      */
148     MUCRole getOccupantByFullJID(String   jid) throws UserNotFoundException;
149 
150     /**
151      * Obtain the roles of all users in the chatroom.
152      *
153      * @return a collection with all users in the chatroom
154      */
155     Collection  <MUCRole> getOccupants();
156 
157     /**
158      * Returns the number of occupants in the chatroom at the moment.
159      *
160      * @return int the number of occupants in the chatroom at the moment.
161      */
162     int getOccupantsCount();
163 
164     /**
165      * Determine if a given nickname is taken.
166      *
167      * @param nickname The nickname of the user you'd like to obtain
168      * @return True if a nickname is taken
169      */
170     boolean hasOccupant(String   nickname);
171 
172     /**
173      * Returns the reserved room nickname for the bare JID or null if none.
174      * 
175      * @param bareJID The bare jid of the user of which you'd like to obtain his reserved nickname.
176      * @return the reserved room nickname for the bare JID or null if none.
177      */
178     String   getReservedNickname(String   bareJID);
179 
180     /**
181      * Returns the affiliation state of the user in the room. Possible affiliations are 
182      * MUCRole.OWNER, MUCRole.ADMINISTRATOR, MUCRole.MEMBER, MUCRole.OUTCAST and MUCRole.NONE.<p>
183      * 
184      * Note: Prerequisite - A lock must already be obtained before sending this message.
185      *  
186      * @param bareJID The bare jid of the user of which you'd like to obtain his affiliation.
187      * @return the affiliation state of the user in the room.
188      */
189     MUCRole.Affiliation getAffiliation(String   bareJID);
190 
191     /**
192      * Joins the room using the given nickname.
193      *
194      * @param nickname       The nickname the user wants to use in the chatroom.
195      * @param password       The password provided by the user to enter the chatroom or null if none.
196      * @param historyRequest The amount of history that the user request or null meaning default.
197      * @param user           The user joining.
198      * @param presence       The presence sent by the user to join the room.
199      * @return The role created for the user.
200      * @throws UnauthorizedException         If the user doesn't have permision to join the room.
201      * @throws UserAlreadyExistsException    If the nickname is already taken.
202      * @throws RoomLockedException           If the user is trying to join a locked room.
203      * @throws ForbiddenException            If the user is an outcast.
204      * @throws RegistrationRequiredException If the user is not a member of a members-only room.
205      * @throws ConflictException             If another user attempts to join the room with a
206      *                                       nickname reserved by the first user.
207      * @throws ServiceUnavailableException   If the user cannot join the room since the max number
208      *                                       of users has been reached.
209      * @throws NotAcceptableException       If the registered user is trying to join with a
210      *                                      nickname different than the reserved nickname.
211      */
212     MUCRole joinRoom(String   nickname, String   password, HistoryRequest historyRequest, MUCUser user,
213             Presence presence) throws UnauthorizedException, UserAlreadyExistsException,
214             RoomLockedException, ForbiddenException, RegistrationRequiredException,
215             ConflictException, ServiceUnavailableException, NotAcceptableException;
216 
217     /**
218      * Remove a member from the chat room.
219      *
220      * @param nickname The user to remove
221      * @throws UserNotFoundException If the nickname is not found.
222      */
223     void leaveRoom(String   nickname) throws UserNotFoundException;
224 
225     /**
226      * Destroys the room. Each occupant will be removed and will receive a presence stanza of type
227      * "unavailable" whose "from" attribute will be the occupant's nickname that the user knows he 
228      * or she has been removed from the room.
229      * 
230      * @param alternateJID the alternate JID. Commonly used to provide a replacement room.
231      * @param reason the reason why the room was destroyed.
232      */
233     void destroyRoom(String   alternateJID, String   reason);
234 
235     /**
236      * Create a new presence in this room for the given role.
237      *
238      * @return The new presence
239      * @throws UnauthorizedException If the user doesn't have permission to leave the room
240      */
241     Presence createPresence(Presence.Type type) throws UnauthorizedException;
242 
243     /**
244      * Broadcast a given message to all members of this chat room. The sender is always set to 
245      * be the chatroom.
246      *
247      * @param msg The message to broadcast
248      */
249     void serverBroadcast(String   msg);
250     
251     /**
252      * Returns the total length of the chat session.
253      * 
254      * @return length of chat session in milliseconds.
255      */
256     public long getChatLength();
257 
258     /**
259      * Adds a new user to the list of owners. The user is the actual creator of the room. Only the
260      * MultiUserChatServer should use this method. Regular owners list maintenance MUST be done
261      * through {@link #addOwner(String,MUCRole)}.
262      * 
263      * @param bareJID The bare JID of the user to add as owner.
264      */
265     public void addFirstOwner(String   bareJID);
266 
267     /**
268      * Adds a new user to the list of owners.
269      * 
270      * @param bareJID The bare JID of the user to add as owner.
271      * @param senderRole the role of the user that is trying to modify the owners list.
272      * @return the list of updated presences of all the client resources that the client used to
273      *         join the room.
274      * @throws ForbiddenException If the user is not allowed to modify the owner list.
275      */
276     public List  <Presence> addOwner(String   bareJID, MUCRole senderRole) throws ForbiddenException;
277 
278     /**
279      * Adds a list of users to the list of owners.
280      *
281      * @param newOwners the list of bare JIDs of the users to add to the list of existing owners.
282      * @param senderRole the role of the user that is trying to modify the owners list.
283      * @return the list of updated presences of all the clients resources that the clients used to
284      *         join the room.
285      * @throws ForbiddenException If the user is not allowed to modify the owner list.
286      */
287     public List  <Presence> addOwners(List  <String  > newOwners, MUCRole senderRole)
288             throws ForbiddenException;
289 
290     /**
291      * Adds a list of users to the list of admins.
292      *
293      * @param newAdmins the list of bare JIDs of the users to add to the list of existing admins.
294      * @param senderRole the role of the user that is trying to modify the admins list.
295      * @return the list of updated presences of all the clients resources that the clients used to
296      *         join the room.
297      * @throws ForbiddenException If the user is not allowed to modify the admin list.
298      * @throws ConflictException If the room was going to lose all its owners.
299      */
300     public List  <Presence> addAdmins(List  <String  > newAdmins, MUCRole senderRole)
301             throws ForbiddenException, ConflictException;
302 
303     /**
304      * Adds a new user to the list of admins.
305      * 
306      * @param bareJID The bare JID of the user to add as admin.
307      * @param senderRole The role of the user that is trying to modify the admins list.
308      * @return the list of updated presences of all the client resources that the client used to
309      *         join the room.
310      * @throws ForbiddenException If the user is not allowed to modify the admin list.
311      * @throws ConflictException If the room was going to lose all its owners.
312      */
313     public List  <Presence> addAdmin(String   bareJID, MUCRole senderRole) throws ForbiddenException,
314             ConflictException;
315 
316     /**
317      * Adds a new user to the list of members.
318      * 
319      * @param bareJID The bare JID of the user to add as a member.
320      * @param nickname The reserved nickname of the member for the room or null if none.
321      * @param senderRole the role of the user that is trying to modify the members list.
322      * @return the list of updated presences of all the client resources that the client used to
323      *         join the room.
324      * @throws ForbiddenException If the user is not allowed to modify the members list.
325      * @throws ConflictException If the desired room nickname is already reserved for the room or if
326      *             the room was going to lose all its owners.
327      */
328     public List  <Presence> addMember(String   bareJID, String   nickname, MUCRole senderRole)
329             throws ForbiddenException, ConflictException;
330 
331     /**
332      * Adds a new user to the list of outcast users.
333      * 
334      * @param bareJID The bare JID of the user to add as an outcast.
335      * @param reason The reason why the user was banned.
336      * @param senderRole The role of the user that initiated the ban.
337      * @return the list of updated presences of all the client resources that the client used to
338      *         join the room.
339      * @throws NotAllowedException Thrown if trying to ban an owner or an administrator.
340      * @throws ForbiddenException If the user is not allowed to modify the outcast list.
341      * @throws ConflictException If the room was going to lose all its owners.
342      */
343     public List  <Presence> addOutcast(String   bareJID, String   reason, MUCRole senderRole)
344             throws NotAllowedException, ForbiddenException, ConflictException;
345 
346     /**
347      * Removes the user from all the other affiliation list thus giving the user a NONE affiliation.
348      * 
349      * @param bareJID The bare JID of the user to keep with a NONE affiliation.
350      * @param senderRole The role of the user that set the affiliation to none.
351      * @return the list of updated presences of all the client resources that the client used to
352      *         join the room or null if none was updated.
353      * @throws ForbiddenException If the user is not allowed to modify the none list.
354      * @throws ConflictException If the room was going to lose all its owners.
355      */
356     public List  <Presence> addNone(String   bareJID, MUCRole senderRole) throws ForbiddenException,
357             ConflictException;
358 
359     /**
360      * Changes the role of the user within the room to moderator. A moderator is allowed to kick
361      * occupants as well as granting/revoking voice from occupants.
362      *
363      * @param fullJID The full JID of the occupant to give moderator privileges.
364      * @param senderRole The role of the user that is granting moderator privileges to an occupant.
365      * @return the updated presence of the occupant or <tt>null</tt> if the JID does not belong to
366      *         an existing occupant.
367      * @throws ForbiddenException If the user is not allowed to grant moderator privileges.
368      */
369     public Presence addModerator(JID fullJID, MUCRole senderRole) throws ForbiddenException;
370 
371     /**
372      * Changes the role of the user within the room to participant. A participant is allowed to send
373      * messages to the room (i.e. has voice) and may change the room's subject.
374      *
375      * @param fullJID The full JID of the occupant to give participant privileges.
376      * @param reason The reason why participant privileges were gave to the user or <tt>null</tt>
377      *        if none.
378      * @param senderRole The role of the user that is granting participant privileges to an occupant.
379      * @return the updated presence of the occupant or <tt>null</tt> if the JID does not belong to
380      *         an existing occupant.
381      * @throws NotAllowedException If trying to change the moderator role to an owner or an admin.
382      * @throws ForbiddenException If the user is not allowed to grant participant privileges.
383      */
384     public Presence addParticipant(JID fullJID, String   reason, MUCRole senderRole)
385             throws NotAllowedException, ForbiddenException;
386 
387     /**
388      * Changes the role of the user within the room to visitor. A visitor can receive messages but
389      * is not allowed to send messages to the room (i.e. does not has voice) and may invite others
390      * to the room.
391      *
392      * @param jid the full JID of the occupant to change to visitor.
393      * @param senderRole the role of the user that is changing the role to visitor.
394      * @return the updated presence of the occupant or <tt>null</tt> if the JID does not belong to
395      *         an existing occupant.
396      * @throws NotAllowedException if trying to change the moderator role to an owner or an admin.
397      * @throws ForbiddenException if the user is not a moderator.
398      */
399     public Presence addVisitor(JID jid, MUCRole senderRole) throws NotAllowedException,
400             ForbiddenException;
401 
402     /**
403      * Returns true if the room is locked. The lock will persist for a defined period of time. If 
404      * the room owner does not configure the room within the timeout period, the room owner is 
405      * assumed to have accepted the default configuration.
406      * 
407      * @return true if the room is locked. 
408      */
409     public boolean isLocked();
410 
411     /**
412      * Returns true if the room is locked and it was locked by a room owner after the room was
413      * initially configured.
414      *
415      * @return true if the room is locked and it was locked by a room owner after the room was
416      *         initially configured.
417      */
418     public boolean isManuallyLocked();
419 
420     /**
421      * An event callback fired whenever an occupant changes his nickname within the chatroom.
422      *  
423      * @param oldNick old nickname within the room.
424      * @param newNick new nickname within the room.
425      */
426     public void nicknameChanged(String   oldNick, String   newNick);
427     
428     /**
429      * Changes the room's subject if the occupant has enough permissions. The occupant must be
430      * a moderator or the room must be configured so that anyone can change its subject. Otherwise
431      * a forbidden exception will be thrown.<p>
432      * 
433      * The new subject will be added to the history of the room.
434      *  
435      * @param packet the sent packet to change the room's subject.
436      * @param role the role of the user that is trying to change the subject.
437      * @throws ForbiddenException If the user is not allowed to change the subject.
438      */
439     public void changeSubject(Message packet, MUCRole role) throws ForbiddenException;
440 
441     /**
442      * Returns the last subject that some occupant set to the room.
443      * 
444      * @return the last subject that some occupant set to the room.
445      */
446     public String   getSubject();
447 
448     /**
449      * Sets the last subject that some occupant set to the room. This message will only be used
450      * when loading a room from the database. 
451      * 
452      * @param subject the last known subject of the room.
453      */
454     public void setSubject(String   subject);
455 
456     /**
457      * Sends a message to the all the occupants. In a moderated room, this privilege is restricted
458      * to occupants with a role of participant or higher. In an unmoderated room, any occupant can
459      * send a message to all other occupants.
460      * 
461      * @param message The message to send.
462      * @param senderRole the role of the user that is trying to send a public message.
463      * @throws ForbiddenException If the user is not allowed to send a public message (i.e. does not
464      *             have voice in the room).
465      */
466     public void sendPublicMessage(Message message, MUCRole senderRole) throws ForbiddenException;
467 
468     /**
469      * Sends a private message to a selected occupant. 
470      * 
471      * @param message The message to send.
472      * @param senderRole the role of the user that is trying to send a public message.
473      * @throws NotFoundException If the user is sending a message to a room JID that does not exist.
474      */
475     public void sendPrivateMessage(Message message, MUCRole senderRole) throws NotFoundException;
476 
477     /**
478      * Kicks a user from the room. If the user was in the room, the returned updated presence will
479      * be sent to the remaining occupants. 
480      * 
481      * @param fullJID The full JID of the kicked user.
482      * @param actorJID The JID of the actor that initiated the kick.
483      * @param reason The reason why the user was kicked.
484      * @return the updated presence of the kicked user or null if the user was not in the room.
485      * @throws NotAllowedException Thrown if trying to ban an owner or an administrator.
486      */
487     public Presence kickOccupant(JID fullJID, JID actorJID, String   reason)
488             throws NotAllowedException;
489 
490     public IQOwnerHandler getIQOwnerHandler();
491 
492     public IQAdminHandler getIQAdminHandler();
493 
494     /**
495      * Returns the history of the room which includes chat transcripts.
496      *
497      * @return the history of the room which includes chat transcripts.
498      */
499     public MUCRoomHistory getRoomHistory();
500 
501     /**
502      * Returns a collection with the current list of owners. The collection contains the bareJID of
503      * the users with owner affiliation.
504      *
505      * @return a collection with the current list of owners.
506      */
507     public Collection  <String  > getOwners();
508 
509     /**
510      * Returns a collection with the current list of admins. The collection contains the bareJID of
511      * the users with admin affiliation.
512      *
513      * @return a collection with the current list of admins.
514      */
515     public Collection  <String  > getAdmins();
516 
517     /**
518      * Returns a collection with the current list of room members. The collection contains the
519      * bareJID of the users with member affiliation. If the room is not members-only then the list
520      * will contain the users that registered with the room and therefore they may have reserved a
521      * nickname.
522      *
523      * @return a collection with the current list of members.
524      */
525     public Collection  <String  > getMembers();
526 
527     /**
528      * Returns a collection with the current list of outcast users. An outcast user is not allowed
529      * to join the room again. The collection contains the bareJID of the users with outcast
530      * affiliation.
531      *
532      * @return a collection with the current list of outcast users.
533      */
534     public Collection  <String  > getOutcasts();
535 
536     /**
537      * Returns a collection with the current list of room moderators. The collection contains the
538      * MUCRole of the occupants with moderator role.
539      *
540      * @return a collection with the current list of moderators.
541      */
542     public Collection  <MUCRole> getModerators();
543 
544     /**
545      * Returns a collection with the current list of room participants. The collection contains the
546      * MUCRole of the occupants with participant role.
547      *
548      * @return a collection with the current list of moderators.
549      */
550     public Collection  <MUCRole> getParticipants();
551 
552     /**
553      * Returns true if every presence packet will include the JID of every occupant. This
554      * configuration can be modified by the owner while editing the room's configuration.
555      *
556      * @return true if every presence packet will include the JID of every occupant.
557      */
558     public boolean canAnyoneDiscoverJID();
559 
560     /**
561      * Sets if every presence packet will include the JID of every occupant. This
562      * configuration can be modified by the owner while editing the room's configuration.
563      *
564      * @param canAnyoneDiscoverJID boolean that specifies if every presence packet will include the
565      *        JID of every occupant.
566      */
567     public void setCanAnyoneDiscoverJID(boolean canAnyoneDiscoverJID);
568 
569     /**
570      * Returns true if participants are allowed to change the room's subject.
571      *
572      * @return true if participants are allowed to change the room's subject.
573      */
574     public boolean canOccupantsChangeSubject();
575 
576     /**
577      * Sets if participants are allowed to change the room's subject.
578      *
579      * @param canOccupantsChangeSubject boolean that specifies if participants are allowed to
580      *        change the room's subject.
581      */
582     public void setCanOccupantsChangeSubject(boolean canOccupantsChangeSubject);
583 
584     /**
585      * Returns true if occupants can invite other users to the room. If the room does not require an
586      * invitation to enter (i.e. is not members-only) then any occupant can send invitations. On
587      * the other hand, if the room is members-only and occupants cannot send invitation then only
588      * the room owners and admins are allowed to send invitations.
589      *
590      * @return true if occupants can invite other users to the room.
591      */
592     public boolean canOccupantsInvite();
593 
594     /**
595      * Sets if occupants can invite other users to the room. If the room does not require an
596      * invitation to enter (i.e. is not members-only) then any occupant can send invitations. On
597      * the other hand, if the room is members-only and occupants cannot send invitation then only
598      * the room owners and admins are allowed to send invitations.
599      *
600      * @param canOccupantsInvite boolean that specified in any occupant can invite other users to
601      *        the room.
602      */
603     public void setCanOccupantsInvite(boolean canOccupantsInvite);
604 
605     /**
606      * Returns the natural language name of the room. This name can only be modified by room owners.
607      * It's mainly used for users while discovering rooms hosted by the Multi-User Chat service.
608      *
609      * @return the natural language name of the room.
610      */
611     public String   getNaturalLanguageName();
612 
613     /**
614      * Sets the natural language name of the room. This name can only be modified by room owners.
615      * It's mainly used for users while discovering rooms hosted by the Multi-User Chat service.
616      *
617      * @param naturalLanguageName the natural language name of the room.
618      */
619     public void setNaturalLanguageName(String   naturalLanguageName);
620 
621     /**
622      * Returns a description set by the room's owners about the room. This information will be used
623      * when discovering extended information about the room.
624      *
625      * @return a description set by the room's owners about the room.
626      */
627     public String   getDescription();
628 
629     /**
630      * Sets a description set by the room's owners about the room. This information will be used
631      * when discovering extended information about the room.
632      *
633      * @param description a description set by the room's owners about the room.
634      */
635     public void setDescription(String   description);
636 
637     /**
638      * Returns true if the room requires an invitation to enter. That is if the room is
639      * members-only.
640      *
641      * @return true if the room requires an invitation to enter.
642      */
643     public boolean isMembersOnly();
644 
645     /**
646      * Sets if the room requires an invitation to enter. That is if the room is members-only.
647      *
648      * @param membersOnly if true then the room is members-only.
649      * @return the list of updated presences of all the occupants that aren't members of the room if
650      *         the room is now members-only.
651      */
652     public List  <Presence> setMembersOnly(boolean membersOnly);
653 
654     /**
655      * Returns true if the room's conversation is being logged. If logging is activated the room
656      * conversation will be saved to the database every couple of minutes. The saving frequency is
657      * the same for all the rooms and can be configured by changing the property
658      * "xmpp.muc.tasks.log.timeout" of MultiUserChatServerImpl.
659      *
660      * @return true if the room's conversation is being logged.
661      */
662     public boolean isLogEnabled();
663 
664     /**
665      * Sets if the room's conversation is being logged. If logging is activated the room
666      * conversation will be saved to the database every couple of minutes. The saving frequency is
667      * the same for all the rooms and can be configured by changing the property
668      * "xmpp.muc.tasks.log.timeout" of MultiUserChatServerImpl.
669      *
670      * @param logEnabled boolean that specified if the room's conversation must be logged.
671      */
672     public void setLogEnabled(boolean logEnabled);
673 
674     /**
675      * Returns true if registered users can only join the room using their registered nickname. By
676      * default, registered users can join the room using any nickname. A not_acceptable error
677      * will be returned if the user tries to join the room with a nickname different than the
678      * reserved nickname.
679      *
680      * @return true if registered users can only join the room using their registered nickname.
681      */
682     public boolean isLoginRestrictedToNickname();
683 
684     /**
685      * Sets if registered users can only join the room using their registered nickname. A
686      * not_acceptable error will be returned if the user tries to join the room with a nickname
687      * different than the reserved nickname.
688      *
689      * @param restricted if registered users can only join the room using their registered nickname.
690      */
691     public void setLoginRestrictedToNickname(boolean restricted);
692 
693     /**
694      * Returns true if room occupants are allowed to change their nicknames in the room. By
695      * default, occupants are allowed to change their nicknames. A not_acceptable error will be
696      * returned if an occupant tries to change his nickname and this feature is not enabled.<p>
697      *
698      * Notice that this feature is not supported by the MUC spec so answering a not_acceptable
699      * error may break some cliens.
700      *
701      * @return true if room occupants are allowed to change their nicknames in the room.
702      */
703     public boolean canChangeNickname();
704 
705     /**
706      * Sets if room occupants are allowed to change their nicknames in the room. By default,
707      * occupants are allowed to change their nicknames. A not_acceptable error will be returned if
708      * an occupant tries to change his nickname and this feature is not enabled.<p>
709      *
710      * Notice that this feature is not supported by the MUC spec so answering a not_acceptable
711      * error may break some cliens. 
712      *
713      * @param canChange if room occupants are allowed to change their nicknames in the room.
714      */
715     public void setChangeNickname(boolean canChange);
716 
717     /**
718      * Returns true if users are allowed to register with the room. By default, room registration
719      * is enabled. A not_allowed error will be returned if a user tries to register with the room
720      * and this feature is disabled.
721      *
722      * @return true if users are allowed to register with the room.
723      */
724     public boolean isRegistrationEnabled();
725 
726     /**
727      * Sets if users are allowed to register with the room. By default, room registration
728      * is enabled. A not_allowed error will be returned if a user tries to register with the room
729      * and this feature is disabled.
730      *
731      * @param registrationEnabled if users are allowed to register with the room.
732      */
733     public void setRegistrationEnabled(boolean registrationEnabled);
734 
735     /**
736      * Returns the maximum number of occupants that can be simultaneously in the room. If the number
737      * is zero then there is no limit.
738      *
739      * @return the maximum number of occupants that can be simultaneously in the room. Zero means
740      *         unlimited number of occupants.
741      */
742     public int getMaxUsers();
743 
744     /**
745      * Sets the maximum number of occupants that can be simultaneously in the room. If the number
746      * is zero then there is no limit.
747      *
748      * @param maxUsers the maximum number of occupants that can be simultaneously in the room. Zero
749      *        means unlimited number of occupants.
750      */
751     public void setMaxUsers(int maxUsers);
752 
753     /**
754      * Returns if the room in which only those with "voice" may send messages to all occupants.
755      *
756      * @return if the room in which only those with "voice" may send messages to all occupants.
757      */
758     public boolean isModerated();
759 
760     /**
761      * Sets if the room in which only those with "voice" may send messages to all occupants.
762      *
763      * @param moderated if the room in which only those with "voice" may send messages to all
764      *        occupants.
765      */
766     public void setModerated(boolean moderated);
767 
768     /**
769      * Returns true if a user cannot enter without first providing the correct password.
770      *
771      * @return true if a user cannot enter without first providing the correct password.
772      */
773     public boolean isPasswordProtected();
774 
775     /**
776      * Returns the password that the user must provide to enter the room.
777      *
778      * @return the password that the user must provide to enter the room.
779      */
780     public String   getPassword();
781 
782     /**
783      * Sets the password that the user must provide to enter the room.
784      *
785      * @param password the password that the user must provide to enter the room.
786      */
787     public void setPassword(String   password);
788 
789     /**
790      * Returns true if the room is not destroyed if the last occupant exits. Persistent rooms are
791      * saved to the database to make their configurations persistent together with the affiliation
792      * of the users.
793      *
794      * @return true if the room is not destroyed if the last occupant exits.
795      */
796     public boolean isPersistent();
797 
798     /**
799      * Sets if the room is not destroyed if the last occupant exits. Persistent rooms are
800      * saved to the database to make their configurations persistent together with the affiliation
801      * of the users.
802      *
803      * @param persistent if the room is not destroyed if the last occupant exits.
804      */
805     public void setPersistent(boolean persistent);
806 
807     /**
808      * Returns true if the room has already been made persistent. If the room is temporary the 
809      * answer will always be false.
810      * 
811      * @return true if the room has already been made persistent.
812      */
813     public boolean wasSavedToDB();
814 
815     /**
816      * Sets if the room has already been made persistent.
817      * 
818      * @param saved boolean that indicates if the room was saved to the database.
819      */
820     public void setSavedToDB(boolean saved);
821 
822     /**
823      * Saves the room configuration to the DB. After the room has been saved to the DB it will
824      * become persistent. 
825      */
826     public void saveToDB();
827 
828     /**
829      * Returns true if the room is searchable and visible through service discovery. 
830      * 
831      * @return true if the room is searchable and visible through service discovery.
832      */
833     public boolean isPublicRoom();
834 
835     /**
836      * Sets if the room is searchable and visible through service discovery.
837      * 
838      * @param publicRoom if the room is searchable and visible through service discovery.
839      */
840     public void setPublicRoom(boolean publicRoom);
841 
842     /**
843      * Returns the list of roles of which presence will be broadcasted to the rest of the occupants.
844      * This feature is useful for implementing "invisible" occupants.
845      * 
846      * @return the list of roles of which presence will be broadcasted to the rest of the occupants.
847      */
848     public List  <String  > getRolesToBroadcastPresence();
849 
850     /**
851      * Sets the list of roles of which presence will be broadcasted to the rest of the occupants.
852      * This feature is useful for implementing "invisible" occupants.
853      * 
854      * @param rolesToBroadcastPresence the list of roles of which presence will be broadcasted to 
855      * the rest of the occupants.
856      */
857     public void setRolesToBroadcastPresence(List  <String  > rolesToBroadcastPresence);
858 
859     /**
860      * Returns true if the presences of the requested role will be broadcasted.
861      * 
862      * @param roleToBroadcast the role to check if its presences will be broadcasted.
863      * @return true if the presences of the requested role will be broadcasted.
864      */
865     public boolean canBroadcastPresence(String   roleToBroadcast);
866 
867     /**
868      * Locks the room so that users cannot join the room. Only the owner of the room can lock/unlock
869      * the room.
870      *
871      * @param senderRole the role of the occupant that locked the room.
872      * @throws ForbiddenException If the user is not an owner of the room.
873      */
874     public void lock(MUCRole senderRole) throws ForbiddenException;
875 
876     /**
877      * Unlocks the room so that users can join the room. The room is locked when created and only
878      * the owner of the room can unlock it by sending the configuration form to the Multi-User Chat
879      * service.
880      *
881      * @param senderRole the role of the occupant that unlocked the room.
882      * @throws ForbiddenException If the user is not an owner of the room.
883      */
884     public void unlock(MUCRole senderRole) throws ForbiddenException;
885 
886     /**
887      * Sends an invitation to a user. The invitation will be sent as if the room is inviting the 
888      * user. The invitation will include the original occupant the sent the invitation together with
889      * the reason for the invitation if any. Since the invitee could be offline at the moment we 
890      * need the originating session so that the offline strategy could potentially bounce the 
891      * message with the invitation.
892      * 
893      * @param to the JID of the user that is being invited.
894      * @param reason the reason of the invitation or null if none.
895      * @param role the role of the occupant that sent the invitation.
896      * @param extensions the list of extensions sent with the original message invitation or null 
897      *        if none.
898      * @throws ForbiddenException If the user is not allowed to send the invitation.
899      */
900     public void sendInvitation(JID to, String   reason, MUCRole role, List  <Element> extensions)
901             throws ForbiddenException;
902 
903     /**
904      * Sends the rejection to the inviter. The rejection will be sent as if the room is rejecting 
905      * the invitation is named of the invitee. The rejection will include the address of the invitee
906      * together with the reason for the rejection if any. Since the inviter could be offline at the 
907      * moment we need the originating session so that the offline strategy could potentially bounce 
908      * the message with the rejection.
909      * 
910      * @param to the JID of the user that is originated the invitation.
911      * @param reason the reason for the rejection or null if none.
912      * @param from the JID of the invitee that is rejecting the invitation.
913      */
914     public void sendInvitationRejection(JID to, String   reason, JID from);
915 
916     /**
917      * Sends a packet to the user.
918      *
919      * @param packet The packet to send
920      */
921     public void send(Packet packet);
922 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags