From 1190edad0f639ea59d9dcc92b7934d614db39e9f Mon Sep 17 00:00:00 2001 From: Florian Schmaus Date: Fri, 6 Feb 2015 09:33:37 +0100 Subject: [PATCH] Add 'Packet' interface to aid transition to the new 'Stanza' class ('Packet' was renamed to 'Stanza' a few commits before this). --- .../org/jivesoftware/smack/packet/Packet.java | 232 ++++++++++++++++++ .../org/jivesoftware/smack/packet/Stanza.java | 3 +- 2 files changed, 234 insertions(+), 1 deletion(-) create mode 100644 smack-core/src/main/java/org/jivesoftware/smack/packet/Packet.java diff --git a/smack-core/src/main/java/org/jivesoftware/smack/packet/Packet.java b/smack-core/src/main/java/org/jivesoftware/smack/packet/Packet.java new file mode 100644 index 000000000..55f301ed4 --- /dev/null +++ b/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 null. + * + * @return the packet's unique ID or null 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 null 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 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.

+ * + * @return who the packet is being sent to, or null 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 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.

+ * + * @return who the packet is being sent from, or null 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 null if there are + * no errors. + * + * @return the error sub-packet or null 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 getExtensions(); + + /** + * Return a set of all extensions with the given element name and namespace. + *

+ * Changes to the returned set will update the packet extensions, if the returned set is not the empty set. + *

+ * + * @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 getExtensions(String elementName, String namespace); + + /** + * Returns the first extension of this packet that has the given namespace. + *

+ * When possible, use {@link #getExtension(String,String)} instead. + *

+ * + * @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 null 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 null if it doesn't exist. + */ + public 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 extensions); + + /** + * Check if a packet extension with the given element and namespace exists. + *

+ * The argument elementName may be null. + *

+ * + * @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(); + +} diff --git a/smack-core/src/main/java/org/jivesoftware/smack/packet/Stanza.java b/smack-core/src/main/java/org/jivesoftware/smack/packet/Stanza.java index 76c173acc..b7226a965 100644 --- a/smack-core/src/main/java/org/jivesoftware/smack/packet/Stanza.java +++ b/smack-core/src/main/java/org/jivesoftware/smack/packet/Stanza.java @@ -45,7 +45,8 @@ import java.util.Set; * @author Matt Tucker * @see RFC 6120 ยง 8. XML Stanzas */ -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";