001/**
002 *
003 * Copyright 2005-2007 Jive Software.
004 *
005 * Licensed under the Apache License, Version 2.0 (the "License");
006 * you may not use this file except in compliance with the License.
007 * You may obtain a copy of the License at
008 *
009 *     http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.jivesoftware.smackx.commands;
018
019import org.jivesoftware.smack.SmackException.NoResponseException;
020import org.jivesoftware.smack.SmackException.NotConnectedException;
021import org.jivesoftware.smack.XMPPConnection;
022import org.jivesoftware.smack.XMPPException.XMPPErrorException;
023import org.jivesoftware.smack.packet.IQ;
024import org.jivesoftware.smackx.commands.packet.AdHocCommandData;
025import org.jivesoftware.smackx.xdata.Form;
026import org.jxmpp.jid.Jid;
027
028/**
029 * Represents a command that is in a remote location. Invoking one of the
030 * {@link AdHocCommand.Action#execute execute}, {@link AdHocCommand.Action#next next},
031 * {@link AdHocCommand.Action#prev prev}, {@link AdHocCommand.Action#cancel cancel} or
032 * {@link AdHocCommand.Action#complete complete} actions results in executing that
033 * action in the remote location. In response to that action the internal state
034 * of the this command instance will change. For example, if the command is a
035 * single stage command, then invoking the execute action will execute this
036 * action in the remote location. After that the local instance will have a
037 * state of "completed" and a form or notes that applies.
038 *
039 * @author Gabriel Guardincerri
040 *
041 */
042public class RemoteCommand extends AdHocCommand {
043
044    /**
045     * The connection that is used to execute this command
046     */
047    private XMPPConnection connection;
048
049    /**
050     * The full JID of the command host
051     */
052    private Jid jid;
053
054    /**
055     * The session ID of this execution.
056     */
057    private String sessionID;
058
059    /**
060     * Creates a new RemoteCommand that uses an specific connection to execute a
061     * command identified by <code>node</code> in the host identified by
062     * <code>jid</code>
063     *
064     * @param connection the connection to use for the execution.
065     * @param node the identifier of the command.
066     * @param jid the JID of the host.
067     */
068    protected RemoteCommand(XMPPConnection connection, String node, Jid jid) {
069        super();
070        this.connection = connection;
071        this.jid = jid;
072        this.setNode(node);
073    }
074
075    @Override
076    public void cancel() throws NoResponseException, XMPPErrorException, NotConnectedException, InterruptedException {
077        executeAction(Action.cancel);
078    }
079
080    @Override
081    public void complete(Form form) throws NoResponseException, XMPPErrorException, NotConnectedException, InterruptedException {
082        executeAction(Action.complete, form);
083    }
084
085    @Override
086    public void execute() throws NoResponseException, XMPPErrorException, NotConnectedException, InterruptedException {
087        executeAction(Action.execute);
088    }
089
090    /**
091     * Executes the default action of the command with the information provided
092     * in the Form. This form must be the answer form of the previous stage. If
093     * there is a problem executing the command it throws an XMPPException.
094     *
095     * @param form the form answer of the previous stage.
096     * @throws XMPPErrorException if an error occurs.
097     * @throws NoResponseException if there was no response from the server.
098     * @throws NotConnectedException 
099     * @throws InterruptedException 
100     */
101    public void execute(Form form) throws NoResponseException, XMPPErrorException, NotConnectedException, InterruptedException {
102        executeAction(Action.execute, form);
103    }
104
105    @Override
106    public void next(Form form) throws NoResponseException, XMPPErrorException, NotConnectedException, InterruptedException {
107        executeAction(Action.next, form);
108    }
109
110    @Override
111    public void prev() throws NoResponseException, XMPPErrorException, NotConnectedException, InterruptedException {
112        executeAction(Action.prev);
113    }
114
115    private void executeAction(Action action) throws NoResponseException, XMPPErrorException, NotConnectedException, InterruptedException {
116        executeAction(action, null);
117    }
118
119    /**
120     * Executes the <code>action</code> with the <code>form</code>.
121     * The action could be any of the available actions. The form must
122     * be the answer of the previous stage. It can be <tt>null</tt> if it is the first stage.
123     *
124     * @param action the action to execute.
125     * @param form the form with the information.
126     * @throws XMPPErrorException if there is a problem executing the command.
127     * @throws NoResponseException if there was no response from the server.
128     * @throws NotConnectedException 
129     * @throws InterruptedException 
130     */
131    private void executeAction(Action action, Form form) throws NoResponseException, XMPPErrorException, NotConnectedException, InterruptedException {
132        // TODO: Check that all the required fields of the form were filled, if
133        // TODO: not throw the corresponding exeption. This will make a faster response,
134        // TODO: since the request is stoped before it's sent.
135        AdHocCommandData data = new AdHocCommandData();
136        data.setType(IQ.Type.set);
137        data.setTo(getOwnerJID());
138        data.setNode(getNode());
139        data.setSessionID(sessionID);
140        data.setAction(action);
141
142        if (form != null) {
143            data.setForm(form.getDataFormToSend());
144        }
145
146        AdHocCommandData responseData = null;
147        try {
148            responseData = connection.createStanzaCollectorAndSend(data).nextResultOrThrow();
149        }
150        finally {
151            // We set the response data in a 'finally' block, so that it also gets set even if an error IQ was returned.
152            if (responseData != null) {
153                this.sessionID = responseData.getSessionID();
154                super.setData(responseData);
155            }
156        }
157
158    }
159
160    @Override
161    public Jid getOwnerJID() {
162        return jid;
163    }
164}