001: /**
002: * $RCSfile$
003: * $Revision: 919 $
004: * $Date: 2005-01-29 19:26:02 -0300 (Sat, 29 Jan 2005) $
005: *
006: * Copyright (C) 2004 Jive Software. All rights reserved.
007: *
008: * This software is published under the terms of the GNU Public License (GPL),
009: * a copy of which is included in this distribution.
010: */package org.jivesoftware.openfire.muc;
011:
012: import org.jivesoftware.openfire.cluster.NodeID;
013: import org.xmpp.packet.JID;
014: import org.xmpp.packet.Packet;
015: import org.xmpp.packet.Presence;
016:
017: /**
018: * Defines the permissions and actions that a MUCUser may use in
019: * a particular room. Each MUCRole defines the relationship between
020: * a MUCRoom and a MUCUser.
021: * <p/>
022: * MUCUsers can play different roles in different chatrooms.
023: *
024: * @author Gaston Dombiak
025: */
026: public interface MUCRole {
027:
028: /**
029: * Obtain the current presence status of a user in a chatroom.
030: *
031: * @return The presence of the user in the room.
032: */
033: public Presence getPresence();
034:
035: /**
036: * Set the current presence status of a user in a chatroom.
037: *
038: * @param presence The presence of the user in the room.
039: */
040: public void setPresence(Presence presence);
041:
042: /**
043: * Call this method to promote or demote a user's role in a chatroom.
044: * It is common for the chatroom or other chat room members to change
045: * the role of users (a moderator promoting another user to moderator
046: * status for example).<p>
047: * <p/>
048: * Owning ChatUsers should have their membership roles updated.
049: *
050: * @param newRole The new role that the user will play.
051: * @throws NotAllowedException Thrown if trying to change the moderator role to an owner or
052: * administrator.
053: */
054: public void setRole(Role newRole) throws NotAllowedException;
055:
056: /**
057: * Obtain the role state of the user.
058: *
059: * @return The role status of this user.
060: */
061: public Role getRole();
062:
063: /**
064: * Call this method to promote or demote a user's affiliation in a chatroom.
065: *
066: * @param newAffiliation the new affiliation that the user will play.
067: * @throws NotAllowedException thrown if trying to ban an owner or an administrator.
068: */
069: public void setAffiliation(Affiliation newAffiliation)
070: throws NotAllowedException;
071:
072: /**
073: * Obtain the affiliation state of the user.
074: *
075: * @return The affiliation status of this user.
076: */
077: public Affiliation getAffiliation();
078:
079: /**
080: * Changes the nickname of the occupant within the room to the new nickname.
081: *
082: * @param nickname the new nickname of the occupant in the room.
083: */
084: void changeNickname(String nickname);
085:
086: /**
087: * Obtain the nickname for the user in the chatroom.
088: *
089: * @return The user's nickname in the room or null if invisible.
090: */
091: public String getNickname();
092:
093: /**
094: * Destroys this role after the occupant left the room. This role will be
095: * removed from MUCUser.
096: */
097: public void destroy();
098:
099: /**
100: * Returns true if the room occupant does not want to get messages broadcasted to all
101: * room occupants. This type of users are called "deaf" occupants. Deaf occupants will still
102: * be able to get private messages, presences, IQ packets or room history.<p>
103: *
104: * To be a deaf occupant the initial presence sent to the room while joining the room has
105: * to include the following child element:
106: * <pre>
107: * <x xmlns='http://jivesoftware.org/protocol/muc'>
108: * <deaf-occupant/>
109: * </x>
110: * </pre>
111: *
112: * Note that this is a custom extension to the MUC specification.
113: *
114: * @return true if the room occupant does not want to get messages broadcasted to all
115: * room occupants.
116: */
117: boolean isVoiceOnly();
118:
119: /**
120: * Obtain the chat room that hosts this user's role.
121: *
122: * @return The chatroom hosting this role.
123: */
124: public MUCRoom getChatRoom();
125:
126: /**
127: * Obtain the XMPPAddress representing this role in a room: room@server/nickname
128: *
129: * @return The Jabber ID that represents this role in the room.
130: */
131: public JID getRoleAddress();
132:
133: /**
134: * Obtain the XMPPAddress of the user that joined the room. A <tt>null</tt> null value
135: * represents the room's role.
136: *
137: * @return The address of the user that joined the room or null if this role belongs to the room itself.
138: */
139: public JID getUserAddress();
140:
141: /**
142: * Returns true if this room occupant is hosted by this JVM.
143: *
144: * @return true if this room occupant is hosted by this JVM
145: */
146: public boolean isLocal();
147:
148: /**
149: * Returns the id of the node that is hosting the room occupant.
150: *
151: * @return the id of the node that is hosting the room occupant.
152: */
153: public NodeID getNodeID();
154:
155: /**
156: * Sends a packet to the user.
157: *
158: * @param packet The packet to send
159: */
160: public void send(Packet packet);
161:
162: public enum Role {
163:
164: /**
165: * Runs moderated discussions. Is allowed to kick users, grant and revoke voice, etc.
166: */
167: moderator(0),
168:
169: /**
170: * A normal occupant of the room. An occupant who does not have administrative privileges; in
171: * a moderated room, a participant is further defined as having voice
172: */
173: participant(1),
174:
175: /**
176: * An occupant who does not have voice (can't speak in the room)
177: */
178: visitor(2),
179:
180: /**
181: * An occupant who does not permission to stay in the room (was banned)
182: */
183: none(3);
184:
185: private int value;
186:
187: Role(int value) {
188: this .value = value;
189: }
190:
191: /**
192: * Returns the value for the role.
193: *
194: * @return the value.
195: */
196: public int getValue() {
197: return value;
198: }
199:
200: /**
201: * Returns the affiliation associated with the specified value.
202: *
203: * @param value the value.
204: * @return the associated affiliation.
205: */
206: public static Role valueOf(int value) {
207: switch (value) {
208: case 0:
209: return moderator;
210: case 1:
211: return participant;
212: case 2:
213: return visitor;
214: default:
215: return none;
216: }
217: }
218: }
219:
220: public enum Affiliation {
221:
222: /**
223: * Owner of the room.
224: */
225: owner(10),
226:
227: /**
228: * Administrator of the room.
229: */
230: admin(20),
231:
232: /**
233: * A user who is on the "whitelist" for a members-only room or who is registered
234: * with an open room.
235: */
236: member(30),
237:
238: /**
239: * A user who has been banned from a room.
240: */
241: outcast(40),
242:
243: /**
244: * A user who doesn't have an affiliation. This kind of users can register with members-only
245: * rooms and may enter an open room.
246: */
247: none(50);
248:
249: private int value;
250:
251: Affiliation(int value) {
252: this .value = value;
253: }
254:
255: /**
256: * Returns the value for the role.
257: *
258: * @return the value.
259: */
260: public int getValue() {
261: return value;
262: }
263:
264: /**
265: * Returns the affiliation associated with the specified value.
266: *
267: * @param value the value.
268: * @return the associated affiliation.
269: */
270: public static Affiliation valueOf(int value) {
271: switch (value) {
272: case 10:
273: return owner;
274: case 20:
275: return admin;
276: case 30:
277: return member;
278: case 40:
279: return outcast;
280: default:
281: return none;
282: }
283: }
284: }
285: }
|