Package rocks.xmpp.core.stanza.model

Class IQ

java.lang.Object

rocks.xmpp.core.stanza.model.Stanza

rocks.xmpp.core.stanza.model.IQ

All Implemented Interfaces:

LanguageElement, StreamElement

Direct Known Subclasses:

ClientIQ, ComponentIQ, ServerIQ

public class IQ
extends Stanza

The implementation of the <iq/> stanza.

8.2.3. IQ Semantics

Info/Query, or IQ, is a "request-response" mechanism, similar in some ways to the Hypertext Transfer Protocol [HTTP]. The semantics of IQ enable an entity to make a request of, and receive a response from, another entity. The data content of the request and response is defined by the schema or other structural definition associated with the XML namespace that qualifies the direct child element of the IQ element (see Section 8.4), and the interaction is tracked by the requesting entity through use of the 'id' attribute. Thus, IQ interactions follow a common pattern of structured data exchange such as get/result or set/result (although an error can be returned in reply to a request if appropriate)

To enforce these semantics, the following rules apply:

1. The 'id' attribute is REQUIRED for IQ stanzas.
2. The 'type' attribute is REQUIRED for IQ stanzas. The value MUST be one of the following; if not, the recipient or an intermediate router MUST return a <bad-request/> stanza error (Section 8.3.3.1).
   • get -- The stanza requests information, inquires about what data is needed in order to complete further operations, etc.
   • set -- The stanza provides data that is needed for an operation to be completed, sets new values, replaces existing values, etc.
   • result -- The stanza is a response to a successful get or set request.
   • error -- The stanza reports an error that has occurred regarding processing or delivery of a get or set request (see Section 8.3).
3. An entity that receives an IQ request of type "get" or "set" MUST reply with an IQ response of type "result" or "error". The response MUST preserve the 'id' attribute of the request (or be empty if the generated stanza did not include an 'id' attribute).
4. An entity that receives a stanza of type "result" or "error" MUST NOT respond to the stanza by sending a further IQ response of type "result" or "error"; however, the requesting entity MAY send another request (e.g., an IQ of type "set" to provide obligatory information discovered through a get/result pair).
5. An IQ stanza of type "get" or "set" MUST contain exactly one child element, which specifies the semantics of the particular request.
6. An IQ stanza of type "result" MUST include zero or one child elements.
7. An IQ stanza of type "error" MAY include the child element contained in the associated "get" or "set" and MUST include an <error/> child.

This class is thread-safe.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	IQ.Type	Represents a <iq/> 'type' attribute.

Constructor Summary

Constructors

Constructor	Description
IQ(Jid to, IQ.Type type, Object extension)	Creates an IQ stanza with the given receiver, type and extension.
IQ(Jid to, IQ.Type type, Object extension, String id)	Creates an IQ stanza with the given receiver, id, type and extension.
IQ(Jid to, IQ.Type type, Object extension, String id, Jid from, Locale language, StanzaError error)	Creates an IQ stanza with the given receiver, id, type, extension and error.
IQ(IQ.Type type, Object extension)	Creates an IQ stanza with the given type and extension.
IQ(IQ.Type type, Object extension, String id)	Creates an IQ stanza with the given id, type and extension.

Method Summary

Modifier and Type	Method	Description
IQ	createError(Condition condition)	Creates an error response for this stanza.
IQ	createError(StanzaError error)	Creates an error response for this stanza.
IQ	createError(StanzaError error, boolean includeOriginal)	Creates an error response for this stanza.
IQ	createResult()	Creates a result IQ stanza, i.e. it uses the same id as this IQ, sets the type to 'result' and switches the 'to' and 'from' attribute.
IQ	createResult(Object extension)	Creates a result IQ stanza with a payload, i.e. it uses the same id as this IQ, sets the type to 'result' and switches the 'to' and 'from' attribute.
static IQ	get(Object extension)	Creates an IQ of type 'get' with a random id.
static IQ	get(Jid to, Object extension)	Creates an IQ of type 'get' with a random id.
IQ.Type	getType()	Gets the type.
boolean	isRequest()	Returns if this is a request IQ, i.e. of type get or set.
boolean	isResponse()	Returns true, if this IQ is a response (either a positive result or an error).
static IQ	set(Object extension)	Creates an IQ of type 'set' with a random id.
static IQ	set(Jid to, Object extension)	Creates an IQ of type 'set' with a random id.
void	setType(IQ.Type type)	Sets the type.
String	toString()

Methods inherited from class rocks.xmpp.core.stanza.model.Stanza

getError, getExtension, getFrom, getId, getLanguage, getTo, hasExtension, isToItselfOrServer, setError, setFrom, setId, setLanguage, setTo

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

IQ

public IQ(IQ.Type type,
          Object extension)

Creates an IQ stanza with the given type and extension. The id attribute will be generated randomly.

Parameters:

type - The type.

extension - The extension.

IQ

public IQ(IQ.Type type,
          Object extension,
          String id)

Creates an IQ stanza with the given id, type and extension.

Parameters:

type - The type.

extension - The extension.

id - The id.

IQ

public IQ(Jid to,
          IQ.Type type,
          Object extension)

Creates an IQ stanza with the given receiver, type and extension. The id attribute will be generated randomly.

Parameters:

to - The receiver.

type - The type.

extension - The extension.

IQ

public IQ(Jid to,
          IQ.Type type,
          Object extension,
          String id)

Creates an IQ stanza with the given receiver, id, type and extension.

Parameters:

to - The receiver.

type - The type.

extension - The extension.

id - The id.

IQ

public IQ(Jid to,
          IQ.Type type,
          Object extension,
          String id,
          Jid from,
          Locale language,
          StanzaError error)

Creates an IQ stanza with the given receiver, id, type, extension and error.

Parameters:

to - The receiver.

type - The type.

extension - The extension.

id - The id.

from - The sender.

language - The language.

error - The error.

Method Detail

get

public static IQ get(Object extension)

Creates an IQ of type 'get' with a random id.

Parameters:

extension - The extension.

Returns:

The IQ.

get

public static IQ get(Jid to,
                     Object extension)

Creates an IQ of type 'get' with a random id.

Parameters:

to - The 'to' attribute.

extension - The extension.

Returns:

The IQ.

set

public static IQ set(Object extension)

Creates an IQ of type 'set' with a random id.

Parameters:

extension - The extension.

Returns:

The IQ.

set

public static IQ set(Jid to,
                     Object extension)

Creates an IQ of type 'set' with a random id.

Parameters:

to - The 'to' attribute.

extension - The extension.

Returns:

The IQ.

getType

public final IQ.Type getType()

Gets the type.

Returns:

The type.

setType

public final void setType(IQ.Type type)

Sets the type.

Parameters:

type - The type.

toString

public final String toString()

Overrides:

toString in class Stanza

isRequest

public final boolean isRequest()

Returns if this is a request IQ, i.e. of type get or set.

Returns:

True if this is a get or set IQ.

isResponse

public final boolean isResponse()

Returns true, if this IQ is a response (either a positive result or an error).

Returns:

If this is a result or error IQ.

createResult

public IQ createResult()

Creates a result IQ stanza, i.e. it uses the same id as this IQ, sets the type to 'result' and switches the 'to' and 'from' attribute.

Returns:

The result IQ stanza.

createResult

public final IQ createResult(Object extension)

Creates a result IQ stanza with a payload, i.e. it uses the same id as this IQ, sets the type to 'result' and switches the 'to' and 'from' attribute.

Parameters:

extension - The extension.

Returns:

The result IQ stanza.

createError

public final IQ createError(StanzaError error,
                            boolean includeOriginal)

Creates an error response for this stanza.

Parameters:

error - The error which is appended to the stanza.

includeOriginal - If true, includes the original child element in the error response.

Returns:

The error response.

See Also:

Stanza.getError()

createError

public final IQ createError(StanzaError error)

Description copied from class: Stanza

Creates an error response for this stanza.

Specified by:

createError in class Stanza

Parameters:

error - The error which is appended to the stanza.

Returns:

The error response.

See Also:

Stanza.getError()

createError

public final IQ createError(Condition condition)

Description copied from class: Stanza

Creates an error response for this stanza.

Specified by:

createError in class Stanza

Parameters:

condition - The error condition which is appended to the stanza.

Returns:

The error response.

See Also:

Stanza.getError()