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;
024
025import org.jivesoftware.smackx.commands.packet.AdHocCommandData;
026import org.jivesoftware.smackx.xdata.Form;
027
028import org.jxmpp.jid.Jid;
029
030/**
031 * Represents a command that is in a remote location. Invoking one of the
032 * {@link AdHocCommand.Action#execute execute}, {@link AdHocCommand.Action#next next},
033 * {@link AdHocCommand.Action#prev prev}, {@link AdHocCommand.Action#cancel cancel} or
034 * {@link AdHocCommand.Action#complete complete} actions results in executing that
035 * action in the remote location. In response to that action the internal state
036 * of the this command instance will change. For example, if the command is a
037 * single stage command, then invoking the execute action will execute this
038 * action in the remote location. After that the local instance will have a
039 * state of "completed" and a form or notes that applies.
040 *
041 * @author Gabriel Guardincerri
042 *
043 */
044public class RemoteCommand extends AdHocCommand {
045
046    /**
047     * The connection that is used to execute this command
048     */
049    private final XMPPConnection connection;
050
051    /**
052     * The full JID of the command host
053     */
054    private final Jid jid;
055
056    /**
057     * The session ID of this execution.
058     */
059    private String sessionID;
060
061    /**
062     * Creates a new RemoteCommand that uses an specific connection to execute a
063     * command identified by <code>node</code> in the host identified by
064     * <code>jid</code>
065     *
066     * @param connection the connection to use for the execution.
067     * @param node the identifier of the command.
068     * @param jid the JID of the host.
069     */
070    protected RemoteCommand(XMPPConnection connection, String node, Jid jid) {
071        super();
072        this.connection = connection;
073        this.jid = jid;
074        this.setNode(node);
075    }
076
077    @Override
078    public void cancel() throws NoResponseException, XMPPErrorException, NotConnectedException, InterruptedException {
079        executeAction(Action.cancel);
080    }
081
082    @Override
083    public void complete(Form form) throws NoResponseException, XMPPErrorException, NotConnectedException, InterruptedException {
084        executeAction(Action.complete, form);
085    }
086
087    @Override
088    public void execute() throws NoResponseException, XMPPErrorException, NotConnectedException, InterruptedException {
089        executeAction(Action.execute);
090    }
091
092    /**
093     * Executes the default action of the command with the information provided
094     * in the Form. This form must be the answer form of the previous stage. If
095     * there is a problem executing the command it throws an XMPPException.
096     *
097     * @param form the form answer of the previous stage.
098     * @throws XMPPErrorException if an error occurs.
099     * @throws NoResponseException if there was no response from the server.
100     * @throws NotConnectedException
101     * @throws InterruptedException
102     */
103    public void execute(Form form) throws NoResponseException, XMPPErrorException, NotConnectedException, InterruptedException {
104        executeAction(Action.execute, form);
105    }
106
107    @Override
108    public void next(Form form) throws NoResponseException, XMPPErrorException, NotConnectedException, InterruptedException {
109        executeAction(Action.next, form);
110    }
111
112    @Override
113    public void prev() throws NoResponseException, XMPPErrorException, NotConnectedException, InterruptedException {
114        executeAction(Action.prev);
115    }
116
117    private void executeAction(Action action) throws NoResponseException, XMPPErrorException, NotConnectedException, InterruptedException {
118        executeAction(action, null);
119    }
120
121    /**
122     * Executes the <code>action</code> with the <code>form</code>.
123     * The action could be any of the available actions. The form must
124     * be the answer of the previous stage. It can be <tt>null</tt> if it is the first stage.
125     *
126     * @param action the action to execute.
127     * @param form the form with the information.
128     * @throws XMPPErrorException if there is a problem executing the command.
129     * @throws NoResponseException if there was no response from the server.
130     * @throws NotConnectedException
131     * @throws InterruptedException
132     */
133    private void executeAction(Action action, Form form) throws NoResponseException, XMPPErrorException, NotConnectedException, InterruptedException {
134        // TODO: Check that all the required fields of the form were filled, if
135        // TODO: not throw the corresponding exception. This will make a faster response,
136        // TODO: since the request is stopped before it's sent.
137        AdHocCommandData data = new AdHocCommandData();
138        data.setType(IQ.Type.set);
139        data.setTo(getOwnerJID());
140        data.setNode(getNode());
141        data.setSessionID(sessionID);
142        data.setAction(action);
143
144        if (form != null) {
145            data.setForm(form.getDataFormToSend());
146        }
147
148        AdHocCommandData responseData = null;
149        try {
150            responseData = connection.createStanzaCollectorAndSend(data).nextResultOrThrow();
151        }
152        finally {
153            // We set the response data in a 'finally' block, so that it also gets set even if an error IQ was returned.
154            if (responseData != null) {
155                this.sessionID = responseData.getSessionID();
156                super.setData(responseData);
157            }
158        }
159
160    }
161
162    @Override
163    public Jid getOwnerJID() {
164        return jid;
165    }
166}