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}