1 /** 2 * $RCSfile$ 3 * $Revision$ 4 * $Date$ 5 * 6 * Copyright 2005-2007 Jive Software. 7 * 8 * All rights reserved. Licensed under the Apache License, Version 2.0 (the "License"); 9 * you may not use this file except in compliance with the License. 10 * You may obtain a copy of the License at 11 * 12 * http://www.apache.org/licenses/LICENSE-2.0 13 * 14 * Unless required by applicable law or agreed to in writing, software 15 * distributed under the License is distributed on an "AS IS" BASIS, 16 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 17 * See the License for the specific language governing permissions and 18 * limitations under the License. 19 */ 20 21 package org.jivesoftware.smackx.commands; 22 23 import org.jivesoftware.smackx.packet.AdHocCommandData; 24 25 /** 26 * Represents a command that can be executed locally from a remote location. This 27 * class must be extended to implement an specific ad-hoc command. This class 28 * provides some useful tools:<ul> 29 * <li>Node</li> 30 * <li>Name</li> 31 * <li>Session ID</li> 32 * <li>Current Stage</li> 33 * <li>Available actions</li> 34 * <li>Default action</li> 35 * </ul><p/> 36 * To implement a new command extend this class and implement all the abstract 37 * methods. When implementing the actions remember that they could be invoked 38 * several times, and that you must use the current stage number to know what to 39 * do. 40 * 41 * @author Gabriel Guardincerri 42 */ 43 public abstract class LocalCommand extends AdHocCommand { 44 45 /** 46 * The time stamp of first invokation of the command. Used to implement the session timeout. 47 */ 48 private long creationDate; 49 50 /** 51 * The unique ID of the execution of the command. 52 */ 53 private String sessionID; 54 55 /** 56 * The full JID of the host of the command. 57 */ 58 private String ownerJID; 59 60 /** 61 * The number of the current stage. 62 */ 63 private int currenStage; 64 LocalCommand()65 public LocalCommand() { 66 super(); 67 this.creationDate = System.currentTimeMillis(); 68 currenStage = -1; 69 } 70 71 /** 72 * The sessionID is an unique identifier of an execution request. This is 73 * automatically handled and should not be called. 74 * 75 * @param sessionID the unique session id of this execution 76 */ setSessionID(String sessionID)77 public void setSessionID(String sessionID) { 78 this.sessionID = sessionID; 79 getData().setSessionID(sessionID); 80 } 81 82 /** 83 * Returns the session ID of this execution. 84 * 85 * @return the unique session id of this execution 86 */ getSessionID()87 public String getSessionID() { 88 return sessionID; 89 } 90 91 /** 92 * Sets the JID of the command host. This is automatically handled and should 93 * not be called. 94 * 95 * @param ownerJID the JID of the owner. 96 */ setOwnerJID(String ownerJID)97 public void setOwnerJID(String ownerJID) { 98 this.ownerJID = ownerJID; 99 } 100 101 @Override getOwnerJID()102 public String getOwnerJID() { 103 return ownerJID; 104 } 105 106 /** 107 * Returns the date the command was created. 108 * 109 * @return the date the command was created. 110 */ getCreationDate()111 public long getCreationDate() { 112 return creationDate; 113 } 114 115 /** 116 * Returns true if the current stage is the last one. If it is then the 117 * execution of some action will complete the execution of the command. 118 * Commands that don't have multiple stages can always return <tt>true</tt>. 119 * 120 * @return true if the command is in the last stage. 121 */ isLastStage()122 public abstract boolean isLastStage(); 123 124 /** 125 * Returns true if the specified requester has permission to execute all the 126 * stages of this action. This is checked when the first request is received, 127 * if the permission is grant then the requester will be able to execute 128 * all the stages of the command. It is not checked again during the 129 * execution. 130 * 131 * @param jid the JID to check permissions on. 132 * @return true if the user has permission to execute this action. 133 */ hasPermission(String jid)134 public abstract boolean hasPermission(String jid); 135 136 /** 137 * Returns the currently executing stage number. The first stage number is 138 * 0. During the execution of the first action this method will answer 0. 139 * 140 * @return the current stage number. 141 */ getCurrentStage()142 public int getCurrentStage() { 143 return currenStage; 144 } 145 146 @Override setData(AdHocCommandData data)147 void setData(AdHocCommandData data) { 148 data.setSessionID(sessionID); 149 super.setData(data); 150 } 151 152 /** 153 * Increase the current stage number. This is automatically handled and should 154 * not be called. 155 * 156 */ incrementStage()157 void incrementStage() { 158 currenStage++; 159 } 160 161 /** 162 * Decrease the current stage number. This is automatically handled and should 163 * not be called. 164 * 165 */ decrementStage()166 void decrementStage() { 167 currenStage--; 168 } 169 }