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}