AdHocCommand (Smack Parent POM 4.1.5 API)

java.lang.Object
- org.jivesoftware.smackx.commands.AdHocCommand

Direct Known Subclasses:

LocalCommand, RemoteCommand
```
public abstract class AdHocCommand
extends Object
```
An ad-hoc command is responsible for executing the provided service and storing the result of the execution. Each new request will create a new instance of the command, allowing information related to executions to be stored in it. For example suppose that a command that retrieves the list of users on a server is implemented. When the command is executed it gets that list and the result is stored as a form in the command instance, i.e. the getForm method retrieves a form with all the users.
Each command has a node that should be unique within a given JID.
Commands may have zero or more stages. Each stage is usually used for gathering information required for the command execution. Users are able to move forward or backward across the different stages. Commands may not be cancelled while they are being executed. However, users may request the "cancel" action when submitting a stage response indicating that the command execution should be aborted. Thus, releasing any collected information. Commands that require user interaction (i.e. have more than one stage) will have to provide the data forms the user must complete in each stage and the allowed actions the user might perform during each stage (e.g. go to the previous stage or go to the next stage).
All the actions may throw an XMPPException if there is a problem executing them. The XMPPError of that exception may have some specific information about the problem. The possible extensions are:
malformed-action. Extension of a bad-request error.
bad-action. Extension of a bad-request error.
bad-locale. Extension of a bad-request error.
bad-payload. Extension of a bad-request error.
bad-sessionid. Extension of a bad-request error.
session-expired. Extension of a not-allowed error.

See the SpecificErrorCondition class for detailed description of each one.

Use the getSpecificErrorConditionFrom to obtain the specific information from an XMPPError.

Author:: Gabriel Guardincerri

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`AdHocCommand.Action`
`static class`	`AdHocCommand.SpecificErrorCondition`
`static class`	`AdHocCommand.Status` The status of the stage in the adhoc command.

Constructor Summary

Constructors
Constructor and Description

AdHocCommand()

Constructors
Constructor and Description
`AdHocCommand()`

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`protected void`	`addActionAvailable(AdHocCommand.Action action)` Add an action to the current stage available actions.
`protected void`	`addNote(AdHocCommandNote note)` Adds a note to the current stage.
`abstract void`	`cancel()` Cancels the execution of the command.
`abstract void`	`complete(Form response)` Completes the command execution with the information provided in the `response`.
`abstract void`	`execute()` Executes the command.
`protected List<AdHocCommand.Action>`	`getActions()` Returns a collection with the allowed actions based on the current stage.
`protected AdHocCommand.Action`	`getExecuteAction()` Returns the action available for the current stage which is considered the equivalent to "execute".
`Form`	`getForm()` Returns the form of the current stage.
`String`	`getName()` Returns the human readable name of the command.
`String`	`getNode()` Returns the unique identifier of the command.
`List<AdHocCommandNote>`	`getNotes()` Returns the notes that the command has at the current stage.
`abstract String`	`getOwnerJID()` Returns the full JID of the owner of this command.
`String`	`getRaw()`
`static AdHocCommand.SpecificErrorCondition`	`getSpecificErrorCondition(XMPPError error)` Returns the specific condition of the `error` or `null` if the error doesn't have any.
`AdHocCommand.Status`	`getStatus()` Returns the status of the current stage.
`protected boolean`	`isValidAction(AdHocCommand.Action action)` Returns true if the `action` is available in the current stage.
`abstract void`	`next(Form response)` Executes the next action of the command with the information provided in the `response`.
`abstract void`	`prev()` Goes to the previous stage.
`protected void`	`setExecuteAction(AdHocCommand.Action action)` Sets which of the actions available for the current stage is considered the equivalent to "execute".
`protected void`	`setForm(Form form)` Sets the form of the current stage.
`void`	`setName(String name)` Set the the human readable name of the command, usually used for displaying in a UI.
`void`	`setNode(String node)` Sets the unique identifier of the command.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - AdHocCommand
```
public AdHocCommand()
```
- Method Detail
  - getSpecificErrorCondition
```
public static AdHocCommand.SpecificErrorCondition getSpecificErrorCondition(XMPPError error)
```
    Returns the specific condition of the error or null if the error doesn't have any.
    
    Parameters:
    
    error - the error the get the specific condition from.
    
    Returns:
    
    the specific condition of this error, or null if it doesn't have any.
  - setName
```
public void setName(String name)
```
    Set the the human readable name of the command, usually used for displaying in a UI.
    
    Parameters:
    
    name - the name.
  - getName
```
public String getName()
```
    Returns the human readable name of the command.
    
    Returns:
    
    the human readable name of the command
  - setNode
```
public void setNode(String node)
```
    Sets the unique identifier of the command. This value must be unique for the OwnerJID.
    
    Parameters:
    
    node - the unique identifier of the command.
  - getNode
```
public String getNode()
```
    Returns the unique identifier of the command. It is unique for the OwnerJID.
    
    Returns:
    
    the unique identifier of the command.
  - getOwnerJID
```
public abstract String getOwnerJID()
```
    Returns the full JID of the owner of this command. This JID is the "to" of a execution request.
    
    Returns:
    
    the owner JID.
  - getNotes
```
public List<AdHocCommandNote> getNotes()
```
    Returns the notes that the command has at the current stage.
    
    Returns:
    
    a list of notes.
  - addNote
```
protected void addNote(AdHocCommandNote note)
```
    Adds a note to the current stage. This should be used when setting a response to the execution of an action. All the notes added here are returned by the getNotes() method during the current stage. Once the stage changes all the notes are discarded.
    
    Parameters:
    
    note - the note.
  - getRaw
```
public String getRaw()
```
  - getForm
```
public Form getForm()
```
    Returns the form of the current stage. Usually it is the form that must be answered to execute the next action. If that is the case it should be used by the requester to fill all the information that the executor needs to continue to the next stage. It can also be the result of the execution.
    
    Returns:
    
    the form of the current stage to fill out or the result of the execution.
  - setForm
```
protected void setForm(Form form)
```
    Sets the form of the current stage. This should be used when setting a response. It could be a form to fill out the information needed to go to the next stage or the result of an execution.
    
    Parameters:
    
    form - the form of the current stage to fill out or the result of the execution.
  - execute
```
public abstract void execute()
                      throws SmackException.NoResponseException,
                             XMPPException.XMPPErrorException,
                             SmackException.NotConnectedException
```
    Executes the command. This is invoked only on the first stage of the command. It is invoked on every command. If there is a problem executing the command it throws an XMPPException.
    
    Throws:
    
    XMPPException.XMPPErrorException - if there is an error executing the command.
    
    SmackException.NotConnectedException
    
    SmackException.NoResponseException
  - next
```
public abstract void next(Form response)
                   throws SmackException.NoResponseException,
                          XMPPException.XMPPErrorException,
                          SmackException.NotConnectedException
```
    Executes the next action of the command with the information provided in the response. This form must be the answer form of the previous stage. This method will be only invoked for commands that have one or more stages. If there is a problem executing the command it throws an XMPPException.
    
    Parameters:
    
    response - the form answer of the previous stage.
    
    Throws:
    
    XMPPException.XMPPErrorException - if there is a problem executing the command.
    
    SmackException.NotConnectedException
    
    SmackException.NoResponseException
  - complete
```
public abstract void complete(Form response)
                       throws SmackException.NoResponseException,
                              XMPPException.XMPPErrorException,
                              SmackException.NotConnectedException
```
    Completes the command execution with the information provided in the response. This form must be the answer form of the previous stage. This method will be only invoked for commands that have one or more stages. If there is a problem executing the command it throws an XMPPException.
    
    Parameters:
    
    response - the form answer of the previous stage.
    
    Throws:
    
    XMPPException.XMPPErrorException - if there is a problem executing the command.
    
    SmackException.NotConnectedException
    
    SmackException.NoResponseException
  - prev
```
public abstract void prev()
                   throws SmackException.NoResponseException,
                          XMPPException.XMPPErrorException,
                          SmackException.NotConnectedException
```
    Goes to the previous stage. The requester is asking to re-send the information of the previous stage. The command must change it state to the previous one. If there is a problem executing the command it throws an XMPPException.
    
    Throws:
    
    XMPPException.XMPPErrorException - if there is a problem executing the command.
    
    SmackException.NotConnectedException
    
    SmackException.NoResponseException
  - cancel
```
public abstract void cancel()
                     throws SmackException.NoResponseException,
                            XMPPException.XMPPErrorException,
                            SmackException.NotConnectedException
```
    Cancels the execution of the command. This can be invoked on any stage of the execution. If there is a problem executing the command it throws an XMPPException.
    
    Throws:
    
    XMPPException.XMPPErrorException - if there is a problem executing the command.
    
    SmackException.NotConnectedException
    
    SmackException.NoResponseException
  - getActions
```
protected List<AdHocCommand.Action> getActions()
```
    Returns a collection with the allowed actions based on the current stage. Possible actions are: prev, next and complete. This method will be only invoked for commands that have one or more stages.
    
    Returns:
    
    a collection with the allowed actions based on the current stage as defined in the SessionData.
  - addActionAvailable
```
protected void addActionAvailable(AdHocCommand.Action action)
```
    Add an action to the current stage available actions. This should be used when creating a response.
    
    Parameters:
    
    action - the action.
  - getExecuteAction
```
protected AdHocCommand.Action getExecuteAction()
```
    Returns the action available for the current stage which is considered the equivalent to "execute". When the requester sends his reply, if no action was defined in the command then the action will be assumed "execute" thus assuming the action returned by this method. This method will never be invoked for commands that have no stages.
    
    Returns:
    
    the action available for the current stage which is considered the equivalent to "execute".
  - setExecuteAction
```
protected void setExecuteAction(AdHocCommand.Action action)
```
    Sets which of the actions available for the current stage is considered the equivalent to "execute". This should be used when setting a response. When the requester sends his reply, if no action was defined in the command then the action will be assumed "execute" thus assuming the action returned by this method.
    
    Parameters:
    
    action - the action.
  - getStatus
```
public AdHocCommand.Status getStatus()
```
    Returns the status of the current stage.
    
    Returns:
    
    the current status.
  - isValidAction
```
protected boolean isValidAction(AdHocCommand.Action action)
```
    Returns true if the action is available in the current stage. The cancel action is always allowed. To define the available actions use the addActionAvailable method.
    
    Parameters:
    
    action - The action to check if it is available.
    
    Returns:
    
    True if the action is available for the current stage.

Class AdHocCommand

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

AdHocCommand

Method Detail

getSpecificErrorCondition

setName

getName

setNode

getNode

getOwnerJID

getNotes

addNote

getRaw

getForm

setForm

execute

next

complete

prev

cancel

getActions

addActionAvailable

getExecuteAction

setExecuteAction

getStatus

isValidAction