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