Class 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 Detail

      • 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​(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.
        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.
      • 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 <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.
      • 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
      • 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.