Mercury-IM/Smack
Mercury-IM/Smack
1
0
Fork 0
mirror of https://codeberg.org/Mercury-IM/Smack synced 2025-09-10 18:59:41 +02:00
Code Issues Releases Wiki Activity

Initial implementation of ad-hoc commands. SMACK-242

Browse source 
git-svn-id: http://svn.igniterealtime.org/svn/repos/smack/trunk@10453 b35dd754-fafc-0310-a699-88a17e54d16e
This commit is contained in:
Gaston Dombiak 2008-05-28 18:59:52 +00:00 • committed by gato
parent babc992e11
commit 8d07e07379
10 changed files with 2088 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

468
source/org/jivesoftware/smackx/commands/AdHocCommand.java Executable file
View file

@ -0,0 +1,468 @@
/**
* $RCSfile$
* $Revision: $
* $Date: $
*
* Copyright 2005-2007 Jive Software.
*
* All rights reserved. Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.jivesoftware.smackx.commands;
import org.jivesoftware.smack.XMPPException;
import org.jivesoftware.smack.packet.XMPPError;
import org.jivesoftware.smackx.Form;
import org.jivesoftware.smackx.packet.AdHocCommandData;
import java.util.List;
/**
* 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 retrieve the list of
* users of 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
* <code>getForm</code> method retrieves a form with all the users.
* <p>
* Each command has a <tt>node</tt> that should be unique within a given JID.
* <p>
* 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).
* <p>
* All the actions may throw an XMPPException if there is a problem executing
* them. The <code>XMPPError</code> of that exception may have some specific
* information about the problem. The possible extensions are:
*
* <li><i>malformed-action</i>. Extension of a <i>bad-request</i> error.</li>
* <li><i>bad-action</i>. Extension of a <i>bad-request</i> error.</li>
* <li><i>bad-locale</i>. Extension of a <i>bad-request</i> error.</li>
* <li><i>bad-payload</i>. Extension of a <i>bad-request</i> error.</li>
* <li><i>bad-sessionid</i>. Extension of a <i>bad-request</i> error.</li>
* <li><i>session-expired</i>. Extension of a <i>not-allowed</i> error.</li>
* <p>
* See the <code>SpecificErrorCondition</code> class for detailed description
* of each one.
* <p>
* Use the <code>getSpecificErrorConditionFrom</code> to obtain the specific
* information from an <code>XMPPError</code>.
*
* @author Gabriel Guardincerri
*
*/
public abstract class AdHocCommand {
// TODO Analize the redesign of command by having an ExecutionResponse as a
// result to the execution of every action. That result should have all the
// information related to the execution, e.g. the form to fill. Maybe this
// design is more intuitive and simpler than the current one that has all in
// one class.
private AdHocCommandData data;
public AdHocCommand() {
super();
data = new AdHocCommandData();
}
/**
* Returns the specific condition of the <code>error</code> or null if the
* error doesn't have any.
*
* @param error
* the error the get the specific condition from
* @return the specific condition of this error, or null if it doesn't have
* any.
*/
public static SpecificErrorCondition getSpecificErrorConditionFrom(
XMPPError error) {
// This method is implemented to provied an easy way of getting a packet
// extension of the XMPPError.
for (SpecificErrorCondition condition : SpecificErrorCondition.values()) {
if (error.getExtension(condition.toString(),
AdHocCommandData.SpecificError.namespace) != null) {
return condition;
}
}
return null;
}
/**
* Set the the human readable name of the command, usually used for
* displaying in a UI.
*
* @param name
*/
public void setName(String name) {
data.setName(name);
}
/**
* Returns the human readable name of the command.
*
* @return the human readable name of the command
*/
public String getName() {
return data.getName();
}
/**
* Sets the unique identifier of the command. This value must be unique for
* the <code>OwnerJID</code>.
*
* @param node
* the unique identifier of the command
*/
public void setNode(String node) {
data.setNode(node);
}
/**
* Returns the unique identifier of the command. It is unique for the
* <code>OwnerJID</code>.
*
* @return the unique identifier of the command
*/
public String getNode() {
return data.getNode();
}
/**
* Gets the full JID of the owner of this command. This JID is the "to" of a
* execution request.
*
* @return
*/
public abstract String getOwnerJID();
/**
* Returns the notes that the command has at the current stage.
*
* @return a list of notes.
*/
public List<AdHocCommandNote> getNotes() {
return data.getNotes();
}
/**
* 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 <code>getNotes</code> method during the current stage.
* Once the stage changes all the notes are discarded.
*
* @param note
*/
protected void addNote(AdHocCommandNote note) {
data.addNote(note);
}
/**
* 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.
*
* @return the form of the current stage to fill out or the result of the
* execution.
*/
public Form getForm() {
if (data.getForm() == null) {
return null;
} else {
return new Form(data.getForm());
}
}
/**
* 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.
*
* @param form
* the form of the current stage to fill out or the result of the
* execution.
*/
protected void setForm(Form form) {
data.setForm(form.getDataFormToSend());
}
/**
* 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
* if there is a problem executing the command.
*/
public abstract void execute() throws XMPPException;
/**
* Executes the next action of the command with the information provided in
* the <code>response</code>. This form must be the answer form of the
* previous stage. This method will be only invoked for commands that have 1
* or more stages. If there is a problem executing the command it throws an
* XMPPException.
*
* @param response
* the form answer of the previous stage.
* @throws XMPPException
* if there is a problem executing the command.
*/
public abstract void next(Form response) throws XMPPException;
/**
* Completes the command execution with the information provided in the
* <code>response</code>. This form must be the answer form of the
* previous stage. This method will be only invoked for commands that have 1
* or more stages. If there is a problem executing the command it throws an
* XMPPException.
*
* @param response
* the form answer of the previous stage.
* @throws XMPPException
* if there is a problem executing the command.
*/
public abstract void complete(Form response) throws XMPPException;
/**
* 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
* if there is a problem executing the command.
*/
public abstract void prev() throws XMPPException;
/**
* 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
* if there is a problem executing the command.
*/
public abstract void cancel() throws XMPPException;
/**
* Returns a collection with the allowed actions based on the current stage
* Possible actions are: <tt>prev</tt>, <tt>next</tt> and
* <tt>complete</tt>. This method will be only invoked for commands that
* have 1 or more stages.
*
* @return a collection with the allowed actions based on the current stage
* as defined in the SessionData.
*/
protected List<Action> getActions() {
return data.getActions();
}
/**
* Add an action to the current stage available actions. This should be used
* when creating a response.
*
* @param action
*/
protected void addActionAvailable(Action action) {
data.addAction(action);
}
/**
* Returns which of the actions available for the current stage 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.
*
* @return which of the actions available for the current stage is
* considered the equivalent to "execute".
*/
protected Action getExecuteAction() {
return data.getExecuteAction();
}
/**
* Returns 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.
*
* @param action
*/
protected void setExecuteAction(Action action) {
data.setExecuteAction(action);
}
/**
* Returns the status of the current stage.
*
* @return
*/
public Status getStatus() {
return data.getStatus();
}
/**
* Sets the data of the current stage. This should not used.
*
* @param data
*/
void setData(AdHocCommandData data) {
this.data = data;
}
/**
* Gets the data of the current stage. This should not used.
*
* @param data
*/
AdHocCommandData getData() {
return data;
}
/**
* Returns if the <code>action</code> is available in the current stage.
* The <code>Action.cancel</code> is always allowed. To define the
* available actions use the <code>addActionAvailable</code> method.
*
* @param action
* The action to check if it is available.
* @return True if the action is available for the current stage.
*/
protected boolean isValidAction(Action action) {
return getActions().contains(action) || Action.cancel.equals(action);
}
public enum Status {
/**
* The command is being executed.
*/
executing,
/**
* The command has completed. The command session has ended.
*/
completed,
/**
* The command has been canceled. The command session has ended.
*/
canceled
}
public enum Action {
/**
* The command should be executed or continue to be executed. This is
* the default value.
*/
execute,
/**
* The command should be canceled.
*/
cancel,
/**
* The command should be digress to the previous stage of execution.
*/
prev,
/**
* The command should progress to the next stage of execution.
*/
next,
/**
* The command should be completed (if possible).
*/
complete,
/**
* The action is unknow. This is used when a recieved message has an
* unknown action. It must not be used to send an execution request.
*/
unknown;
}
public enum SpecificErrorCondition {
/**
* The responding JID cannot accept the specified action.
*/
badAction,
/**
* The responding JID does not understand the specified action.
*/
malformedAction,
/**
* The responding JID cannot accept the specified language/locale.
*/
badLocale,
/**
* The responding JID cannot accept the specified payload (e.g. the data
* form did not provide one or more required fields).
*/
badPayload,
/**
* The responding JID cannot accept the specified sessionid.
*/
badSessionid,
/**
* The requesting JID specified a sessionid that is no longer active
* (either because it was completed, canceled, or timed out).
*/
sessionExpired;
public String toString() {
String result = null;
switch (this) {
case badAction:
result = "bad-action";
break;
case malformedAction:
result = "malformed-action";
break;
case badLocale:
result = "bad-locale";
break;
case badPayload:
result = "bad-payload";
break;
case badSessionid:
result = "bad-sessionid";
break;
case sessionExpired:
result = "session-expired";
break;
}
return result;
}
}
}