org.jivesoftware.smack.packet

Class Stanza

java.lang.Object

org.jivesoftware.smack.packet.Stanza

All Implemented Interfaces:

Element, FullyQualifiedElement, NamedElement, StanzaView, TopLevelStreamElement, XmlLangElement

Direct Known Subclasses:

IQ, MessageOrPresence

public abstract class Stanza
extends java.lang.Object
implements StanzaView, TopLevelStreamElement

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 Message, IQ and Presence. Which therefore subclass this class. If you think you need to subclass this class, then you are doing something wrong.

Use 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.

See Also:

RFC 6120 § 8. XML Stanzas

Field Summary

Fields

Modifier and Type	Field and Description
protected static java.lang.String	DEFAULT_LANGUAGE
static java.lang.String	ITEM
protected java.lang.String	language Optional value of the 'xml:lang' attribute of the outermost element of the stanza.
static java.lang.String	TEXT

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Stanza()
protected	Stanza(Stanza p)
protected	Stanza(StanzaBuilder<?> stanzaBuilder)

Method Summary

Modifier and Type	Method and Description
protected void	addCommonAttributes(XmlStringBuilder xml) Add to, from, and id attributes.
void	addExtension(ExtensionElement extension) Adds a stanza extension to the packet.
void	addExtensions(java.util.Collection<? extends ExtensionElement> extensions) Adds a collection of stanza extensions to the packet.
protected void	appendErrorIfExists(XmlStringBuilder xml) Append an XMPPError is this stanza has one set.
static java.lang.String	getDefaultLanguage() Returns the default language used for all messages containing localized content.
StanzaError	getError() Returns the error associated with this packet, or null if there are no errors.
ExtensionElement	getExtension(javax.xml.namespace.QName qname)
ExtensionElement	getExtension(java.lang.String namespace) Returns the first extension of this stanza that has the given namespace.
<E extends ExtensionElement> E	getExtension(java.lang.String elementName, java.lang.String namespace) Deprecated. use StanzaView.getExtension(Class) or getExtensionElement(String, String) instead.
ExtensionElement	getExtensionElement(java.lang.String elementName, java.lang.String namespace) Returns the first extension that matches the specified element name and namespace, or null if it doesn't exist.
java.util.List<ExtensionElement>	getExtensions() Returns a list of all extension elements of this stanza.
<E extends ExtensionElement> java.util.List<E>	getExtensions(java.lang.Class<E> extensionElementClass) Return all extension elements of the given type.
java.util.List<ExtensionElement>	getExtensions(javax.xml.namespace.QName qname)
java.util.List<ExtensionElement>	getExtensions(java.lang.String elementName, java.lang.String namespace) Return a list of all extensions with the given element name and namespace.
MultiMap<javax.xml.namespace.QName,ExtensionElement>	getExtensionsMap()
org.jxmpp.jid.Jid	getFrom() Returns who the stanza is being sent "from" or null if the value is not set.
java.lang.String	getLanguage() Returns the xml:lang of this XML element, or null if one has not been set.
java.lang.String	getNamespace() Returns the root element XML namespace.
java.lang.String	getStanzaId() Returns the unique ID of the stanza.
org.jxmpp.jid.Jid	getTo() Returns who the stanza is being sent "to", or null if the value is not set.
boolean	hasExtension(java.lang.String namespace) Check if a extension element with the given namespace exists.
boolean	hasExtension(java.lang.String elementName, java.lang.String namespace) Check if a stanza extension with the given element and namespace exists.
boolean	hasStanzaIdSet() Check if this stanza has an ID set.
protected void	logCommonAttributes(java.lang.StringBuilder sb)
ExtensionElement	overrideExtension(ExtensionElement extension) Add the given extension and override eventually existing extensions with the same name and namespace.
ExtensionElement	removeExtension(ExtensionElement extension) Deprecated. use StanzaBuilder instead.
ExtensionElement	removeExtension(java.lang.String elementName, java.lang.String namespace) Remove the stanza extension with the given elementName and namespace.
void	setError(StanzaError.Builder stanzaError) Deprecated. use StanzaBuilder instead.
void	setError(StanzaError stanzaError) Sets the error for this stanza.
void	setFrom(org.jxmpp.jid.Jid from) Sets who the packet is being sent "from".
void	setLanguage(java.lang.String language) Deprecated. use StanzaBuilder.setLanguage(String) instead.
protected java.lang.String	setNewStanzaId() Ensure that a stanza ID is set.
java.lang.String	setStanzaId() Deprecated. use StanzaBuilder instead.
void	setStanzaId(java.lang.String id) Sets the unique ID of the packet.
void	setTo(org.jxmpp.jid.Jid to) Sets who the packet is being sent "to".
void	throwIfNoStanzaId() Throws an IllegalArgumentException if this stanza has no stanza ID set.
abstract java.lang.String	toString() Returns a short String describing the Stanza.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.jivesoftware.smack.packet.StanzaView

getExtension, hasExtension, hasExtension

Methods inherited from interface org.jivesoftware.smack.packet.FullyQualifiedElement

getQName

Methods inherited from interface org.jivesoftware.smack.packet.NamedElement

getElementName

Methods inherited from interface org.jivesoftware.smack.packet.Element

toXML, toXML, toXML

Field Detail

TEXT

public static final java.lang.String TEXT

See Also:

Constant Field Values

ITEM

public static final java.lang.String ITEM

See Also:

Constant Field Values

DEFAULT_LANGUAGE

protected static final java.lang.String DEFAULT_LANGUAGE

language

protected java.lang.String language

Optional value of the 'xml:lang' attribute of the outermost element of the stanza.

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."

Constructor Detail

Stanza

protected Stanza()

Stanza

protected Stanza(StanzaBuilder<?> stanzaBuilder)

Stanza

protected Stanza(Stanza p)

Method Detail

getStanzaId

public final java.lang.String getStanzaId()

Description copied from interface: StanzaView

Returns the unique ID of the stanza. The returned value could be null.

Specified by:

getStanzaId in interface StanzaView

Returns:

the packet's unique ID or null if the id is not available.

setStanzaId

public void setStanzaId(java.lang.String id)

Sets the unique ID of the packet. To indicate that a stanza has no id pass null as the packet's id value.

Parameters:

id - the unique ID for the packet.

hasStanzaIdSet

public final boolean hasStanzaIdSet()

Check if this stanza has an ID set.

Returns:

true if the stanza ID is set, false otherwise.

Since:

4.1

setStanzaId

@Deprecated
public java.lang.String setStanzaId()

Deprecated. use StanzaBuilder instead.

Set the stanza id if none is set.

Returns:

the stanza id.

Since:

4.2

throwIfNoStanzaId

public final void throwIfNoStanzaId()

Throws an IllegalArgumentException if this stanza has no stanza ID set.

Throws:

java.lang.IllegalArgumentException - if this stanza has no stanza ID set.

Since:

4.4.

setNewStanzaId

protected java.lang.String setNewStanzaId()

Ensure that a stanza ID is set.

Returns:

the stanza ID.

Since:

4.4

getTo

public final org.jxmpp.jid.Jid getTo()

Description copied from interface: StanzaView

Returns who the stanza is being sent "to", or null if the value is not set. The XMPP protocol often makes the "to" attribute optional, so it does not always need to be set.

Specified by:

getTo in interface StanzaView

Returns:

who the stanza is being sent to, or null if the value has not been set.

setTo

public void setTo(org.jxmpp.jid.Jid 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.

Parameters:

to - who the packet is being sent to.

getFrom

public final org.jxmpp.jid.Jid getFrom()

Description copied from interface: StanzaView

Returns who the stanza is being sent "from" or null if the value is not set. The XMPP protocol often makes the "from" attribute optional, so it does not always need to be set.

Specified by:

getFrom in interface StanzaView

Returns:

who the stanza is being sent from, or null if the value has not been set.

setFrom

public void setFrom(org.jxmpp.jid.Jid 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.

Parameters:

from - who the packet is being sent to.

getError

public final StanzaError getError()

Description copied from interface: StanzaView

Returns the error associated with this packet, or null if there are no errors.

Specified by:

getError in interface StanzaView

Returns:

the error sub-packet or null if there isn't an error.

setError

public void setError(StanzaError stanzaError)

Sets the error for this stanza.

Parameters:

stanzaError - the error that this stanza carries and hence signals.

setError

@Deprecated
public void setError(StanzaError.Builder stanzaError)

Deprecated. use StanzaBuilder instead.

Deprecated.

Parameters:

stanzaError - the stanza error.

getLanguage

public final java.lang.String getLanguage()

Description copied from interface: XmlLangElement

Returns the xml:lang of this XML element, or null if one has not been set.

Specified by:

getLanguage in interface FullyQualifiedElement

Specified by:

getLanguage in interface XmlLangElement

Returns:

the xml:lang of this XML element, or null.

setLanguage

@Deprecated
public void setLanguage(java.lang.String language)

Deprecated. use StanzaBuilder.setLanguage(String) instead.

Sets the xml:lang of this Stanza.

Parameters:

language - the xml:lang of this Stanza.

getExtensions

public final java.util.List<ExtensionElement> getExtensions()

Description copied from interface: StanzaView

Returns a list of all extension elements of this stanza.

Specified by:

getExtensions in interface StanzaView

Returns:

a list of all extension elements of this stanza.

getExtensionsMap

public final MultiMap<javax.xml.namespace.QName,ExtensionElement> getExtensionsMap()

getExtensions

public final java.util.List<ExtensionElement> getExtensions(java.lang.String elementName,
                                                            java.lang.String namespace)

Return a list of all extensions with the given element name and namespace.

Changes to the returned set will update the stanza extensions, if the returned set is not the empty set.

Parameters:

elementName - the element name, must not be null.

namespace - the namespace of the element(s), must not be null.

Returns:

a set of all matching extensions.

Since:

4.1

getExtensions

public final java.util.List<ExtensionElement> getExtensions(javax.xml.namespace.QName qname)

Specified by:

getExtensions in interface StanzaView

getExtensions

public final <E extends ExtensionElement> java.util.List<E> getExtensions(java.lang.Class<E> extensionElementClass)

Description copied from interface: StanzaView

Return all extension elements of the given type. Returns the empty list if there a none.

Specified by:

getExtensions in interface StanzaView

Type Parameters:

E - the type of extension elements.

Parameters:

extensionElementClass - the class of the type of extension elements.

Returns:

a list of extension elements of that type, which may be empty.

getExtension

public final ExtensionElement getExtension(java.lang.String namespace)

Returns the first extension of this stanza that has the given namespace.

When possible, use getExtensionElement(String, String) instead.

Parameters:

namespace - the namespace of the extension that is desired.

Returns:

the stanza extension with the given namespace.

getExtensionElement

public final ExtensionElement getExtensionElement(java.lang.String elementName,
                                                  java.lang.String namespace)

Returns the first extension that matches the specified element name and namespace, or null if it doesn't exist. Extensions are are arbitrary XML elements in standard XMPP stanzas.

Note that it is recommended to use StanzaView.getExtension(Class) instead of this method. The StanzaView.getExtension(Class) is more robust, as it is type safe.

Parameters:

elementName - the XML element name of the extension.

namespace - the XML element namespace of the extension.

Returns:

the extension, or null if it doesn't exist.

getExtension

@Deprecated
public final <E extends ExtensionElement> E getExtension(java.lang.String elementName,
                                                                     java.lang.String namespace)

Deprecated. use StanzaView.getExtension(Class) or getExtensionElement(String, String) instead.

This method is deprecated. Use preferably StanzaView.getExtension(Class) or getExtensionElement(String, String).

Type Parameters:

E - the type to cast to.

Parameters:

elementName - the XML element name of the extension. (May be null)

namespace - the XML element namespace of the extension.

Returns:

the extension, or null if it doesn't exist.

getExtension

public final ExtensionElement getExtension(javax.xml.namespace.QName qname)

Specified by:

getExtension in interface StanzaView

addExtension

public final void addExtension(ExtensionElement extension)

Adds a stanza extension to the packet. Does nothing if extension is null.

Please note that although this method is not yet marked as deprecated, it is recommended to use StanzaBuilder.addExtension(ExtensionElement) instead.

Parameters:

extension - a stanza extension.

overrideExtension

public final ExtensionElement overrideExtension(ExtensionElement 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 StanzaBuilder.overrideExtension(ExtensionElement) instead.

Parameters:

extension - the extension element to add.

Returns:

one of the removed extensions or null if there are none.

Since:

4.1.2

addExtensions

public final void addExtensions(java.util.Collection<? extends ExtensionElement> extensions)

Adds a collection of stanza extensions to the packet. Does nothing if extensions is null.

Parameters:

extensions - a collection of stanza extensions

hasExtension

public final boolean hasExtension(java.lang.String elementName,
                                  java.lang.String namespace)

Check if a stanza extension with the given element and namespace exists.

The argument elementName may be null.

Parameters:

elementName - TODO javadoc me please

namespace - TODO javadoc me please

Returns:

true if a stanza extension exists, false otherwise.

hasExtension

public final boolean hasExtension(java.lang.String namespace)

Description copied from interface: StanzaView

Check if a extension element with the given namespace exists.

Specified by:

hasExtension in interface StanzaView

Parameters:

namespace - the namespace of the extension element to check for.

Returns:

true if a stanza extension exists, false otherwise.

removeExtension

public final ExtensionElement removeExtension(java.lang.String elementName,
                                              java.lang.String namespace)

Remove the stanza extension with the given elementName and namespace.

Parameters:

elementName - TODO javadoc me please

namespace - TODO javadoc me please

Returns:

the removed stanza extension or null.

removeExtension

@Deprecated
public final ExtensionElement removeExtension(ExtensionElement extension)

Deprecated. use StanzaBuilder instead.

Removes a stanza extension from the packet.

Parameters:

extension - the stanza extension to remove.

Returns:

the removed stanza extension or null.

toString

public abstract java.lang.String toString()

Returns a short String describing the Stanza. This method is suited for log purposes.

Overrides:

toString in class java.lang.Object

getNamespace

public final java.lang.String getNamespace()

Description copied from interface: FullyQualifiedElement

Returns the root element XML namespace.

Specified by:

getNamespace in interface FullyQualifiedElement

Returns:

the namespace.

getDefaultLanguage

public static java.lang.String getDefaultLanguage()

Returns the default language used for all messages containing localized content.

Returns:

the default language

addCommonAttributes

protected final void addCommonAttributes(XmlStringBuilder xml)

Add to, from, and id attributes.

Parameters:

xml - the XmlStringBuilder.

logCommonAttributes

protected void logCommonAttributes(java.lang.StringBuilder sb)

appendErrorIfExists

protected final void appendErrorIfExists(XmlStringBuilder xml)

Append an XMPPError is this stanza has one set.

Parameters:

xml - the XmlStringBuilder to append the error to.