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;
019
020import org.jivesoftware.smack.packet.NamedElement;
021import org.jivesoftware.smack.packet.Stanza;
022import org.jivesoftware.smack.packet.ExtensionElement;
023import org.jivesoftware.smack.util.XmlStringBuilder;
024import org.jxmpp.util.XmppDateTime;
025
026import java.util.Date;
027
028/**
029 * Represents extended presence information whose sole purpose is to signal the ability of 
030 * the occupant to speak the MUC protocol when joining a room. If the room requires a password 
031 * then the MUCInitialPresence should include one.
032 * <p>
033 * The amount of discussion history provided on entering a room (perhaps because the 
034 * user is on a low-bandwidth connection or is using a small-footprint client) could be managed by
035 * setting a configured History instance to the MUCInitialPresence instance. 
036 *
037 * @author Gaston Dombiak
038 * @see MUCInitialPresence#setHistory(MUCInitialPresence.History)
039 */
040public class MUCInitialPresence implements ExtensionElement {
041
042    public static final String ELEMENT = "x";
043    public static final String NAMESPACE = "http://jabber.org/protocol/muc";
044
045    // TODO make those fields final once deprecated setter methods have been removed.
046    private String password;
047    private History history; 
048
049    /**
050     * Deprecated constructor.
051     * @deprecated use {@link #MUCInitialPresence(String, int, int, int, Date)} instead.
052     */
053    @Deprecated
054    public MUCInitialPresence() {
055    }
056
057    /**
058     * Construct a new MUC initial presence extension.
059     *
060     * @param password the optional password used to enter the room.
061     * @param maxChars the maximal count of characters of history to request.
062     * @param maxStanzas the maximal count of stanzas of history to request.
063     * @param seconds the last seconds since when to request history.
064     * @param since the date since when to request history.
065     */
066    public MUCInitialPresence(String password, int maxChars, int maxStanzas, int seconds, Date since) {
067        this.password = password;
068        if (maxChars > -1 || maxStanzas > -1 || seconds > -1 || since != null) {
069            this.history = new History(maxChars, maxStanzas, seconds, since);
070        } else {
071            this.history = null;
072        }
073    }
074
075    @Override
076    public String getElementName() {
077        return ELEMENT;
078    }
079
080    @Override
081    public String getNamespace() {
082        return NAMESPACE;
083    }
084
085    @Override
086    public XmlStringBuilder toXML() {
087        XmlStringBuilder xml = new XmlStringBuilder(this);
088        xml.rightAngleBracket();
089        xml.optElement("password", getPassword());
090        xml.optElement(getHistory());
091        xml.closeElement(this);
092        return xml;
093    }
094
095    /**
096     * Returns the history that manages the amount of discussion history provided on 
097     * entering a room.
098     * 
099     * @return the history that manages the amount of discussion history provided on 
100     * entering a room.
101     */
102    public History getHistory() {
103        return history;
104    }
105
106    /**
107     * Returns the password to use when the room requires a password.
108     * 
109     * @return the password to use when the room requires a password.
110     */
111    public String getPassword() {
112        return password;
113    }
114
115    /**
116     * Sets the History that manages the amount of discussion history provided on 
117     * entering a room.
118     * 
119     * @param history that manages the amount of discussion history provided on 
120     * entering a room.
121     * @deprecated use {@link #MUCInitialPresence(String, int, int, int, Date)} instead.
122     */
123    @Deprecated
124    public void setHistory(History history) {
125        this.history = history;
126    }
127
128    /**
129     * Sets the password to use when the room requires a password.
130     * 
131     * @param password the password to use when the room requires a password.
132     * @deprecated use {@link #MUCInitialPresence(String, int, int, int, Date)} instead.
133     */
134    @Deprecated
135    public void setPassword(String password) {
136        this.password = password;
137    }
138
139    /**
140     * Retrieve the MUCInitialPresence PacketExtension from packet, if any.
141     *
142     * @param packet
143     * @return the MUCInitialPresence PacketExtension or {@code null}
144     * @deprecated use {@link #from(Stanza)} instead
145     */
146    @Deprecated
147    public static MUCInitialPresence getFrom(Stanza packet) {
148        return from(packet);
149    }
150
151    /**
152     * Retrieve the MUCInitialPresence PacketExtension from packet, if any.
153     *
154     * @param packet
155     * @return the MUCInitialPresence PacketExtension or {@code null}
156     */
157    public static MUCInitialPresence from(Stanza packet) {
158        return packet.getExtension(ELEMENT, NAMESPACE);
159    }
160
161    /**
162     * The History class controls the number of characters or messages to receive
163     * when entering a room.
164     * 
165     * @author Gaston Dombiak
166     */
167    public static class History implements NamedElement {
168
169        public static final String ELEMENT = "history";
170
171        // TODO make those fields final once the deprecated setter methods have been removed.
172        private int maxChars;
173        private int maxStanzas;
174        private int seconds;
175        private Date since; 
176
177        /**
178         * Deprecated constructor.
179         * @deprecated use {@link #MUCInitialPresence.History(int, int, int, Date)} instead.
180         */
181        @Deprecated
182        public History() {
183            this.maxChars = -1;
184            this.maxStanzas = -1;
185            this.seconds = -1;
186        }
187
188        public History(int maxChars, int maxStanzas, int seconds, Date since) {
189            if (maxChars < 0 && maxStanzas < 0 && seconds < 0 && since == null) {
190                throw new IllegalArgumentException();
191            }
192            this.maxChars = maxChars;
193            this.maxStanzas = maxStanzas;
194            this.seconds = seconds;
195            this.since = since;
196        }
197
198        /**
199         * Returns the total number of characters to receive in the history.
200         * 
201         * @return total number of characters to receive in the history.
202         */
203        public int getMaxChars() {
204            return maxChars;
205        }
206
207        /**
208         * Returns the total number of messages to receive in the history.
209         * 
210         * @return the total number of messages to receive in the history.
211         */
212        public int getMaxStanzas() {
213            return maxStanzas;
214        }
215
216        /**
217         * Returns the number of seconds to use to filter the messages received during that time. 
218         * In other words, only the messages received in the last "X" seconds will be included in 
219         * the history.
220         * 
221         * @return the number of seconds to use to filter the messages received during that time.
222         */
223        public int getSeconds() {
224            return seconds;
225        }
226
227        /**
228         * Returns the since date to use to filter the messages received during that time. 
229         * In other words, only the messages received since the datetime specified will be 
230         * included in the history.
231         * 
232         * @return the since date to use to filter the messages received during that time.
233         */
234        public Date getSince() {
235            return since;
236        }
237
238        /**
239         * Sets the total number of characters to receive in the history.
240         * 
241         * @param maxChars the total number of characters to receive in the history.
242         * @deprecated use {@link #MUCInitialPresence.History(int, int, int, Date)} instead.
243         */
244        @Deprecated
245        public void setMaxChars(int maxChars) {
246            this.maxChars = maxChars;
247        }
248
249        /**
250         * Sets the total number of messages to receive in the history.
251         * 
252         * @param maxStanzas the total number of messages to receive in the history.
253         * @deprecated use {@link #MUCInitialPresence.History(int, int, int, Date)} instead.
254         */
255        @Deprecated
256        public void setMaxStanzas(int maxStanzas) {
257            this.maxStanzas = maxStanzas;
258        }
259
260        /**
261         * Sets the number of seconds to use to filter the messages received during that time. 
262         * In other words, only the messages received in the last "X" seconds will be included in 
263         * the history.
264         * 
265         * @param seconds the number of seconds to use to filter the messages received during 
266         * that time.
267         * @deprecated use {@link #MUCInitialPresence.History(int, int, int, Date)} instead.
268         */
269        @Deprecated
270        public void setSeconds(int seconds) {
271            this.seconds = seconds;
272        }
273
274        /**
275         * Sets the since date to use to filter the messages received during that time. 
276         * In other words, only the messages received since the datetime specified will be 
277         * included in the history.
278         * 
279         * @param since the since date to use to filter the messages received during that time.
280         * @deprecated use {@link #MUCInitialPresence.History(int, int, int, Date)} instead.
281         */
282        @Deprecated
283        public void setSince(Date since) {
284            this.since = since;
285        }
286
287        @Override
288        public XmlStringBuilder toXML() {
289            XmlStringBuilder xml = new XmlStringBuilder(this);
290            xml.optIntAttribute("maxchars", getMaxChars());
291            xml.optIntAttribute("maxstanzas", getMaxStanzas());
292            xml.optIntAttribute("seconds", getSeconds());
293            if (getSince() != null) {
294                xml.attribute("since", XmppDateTime.formatXEP0082Date(getSince()));
295            }
296            xml.closeEmptyElement();
297            return xml;
298        }
299
300        @Override
301        public String getElementName() {
302            return ELEMENT;
303        }
304    }
305}