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