2015-02-06 09:33:37 +01:00
|
|
|
/**
|
|
|
|
*
|
|
|
|
* 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 {
|
|
|
|
|
2017-12-13 23:10:11 +01:00
|
|
|
String TEXT = "text";
|
|
|
|
String ITEM = "item";
|
2015-02-06 09:33:37 +01:00
|
|
|
|
|
|
|
/**
|
|
|
|
* 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.
|
|
|
|
*/
|
2017-12-13 23:10:11 +01:00
|
|
|
String getStanzaId();
|
2015-02-06 09:33:37 +01:00
|
|
|
|
|
|
|
/**
|
2015-03-29 12:15:32 +02:00
|
|
|
* Get the stanza id.
|
2015-02-06 09:33:37 +01:00
|
|
|
* @return the stanza id.
|
|
|
|
* @deprecated use {@link #getStanzaId()} instead.
|
|
|
|
*/
|
|
|
|
@Deprecated
|
2017-12-13 23:10:11 +01:00
|
|
|
String getPacketID();
|
2015-02-06 09:33:37 +01:00
|
|
|
|
|
|
|
/**
|
2018-03-31 14:17:30 +02:00
|
|
|
* Sets the unique ID of the packet. To indicate that a stanza has no id
|
2015-02-06 09:33:37 +01:00
|
|
|
* pass <code>null</code> as the packet's id value.
|
|
|
|
*
|
|
|
|
* @param id the unique ID for the packet.
|
|
|
|
*/
|
2017-12-13 23:10:11 +01:00
|
|
|
void setStanzaId(String id);
|
2015-02-06 09:33:37 +01:00
|
|
|
|
|
|
|
/**
|
2015-03-29 12:15:32 +02:00
|
|
|
* Set the stanza ID.
|
2015-02-06 09:33:37 +01:00
|
|
|
* @param packetID
|
|
|
|
* @deprecated use {@link #setStanzaId(String)} instead.
|
|
|
|
*/
|
|
|
|
@Deprecated
|
2017-12-13 23:10:11 +01:00
|
|
|
void setPacketID(String packetID);
|
2015-02-06 09:33:37 +01:00
|
|
|
|
|
|
|
/**
|
2018-03-31 14:17:30 +02:00
|
|
|
* Returns who the stanza is being sent "to", or <tt>null</tt> if
|
2015-02-06 09:33:37 +01:00
|
|
|
* the value is not set. The XMPP protocol often makes the "to"
|
|
|
|
* attribute optional, so it does not always need to be set.<p>
|
|
|
|
*
|
2018-03-31 14:17:30 +02:00
|
|
|
* @return who the stanza is being sent to, or <tt>null</tt> if the
|
2015-02-06 09:33:37 +01:00
|
|
|
* value has not been set.
|
|
|
|
*/
|
2017-12-13 23:10:11 +01:00
|
|
|
String getTo();
|
2015-02-06 09:33:37 +01:00
|
|
|
|
|
|
|
/**
|
2018-03-31 14:17:30 +02:00
|
|
|
* Sets who the stanza is being sent "to". The XMPP protocol often makes
|
2015-02-06 09:33:37 +01:00
|
|
|
* the "to" attribute optional, so it does not always need to be set.
|
|
|
|
*
|
2018-03-31 14:17:30 +02:00
|
|
|
* @param to who the stanza is being sent to.
|
2015-02-06 09:33:37 +01:00
|
|
|
*/
|
2017-12-13 23:10:11 +01:00
|
|
|
void setTo(String to);
|
2015-02-06 09:33:37 +01:00
|
|
|
|
|
|
|
/**
|
2018-03-31 14:17:30 +02:00
|
|
|
* Returns who the stanza is being sent "from" or <tt>null</tt> if
|
2015-02-06 09:33:37 +01:00
|
|
|
* the value is not set. The XMPP protocol often makes the "from"
|
|
|
|
* attribute optional, so it does not always need to be set.<p>
|
|
|
|
*
|
2018-03-31 14:17:30 +02:00
|
|
|
* @return who the stanza is being sent from, or <tt>null</tt> if the
|
2015-02-06 09:33:37 +01:00
|
|
|
* value has not been set.
|
|
|
|
*/
|
2017-12-13 23:10:11 +01:00
|
|
|
String getFrom();
|
2015-02-06 09:33:37 +01:00
|
|
|
|
|
|
|
/**
|
2018-03-31 14:17:30 +02:00
|
|
|
* Sets who the stanza is being sent "from". The XMPP protocol often
|
2015-02-06 09:33:37 +01:00
|
|
|
* makes the "from" attribute optional, so it does not always need to
|
|
|
|
* be set.
|
|
|
|
*
|
2018-03-31 14:17:30 +02:00
|
|
|
* @param from who the stanza is being sent to.
|
2015-02-06 09:33:37 +01:00
|
|
|
*/
|
2017-12-13 23:10:11 +01:00
|
|
|
void setFrom(String from);
|
2015-02-06 09:33:37 +01:00
|
|
|
|
|
|
|
/**
|
|
|
|
* 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.
|
|
|
|
*/
|
2018-04-07 21:25:40 +02:00
|
|
|
StanzaError getError();
|
2015-02-06 09:33:37 +01:00
|
|
|
/**
|
|
|
|
* Sets the error for this packet.
|
|
|
|
*
|
|
|
|
* @param error the error to associate with this packet.
|
|
|
|
*/
|
2018-04-07 21:25:40 +02:00
|
|
|
void setError(StanzaError error);
|
2015-02-06 09:33:37 +01:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Returns the xml:lang of this Stanza, or null if one has not been set.
|
|
|
|
*
|
|
|
|
* @return the xml:lang of this Stanza, or null.
|
|
|
|
*/
|
2017-12-13 23:10:11 +01:00
|
|
|
String getLanguage();
|
2015-02-06 09:33:37 +01:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Sets the xml:lang of this Stanza.
|
|
|
|
*
|
|
|
|
* @param language the xml:lang of this Stanza.
|
|
|
|
*/
|
2017-12-13 23:10:11 +01:00
|
|
|
void setLanguage(String language);
|
2015-02-06 09:33:37 +01:00
|
|
|
|
|
|
|
/**
|
2018-03-31 14:17:30 +02:00
|
|
|
* Returns a copy of the stanza extensions attached to the packet.
|
2015-02-06 09:33:37 +01:00
|
|
|
*
|
2018-03-31 14:17:30 +02:00
|
|
|
* @return the stanza extensions.
|
2015-02-06 09:33:37 +01:00
|
|
|
*/
|
2017-12-13 23:10:11 +01:00
|
|
|
List<ExtensionElement> getExtensions();
|
2015-02-06 09:33:37 +01:00
|
|
|
|
|
|
|
/**
|
2017-12-25 12:51:41 +01:00
|
|
|
* Return a set of all extensions with the given element name <i>and</i> namespace.
|
2015-02-06 09:33:37 +01:00
|
|
|
* <p>
|
2018-03-31 14:17:30 +02:00
|
|
|
* Changes to the returned set will update the stanza extensions, if the returned set is not the empty set.
|
2015-02-06 09:33:37 +01:00
|
|
|
* </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
|
|
|
|
*/
|
2017-12-13 23:10:11 +01:00
|
|
|
Set<ExtensionElement> getExtensions(String elementName, String namespace);
|
2015-02-06 09:33:37 +01:00
|
|
|
|
|
|
|
/**
|
2018-03-31 14:17:30 +02:00
|
|
|
* Returns the first extension of this stanza that has the given namespace.
|
2015-02-06 09:33:37 +01:00
|
|
|
* <p>
|
|
|
|
* When possible, use {@link #getExtension(String,String)} instead.
|
|
|
|
* </p>
|
|
|
|
*
|
|
|
|
* @param namespace the namespace of the extension that is desired.
|
2018-03-31 14:17:30 +02:00
|
|
|
* @return the stanza extension with the given namespace.
|
2015-02-06 09:33:37 +01:00
|
|
|
*/
|
2017-12-13 23:10:11 +01:00
|
|
|
ExtensionElement getExtension(String namespace);
|
2015-02-06 09:33:37 +01:00
|
|
|
|
|
|
|
/**
|
2018-03-31 14:17:30 +02:00
|
|
|
* Returns the first stanza extension that matches the specified element name and
|
2015-02-06 09:33:37 +01:00
|
|
|
* namespace, or <tt>null</tt> if it doesn't exist. If the provided elementName is null,
|
2018-04-23 21:06:35 +02:00
|
|
|
* only the namespace is matched. Stanza extensions are
|
2018-05-09 23:06:12 +02:00
|
|
|
* 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
|
2015-02-06 09:33:37 +01:00
|
|
|
* {@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.
|
|
|
|
*
|
2018-03-31 14:17:30 +02:00
|
|
|
* @param elementName the XML element name of the stanza extension. (May be null)
|
|
|
|
* @param namespace the XML element namespace of the stanza extension.
|
2017-12-23 20:21:19 +01:00
|
|
|
* @param <PE> type of the ExtensionElement.
|
2015-02-06 09:33:37 +01:00
|
|
|
* @return the extension, or <tt>null</tt> if it doesn't exist.
|
|
|
|
*/
|
2017-12-13 23:10:11 +01:00
|
|
|
<PE extends ExtensionElement> PE getExtension(String elementName, String namespace);
|
2015-02-06 09:33:37 +01:00
|
|
|
/**
|
2018-03-31 14:17:30 +02:00
|
|
|
* Adds a stanza extension to the packet. Does nothing if extension is null.
|
2015-02-06 09:33:37 +01:00
|
|
|
*
|
2018-03-31 14:17:30 +02:00
|
|
|
* @param extension a stanza extension.
|
2015-02-06 09:33:37 +01:00
|
|
|
*/
|
2017-12-13 23:10:11 +01:00
|
|
|
void addExtension(ExtensionElement extension);
|
2015-02-06 09:33:37 +01:00
|
|
|
|
|
|
|
/**
|
2018-03-31 14:17:30 +02:00
|
|
|
* Adds a collection of stanza extensions to the packet. Does nothing if extensions is null.
|
2018-05-09 23:06:12 +02:00
|
|
|
*
|
2018-03-31 14:17:30 +02:00
|
|
|
* @param extensions a collection of stanza extensions
|
2015-02-06 09:33:37 +01:00
|
|
|
*/
|
2017-12-13 23:10:11 +01:00
|
|
|
void addExtensions(Collection<ExtensionElement> extensions);
|
2015-02-06 09:33:37 +01:00
|
|
|
|
|
|
|
/**
|
2018-03-31 14:17:30 +02:00
|
|
|
* Check if a stanza extension with the given element and namespace exists.
|
2015-02-06 09:33:37 +01:00
|
|
|
* <p>
|
|
|
|
* The argument <code>elementName</code> may be null.
|
|
|
|
* </p>
|
|
|
|
*
|
|
|
|
* @param elementName
|
|
|
|
* @param namespace
|
2018-03-31 14:17:30 +02:00
|
|
|
* @return true if a stanza extension exists, false otherwise.
|
2015-02-06 09:33:37 +01:00
|
|
|
*/
|
2017-12-13 23:10:11 +01:00
|
|
|
boolean hasExtension(String elementName, String namespace);
|
2015-02-06 09:33:37 +01:00
|
|
|
|
|
|
|
/**
|
2018-03-31 14:17:30 +02:00
|
|
|
* Check if a stanza extension with the given namespace exists.
|
2018-05-09 23:06:12 +02:00
|
|
|
*
|
2015-02-06 09:33:37 +01:00
|
|
|
* @param namespace
|
2018-03-31 14:17:30 +02:00
|
|
|
* @return true if a stanza extension exists, false otherwise.
|
2015-02-06 09:33:37 +01:00
|
|
|
*/
|
2017-12-13 23:10:11 +01:00
|
|
|
boolean hasExtension(String namespace);
|
2015-02-06 09:33:37 +01:00
|
|
|
|
|
|
|
/**
|
2018-03-31 14:17:30 +02:00
|
|
|
* Remove the stanza extension with the given elementName and namespace.
|
2015-02-06 09:33:37 +01:00
|
|
|
*
|
|
|
|
* @param elementName
|
|
|
|
* @param namespace
|
2018-03-31 14:17:30 +02:00
|
|
|
* @return the removed stanza extension or null.
|
2015-02-06 09:33:37 +01:00
|
|
|
*/
|
2017-12-13 23:10:11 +01:00
|
|
|
ExtensionElement removeExtension(String elementName, String namespace);
|
2015-02-06 09:33:37 +01:00
|
|
|
|
|
|
|
/**
|
2018-03-31 14:17:30 +02:00
|
|
|
* Removes a stanza extension from the packet.
|
2015-02-06 09:33:37 +01:00
|
|
|
*
|
2018-03-31 14:17:30 +02:00
|
|
|
* @param extension the stanza extension to remove.
|
|
|
|
* @return the removed stanza extension or null.
|
2015-02-06 09:33:37 +01:00
|
|
|
*/
|
2017-12-13 23:10:11 +01:00
|
|
|
ExtensionElement removeExtension(ExtensionElement extension);
|
2015-02-06 09:33:37 +01:00
|
|
|
|
|
|
|
@Override
|
|
|
|
// NOTE When Smack is using Java 8, then this method should be moved in Element as "Default Method".
|
2017-12-13 23:10:11 +01:00
|
|
|
String toString();
|
2015-02-06 09:33:37 +01:00
|
|
|
|
|
|
|
}
|