001/**
002 *
003 * Copyright 2003-2007 Jive Software.
004 *
005 * Licensed under the Apache License, Version 2.0 (the "License");
006 * you may not use this file except in compliance with the License.
007 * You may obtain a copy of the License at
008 *
009 *     http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018package org.jivesoftware.smackx.muc.packet;
019import org.jivesoftware.smack.packet.IQ;
020
021import java.util.ArrayList;
022import java.util.Collections;
023import java.util.List;
024
025/**
026 * IQ packet that serves for granting and revoking ownership privileges, granting 
027 * and revoking administrative privileges and destroying a room. All these operations 
028 * are scoped by the 'http://jabber.org/protocol/muc#owner' namespace.
029 * 
030 * @author Gaston Dombiak
031 */
032public class MUCOwner extends IQ {
033
034    private List<Item> items = new ArrayList<Item>();
035    private Destroy destroy;
036
037    /**
038     * Returns a List of item childs that holds information about affiliation,
039     * jids and nicks.
040     * 
041     * @return a List of item childs that holds information about affiliation,
042     *          jids and nicks.
043     */
044    public List<Item> getItems() {
045        synchronized (items) {
046            return Collections.unmodifiableList(new ArrayList<Item>(items));
047        }
048    }
049
050    /**
051     * Returns a request to the server to destroy a room. The sender of the request
052     * should be the room's owner. If the sender of the destroy request is not the room's owner
053     * then the server will answer a "Forbidden" error.
054     * 
055     * @return a request to the server to destroy a room.
056     */
057    public Destroy getDestroy() {
058        return destroy;
059    }
060
061    /**
062     * Sets a request to the server to destroy a room. The sender of the request
063     * should be the room's owner. If the sender of the destroy request is not the room's owner
064     * then the server will answer a "Forbidden" error.
065     * 
066     * @param destroy the request to the server to destroy a room.
067     */
068    public void setDestroy(Destroy destroy) {
069        this.destroy = destroy;
070    }
071
072    /**
073     * Adds an item child that holds information about affiliation, jids and nicks.
074     * 
075     * @param item the item child that holds information about affiliation, jids and nicks.
076     */
077    public void addItem(Item item) {
078        synchronized (items) {
079            items.add(item);
080        }
081    }
082
083    public String getChildElementXML() {
084        StringBuilder buf = new StringBuilder();
085        buf.append("<query xmlns=\"http://jabber.org/protocol/muc#owner\">");
086        synchronized (items) {
087            for (int i = 0; i < items.size(); i++) {
088                Item item = (Item) items.get(i);
089                buf.append(item.toXML());
090            }
091        }
092        if (getDestroy() != null) {
093            buf.append(getDestroy().toXML());
094        }
095        // Add packet extensions, if any are defined.
096        buf.append(getExtensionsXML());
097        buf.append("</query>");
098        return buf.toString();
099    }
100
101    /**
102     * Item child that holds information about affiliation, jids and nicks.
103     *
104     * @author Gaston Dombiak
105     */
106    public static class Item {
107        
108        private String actor;
109        private String reason;
110        private String affiliation;
111        private String jid;
112        private String nick;
113        private String role;
114
115        /**
116         * Creates a new item child. 
117         * 
118         * @param affiliation the actor's affiliation to the room
119         */
120        public Item(String affiliation) {
121            this.affiliation = affiliation;
122        }
123        
124        /**
125         * Returns the actor (JID of an occupant in the room) that was kicked or banned.
126         * 
127         * @return the JID of an occupant in the room that was kicked or banned.
128         */
129        public String getActor() {
130            return actor;
131        }
132
133        /**
134         * Returns the reason for the item child. The reason is optional and could be used to
135         * explain the reason why a user (occupant) was kicked or banned.
136         *  
137         * @return the reason for the item child.
138         */
139        public String getReason() {
140            return reason;
141        }
142
143        /**
144         * Returns the occupant's affiliation to the room. The affiliation is a semi-permanent 
145         * association or connection with a room. The possible affiliations are "owner", "admin", 
146         * "member", and "outcast" (naturally it is also possible to have no affiliation). An 
147         * affiliation lasts across a user's visits to a room.
148         * 
149         * @return the actor's affiliation to the room
150         */
151        public String getAffiliation() {
152            return affiliation;
153        }
154
155        /**
156         * Returns the <room@service/nick> by which an occupant is identified within the context 
157         * of a room. If the room is non-anonymous, the JID will be included in the item. 
158         * 
159         * @return the room JID by which an occupant is identified within the room.
160         */
161        public String getJid() {
162            return jid;
163        }
164
165        /**
166         * Returns the new nickname of an occupant that is changing his/her nickname. The new 
167         * nickname is sent as part of the unavailable presence.  
168         * 
169         * @return the new nickname of an occupant that is changing his/her nickname.
170         */
171        public String getNick() {
172            return nick;
173        }
174
175        /**
176         * Returns the temporary position or privilege level of an occupant within a room. The
177         * possible roles are "moderator", "participant", and "visitor" (it is also possible to
178         * have no defined role). A role lasts only for the duration of an occupant's visit to
179         * a room.
180         *
181         * @return the privilege level of an occupant within a room.
182         */
183        public String getRole() {
184            return role;
185        }
186
187        /**
188         * Sets the actor (JID of an occupant in the room) that was kicked or banned.
189         * 
190         * @param actor the actor (JID of an occupant in the room) that was kicked or banned.
191         */
192        public void setActor(String actor) {
193            this.actor = actor;
194        }
195
196        /**
197         * Sets the reason for the item child. The reason is optional and could be used to
198         * explain the reason why a user (occupant) was kicked or banned.
199         * 
200         * @param reason the reason why a user (occupant) was kicked or banned.
201         */
202        public void setReason(String reason) {
203            this.reason = reason;
204        }
205
206        /**
207         * Sets the <room@service/nick> by which an occupant is identified within the context 
208         * of a room. If the room is non-anonymous, the JID will be included in the item.
209         *  
210         * @param jid the JID by which an occupant is identified within a room.
211         */
212        public void setJid(String jid) {
213            this.jid = jid;
214        }
215
216        /**
217         * Sets the new nickname of an occupant that is changing his/her nickname. The new 
218         * nickname is sent as part of the unavailable presence.
219         *   
220         * @param nick the new nickname of an occupant that is changing his/her nickname.
221         */
222        public void setNick(String nick) {
223            this.nick = nick;
224        }
225
226        /**
227         * Sets the temporary position or privilege level of an occupant within a room. The
228         * possible roles are "moderator", "participant", and "visitor" (it is also possible to
229         * have no defined role). A role lasts only for the duration of an occupant's visit to
230         * a room.
231         *
232         * @param role the new privilege level of an occupant within a room.
233         */
234        public void setRole(String role) {
235            this.role = role;
236        }
237
238        public String toXML() {
239            StringBuilder buf = new StringBuilder();
240            buf.append("<item");
241            if (getAffiliation() != null) {
242                buf.append(" affiliation=\"").append(getAffiliation()).append("\"");
243            }
244            if (getJid() != null) {
245                buf.append(" jid=\"").append(getJid()).append("\"");
246            }
247            if (getNick() != null) {
248                buf.append(" nick=\"").append(getNick()).append("\"");
249            }
250            if (getRole() != null) {
251                buf.append(" role=\"").append(getRole()).append("\"");
252            }
253            if (getReason() == null && getActor() == null) {
254                buf.append("/>");
255            }
256            else {
257                buf.append(">");
258                if (getReason() != null) {
259                    buf.append("<reason>").append(getReason()).append("</reason>");
260                }
261                if (getActor() != null) {
262                    buf.append("<actor jid=\"").append(getActor()).append("\"/>");
263                }
264                buf.append("</item>");
265            }
266            return buf.toString();
267        }
268    };
269
270    /**
271     * Represents a request to the server to destroy a room. The sender of the request
272     * should be the room's owner. If the sender of the destroy request is not the room's owner
273     * then the server will answer a "Forbidden" error.
274     * 
275     * @author Gaston Dombiak
276     */
277    public static class Destroy {
278        private String reason;
279        private String jid;
280        
281        
282        /**
283         * Returns the JID of an alternate location since the current room is being destroyed.
284         * 
285         * @return the JID of an alternate location.
286         */
287        public String getJid() {
288            return jid;
289        }
290
291        /**
292         * Returns the reason for the room destruction.
293         * 
294         * @return the reason for the room destruction.
295         */
296        public String getReason() {
297            return reason;
298        }
299
300        /**
301         * Sets the JID of an alternate location since the current room is being destroyed.
302         * 
303         * @param jid the JID of an alternate location.
304         */
305        public void setJid(String jid) {
306            this.jid = jid;
307        }
308
309        /**
310         * Sets the reason for the room destruction.
311         * 
312         * @param reason the reason for the room destruction.
313         */
314        public void setReason(String reason) {
315            this.reason = reason;
316        }
317
318        public String toXML() {
319            StringBuilder buf = new StringBuilder();
320            buf.append("<destroy");
321            if (getJid() != null) {
322                buf.append(" jid=\"").append(getJid()).append("\"");
323            }
324            if (getReason() == null) {
325                buf.append("/>");
326            }
327            else {
328                buf.append(">");
329                if (getReason() != null) {
330                    buf.append("<reason>").append(getReason()).append("</reason>");
331                }
332                buf.append("</destroy>");
333            }
334            return buf.toString();
335        }
336
337    }
338}