Smack XMPP Client Library

Providers are responsible for parsing the XMPP XML stream into new Java objects.

When implementing a provider, follow these patterns:

• Use a while(true) loop with a labeled break (e.g., outerloop:) to handle the parsing lifecycle.
• Use switch/case on XmlPullParser.Event (integers) for the main loop and switch/case on element names (Strings) for sub-elements.
• Use XmlPullParser.nextText() only when an element is required to have text.
• Use ParserUtils to parse Java primitives (e.g., ParserUtils.getBooleanAttribute, ParserUtils.getIntegerAttribute).
• Design the resulting classes to be as immutable as possible.

Common Pitfall: Use a long instead of int when the XML schema specifies xs:unsignedInt, as Java's int range is too small for this type.

public MyExtension parse(XmlPullParser parser, int initialDepth) {
  MyElement myElement = null;
  MyInfo myInfo = null;
  String attrFoo = parser.getAttributeValue("", "attrFoo");

  outerloop: while(true) {
    XmlPullParser.Event event = parser.next();

    switch (event) {
    case START_ELEMENT:
      String name = parser.getName();
      switch(name) {
      case "myElement":
        myElement = new MyElement(parser.nextText());
        break;
      case "myInfo":
        boolean alpha = ParserUtils.getBooleanAttribute(parser, "alpha");
        int delta = ParserUtils.getIntegerAttribute(parser, "delta");
        myInfo = new MyInfo(alpha, delta);
        break;
      }
      break;
    case END_ELEMENT:
      if (parser.getDepth() == initialDepth) {
        break outerloop;
      }
      break;
    default:
      break;
    }
  }

  return new MyExtension(attrFoo, myElement, myInfo);
}

An Ad-Hoc command is an abstraction for executing a service on an XMPP server and managing the resulting execution state. Each command instance is responsible for storing the results of its execution (such as data forms) and managing its lifecycle.

Key Concepts:

• Nodes: Each command has a node that must be unique within a given JID.
• Stages: Commands can consist of multiple stages. These stages are used to gather information required for execution. Users can move through stages using allowed actions like prev or next.
• Actions: During a stage, a user can perform specific actions. While a command cannot be cancelled while actively executing, a user can request a cancel action when submitting a stage response to abort the execution and release collected information.
• Session ID: Each execution is associated with a sessionId to track the state across multiple requests/stages.

Lifecycle and State:

• Completion: A command is considered finished when its status reaches AdHocCommandData.Status.completed (checked via isCompleted()).
• Error Handling: Commands may throw XMPPException during actions. Specific error conditions (like malformed-action or session-expired) can be extracted from the StanzaError to understand the failure reason.

The AdHocCommandManager handles both the server-side (hosting commands) and client-side (executing remote commands) aspects of the AdHoc Commands protocol.

Server-side (Hosting)

When you register commands, the manager:

1. Exposes via Service Discovery: Automatically adds the command nodes to the connection's service discovery information.
2. Handles Requests: Listens for incoming IQ requests. If a request has no sessionId, it starts a new session. If it has a sessionId, it resumes an existing execution.
3. Manages Multi-stage Sessions: Supports commands that require multiple steps (e.g., next, prev, complete, cancel). It tracks the state of these sessions in an executingCommands map.
4. Session Cleanup: A background 'sweeper' thread periodically removes expired sessions based on the configured sessionTimeoutSecs to prevent memory leaks.

Client-side (Executing)

When you use getRemoteCommand, you receive a proxy object. This allows you to interact with remote commands using a local API, abstracting the underlying XMPP stanzas.

The AdHocCommandData object represents the data returned by an Ad-Hoc command execution. It is constructed via an AdHocCommandDataBuilder and contains information about the command's status, the action being performed, session identifiers, associated data forms, notes, and potential errors.

Key components of an AdHocCommandData object include:

• Session ID: A unique identifier for the command session.
• Status: The current state of the command, which can be executing, completed, or canceled.
• Action: The specific action being taken (e.g., via the action attribute).
• Allowed Actions: A list of possible next steps, such as next, complete, or prev.
• Data Form: An optional DataForm (from the jabber:x:data namespace) containing structured data.
• Notes: A collection of AdHocCommandNote objects, which can be categorized by type (e.g., info).
• Error: A StanzaError if the command failed.