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}