Add 'Packet' interface

to aid transition to the new 'Stanza' class ('Packet' was renamed to
'Stanza' a few commits before this).

smack-core/src/main/java/org/jivesoftware/smack/packet/Packet.java

@@ -0,0 +1,232 @@
+/**
+ *
+ * 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 java.util.Collection;
+import java.util.List;
+import java.util.Set;
+
+/**
+ * Deprecated interface of pre Smack 4.1 Stanzas.
+ * @deprecated use {@link Stanza} instead
+ */
+@Deprecated
+public interface Packet extends TopLevelStreamElement {
+
+    public static final String TEXT = "text";
+    public static final String ITEM = "item";
+
+    /**
+     * Returns the unique ID of the stanza. The returned value could be <code>null</code>.
+     *
+     * @return the packet's unique ID or <code>null</code> if the id is not available.
+     */
+    public String getStanzaId();
+
+    /**
+     * 
+     * @return the stanza id.
+     * @deprecated use {@link #getStanzaId()} instead.
+     */
+    @Deprecated
+    public String getPacketID();
+
+    /**
+     * Sets the unique ID of the packet. To indicate that a packet has no id
+     * pass <code>null</code> as the packet's id value.
+     *
+     * @param id the unique ID for the packet.
+     */
+    public void setStanzaId(String id);
+
+    /**
+     * 
+     * @param packetID
+     * @deprecated use {@link #setStanzaId(String)} instead.
+     */
+    @Deprecated
+    public void setPacketID(String packetID);
+
+    /**
+     * Returns who the packet is being sent "to", or <tt>null</tt> if
+     * the value is not set. The XMPP protocol often makes the "to"
+     * attribute optional, so it does not always need to be set.<p>
+     *
+     * @return who the packet is being sent to, or <tt>null</tt> if the
+     *      value has not been set.
+     */
+    public String getTo();
+
+    /**
+     * 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.
+     */
+    public void setTo(String to);
+
+    /**
+     * Returns who the packet is being sent "from" or <tt>null</tt> if
+     * the value is not set. The XMPP protocol often makes the "from"
+     * attribute optional, so it does not always need to be set.<p>
+     *
+     * @return who the packet is being sent from, or <tt>null</tt> if the
+     *      value has not been set.
+     */
+    public String getFrom();
+
+    /**
+     * 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.
+     */
+    public void setFrom(String from);
+
+    /**
+     * Returns the error associated with this packet, or <tt>null</tt> if there are
+     * no errors.
+     *
+     * @return the error sub-packet or <tt>null</tt> if there isn't an error.
+     */
+    public XMPPError getError();
+    /**
+     * Sets the error for this packet.
+     *
+     * @param error the error to associate with this packet.
+     */
+    public void setError(XMPPError error);
+
+    /**
+     * Returns the xml:lang of this Stanza, or null if one has not been set.
+     *
+     * @return the xml:lang of this Stanza, or null.
+     */
+    public String getLanguage();
+
+    /**
+     * Sets the xml:lang of this Stanza.
+     *
+     * @param language the xml:lang of this Stanza.
+     */
+    public void setLanguage(String language);
+
+    /**
+     * Returns a copy of the packet extensions attached to the packet.
+     *
+     * @return the packet extensions.
+     */
+    public List<PacketExtension> getExtensions();
+
+    /**
+     * Return a set of all extensions with the given element name <emph>and</emph> namespace.
+     * <p>
+     * Changes to the returned set will update the packet extensions, if the returned set is not the empty set.
+     * </p>
+     *
+     * @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 Set<PacketExtension> getExtensions(String elementName, String namespace);
+
+    /**
+     * Returns the first extension of this packet that has the given namespace.
+     * <p>
+     * When possible, use {@link #getExtension(String,String)} instead.
+     * </p>
+     *
+     * @param namespace the namespace of the extension that is desired.
+     * @return the packet extension with the given namespace.
+     */
+    public PacketExtension getExtension(String namespace);
+
+    /**
+     * Returns the first packet extension that matches the specified element name and
+     * namespace, or <tt>null</tt> if it doesn't exist. If the provided elementName is null,
+     * only the namespace is matched. Packet extensions are
+     * are arbitrary XML sub-documents in standard XMPP packets. By default, a 
+     * DefaultPacketExtension instance will be returned for each extension. However, 
+     * PacketExtensionProvider instances can be registered with the 
+     * {@link org.jivesoftware.smack.provider.ProviderManager ProviderManager}
+     * class to handle custom parsing. In that case, the type of the Object
+     * will be determined by the provider.
+     *
+     * @param elementName the XML element name of the packet extension. (May be null)
+     * @param namespace the XML element namespace of the packet extension.
+     * @return the extension, or <tt>null</tt> if it doesn't exist.
+     */
+    public <PE extends PacketExtension> PE getExtension(String elementName, String namespace);
+    /**
+     * Adds a packet extension to the packet. Does nothing if extension is null.
+     *
+     * @param extension a packet extension.
+     */
+    public void addExtension(PacketExtension extension);
+
+    /**
+     * Adds a collection of packet extensions to the packet. Does nothing if extensions is null.
+     * 
+     * @param extensions a collection of packet extensions
+     */
+    public void addExtensions(Collection<PacketExtension> extensions);
+
+    /**
+     * Check if a packet extension with the given element and namespace exists.
+     * <p>
+     * The argument <code>elementName</code> may be null.
+     * </p>
+     *
+     * @param elementName
+     * @param namespace
+     * @return true if a packet extension exists, false otherwise.
+     */
+    public boolean hasExtension(String elementName, String namespace);
+
+    /**
+     * Check if a packet extension with the given namespace exists.
+     * 
+     * @param namespace
+     * @return true if a packet extension exists, false otherwise.
+     */
+    public boolean hasExtension(String namespace);
+
+    /**
+     * Remove the packet extension with the given elementName and namespace.
+     *
+     * @param elementName
+     * @param namespace
+     * @return the removed packet extension or null.
+     */
+    public PacketExtension removeExtension(String elementName, String namespace);
+
+    /**
+     * Removes a packet extension from the packet.
+     *
+     * @param extension the packet extension to remove.
+     * @return the removed packet extension or null.
+     */
+    public PacketExtension removeExtension(PacketExtension extension);
+
+    @Override
+    // NOTE When Smack is using Java 8, then this method should be moved in Element as "Default Method".
+    public String toString();
+
+}

smack-core/src/main/java/org/jivesoftware/smack/packet/Stanza.java

@@ -45,7 +45,8 @@ import java.util.Set;
  * @author Matt Tucker
  * @see <a href="http://xmpp.org/rfcs/rfc6120.html#stanzas">RFC 6120 § 8. XML Stanzas</a>
  */
-public abstract class Stanza implements TopLevelStreamElement {
+@SuppressWarnings("deprecation") // FIXME Remove when 'Packet' is removed from Smack
+public abstract class Stanza implements TopLevelStreamElement, Packet {
 
     public static final String TEXT = "text";
     public static final String ITEM = "item";