| /** |
| * $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 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 |
| * <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: Analyze the redesign of command by having an ExecutionResponse as a |
| // TODO: result to the execution of every action. That result should have all the |
| // TODO: information related to the execution, e.g. the form to fill. Maybe this |
| // TODO: design is more intuitive and simpler than the current one that has all in |
| // TODO: one class. |
| |
| private AdHocCommandData data; |
| |
| public AdHocCommand() { |
| super(); |
| data = new AdHocCommandData(); |
| } |
| |
| /** |
| * Returns the specific condition of the <code>error</code> or <tt>null</tt> 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 getSpecificErrorCondition(XMPPError error) { |
| // This method is implemented to provide 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 the 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(); |
| } |
| |
| /** |
| * Returns the full JID of the owner of this command. This JID is the "to" of a |
| * execution request. |
| * |
| * @return the owner JID. |
| */ |
| 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 {@link #getNotes} method during the current stage. |
| * Once the stage changes all the notes are discarded. |
| * |
| * @param note the note. |
| */ |
| protected void addNote(AdHocCommandNote note) { |
| data.addNote(note); |
| } |
| |
| public String getRaw() { |
| return data.getChildElementXML(); |
| } |
| |
| /** |
| * 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 an error 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 one |
| * 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 one |
| * 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: {@link Action#prev prev}, {@link Action#next next} and |
| * {@link Action#complete complete}. This method will be only invoked for commands that |
| * have one 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 the action. |
| */ |
| protected void addActionAvailable(Action action) { |
| data.addAction(action); |
| } |
| |
| /** |
| * 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. |
| * |
| * @return the action available for the current stage which is considered |
| * the equivalent to "execute". |
| */ |
| protected Action getExecuteAction() { |
| return data.getExecuteAction(); |
| } |
| |
| /** |
| * 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. |
| * |
| * @param action the action. |
| */ |
| protected void setExecuteAction(Action action) { |
| data.setExecuteAction(action); |
| } |
| |
| /** |
| * Returns the status of the current stage. |
| * |
| * @return the current status. |
| */ |
| public Status getStatus() { |
| return data.getStatus(); |
| } |
| |
| /** |
| * Sets the data of the current stage. This should not used. |
| * |
| * @param data the data. |
| */ |
| void setData(AdHocCommandData data) { |
| this.data = data; |
| } |
| |
| /** |
| * Gets the data of the current stage. This should not used. |
| * |
| * @return the data. |
| */ |
| AdHocCommandData getData() { |
| return data; |
| } |
| |
| /** |
| * Returns true if the <code>action</code> is available in the current stage. |
| * The {@link Action#cancel cancel} action 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); |
| } |
| |
| /** |
| * The status of the stage in the adhoc command. |
| */ |
| 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("bad-action"), |
| |
| /** |
| * The responding JID does not understand the specified action. |
| */ |
| malformedAction("malformed-action"), |
| |
| /** |
| * The responding JID cannot accept the specified language/locale. |
| */ |
| badLocale("bad-locale"), |
| |
| /** |
| * The responding JID cannot accept the specified payload (e.g. the data |
| * form did not provide one or more required fields). |
| */ |
| badPayload("bad-payload"), |
| |
| /** |
| * The responding JID cannot accept the specified sessionid. |
| */ |
| badSessionid("bad-sessionid"), |
| |
| /** |
| * The requesting JID specified a sessionid that is no longer active |
| * (either because it was completed, canceled, or timed out). |
| */ |
| sessionExpired("session-expired"); |
| |
| private String value; |
| |
| SpecificErrorCondition(String value) { |
| this.value = value; |
| } |
| |
| public String toString() { |
| return value; |
| } |
| } |
| } |