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 */ 017 018package org.jivesoftware.smackx.commands; 019 020import org.jivesoftware.smackx.commands.packet.AdHocCommandData; 021import org.jxmpp.jid.Jid; 022 023/** 024 * Represents a command that can be executed locally from a remote location. This 025 * class must be extended to implement an specific ad-hoc command. This class 026 * provides some useful tools:<ul> 027 * <li>Node</li> 028 * <li>Name</li> 029 * <li>Session ID</li> 030 * <li>Current Stage</li> 031 * <li>Available actions</li> 032 * <li>Default action</li> 033 * </ul><p/> 034 * To implement a new command extend this class and implement all the abstract 035 * methods. When implementing the actions remember that they could be invoked 036 * several times, and that you must use the current stage number to know what to 037 * do. 038 * 039 * @author Gabriel Guardincerri 040 */ 041public abstract class LocalCommand extends AdHocCommand { 042 043 /** 044 * The time stamp of first invokation of the command. Used to implement the session timeout. 045 */ 046 private long creationDate; 047 048 /** 049 * The unique ID of the execution of the command. 050 */ 051 private String sessionID; 052 053 /** 054 * The full JID of the host of the command. 055 */ 056 private Jid ownerJID; 057 058 /** 059 * The number of the current stage. 060 */ 061 private int currenStage; 062 063 public LocalCommand() { 064 super(); 065 this.creationDate = System.currentTimeMillis(); 066 currenStage = -1; 067 } 068 069 /** 070 * The sessionID is an unique identifier of an execution request. This is 071 * automatically handled and should not be called. 072 * 073 * @param sessionID the unique session id of this execution 074 */ 075 public void setSessionID(String sessionID) { 076 this.sessionID = sessionID; 077 getData().setSessionID(sessionID); 078 } 079 080 /** 081 * Returns the session ID of this execution. 082 * 083 * @return the unique session id of this execution 084 */ 085 public String getSessionID() { 086 return sessionID; 087 } 088 089 /** 090 * Sets the JID of the command host. This is automatically handled and should 091 * not be called. 092 * 093 * @param ownerJID the JID of the owner. 094 */ 095 public void setOwnerJID(Jid ownerJID) { 096 this.ownerJID = ownerJID; 097 } 098 099 @Override 100 public Jid getOwnerJID() { 101 return ownerJID; 102 } 103 104 /** 105 * Returns the date the command was created. 106 * 107 * @return the date the command was created. 108 */ 109 public long getCreationDate() { 110 return creationDate; 111 } 112 113 /** 114 * Returns true if the current stage is the last one. If it is then the 115 * execution of some action will complete the execution of the command. 116 * Commands that don't have multiple stages can always return <tt>true</tt>. 117 * 118 * @return true if the command is in the last stage. 119 */ 120 public abstract boolean isLastStage(); 121 122 /** 123 * Returns true if the specified requester has permission to execute all the 124 * stages of this action. This is checked when the first request is received, 125 * if the permission is grant then the requester will be able to execute 126 * all the stages of the command. It is not checked again during the 127 * execution. 128 * 129 * @param jid the JID to check permissions on. 130 * @return true if the user has permission to execute this action. 131 */ 132 public abstract boolean hasPermission(Jid jid); 133 134 /** 135 * Returns the currently executing stage number. The first stage number is 136 * 0. During the execution of the first action this method will answer 0. 137 * 138 * @return the current stage number. 139 */ 140 public int getCurrentStage() { 141 return currenStage; 142 } 143 144 @Override 145 void setData(AdHocCommandData data) { 146 data.setSessionID(sessionID); 147 super.setData(data); 148 } 149 150 /** 151 * Increase the current stage number. This is automatically handled and should 152 * not be called. 153 * 154 */ 155 void incrementStage() { 156 currenStage++; 157 } 158 159 /** 160 * Decrease the current stage number. This is automatically handled and should 161 * not be called. 162 * 163 */ 164 void decrementStage() { 165 currenStage--; 166 } 167}