forked from igniterealtime/Smack
/
Stanza.java
500 lines (455 loc) · 16 KB
/
Stanza.java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
/**
*
* Copyright 2003-2007 Jive Software.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.jivesoftware.smack.packet;
import static org.jivesoftware.smack.util.StringUtils.requireNotNullOrEmpty;
import org.jivesoftware.smack.packet.id.StanzaIdUtil;
import org.jivesoftware.smack.util.MultiMap;
import org.jivesoftware.smack.util.PacketUtil;
import org.jivesoftware.smack.util.XmlStringBuilder;
import org.jxmpp.jid.Jid;
import org.jxmpp.jid.impl.JidCreate;
import org.jxmpp.stringprep.XmppStringprepException;
import org.jxmpp.util.XmppStringUtils;
import java.util.Collection;
import java.util.List;
import java.util.Locale;
/**
* Base class for XMPP Stanzas, which are called Stanza(/Packet) in older versions of Smack (i.e. < 4.1).
* <p>
* Every stanza has a unique ID (which is automatically generated, but can be overridden). Stanza
* IDs are required for IQ stanzas and recommended for presence and message stanzas. Optionally, the
* "to" and "from" fields can be set.
* </p>
* <p>
* XMPP Stanzas are {@link Message}, {@link IQ} and {@link Presence}. Which therefore subclass this
* class. <b>If you think you need to subclass this class, then you are doing something wrong.</b>
* </p>
*
* @author Matt Tucker
* @see <a href="http://xmpp.org/rfcs/rfc6120.html#stanzas">RFC 6120 § 8. XML Stanzas</a>
*/
public abstract class Stanza implements TopLevelStreamElement {
public static final String TEXT = "text";
public static final String ITEM = "item";
protected static final String DEFAULT_LANGUAGE =
java.util.Locale.getDefault().getLanguage().toLowerCase(Locale.US);
private final MultiMap<String, ExtensionElement> packetExtensions = new MultiMap<>();
private String id = null;
private Jid to;
private Jid from;
private XMPPError error = null;
/**
* Optional value of the 'xml:lang' attribute of the outermost element of
* the stanza.
* <p>
* Such an attribute is defined for all stanza types. For IQ, see for
* example XEP-50 3.7:
* "The requester SHOULD provide its locale information using the "xml:lang
* " attribute on either the <iq/> (RECOMMENDED) or <command/> element."
* </p>
*/
protected String language;
protected Stanza() {
this(StanzaIdUtil.newStanzaId());
}
protected Stanza(String stanzaId) {
setStanzaId(stanzaId);
}
protected Stanza(Stanza p) {
id = p.getStanzaId();
to = p.getTo();
from = p.getFrom();
error = p.error;
// Copy extensions
for (ExtensionElement pe : p.getExtensions()) {
addExtension(pe);
}
}
/**
* Returns the unique ID of the stanza. The returned value could be <code>null</code>.
*
* @return the packet's unique ID or <code>null</code> if the id is not available.
*/
public String getStanzaId() {
return id;
}
/**
* Get the Stanza ID.
* @return the stanza id.
* @deprecated use {@link #getStanzaId()} instead.
*/
@Deprecated
public String getPacketID() {
return getStanzaId();
}
/**
* Sets the unique ID of the packet. To indicate that a stanza(/packet) has no id
* pass <code>null</code> as the packet's id value.
*
* @param id the unique ID for the packet.
*/
public void setStanzaId(String id) {
if (id != null) {
requireNotNullOrEmpty(id, "id must either be null or not the empty String");
}
this.id = id;
}
/**
* Set the stanza ID.
* @param packetID
* @deprecated use {@link #setStanzaId(String)} instead.
*/
@Deprecated
public void setPacketID(String packetID) {
setStanzaId(packetID);
}
/**
* Check if this stanza has an ID set.
*
* @return true if the stanza ID is set, false otherwise.
* @since 4.1
*/
public boolean hasStanzaIdSet() {
// setStanzaId ensures that the id is either null or not empty,
// so we can assume that it is set if it's not null.
return id != null;
}
/**
* Returns who the stanza(/packet) is being sent "to", or <tt>null</tt> if
* the value is not set. The XMPP protocol often makes the "to"
* attribute optional, so it does not always need to be set.<p>
*
* @return who the stanza(/packet) is being sent to, or <tt>null</tt> if the
* value has not been set.
*/
public Jid getTo() {
return to;
}
/**
* Sets who the stanza(/packet) is being sent "to". The XMPP protocol often makes
* the "to" attribute optional, so it does not always need to be set.
*
* @param to who the stanza(/packet) is being sent to.
* @throws IllegalArgumentException if to is not a valid JID String.
* @deprecated use {@link #setTo(Jid)} instead.
*/
@Deprecated
public void setTo(String to) {
Jid jid;
try {
jid = JidCreate.from(to);
}
catch (XmppStringprepException e) {
throw new IllegalArgumentException(e);
}
setTo(jid);
}
/**
* Sets who the packet is being sent "to". The XMPP protocol often makes
* the "to" attribute optional, so it does not always need to be set.
*
* @param to who the packet is being sent to.
*/
public void setTo(Jid to) {
this.to = to;
}
/**
* Returns who the stanza(/packet) is being sent "from" or <tt>null</tt> if
* the value is not set. The XMPP protocol often makes the "from"
* attribute optional, so it does not always need to be set.<p>
*
* @return who the stanza(/packet) is being sent from, or <tt>null</tt> if the
* value has not been set.
*/
public Jid getFrom() {
return from;
}
/**
* Sets who the stanza(/packet) is being sent "from". The XMPP protocol often
* makes the "from" attribute optional, so it does not always need to
* be set.
*
* @param from who the stanza(/packet) is being sent to.
* @throws IllegalArgumentException if from is not a valid JID String.
* @deprecated use {@link #setFrom(Jid)} instead.
*/
@Deprecated
public void setFrom(String from) {
Jid jid;
try {
jid = JidCreate.from(from);
}
catch (XmppStringprepException e) {
throw new IllegalArgumentException(e);
}
setFrom(jid);
}
/**
* Sets who the packet is being sent "from". The XMPP protocol often
* makes the "from" attribute optional, so it does not always need to
* be set.
*
* @param from who the packet is being sent to.
*/
public void setFrom(Jid from) {
this.from = from;
}
/**
* Returns the error associated with this packet, or <tt>null</tt> if there are
* no errors.
*
* @return the error sub-packet or <tt>null</tt> if there isn't an error.
*/
public XMPPError getError() {
return error;
}
/**
* Sets the error for this packet.
*
* @param error the error to associate with this packet.
*/
public void setError(XMPPError error) {
this.error = error;
}
/**
* Returns the xml:lang of this Stanza, or null if one has not been set.
*
* @return the xml:lang of this Stanza, or null.
*/
public String getLanguage() {
return language;
}
/**
* Sets the xml:lang of this Stanza.
*
* @param language the xml:lang of this Stanza.
*/
public void setLanguage(String language) {
this.language = language;
}
/**
* Returns a list of all extension elements of this stanza.
*
* @return a list of all extension elements of this stanza.
*/
public List<ExtensionElement> getExtensions() {
synchronized (packetExtensions) {
// No need to create a new list, values() will already create a new one for us
return packetExtensions.values();
}
}
/**
* Return a list of all extensions with the given element name <em>and</em> namespace.
* <p>
* Changes to the returned set will update the stanza(/packet) extensions, if the returned set is not the empty set.
* </p>
*
* @param elementName the element name, must not be null.
* @param namespace the namespace of the element(s), must not be null.
* @return a set of all matching extensions.
* @since 4.1
*/
public List<ExtensionElement> getExtensions(String elementName, String namespace) {
requireNotNullOrEmpty(elementName, "elementName must not be null or empty");
requireNotNullOrEmpty(namespace, "namespace must not be null or empty");
String key = XmppStringUtils.generateKey(elementName, namespace);
return packetExtensions.getAll(key);
}
/**
* Returns the first extension of this stanza(/packet) that has the given namespace.
* <p>
* When possible, use {@link #getExtension(String,String)} instead.
* </p>
*
* @param namespace the namespace of the extension that is desired.
* @return the stanza(/packet) extension with the given namespace.
*/
public ExtensionElement getExtension(String namespace) {
return PacketUtil.extensionElementFrom(getExtensions(), null, namespace);
}
/**
* Returns the first extension that matches the specified element name and
* namespace, or <tt>null</tt> if it doesn't exist. If the provided elementName is null,
* only the namespace is matched. Extensions are
* are arbitrary XML elements in standard XMPP stanzas.
*
* @param elementName the XML element name of the extension. (May be null)
* @param namespace the XML element namespace of the extension.
* @return the extension, or <tt>null</tt> if it doesn't exist.
*/
@SuppressWarnings("unchecked")
public <PE extends ExtensionElement> PE getExtension(String elementName, String namespace) {
if (namespace == null) {
return null;
}
String key = XmppStringUtils.generateKey(elementName, namespace);
ExtensionElement packetExtension;
synchronized (packetExtensions) {
packetExtension = packetExtensions.getFirst(key);
}
if (packetExtension == null) {
return null;
}
return (PE) packetExtension;
}
/**
* Adds a stanza(/packet) extension to the packet. Does nothing if extension is null.
*
* @param extension a stanza(/packet) extension.
*/
public void addExtension(ExtensionElement extension) {
if (extension == null) return;
String key = XmppStringUtils.generateKey(extension.getElementName(), extension.getNamespace());
synchronized (packetExtensions) {
packetExtensions.put(key, extension);
}
}
/**
* Add the given extension and override eventually existing extensions with the same name and
* namespace.
*
* @param extension the extension element to add.
* @return one of the removed extensions or <code>null</code> if there are none.
* @since 4.1.2
*/
public ExtensionElement overrideExtension(ExtensionElement extension) {
if (extension == null) return null;
synchronized (packetExtensions) {
ExtensionElement removedExtension = removeExtension(extension);
addExtension(extension);
return removedExtension;
}
}
/**
* Adds a collection of stanza(/packet) extensions to the packet. Does nothing if extensions is null.
*
* @param extensions a collection of stanza(/packet) extensions
*/
public void addExtensions(Collection<ExtensionElement> extensions) {
if (extensions == null) return;
for (ExtensionElement packetExtension : extensions) {
addExtension(packetExtension);
}
}
/**
* Check if a stanza(/packet) extension with the given element and namespace exists.
* <p>
* The argument <code>elementName</code> may be null.
* </p>
*
* @param elementName
* @param namespace
* @return true if a stanza(/packet) extension exists, false otherwise.
*/
public boolean hasExtension(String elementName, String namespace) {
if (elementName == null) {
return hasExtension(namespace);
}
String key = XmppStringUtils.generateKey(elementName, namespace);
synchronized (packetExtensions) {
return packetExtensions.containsKey(key);
}
}
/**
* Check if a stanza(/packet) extension with the given namespace exists.
*
* @param namespace
* @return true if a stanza(/packet) extension exists, false otherwise.
*/
public boolean hasExtension(String namespace) {
synchronized (packetExtensions) {
for (ExtensionElement packetExtension : packetExtensions.values()) {
if (packetExtension.getNamespace().equals(namespace)) {
return true;
}
}
}
return false;
}
/**
* Remove the stanza(/packet) extension with the given elementName and namespace.
*
* @param elementName
* @param namespace
* @return the removed stanza(/packet) extension or null.
*/
public ExtensionElement removeExtension(String elementName, String namespace) {
String key = XmppStringUtils.generateKey(elementName, namespace);
synchronized (packetExtensions) {
return packetExtensions.remove(key);
}
}
/**
* Removes a stanza(/packet) extension from the packet.
*
* @param extension the stanza(/packet) extension to remove.
* @return the removed stanza(/packet) extension or null.
*/
public ExtensionElement removeExtension(ExtensionElement extension) {
return removeExtension(extension.getElementName(), extension.getNamespace());
}
@Override
// NOTE When Smack is using Java 8, then this method should be moved in Element as "Default Method".
public String toString() {
return toXML().toString();
}
/**
* Returns the extension sub-packets (including properties data) as an XML
* String, or the Empty String if there are no stanza(/packet) extensions.
*
* @return the extension sub-packets as XML or the Empty String if there
* are no stanza(/packet) extensions.
*/
protected final XmlStringBuilder getExtensionsXML() {
XmlStringBuilder xml = new XmlStringBuilder();
// Add in all standard extension sub-packets.
for (ExtensionElement extension : getExtensions()) {
xml.append(extension.toXML());
}
return xml;
}
/**
* Returns the default language used for all messages containing localized content.
*
* @return the default language
*/
public static String getDefaultLanguage() {
return DEFAULT_LANGUAGE;
}
/**
* Add to, from, id and 'xml:lang' attributes
*
* @param xml
*/
protected void addCommonAttributes(XmlStringBuilder xml) {
xml.optAttribute("to", getTo());
xml.optAttribute("from", getFrom());
xml.optAttribute("id", getStanzaId());
xml.xmllangAttribute(getLanguage());
}
/**
* Append an XMPPError is this stanza(/packet) has one set.
*
* @param xml the XmlStringBuilder to append the error to.
*/
protected void appendErrorIfExists(XmlStringBuilder xml) {
XMPPError error = getError();
if (error != null) {
xml.append(error.toXML());
}
}
}