org.xmpp.packet
Class IQ

java.lang.Object
  org.xmpp.packet.Packet
      org.xmpp.packet.IQ

Direct Known Subclasses:

DestroyRoom, RoomConfiguration, Roster

public class IQ
extends Packet

IQ (Info/Query) packet. IQ packets are used to get and set information on the server, including authentication, roster operations, and creating accounts. Each IQ packet has a specific type that indicates what type of action is being taken: "get", "set", "result", or "error".

IQ packets can contain a single child element that exists in a extended XML namespace.

Nested Class Summary

static class

IQ.Type Type-safe enumeration to represent the type of the IQ packet.

Field Summary

Fields inherited from class org.xmpp.packet.Packet

docFactory, element, fromJID, toJID

Constructor Summary

IQ()
Constructs a new IQ with an automatically generated ID and a type of IQ.Type.get.

IQ(org.dom4j.Element element)
Constructs a new IQ using an existing Element.

IQ(org.dom4j.Element element, boolean skipValidation)
Constructs a new IQ using an existing Element.

IQ(IQ.Type type)
Constructs a new IQ using the specified type.

IQ(IQ.Type type, String ID)
Constructs a new IQ using the specified type and ID.

Method Summary

void	addExtension(PacketExtension extension) Adds the element contained in the PacketExtension to the child element of the IQ packet.
IQ	createCopy() Returns a deep copy of this IQ.
static IQ	createResultIQ(IQ iq) Convenience method to create a new IQ.Type.result IQ based on a IQ.Type.get or IQ.Type.set IQ.
boolean	deleteExtension(String name, String namespace) Deletes the first element whose element name and namespace matches the specified element name and namespace in this packet's child element.
org.dom4j.Element	getChildElement() Returns the child element of this IQ.
PacketExtension	getExtension(String name, String namespace) Returns a PacketExtension on the first element found in this packet's child element for the specified name and namespace or null if none was found.
IQ.Type	getType() Returns the type of this IQ.
void	setChildElement(org.dom4j.Element childElement) Sets the child element of this IQ.
org.dom4j.Element	setChildElement(String name, String namespace) Sets the child element of this IQ by constructing a new Element with the given name and namespace.
void	setType(IQ.Type type) Sets the type of this IQ.

Methods inherited from class org.xmpp.packet.Packet

getElement, getError, getFrom, getID, getTo, setError, setError, setFrom, setFrom, setID, setTo, setTo, toString, toXML

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

IQ

public IQ()

Constructs a new IQ with an automatically generated ID and a type of IQ.Type.get.

IQ

public IQ(IQ.Type type)

Constructs a new IQ using the specified type. A packet ID will be automatically generated.

Parameters:

type - the IQ type.

IQ

public IQ(IQ.Type type,
          String ID)

Constructs a new IQ using the specified type and ID.

Parameters:

ID - the packet ID of the IQ.

type - the IQ type.

IQ

public IQ(org.dom4j.Element element)

Constructs a new IQ using an existing Element. This is useful for parsing incoming IQ Elements into IQ objects.

Parameters:

element - the IQ Element.

IQ

public IQ(org.dom4j.Element element,
          boolean skipValidation)

Constructs a new IQ using an existing Element. This is useful for parsing incoming IQ Elements into IQ objects. Stringprep validation on the TO address can be disabled. The FROM address will not be validated since the server is the one that sets that value.

Parameters:

element - the IQ Element.

skipValidation - true if stringprep should not be applied to the TO address.

Method Detail

getType

public IQ.Type getType()

Returns the type of this IQ.

Returns:

the IQ type.

See Also:

IQ.Type

setType

public void setType(IQ.Type type)

Sets the type of this IQ.

Parameters:

type - the IQ type.

See Also:

IQ.Type

getChildElement

public org.dom4j.Element getChildElement()

Returns the child element of this IQ. IQ packets may have a single child element in an extended namespace. This is a convenience method to avoid manipulating the underlying packet's Element instance directly.

An IQ child element in extended namespaces is used to extend the features of XMPP. Although any valid XML can be included in a child element in an extended namespace, many common features have been standardized as Jabber Enhancement Proposals (JEPs).

Returns:

the child element.

setChildElement

public void setChildElement(org.dom4j.Element childElement)

Sets the child element of this IQ. IQ packets may have a single child element in an extended namespace. This is a convenience method to avoid manipulating this underlying packet's Element instance directly.

A sample use of this method might look like the following:

 IQ iq = new IQ("time_1");
 iq.setTo("mary@example.com");
 iq.setType(IQ.Type.GET);
 iq.setChildElement(docFactory.createElement("query", "jabber:iq:time"));

An IQ child element in extended namespaces is used to extend the features of XMPP. Although any valid XML can be included in a child element in an extended namespace, many common features have been standardized as Jabber Enhancement Proposals (JEPs).

Parameters:

childElement - the child element.

setChildElement

public org.dom4j.Element setChildElement(String name,
                                         String namespace)

Sets the child element of this IQ by constructing a new Element with the given name and namespace. The newly created child element is returned. IQ packets may have a single child element in an extended namespace. This method is a convenience method to avoid manipulating the underlying packet's Element instance directly.

In some cases, additional custom sub-elements must be added to an IQ child element (called packet extensions). For example, when adding a data form to an IQ response. See addExtension(PacketExtension).

A sample use of this method might look like the following:

 IQ iq = new IQ("time_1");
 iq.setTo("mary@example.com");
 iq.setType(IQ.Type.GET);
 iq.setChildElement("query", "jabber:iq:time");

Parameters:

name - the child element name.

namespace - the child element namespace.

Returns:

the newly created child element.

addExtension

public void addExtension(PacketExtension extension)

Adds the element contained in the PacketExtension to the child element of the IQ packet. IQ packets, unlike the other packet types, have a unique child element that holds the packet extensions. If an extension is added to an IQ packet that does not have a child element then an IllegalStateException will be thrown.

It is important that this is the first and last time the element contained in PacketExtension is added to another Packet. Otherwise, a runtime error will be thrown when trying to add the PacketExtension's element to the Packet's element. Future modifications to the PacketExtension will be reflected in this Packet.

Note: packet extensions on IQ packets are only for use in specialized situations. In most cases, you should only need to set the child element of the IQ.

Overrides:

addExtension in class Packet

Parameters:

extension - the PacketExtension whose element will be added to this Packet's element.

getExtension

public PacketExtension getExtension(String name,
                                    String namespace)

Returns a PacketExtension on the first element found in this packet's child element for the specified name and namespace or null if none was found. If the IQ packet does not have a child element then null will be returned.

Note: packet extensions on IQ packets are only for use in specialized situations. In most cases, you should only need to set the child element of the IQ.

Overrides:

getExtension in class Packet

Parameters:

name - the child element name.

namespace - the child element namespace.

Returns:

a PacketExtension on the first element found in this packet for the specified name and namespace or null if none was found.

deleteExtension

public boolean deleteExtension(String name,
                               String namespace)

Deletes the first element whose element name and namespace matches the specified element name and namespace in this packet's child element. If the IQ packet does not have a child element then this method does nothing and returns false.

Notice that this method may remove any child element that matches the specified element name and namespace even if that element was not added to the Packet using a PacketExtension.

Note: packet extensions on IQ packets are only for use in specialized situations. In most cases, you should only need to set the child element of the IQ.

Overrides:

deleteExtension in class Packet

Parameters:

name - the child element name.

namespace - the child element namespace.

Returns:

true if a child element was removed.

createCopy

public IQ createCopy()

Returns a deep copy of this IQ.

Specified by:

createCopy in class Packet

Returns:

a deep copy of this IQ.

createResultIQ

public static IQ createResultIQ(IQ iq)

Convenience method to create a new IQ.Type.result IQ based on a IQ.Type.get or IQ.Type.set IQ. The new packet will be initialized with:

• The sender set to the recipient of the originating IQ.
• The recipient set to the sender of the originating IQ.
• The type set to IQ.Type.result.
• The id set to the id of the originating IQ.

Parameters:

iq - the IQ.Type.get or IQ.Type.set IQ packet.

Returns:

a new IQ.Type.result IQ based on the originating IQ.

Throws:

IllegalArgumentException - if the IQ packet does not have a type of IQ.Type.get or IQ.Type.set.