org.jivesoftware.smack.packet
Class Packet

java.lang.Object
  org.jivesoftware.smack.packet.Packet

Direct Known Subclasses:

IQ, Message, Presence

public abstract class Packet
extends Object

Base class for XMPP packets. Every packet has a unique ID (which is automatically generated, but can be overriden). Optionally, the "to" and "from" fields can be set, as well as an arbitrary number of properties. Properties provide an easy mechanism for clients to share data. Each property has a String name, and a value that is a Java primitive (int, long, float, double, boolean) or any Serializable object (a Java object is Serializable when it implements the Serializable interface).

Author:

Matt Tucker

Field Summary

protected static String	DEFAULT_LANGUAGE
static String	ID_NOT_AVAILABLE Constant used as packetID to indicate that a packet has no id.

Constructor Summary

Packet()

Method Summary

void	addExtension(PacketExtension extension) Adds a packet extension to the packet.
void	deleteProperty(String name) Deletes a property.
boolean	equals(Object o)
protected static String	getDefaultLanguage()
XMPPError	getError() Returns the error associated with this packet, or null if there are no errors.
PacketExtension	getExtension(String namespace) Returns the first extension of this packet that has the given namespace.
PacketExtension	getExtension(String elementName, String namespace) Returns the first packet extension that matches the specified element name and namespace, or null if it doesn't exist.
Collection<PacketExtension>	getExtensions() Returns an unmodifiable collection of the packet extensions attached to the packet.
protected String	getExtensionsXML() Returns the extension sub-packets (including properties data) as an XML String, or the Empty String if there are no packet extensions.
String	getFrom() Returns who the packet is being sent "from" or null if the value is not set.
String	getPacketID() Returns the unique ID of the packet.
Object	getProperty(String name) Returns the packet property with the specified name or null if the property doesn't exist.
Collection<String>	getPropertyNames() Returns an unmodifiable collection of all the property names that are set.
String	getTo() Returns who the packet is being sent "to", or null if the value is not set.
String	getXmlns()
int	hashCode()
static String	nextID() Returns the next unique id.
protected static String	parseXMLLang(String language)
void	removeExtension(PacketExtension extension) Removes a packet extension from the packet.
static void	setDefaultXmlns(String defaultXmlns)
void	setError(XMPPError error) Sets the error for this packet.
void	setFrom(String from) Sets who the packet is being sent "from".
void	setPacketID(String packetID) Sets the unique ID of the packet.
void	setProperty(String name, Object value) Sets a property with an Object as the value.
void	setTo(String to) Sets who the packet is being sent "to".
abstract String	toXML() Returns the packet as XML.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_LANGUAGE

protected static final String DEFAULT_LANGUAGE

ID_NOT_AVAILABLE

public static final String ID_NOT_AVAILABLE

Constant used as packetID to indicate that a packet has no id. To indicate that a packet has no id set this constant as the packet's id. When the packet is asked for its id the answer will be null.

See Also:

Constant Field Values

Constructor Detail

Packet

public Packet()

Method Detail

nextID

public static String nextID()

Returns the next unique id. Each id made up of a short alphanumeric prefix along with a unique numeric value.

Returns:

the next id.

setDefaultXmlns

public static void setDefaultXmlns(String defaultXmlns)

getPacketID

public String getPacketID()

Returns the unique ID of the packet. The returned value could be null when ID_NOT_AVAILABLE was set as the packet's id.

Returns:

the packet's unique ID or null if the packet's id is not available.

setPacketID

public void setPacketID(String packetID)

Sets the unique ID of the packet. To indicate that a packet has no id pass the constant ID_NOT_AVAILABLE as the packet's id value.

Parameters:

packetID - the unique ID for the packet.

getTo

public String getTo()

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.

The StringUtils class provides several useful methods for dealing with XMPP addresses such as parsing the bare address, user name, server, and resource.

Returns:

who the packet is being sent to, or null if the value has not been set.

setTo

public void setTo(String 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 String getFrom()

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.

The StringUtils class provides several useful methods for dealing with XMPP addresses such as parsing the bare address, user name, server, and resource.

Returns:

who the packet is being sent from, or null if the value has not been set.

setFrom

public void setFrom(String 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 XMPPError getError()

Returns the error associated with this packet, or null if there are no errors.

Returns:

the error sub-packet or null if there isn't an error.

setError

public void setError(XMPPError error)

Sets the error for this packet.

Parameters:

error - the error to associate with this packet.

getExtensions

public Collection<PacketExtension> getExtensions()

Returns an unmodifiable collection of the packet extensions attached to the packet.

Returns:

the packet extensions.

getExtension

public PacketExtension getExtension(String namespace)

Returns the first extension of this packet that has the given namespace.

Parameters:

namespace - the namespace of the extension that is desired.

Returns:

the packet extension with the given namespace.

getExtension

public PacketExtension getExtension(String elementName,
                                    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 than only the provided namespace is attempted to be 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 ProviderManager class to handle custom parsing. In that case, the type of the Object will be determined by the provider.

Parameters:

elementName - the XML element name of the packet extension. (May be null)

namespace - the XML element namespace of the packet extension.

Returns:

the extension, or null if it doesn't exist.

addExtension

public void addExtension(PacketExtension extension)

Adds a packet extension to the packet.

Parameters:

extension - a packet extension.

removeExtension

public void removeExtension(PacketExtension extension)

Removes a packet extension from the packet.

Parameters:

extension - the packet extension to remove.

getProperty

public Object getProperty(String name)

Returns the packet property with the specified name or null if the property doesn't exist. Property values that were orginally primitives will be returned as their object equivalent. For example, an int property will be returned as an Integer, a double as a Double, etc.

Parameters:

name - the name of the property.

Returns:

the property, or null if the property doesn't exist.

setProperty

public void setProperty(String name,
                        Object value)

Sets a property with an Object as the value. The value must be Serializable or an IllegalArgumentException will be thrown.

Parameters:

name - the name of the property.

value - the value of the property.

deleteProperty

public void deleteProperty(String name)

Deletes a property.

Parameters:

name - the name of the property to delete.

getPropertyNames

public Collection<String> getPropertyNames()

Returns an unmodifiable collection of all the property names that are set.

Returns:

all property names.

toXML

public abstract String toXML()

Returns the packet as XML. Every concrete extension of Packet must implement this method. In addition to writing out packet-specific data, every sub-class should also write out the error and the extensions data if they are defined.

Returns:

the XML format of the packet as a String.

getExtensionsXML

protected String getExtensionsXML()

Returns the extension sub-packets (including properties data) as an XML String, or the Empty String if there are no packet extensions.

Returns:

the extension sub-packets as XML or the Empty String if there are no packet extensions.

getXmlns

public String getXmlns()

parseXMLLang

protected static String parseXMLLang(String language)

getDefaultLanguage

protected static String getDefaultLanguage()

equals

public boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object