Package org.jivesoftware.smackx.commands

Class AbstractAdHocCommand

java.lang.Object

org.jivesoftware.smackx.commands.AbstractAdHocCommand

Direct Known Subclasses:

AdHocCommand, AdHocCommandHandler

public abstract class AbstractAdHocCommand
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.

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	AbstractAdHocCommand(String node)
protected	AbstractAdHocCommand(String node, String name)

Method Summary

Modifier and Type	Method	Description
abstract void	cancel()	Cancels the execution of the command.
final Set<AdHocCommandData.AllowedAction>	getActions()	Returns a collection with the allowed actions based on the current stage.
protected AdHocCommandData.AllowedAction	getExecuteAction()	Returns the action available for the current stage which is considered the equivalent to "execute".
AdHocCommandData	getLastRequest()
AdHocCommandResult	getLastResult()
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.
String	getSessionId()
static SpecificErrorCondition	getSpecificErrorCondition(StanzaError error)	Returns the specific condition of the error or null if the error doesn't have any.
AdHocCommandData.Status	getStatus()	Returns the status of the current stage.
boolean	isCompleted()	Check if this command has been completed successfully.
final boolean	isValidAction(AdHocCommandData.Action action)	Returns true if the action is available in the current stage.
protected void	setSessionId(String sessionId)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

AbstractAdHocCommand

protected AbstractAdHocCommand(String node,
 String name)

AbstractAdHocCommand

protected AbstractAdHocCommand(String node)

Method Details

getSpecificErrorCondition

public static SpecificErrorCondition getSpecificErrorCondition(StanzaError 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.

getName

public String getName()

Returns the human readable name of the command.

Returns:

the human readable name 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.

getSessionId

public String getSessionId()

setSessionId

protected void setSessionId(String sessionId)

getLastRequest

public AdHocCommandData getLastRequest()

getLastResult

public AdHocCommandResult getLastResult()

getNotes

public List<AdHocCommandNote> getNotes()

Returns the notes that the command has at the current stage.

Returns:

a list of notes.

cancel

public abstract void cancel()
                     throws SmackException.NoResponseException,
XMPPException.XMPPErrorException,
SmackException.NotConnectedException,
InterruptedException

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:

SmackException.NoResponseException - if there was no response from the remote entity.

XMPPException.XMPPErrorException - if there is a problem executing the command.

SmackException.NotConnectedException - if the XMPP connection is not connected.

InterruptedException - if the calling thread was interrupted.

getActions

public final Set<AdHocCommandData.AllowedAction> 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.

getExecuteAction

protected AdHocCommandData.AllowedAction 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".

getStatus

public AdHocCommandData.Status getStatus()

Returns the status of the current stage.

Returns:

the current status.

isCompleted

public boolean isCompleted()

Check if this command has been completed successfully.

Returns:

true if this command is completed.

Since:

4.2

isValidAction

public final boolean isValidAction(AdHocCommandData.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.