KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > jivesoftware > messenger > muc > MUCRole


1 /**
2  * $RCSfile: MUCRole.java,v $
3  * $Revision: 1.7 $
4  * $Date: 2005/01/29 22:26:02 $
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 org.xmpp.packet.JID;
15 import org.xmpp.packet.Presence;
16 import org.xmpp.packet.Packet;
17 import org.dom4j.Element;
18
19 /**
20  * Defines the permissions and actions that a MUCUser may use in
21  * a particular room. Each MUCRole defines the relationship between
22  * a MUCRoom and a MUCUser.
23  * <p/>
24  * MUCUsers can play different roles in different chatrooms.
25  *
26  * @author Gaston Dombiak
27  */
28 public interface MUCRole {
29
30     public enum Role {
31
32         /**
33          * Runs moderated discussions. Is allowed to kick users, grant and revoke voice, etc.
34          */
35         moderator(0),
36
37         /**
38          * A normal occupant of the room. An occupant who does not have administrative privileges; in
39          * a moderated room, a participant is further defined as having voice
40          */
41         participant(1),
42
43         /**
44          * An occupant who does not have voice (can't speak in the room)
45          */
46         visitor(2),
47
48         /**
49          * An occupant who does not permission to stay in the room (was banned)
50          */
51         none(3);
52
53         private int value;
54
55         Role(int value) {
56             this.value = value;
57         }
58
59         /**
60          * Returns the value for the role.
61          *
62          * @return the value.
63          */
64         public int getValue() {
65             return value;
66         }
67
68         /**
69          * Returns the affiliation associated with the specified value.
70          *
71          * @param value the value.
72          * @return the associated affiliation.
73          */
74         public static Role valueOf(int value) {
75             switch (value) {
76                 case 0: return moderator;
77                 case 1: return participant;
78                 case 2: return visitor;
79                 default: return none;
80             }
81         }
82     }
83
84     public enum Affiliation {
85
86         /**
87          * Owner of the room.
88          */
89         owner(10),
90
91         /**
92          * Administrator of the room.
93          */
94         admin(20),
95
96         /**
97          * A user who is on the "whitelist" for a members-only room or who is registered
98          * with an open room.
99          */
100         member(30),
101
102         /**
103          * A user who has been banned from a room.
104          */
105         outcast(40),
106
107         /**
108          * A user who doesn't have an affiliation. This kind of users can register with members-only
109          * rooms and may enter an open room.
110          */
111         none(50);
112
113         private int value;
114
115         Affiliation(int value) {
116             this.value = value;
117         }
118
119         /**
120          * Returns the value for the role.
121          *
122          * @return the value.
123          */
124         public int getValue() {
125             return value;
126         }
127
128         /**
129          * Returns the affiliation associated with the specified value.
130          *
131          * @param value the value.
132          * @return the associated affiliation.
133          */
134         public static Affiliation valueOf(int value) {
135             switch (value) {
136                 case 10: return owner;
137                 case 20: return admin;
138                 case 30: return member;
139                 case 40: return outcast;
140                 default: return none;
141             }
142         }
143     }
144
145     /**
146      * Obtain the current presence status of a user in a chatroom.
147      *
148      * @return The presence of the user in the room.
149      */
150     public Presence getPresence();
151
152     /**
153      * Returns the extended presence information that includes information about roles,
154      * affiliations, JIDs, etc.
155      *
156      * @return the extended presence information that includes information about roles,
157      * affiliations.
158      */
159     public Element getExtendedPresenceInformation();
160
161     /**
162      * Set the current presence status of a user in a chatroom.
163      *
164      * @param presence The presence of the user in the room.
165      */
166     public void setPresence(Presence presence);
167
168     /**
169      * Call this method to promote or demote a user's role in a chatroom.
170      * It is common for the chatroom or other chat room members to change
171      * the role of users (a moderator promoting another user to moderator
172      * status for example).<p>
173      * <p/>
174      * Owning ChatUsers should have their membership roles updated.
175      *
176      * @param newRole The new role that the user will play.
177      * @throws NotAllowedException Thrown if trying to change the moderator role to an owner or
178      * administrator.
179      */
180     public void setRole(Role newRole) throws NotAllowedException;
181
182     /**
183      * Obtain the role state of the user.
184      *
185      * @return The role status of this user.
186      */
187     public Role getRole();
188
189     /**
190      * Call this method to promote or demote a user's affiliation in a chatroom.
191      *
192      * @param newAffiliation the new affiliation that the user will play.
193      * @throws NotAllowedException thrown if trying to ban an owner or an administrator.
194      */
195     public void setAffiliation(Affiliation newAffiliation) throws NotAllowedException;
196
197     /**
198      * Obtain the affiliation state of the user.
199      *
200      * @return The affiliation status of this user.
201      */
202     public Affiliation getAffiliation();
203
204     /**
205      * Obtain the nickname for the user in the chatroom.
206      *
207      * @return The user's nickname in the room or null if invisible.
208      */
209     public String JavaDoc getNickname();
210
211     /**
212      * Changes the nickname of the occupant within the room to the new nickname.
213      *
214      * @param nickname the new nickname of the occupant in the room.
215      */
216     public void changeNickname(String JavaDoc nickname);
217
218     /**
219      * Obtain the chat user that plays this role.
220      *
221      * @return The chatuser playing this role.
222      */
223     public MUCUser getChatUser();
224
225     /**
226      * Obtain the chat room that hosts this user's role.
227      *
228      * @return The chatroom hosting this role.
229      */
230     public MUCRoom getChatRoom();
231
232     /**
233      * Obtain the XMPPAddress representing this role in a room: room@server/nickname
234      *
235      * @return The Jabber ID that represents this role in the room.
236      */
237     public JID getRoleAddress();
238
239     /**
240      * Sends a packet to the user.
241      *
242      * @param packet The packet to send
243      */
244     public void send(Packet packet);
245 }
Popular Tags