Class IQ

  • All Implemented Interfaces:
    Element, FullyQualifiedElement, IqView, NamedElement, StanzaView, TopLevelStreamElement, XmlLangElement
    Direct Known Subclasses:
    Bind, EmptyResultIQ, SimpleIQ, UnparsedIQ

    public abstract class IQ
    extends Stanza
    implements IqView
    The base 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 stanza 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 specific XML namespace. The combination of the element name and namespace determines what type of IQ stanza it is. Some example IQ subpacket snippets:

    • <query xmlns="jabber:iq:auth"> -- an authentication IQ.
    • <query xmlns="jabber:iq:private"> -- a private storage IQ.
    • <pubsub xmlns="http://jabber.org/protocol/pubsub"> -- a pubsub IQ.
    • Constructor Detail

      • IQ

        protected IQ​(IQ iq)
      • IQ

        protected IQ​(java.lang.String childElementName,
                     java.lang.String childElementNamespace)
      • IQ

        protected IQ​(AbstractIqBuilder<?> iqBuilder,
                     java.lang.String childElementName,
                     java.lang.String childElementNamespace)
    • Method Detail

      • getType

        public IQ.Type getType()
        Description copied from interface: IqView
        Returns the type of the IQ packet.
        Specified by:
        getType in interface IqView
        Returns:
        the type of the IQ packet.
      • setType

        public void setType​(IQ.Type type)
        Sets the type of the IQ packet.

        Since the type of an IQ must present, an IllegalArgmentException will be thrown when type is null.

        Parameters:
        type - the type of the IQ packet.
      • isRequestIQ

        public boolean isRequestIQ()
        Return true if this IQ is a request IQ, i.e. an IQ of type IQ.Type.get or IQ.Type.set.
        Returns:
        true if IQ type is 'get' or 'set', false otherwise.
        Since:
        4.1
      • isResponseIQ

        public boolean isResponseIQ()
        Return true if this IQ is a request, i.e. an IQ of type IQ.Type.result or IQ.Type.error.
        Returns:
        true if IQ type is 'result' or 'error', false otherwise.
        Since:
        4.4
      • getChildElementQName

        public final javax.xml.namespace.QName getChildElementQName()
      • getChildElementName

        public final java.lang.String getChildElementName()
      • getChildElementNamespace

        public final java.lang.String getChildElementNamespace()
      • getElementName

        public final java.lang.String getElementName()
        Description copied from interface: NamedElement
        Returns the root element name.
        Specified by:
        getElementName in interface NamedElement
        Returns:
        the element name.
      • toString

        public final java.lang.String toString()
        Description copied from class: Stanza
        Returns a short String describing the Stanza. This method is suited for log purposes.
        Specified by:
        toString in class Stanza
      • getChildElementXML

        public final XmlStringBuilder getChildElementXML()
        Returns the sub-element XML section of the IQ packet, or the empty String if there isn't one.
        Returns:
        the child element section of the IQ XML.
      • getIQChildElementBuilder

        protected abstract IQ.IQChildElementXmlStringBuilder getIQChildElementBuilder​(IQ.IQChildElementXmlStringBuilder xml)
        This method must be overwritten by IQ subclasses to create their child content. It is important you don't use the builder to add the final end tag. This will be done automatically by IQ.IQChildElementXmlStringBuilder after eventual existing ExtensionElements have been added.

        For example to create an IQ with a extra attribute and an additional child element

         
         <iq to='foo@example.org' id='123'>
           <bar xmlns='example:bar' extraAttribute='blaz'>
              <extraElement>elementText</extraElement>
           </bar>
         </iq>
         
         
        the body of the getIQChildElementBuilder looks like
         
         // The builder 'xml' will already have the child element and the 'xmlns' attribute added
         // So the current builder state is "<bar xmlns='example:bar'"
         xml.attribute("extraAttribute", "blaz");
         xml.rightAngleBracket();
         xml.element("extraElement", "elementText");
         // Do not close the 'bar' attribute by calling xml.closeElement('bar')
         
         
        If your IQ only contains attributes and no child elements, i.e. it can be represented as empty element, then you can mark it as such.
         xml.attribute("myAttribute", "myAttributeValue");
         xml.setEmptyElement();
         
        If your IQ does not contain any attributes or child elements (besides ExtensionElements), consider sub-classing SimpleIQ instead.
        Parameters:
        xml - a pre-created builder which already has the child element and the 'xmlns' attribute set.
        Returns:
        the build to create the IQ child content.
      • createResultIQ

        public static IQ createResultIQ​(IQ request)
        Convenience method to create a new empty IQ.Type.result IQ based on a IQ.Type.get or IQ.Type.set IQ. The new stanza 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.
        • No child element of the IQ element.
        Parameters:
        request - the IQ.Type.get or IQ.Type.set IQ packet.
        Returns:
        a new IQ.Type.result IQ based on the originating IQ.
        Throws:
        java.lang.IllegalArgumentException - if the IQ stanza does not have a type of IQ.Type.get or IQ.Type.set.
      • createErrorResponse

        public static ErrorIQ createErrorResponse​(IQ request,
                                                  StanzaError error)
        Convenience method to create a new IQ.Type.error IQ based on a IQ.Type.get or IQ.Type.set IQ. The new stanza 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.error.
        • The id set to the id of the originating IQ.
        • The child element contained in the associated originating IQ.
        • The provided XMPPError.
        Parameters:
        request - the IQ.Type.get or IQ.Type.set IQ packet.
        error - the error to associate with the created IQ packet.
        Returns:
        a new IQ.Type.error IQ based on the originating IQ.
        Throws:
        java.lang.IllegalArgumentException - if the IQ stanza does not have a type of IQ.Type.get or IQ.Type.set.