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 java.util.ArrayList;
020import java.util.Collections;
021import java.util.List;
022
023import org.jivesoftware.smack.packet.IQ;
024
025/**
026 * IQ packet that serves for kicking users, granting and revoking voice, banning users, 
027 * modifying the ban list, granting and revoking membership and granting and revoking 
028 * moderator privileges. All these operations are scoped by the 
029 * 'http://jabber.org/protocol/muc#admin' namespace.
030 * 
031 * @author Gaston Dombiak
032 */
033public class MUCAdmin extends IQ {
034
035    private List<Item> items = new ArrayList<Item>();
036
037    /**
038     * Returns a List of item childs that holds information about roles, affiliation,
039     * jids and nicks.
040     * 
041     * @return a List of item childs that holds information about roles, 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     * Adds an item child that holds information about roles, affiliation, jids and nicks.
052     * 
053     * @param item the item child that holds information about roles, affiliation, jids and nicks.
054     */
055    public void addItem(Item item) {
056        synchronized (items) {
057            items.add(item);
058        }
059    }
060
061    public String getChildElementXML() {
062        StringBuilder buf = new StringBuilder();
063        buf.append("<query xmlns=\"http://jabber.org/protocol/muc#admin\">");
064        synchronized (items) {
065            for (int i = 0; i < items.size(); i++) {
066                Item item = items.get(i);
067                buf.append(item.toXML());
068            }
069        }
070        // Add packet extensions, if any are defined.
071        buf.append(getExtensionsXML());
072        buf.append("</query>");
073        return buf.toString();
074    }
075
076    /**
077     * Item child that holds information about roles, affiliation, jids and nicks.
078     *
079     * @author Gaston Dombiak
080     */
081    public static class Item {
082        private String actor;
083        private String reason;
084        private String affiliation;
085        private String jid;
086        private String nick;
087        private String role;
088        
089        /**
090         * Creates a new item child. 
091         * 
092         * @param affiliation the actor's affiliation to the room
093         * @param role the privilege level of an occupant within a room.
094         */
095        public Item(String affiliation, String role) {
096            this.affiliation = affiliation;
097            this.role = role;
098        }
099        
100        /**
101         * Returns the actor (JID of an occupant in the room) that was kicked or banned.
102         * 
103         * @return the JID of an occupant in the room that was kicked or banned.
104         */
105        public String getActor() {
106            return actor;
107        }
108
109        /**
110         * Returns the reason for the item child. The reason is optional and could be used to
111         * explain the reason why a user (occupant) was kicked or banned.
112         *  
113         * @return the reason for the item child.
114         */
115        public String getReason() {
116            return reason;
117        }
118
119        /**
120         * Returns the occupant's affiliation to the room. The affiliation is a semi-permanent 
121         * association or connection with a room. The possible affiliations are "owner", "admin", 
122         * "member", and "outcast" (naturally it is also possible to have no affiliation). An 
123         * affiliation lasts across a user's visits to a room.
124         * 
125         * @return the actor's affiliation to the room
126         */
127        public String getAffiliation() {
128            return affiliation;
129        }
130
131        /**
132         * Returns the <room@service/nick> by which an occupant is identified within the context 
133         * of a room. If the room is non-anonymous, the JID will be included in the item. 
134         * 
135         * @return the room JID by which an occupant is identified within the room.
136         */
137        public String getJid() {
138            return jid;
139        }
140
141        /**
142         * Returns the new nickname of an occupant that is changing his/her nickname. The new 
143         * nickname is sent as part of the unavailable presence.  
144         * 
145         * @return the new nickname of an occupant that is changing his/her nickname.
146         */
147        public String getNick() {
148            return nick;
149        }
150
151        /**
152         * Returns the temporary position or privilege level of an occupant within a room. The 
153         * possible roles are "moderator", "participant", and "visitor" (it is also possible to 
154         * have no defined role). A role lasts only for the duration of an occupant's visit to 
155         * a room. 
156         * 
157         * @return the privilege level of an occupant within a room.
158         */
159        public String getRole() {
160            return role;
161        }
162
163        /**
164         * Sets the actor (JID of an occupant in the room) that was kicked or banned.
165         * 
166         * @param actor the actor (JID of an occupant in the room) that was kicked or banned.
167         */
168        public void setActor(String actor) {
169            this.actor = actor;
170        }
171
172        /**
173         * Sets the reason for the item child. The reason is optional and could be used to
174         * explain the reason why a user (occupant) was kicked or banned.
175         * 
176         * @param reason the reason why a user (occupant) was kicked or banned.
177         */
178        public void setReason(String reason) {
179            this.reason = reason;
180        }
181
182        /**
183         * Sets the <room@service/nick> by which an occupant is identified within the context 
184         * of a room. If the room is non-anonymous, the JID will be included in the item.
185         *  
186         * @param jid the JID by which an occupant is identified within a room.
187         */
188        public void setJid(String jid) {
189            this.jid = jid;
190        }
191
192        /**
193         * Sets the new nickname of an occupant that is changing his/her nickname. The new 
194         * nickname is sent as part of the unavailable presence.
195         *   
196         * @param nick the new nickname of an occupant that is changing his/her nickname.
197         */
198        public void setNick(String nick) {
199            this.nick = nick;
200        }
201
202        public String toXML() {
203            StringBuilder buf = new StringBuilder();
204            buf.append("<item");
205            if (getAffiliation() != null) {
206                buf.append(" affiliation=\"").append(getAffiliation()).append("\"");
207            }
208            if (getJid() != null) {
209                buf.append(" jid=\"").append(getJid()).append("\"");
210            }
211            if (getNick() != null) {
212                buf.append(" nick=\"").append(getNick()).append("\"");
213            }
214            if (getRole() != null) {
215                buf.append(" role=\"").append(getRole()).append("\"");
216            }
217            if (getReason() == null && getActor() == null) {
218                buf.append("/>");
219            }
220            else {
221                buf.append(">");
222                if (getReason() != null) {
223                    buf.append("<reason>").append(getReason()).append("</reason>");
224                }
225                if (getActor() != null) {
226                    buf.append("<actor jid=\"").append(getActor()).append("\"/>");
227                }
228                buf.append("</item>");
229            }
230            return buf.toString();
231        }
232    };
233}