Package org.xmpp.packet

Class IQ

  • Direct Known Subclasses:
    DestroyRoom, RoomConfiguration, Roster
    @NotThreadSafe
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.

    • 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

      • isRequest

        public boolean isRequest()
        Convenience routine to indicate if this is a request stanza. (get or set)
        Returns:
        True or false if this is a request stanza

      • isResponse

        public boolean isResponse()
        Convenience routine to indicate if this is a response stanza. (result or error)
        Returns:
        True or false if this is a response stanza

      • 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 XMPP Extension Protocols (XEPs).

        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 XMPP Extension Protocols (XEPs).

        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.