Stanza.java

  1. /**
  2.  *
  3.  * Copyright 2003-2007 Jive Software.
  4.  *
  5.  * Licensed under the Apache License, Version 2.0 (the "License");
  6.  * you may not use this file except in compliance with the License.
  7.  * You may obtain a copy of the License at
  8.  *
  9.  *     http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */

  18. package org.jivesoftware.smack.packet;

  20. import static org.jivesoftware.smack.util.StringUtils.requireNotNullOrEmpty;

  22. import org.jivesoftware.smack.packet.id.StanzaIdUtil;
  23. import org.jivesoftware.smack.util.MultiMap;
  24. import org.jivesoftware.smack.util.PacketUtil;
  25. import org.jivesoftware.smack.util.XmlStringBuilder;
  26. import org.jxmpp.jid.Jid;
  27. import org.jxmpp.jid.impl.JidCreate;
  28. import org.jxmpp.stringprep.XmppStringprepException;
  29. import org.jxmpp.util.XmppStringUtils;

  31. import java.util.Collection;
  32. import java.util.List;
  33. import java.util.Locale;
  34. import java.util.Set;

  36. /**
  37.  * Base class for XMPP Stanzas, which are called Packet in older versions of Smack (i.e. < 4.1).
  38.  * <p>
  39.  * Every stanza has a unique ID (which is automatically generated, but can be overridden). Stanza
  40.  * IDs are required for IQ stanzas and recommended for presence and message stanzas. Optionally, the
  41.  * "to" and "from" fields can be set.
  42.  * </p>
  43.  * <p>
  44.  * XMPP Stanzas are {@link Message}, {@link IQ} and {@link Presence}. Which therefore subclass this
  45.  * class. <b>If you think you need to subclass this class, then you are doing something wrong.</b>
  46.  * </p>
  47.  *
  48.  * @author Matt Tucker
  49.  * @see <a href="http://xmpp.org/rfcs/rfc6120.html#stanzas">RFC 6120 ยง 8. XML Stanzas</a>
  50.  */
  51. public abstract class Stanza implements TopLevelStreamElement {

  53.     public static final String TEXT = "text";
  54.     public static final String ITEM = "item";

  56.     protected static final String DEFAULT_LANGUAGE =
  57.             java.util.Locale.getDefault().getLanguage().toLowerCase(Locale.US);

  59.     private final MultiMap<String, ExtensionElement> packetExtensions = new MultiMap<>();

  61.     private String id = null;
  62.     private Jid to;
  63.     private Jid from;
  64.     private XMPPError error = null;

  66.     /**
  67.      * Optional value of the 'xml:lang' attribute of the outermost element of
  68.      * the stanza.
  69.      * <p>
  70.      * Such an attribute is defined for all stanza types. For IQ, see for
  71.      * example XEP-50 3.7:
  72.      * "The requester SHOULD provide its locale information using the "xml:lang
  73.      * " attribute on either the <iq/> (RECOMMENDED) or <command/> element."
  74.      * </p>
  75.      */
  76.     protected String language;

  78.     protected Stanza() {
  79.         this(StanzaIdUtil.newStanzaId());
  80.     }

  82.     protected Stanza(String stanzaId) {
  83.         setStanzaId(stanzaId);
  84.     }

  86.     protected Stanza(Stanza p) {
  87.         id = p.getStanzaId();
  88.         to = p.getTo();
  89.         from = p.getFrom();
  90.         error = p.error;

  92.         // Copy extensions
  93.         for (ExtensionElement pe : p.getExtensions()) {
  94.             addExtension(pe);
  95.         }
  96.     }

  98.     /**
  99.      * Returns the unique ID of the stanza. The returned value could be <code>null</code>.
  100.      *
  101.      * @return the packet's unique ID or <code>null</code> if the id is not available.
  102.      */
  103.     public String getStanzaId() {
  104.         return id;
  105.     }

  107.     /**
  108.      * 
  109.      * @return the stanza id.
  110.      * @deprecated use {@link #getStanzaId()} instead.
  111.      */
  112.     @Deprecated
  113.     public String getPacketID() {
  114.         return getStanzaId();
  115.     }

  117.     /**
  118.      * Sets the unique ID of the packet. To indicate that a packet has no id
  119.      * pass <code>null</code> as the packet's id value.
  120.      *
  121.      * @param id the unique ID for the packet.
  122.      */
  123.     public void setStanzaId(String id) {
  124.         if (id != null) {
  125.             requireNotNullOrEmpty(id, "id must either be null or not the empty String");
  126.         }
  127.         this.id = id;
  128.     }

  130.     /**
  131.      * 
  132.      * @param packetID
  133.      * @deprecated use {@link #setStanzaId(String)} instead.
  134.      */
  135.     @Deprecated
  136.     public void setPacketID(String packetID) {
  137.         setStanzaId(packetID);
  138.     }

  140.     /**
  141.      * Check if this stanza has an ID set.
  142.      *
  143.      * @return true if the stanza ID is set, false otherwise.
  144.      * @since 4.1
  145.      */
  146.     public boolean hasStanzaIdSet() {
  147.         // setStanzaId ensures that the id is either null or not empty,
  148.         // so we can assume that it is set if it's not null.
  149.         return id != null;
  150.     }

  152.     /**
  153.      * Returns who the packet is being sent "to", or <tt>null</tt> if
  154.      * the value is not set. The XMPP protocol often makes the "to"
  155.      * attribute optional, so it does not always need to be set.<p>
  156.      *
  157.      * @return who the packet is being sent to, or <tt>null</tt> if the
  158.      *      value has not been set.
  159.      */
  160.     public Jid getTo() {
  161.         return to;
  162.     }

  164.     /**
  165.      * Sets who the packet is being sent "to". The XMPP protocol often makes
  166.      * the "to" attribute optional, so it does not always need to be set.
  167.      *
  168.      * @param to who the packet is being sent to.
  169.      * @throws IllegalArgumentException if to is not a valid JID String.
  170.      * @deprecated use {@link #setTo(Jid)} instead.
  171.      */
  172.     @Deprecated
  173.     public void setTo(String to) {
  174.         Jid jid;
  175.         try {
  176.             jid = JidCreate.from(to);
  177.         }
  178.         catch (XmppStringprepException e) {
  179.             throw new IllegalArgumentException(e);
  180.         }
  181.         setTo(jid);
  182.     }

  184.     /**
  185.      * Sets who the packet is being sent "to". The XMPP protocol often makes
  186.      * the "to" attribute optional, so it does not always need to be set.
  187.      *
  188.      * @param to who the packet is being sent to.
  189.      */
  190.     public void setTo(Jid to) {
  191.         this.to = to;
  192.     }

  194.     /**
  195.      * Returns who the packet is being sent "from" or <tt>null</tt> if
  196.      * the value is not set. The XMPP protocol often makes the "from"
  197.      * attribute optional, so it does not always need to be set.<p>
  198.      *
  199.      * @return who the packet is being sent from, or <tt>null</tt> if the
  200.      *      value has not been set.
  201.      */
  202.     public Jid getFrom() {
  203.         return from;
  204.     }

  206.     /**
  207.      * Sets who the packet is being sent "from". The XMPP protocol often
  208.      * makes the "from" attribute optional, so it does not always need to
  209.      * be set.
  210.      *
  211.      * @param from who the packet is being sent to.
  212.      * @throws IllegalArgumentException if from is not a valid JID String.
  213.      * @deprecated use {@link #setFrom(Jid)} instead.
  214.      */
  215.     @Deprecated
  216.     public void setFrom(String from) {
  217.         Jid jid;
  218.         try {
  219.             jid = JidCreate.from(from);
  220.         }
  221.         catch (XmppStringprepException e) {
  222.             throw new IllegalArgumentException(e);
  223.         }
  224.         setFrom(jid);
  225.     }

  227.     /**
  228.      * Sets who the packet is being sent "from". The XMPP protocol often
  229.      * makes the "from" attribute optional, so it does not always need to
  230.      * be set.
  231.      *
  232.      * @param from who the packet is being sent to.
  233.      */
  234.     public void setFrom(Jid from) {
  235.         this.from = from;
  236.     }

  238.     /**
  239.      * Returns the error associated with this packet, or <tt>null</tt> if there are
  240.      * no errors.
  241.      *
  242.      * @return the error sub-packet or <tt>null</tt> if there isn't an error.
  243.      */
  244.     public XMPPError getError() {
  245.         return error;
  246.     }

  248.     /**
  249.      * Sets the error for this packet.
  250.      *
  251.      * @param error the error to associate with this packet.
  252.      */
  253.     public void setError(XMPPError error) {
  254.         this.error = error;
  255.     }

  257.     /**
  258.      * Returns the xml:lang of this Stanza, or null if one has not been set.
  259.      *
  260.      * @return the xml:lang of this Stanza, or null.
  261.      */
  262.     public String getLanguage() {
  263.         return language;
  264.     }

  266.     /**
  267.      * Sets the xml:lang of this Stanza.
  268.      *
  269.      * @param language the xml:lang of this Stanza.
  270.      */
  271.     public void setLanguage(String language) {
  272.         this.language = language;
  273.     }

  275.     /**
  276.      * Returns a list of all extension elements of this stanza.
  277.      *
  278.      * @return a list of all extension elements of this stanza.
  279.      */
  280.     public List<ExtensionElement> getExtensions() {
  281.         synchronized (packetExtensions) {
  282.             // No need to create a new list, values() will already create a new one for us
  283.             return packetExtensions.values();
  284.         }
  285.     }

  287.     /**
  288.      * Return a set of all extensions with the given element name <emph>and</emph> namespace.
  289.      * <p>
  290.      * Changes to the returned set will update the packet extensions, if the returned set is not the empty set.
  291.      * </p>
  292.      *
  293.      * @param elementName the element name, must not be null.
  294.      * @param namespace the namespace of the element(s), must not be null.
  295.      * @return a set of all matching extensions.
  296.      * @since 4.1
  297.      */
  298.     public Set<ExtensionElement> getExtensions(String elementName, String namespace) {
  299.         requireNotNullOrEmpty(elementName, "elementName must not be null or empty");
  300.         requireNotNullOrEmpty(namespace, "namespace must not be null or empty");
  301.         String key = XmppStringUtils.generateKey(elementName, namespace);
  302.         return packetExtensions.getAll(key);
  303.     }

  305.     /**
  306.      * Returns the first extension of this packet that has the given namespace.
  307.      * <p>
  308.      * When possible, use {@link #getExtension(String,String)} instead.
  309.      * </p>
  310.      *
  311.      * @param namespace the namespace of the extension that is desired.
  312.      * @return the packet extension with the given namespace.
  313.      */
  314.     public ExtensionElement getExtension(String namespace) {
  315.         return PacketUtil.extensionElementFrom(getExtensions(), null, namespace);
  316.     }

  318.     /**
  319.      * Returns the first extension that matches the specified element name and
  320.      * namespace, or <tt>null</tt> if it doesn't exist. If the provided elementName is null,
  321.      * only the namespace is matched. Extensions are
  322.      * are arbitrary XML sub-documents in standard XMPP packets. By default, a 
  323.      * {@link DefaultExtensionElement} instance will be returned for each extension. However, 
  324.      * ExtensionElementProvider instances can be registered with the 
  325.      * {@link org.jivesoftware.smack.provider.ProviderManager ProviderManager}
  326.      * class to handle custom parsing. In that case, the type of the Object
  327.      * will be determined by the provider.
  328.      *
  329.      * @param elementName the XML element name of the extension. (May be null)
  330.      * @param namespace the XML element namespace of the extension.
  331.      * @return the extension, or <tt>null</tt> if it doesn't exist.
  332.      */
  333.     @SuppressWarnings("unchecked")
  334.     public <PE extends ExtensionElement> PE getExtension(String elementName, String namespace) {
  335.         if (namespace == null) {
  336.             return null;
  337.         }
  338.         String key = XmppStringUtils.generateKey(elementName, namespace);
  339.         ExtensionElement packetExtension;
  340.         synchronized (packetExtensions) {
  341.             packetExtension = packetExtensions.getFirst(key);
  342.         }
  343.         if (packetExtension == null) {
  344.             return null;
  345.         }
  346.         return (PE) packetExtension;
  347.     }

  349.     /**
  350.      * Adds a packet extension to the packet. Does nothing if extension is null.
  351.      *
  352.      * @param extension a packet extension.
  353.      */
  354.     public void addExtension(ExtensionElement extension) {
  355.         if (extension == null) return;
  356.         String key = XmppStringUtils.generateKey(extension.getElementName(), extension.getNamespace());
  357.         synchronized (packetExtensions) {
  358.             packetExtensions.put(key, extension);
  359.         }
  360.     }

  362.     /**
  363.      * Adds a collection of packet extensions to the packet. Does nothing if extensions is null.
  364.      * 
  365.      * @param extensions a collection of packet extensions
  366.      */
  367.     public void addExtensions(Collection<ExtensionElement> extensions) {
  368.         if (extensions == null) return;
  369.         for (ExtensionElement packetExtension : extensions) {
  370.             addExtension(packetExtension);
  371.         }
  372.     }

  374.     /**
  375.      * Check if a packet extension with the given element and namespace exists.
  376.      * <p>
  377.      * The argument <code>elementName</code> may be null.
  378.      * </p>
  379.      *
  380.      * @param elementName
  381.      * @param namespace
  382.      * @return true if a packet extension exists, false otherwise.
  383.      */
  384.     public boolean hasExtension(String elementName, String namespace) {
  385.         if (elementName == null) {
  386.             return hasExtension(namespace);
  387.         }
  388.         String key = XmppStringUtils.generateKey(elementName, namespace);
  389.         synchronized (packetExtensions) {
  390.             return packetExtensions.containsKey(key);
  391.         }
  392.     }

  394.     /**
  395.      * Check if a packet extension with the given namespace exists.
  396.      * 
  397.      * @param namespace
  398.      * @return true if a packet extension exists, false otherwise.
  399.      */
  400.     public boolean hasExtension(String namespace) {
  401.         synchronized (packetExtensions) {
  402.             for (ExtensionElement packetExtension : packetExtensions.values()) {
  403.                 if (packetExtension.getNamespace().equals(namespace)) {
  404.                     return true;
  405.                 }
  406.             }
  407.         }
  408.         return false;
  409.     }

  411.     /**
  412.      * Remove the packet extension with the given elementName and namespace.
  413.      *
  414.      * @param elementName
  415.      * @param namespace
  416.      * @return the removed packet extension or null.
  417.      */
  418.     public ExtensionElement removeExtension(String elementName, String namespace) {
  419.         String key = XmppStringUtils.generateKey(elementName, namespace);
  420.         synchronized (packetExtensions) {
  421.             return packetExtensions.remove(key);
  422.         }
  423.     }

  425.     /**
  426.      * Removes a packet extension from the packet.
  427.      *
  428.      * @param extension the packet extension to remove.
  429.      * @return the removed packet extension or null.
  430.      */
  431.     public ExtensionElement removeExtension(ExtensionElement extension)  {
  432.         return removeExtension(extension.getElementName(), extension.getNamespace());
  433.     }

  435.     @Override
  436.     // NOTE When Smack is using Java 8, then this method should be moved in Element as "Default Method".
  437.     public String toString() {
  438.         return toXML().toString();
  439.     }

  441.     /**
  442.      * Returns the extension sub-packets (including properties data) as an XML
  443.      * String, or the Empty String if there are no packet extensions.
  444.      *
  445.      * @return the extension sub-packets as XML or the Empty String if there
  446.      * are no packet extensions.
  447.      */
  448.     protected final XmlStringBuilder getExtensionsXML() {
  449.         XmlStringBuilder xml = new XmlStringBuilder();
  450.         // Add in all standard extension sub-packets.
  451.         for (ExtensionElement extension : getExtensions()) {
  452.             xml.append(extension.toXML());
  453.         }
  454.         return xml;
  455.     }

  457.     /**
  458.      * Returns the default language used for all messages containing localized content.
  459.      * 
  460.      * @return the default language
  461.      */
  462.     public static String getDefaultLanguage() {
  463.         return DEFAULT_LANGUAGE;
  464.     }

  466.     /**
  467.      * Add to, from, id and 'xml:lang' attributes
  468.      *
  469.      * @param xml
  470.      */
  471.     protected void addCommonAttributes(XmlStringBuilder xml) {
  472.         xml.optAttribute("to", getTo());
  473.         xml.optAttribute("from", getFrom());
  474.         xml.optAttribute("id", getStanzaId());
  475.         xml.xmllangAttribute(getLanguage());
  476.     }

  478.     /**
  479.      * Append an XMPPError is this packet has one set.
  480.      *
  481.      * @param xml the XmlStringBuilder to append the error to.
  482.      */
  483.     protected void appendErrorIfExists(XmlStringBuilder xml) {
  484.         XMPPError error = getError();
  485.         if (error != null) {
  486.             xml.append(error.toXML());
  487.         }
  488.     }
  489. }
Created with JaCoCo 0.7.4.201502262128