/** * * 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.requireNotNullNorEmpty; import java.util.Collection; import java.util.Collections; import java.util.List; import java.util.Locale; import javax.xml.namespace.QName; import org.jivesoftware.smack.packet.id.StandardStanzaIdSource; import org.jivesoftware.smack.packet.id.StanzaIdSource; import org.jivesoftware.smack.util.MultiMap; import org.jivesoftware.smack.util.PacketUtil; import org.jivesoftware.smack.util.StringUtils; import org.jivesoftware.smack.util.XmlStringBuilder; import org.jivesoftware.smack.util.XmppElementUtil; import org.jxmpp.jid.Jid; /** * Base class for XMPP Stanzas, which are called Stanza in older versions of Smack (i.e. < 4.1). *
* 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. *
** XMPP Stanzas are {@link Message}, {@link IQ} and {@link Presence}. Which therefore subclass this * class. If you think you need to subclass this class, then you are doing something wrong. *
** Use {@link StanzaBuilder} to construct a stanza instance. All instance mutating methods of this * class are deprecated, although not all of them are currently marked as such, and must not be used. *
* * @author Matt Tucker * @author Florian Schmaus * @see RFC 6120 ยง 8. XML Stanzas */ public abstract class Stanza implements StanzaView, 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* 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." *
*/ protected String language; protected Stanza() { extensionElements = new MultiMap<>(); usedStanzaIdSource = null; id = StandardStanzaIdSource.DEFAULT.getNewStanzaId(); } protected Stanza(StanzaBuilder> stanzaBuilder) { if (stanzaBuilder.stanzaIdSource != null) { id = stanzaBuilder.stanzaIdSource.getNewStanzaId(); // Note that some stanza ID sources, e.g. StanzaBuilder.PresenceBuilder.EMPTY return null here. Hence we // only check that the returned string is not empty. assert StringUtils.isNullOrNotEmpty(id); usedStanzaIdSource = stanzaBuilder.stanzaIdSource; } else { // N.B. It is ok if stanzaId here is null. id = stanzaBuilder.stanzaId; usedStanzaIdSource = null; } to = stanzaBuilder.to; from = stanzaBuilder.from; error = stanzaBuilder.stanzaError; language = stanzaBuilder.language; extensionElements = stanzaBuilder.extensionElements.clone(); } protected Stanza(Stanza p) { usedStanzaIdSource = p.usedStanzaIdSource; id = p.getStanzaId(); to = p.getTo(); from = p.getFrom(); error = p.error; extensionElements = p.extensionElements.clone(); } @Override public final String getStanzaId() { return id; } /** * Sets the unique ID of the packet. To indicate that a stanza has no id * passnull
as the packet's id value.
*
* @param id the unique ID for the packet.
*/
public void setStanzaId(String id) {
if (id != null) {
requireNotNullNorEmpty(id, "id must either be null or not the empty String");
}
this.id = id;
}
/**
* Check if this stanza has an ID set.
*
* @return true if the stanza ID is set, false otherwise.
* @since 4.1
*/
public final 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;
}
/**
* Set the stanza id if none is set.
*
* @return the stanza id.
* @since 4.2
* @deprecated use {@link StanzaBuilder} instead.
*/
@Deprecated
// TODO: Remove in Smack 4.5.
public String setStanzaId() {
if (!hasStanzaIdSet()) {
setNewStanzaId();
}
return getStanzaId();
}
/**
* Throws an {@link IllegalArgumentException} if this stanza has no stanza ID set.
*
* @throws IllegalArgumentException if this stanza has no stanza ID set.
* @since 4.4.
*/
public final void throwIfNoStanzaId() {
if (hasStanzaIdSet()) {
return;
}
throw new IllegalArgumentException("The stanza has no RFC stanza ID set, although one is required");
}
/**
* Ensure that a stanza ID is set.
*
* @return the stanza ID.
* @since 4.4
*/
// TODO: Remove this method once StanzaBuilder is ready.
protected String setNewStanzaId() {
if (usedStanzaIdSource != null) {
id = usedStanzaIdSource.getNewStanzaId();
}
else {
id = StandardStanzaIdSource.DEFAULT.getNewStanzaId();
}
return getStanzaId();
}
@Override
public final Jid getTo() {
return to;
}
/**
* 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.
*/
// TODO: Mark this as deprecated once StanzaBuilder is ready and all call sites are gone.
public void setTo(Jid to) {
this.to = to;
}
@Override
public final Jid getFrom() {
return from;
}
/**
* 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.
*/
// TODO: Mark this as deprecated once StanzaBuilder is ready and all call sites are gone.
public void setFrom(Jid from) {
this.from = from;
}
@Override
public final StanzaError getError() {
return error;
}
/**
* Sets the error for this stanza.
*
* @param stanzaError the error that this stanza carries and hence signals.
*/
// TODO: Mark this as deprecated once StanzaBuilder is ready and all call sites are gone.
public void setError(StanzaError stanzaError) {
error = stanzaError;
}
/**
* Deprecated.
* @param stanzaError the stanza error.
* @deprecated use {@link StanzaBuilder} instead.
*/
@Deprecated
// TODO: Remove in Smack 4.5.
public void setError(StanzaError.Builder stanzaError) {
setError(stanzaError.build());
}
@Override
public final String getLanguage() {
return language;
}
/**
* Sets the xml:lang of this Stanza.
*
* @param language the xml:lang of this Stanza.
* @deprecated use {@link StanzaBuilder#setLanguage(String)} instead.
*/
@Deprecated
// TODO: Remove in Smack 4.5.
public void setLanguage(String language) {
this.language = language;
}
@Override
public final List* Changes to the returned set will update the stanza extensions, if the returned set is not the empty set. *
* * @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 final List* When possible, use {@link #getExtensionElement(String, String)} instead. *
* * @param namespace the namespace of the extension that is desired. * @return the stanza extension with the given namespace. */ public final ExtensionElement getExtension(String namespace) { return PacketUtil.extensionElementFrom(getExtensions(), null, namespace); } /** * Returns the first extension that matches the specified element name and * namespace, ornull
if it doesn't exist. Extensions are
* are arbitrary XML elements in standard XMPP stanzas.
* * Note that it is recommended to use {@link #getExtension(Class)} instead of this method. * The {@link #getExtension(Class)} is more robust, as it is type safe. *
* * @param elementName the XML element name of the extension. * @param namespace the XML element namespace of the extension. * @return the extension, ornull
if it doesn't exist.
*/
public final ExtensionElement getExtensionElement(String elementName, String namespace) {
if (namespace == null) {
return null;
}
QName key = new QName(namespace, elementName);
ExtensionElement packetExtension = getExtension(key);
if (packetExtension == null) {
return null;
}
return packetExtension;
}
/**
* This method is deprecated. Use preferably {@link #getExtension(Class)} or {@link #getExtensionElement(String, String)}.
*
* @param null
if it doesn't exist.
* @deprecated use {@link #getExtension(Class)} or {@link #getExtensionElement(String, String)} instead.
*/
// TODO: Remove in Smack 4.5.
@SuppressWarnings("unchecked")
@Deprecated
public final * Please note that although this method is not yet marked as deprecated, it is recommended to use * {@link StanzaBuilder#addExtension(ExtensionElement)} instead. *
* * @param extension a stanza extension. */ // TODO: Mark this as deprecated once StanzaBuilder is ready and all call sites are gone. public final void addExtension(ExtensionElement extension) { if (extension == null) return; QName key = extension.getQName(); synchronized (extensionElements) { extensionElements.put(key, extension); } } /** * Add the given extension and override eventually existing extensions with the same name and * namespace. ** Please note that although this method is not yet marked as deprecated, it is recommended to use * {@link StanzaBuilder#overrideExtension(ExtensionElement)} instead. *
* * @param extension the extension element to add. * @return one of the removed extensions ornull
if there are none.
* @since 4.1.2
*/
// TODO: Mark this as deprecated once StanzaBuilder is ready and all call sites are gone.
public final ExtensionElement overrideExtension(ExtensionElement extension) {
if (extension == null) return null;
synchronized (extensionElements) {
// Note that we need to use removeExtension(String, String) here. If would use
// removeExtension(ExtensionElement) then we would remove based on the equality of ExtensionElement, which
// is not what we want in this case.
ExtensionElement removedExtension = removeExtension(extension.getElementName(), extension.getNamespace());
addExtension(extension);
return removedExtension;
}
}
/**
* Adds a collection of stanza extensions to the packet. Does nothing if extensions is null.
*
* @param extensions a collection of stanza extensions
*/
// TODO: Mark this as deprecated once StanzaBuilder is ready and all call sites are gone.
public final void addExtensions(Collection extends ExtensionElement> extensions) {
if (extensions == null) return;
for (ExtensionElement packetExtension : extensions) {
addExtension(packetExtension);
}
}
/**
* Check if a stanza extension with the given element and namespace exists.
*
* The argument elementName
may be null.
*