Package org.jivesoftware.smack.packet

Class Stanza

java.lang.Object
org.jivesoftware.smack.packet.Stanza
All Implemented Interfaces:
Element, NamedElement, StanzaView, TopLevelStreamElement, XmlElement, XmlLangElement
Direct Known Subclasses:
IQ, MessageOrPresence
public abstract class Stanza extends 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:

  • Field Details

    • TEXT

      public static final String TEXT
      See Also:

    • ITEM

      public static final String ITEM
      See Also:

    • DEFAULT_LANGUAGE

      protected static final String DEFAULT_LANGUAGE

    • language

      protected 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 Details

    • Stanza

      protected Stanza()

    • Stanza

      protected Stanza(StanzaBuilder<?> stanzaBuilder)

    • Stanza

      protected Stanza(Stanza p)

  • Method Details

    • getStanzaId

      public final 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(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

    • throwIfNoStanzaId

      public final void throwIfNoStanzaId()
      Throws an IllegalArgumentException if this stanza has no stanza ID set.
      Throws:
      IllegalArgumentException - if this stanza has no stanza ID set.
      Since:
      4.4.

    • setNewStanzaId

      protected 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 final 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.

    • getLanguage

      public final 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 XmlElement
      Specified by:
      getLanguage in interface XmlLangElement
      Returns:
      the xml:lang of this XML element, or null.

    • getExtensions

      public final List<XmlElement> 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<QName,XmlElement> getExtensionsMap()

    • getExtensions

      public final List<XmlElement> getExtensions(String elementName, 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 List<XmlElement> getExtensions(QName qname)
      Specified by:
      getExtensions in interface StanzaView

    • getExtensions

      public final <E extends ExtensionElement> List<E> getExtensions(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 XmlElement getExtension(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 XmlElement getExtensionElement(String elementName, 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

      public final XmlElement getExtension(QName qname)
      Specified by:
      getExtension in interface StanzaView

    • addExtension

      public final void addExtension(XmlElement 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(XmlElement) instead.

      Parameters:
      extension - a stanza extension.

    • overrideExtension

      public final XmlElement overrideExtension(XmlElement 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(XmlElement) 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(Collection<? extends XmlElement> 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(String elementName, 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(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 XmlElement removeExtension(String elementName, 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.

    • toString

      public abstract String toString()
      Returns a short String describing the Stanza. This method is suited for log purposes.
      Overrides:
      toString in class Object

    • getNamespace

      public final String getNamespace()
      Description copied from interface: XmlElement
      Returns the root element XML namespace.
      Specified by:
      getNamespace in interface XmlElement
      Returns:
      the namespace.

    • getDefaultLanguage

      public static 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(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.