1
0
Fork 0
mirror of https://github.com/vanitasvitae/Smack.git synced 2024-11-26 14:02:06 +01:00

Javadoc cleanup.

git-svn-id: http://svn.igniterealtime.org/svn/repos/smack/trunk@10879 b35dd754-fafc-0310-a699-88a17e54d16e
This commit is contained in:
Matt Tucker 2008-11-13 18:34:03 +00:00 committed by matt
parent a631b163e8
commit 18d38845e9
3 changed files with 59 additions and 59 deletions

View file

@ -30,8 +30,8 @@ import java.util.List;
* An ad-hoc command is responsible for executing the provided service and * An ad-hoc command is responsible for executing the provided service and
* storing the result of the execution. Each new request will create a new * storing the result of the execution. Each new request will create a new
* instance of the command, allowing information related to executions to be * instance of the command, allowing information related to executions to be
* stored in it. For example suppose that a command that retrieve the list of * stored in it. For example suppose that a command that retrieves the list of
* users of a server is implemented. When the command is executed it gets that * users on a server is implemented. When the command is executed it gets that
* list and the result is stored as a form in the command instance, i.e. the * list and the result is stored as a form in the command instance, i.e. the
* <code>getForm</code> method retrieves a form with all the users. * <code>getForm</code> method retrieves a form with all the users.
* <p> * <p>
@ -69,7 +69,7 @@ import java.util.List;
* *
*/ */
public abstract class AdHocCommand { public abstract class AdHocCommand {
// TODO: Analize the redesign of command by having an ExecutionResponse as a // TODO: Analyze the redesign of command by having an ExecutionResponse as a
// TODO: result to the execution of every action. That result should have all the // TODO: result to the execution of every action. That result should have all the
// TODO: information related to the execution, e.g. the form to fill. Maybe this // TODO: information related to the execution, e.g. the form to fill. Maybe this
// TODO: design is more intuitive and simpler than the current one that has all in // TODO: design is more intuitive and simpler than the current one that has all in
@ -225,7 +225,7 @@ public abstract class AdHocCommand {
/** /**
* Completes the command execution with the information provided in the * Completes the command execution with the information provided in the
* <code>response</code>. This form must be the answer form of the * <code>response</code>. This form must be the answer form of the
* previous stage. This method will be only invoked for commands that have 1 * previous stage. This method will be only invoked for commands that have one
* or more stages. If there is a problem executing the command it throws an * or more stages. If there is a problem executing the command it throws an
* XMPPException. * XMPPException.
* *
@ -291,7 +291,7 @@ public abstract class AdHocCommand {
} }
/** /**
* Returns which of the actions available for the current stage is * Sets which of the actions available for the current stage is
* considered the equivalent to "execute". This should be used when setting * considered the equivalent to "execute". This should be used when setting
* a response. When the requester sends his reply, if no action was defined * a response. When the requester sends his reply, if no action was defined
* in the command then the action will be assumed "execute" thus assuming * in the command then the action will be assumed "execute" thus assuming

View file

@ -46,12 +46,13 @@ import java.util.concurrent.ConcurrentHashMap;
/** /**
* An AdHocCommandManager is responsible for keeping the list of available * An AdHocCommandManager is responsible for keeping the list of available
* commands offered by a service and for processing commands requests. * commands offered by a service and for processing commands requests.
* Typically, instances of this class are private to the service offering ad-hoc *
* commands. * Pass in an XMPPConnection isntance to
* {@link #getAddHocCommandsManager(org.jivesoftware.smack.XMPPConnection)} in order to
* get an instance of this class.
* *
* @author Gabriel Guardincerri * @author Gabriel Guardincerri
*/ */
public class AdHocCommandManager { public class AdHocCommandManager {
private static final String DISCO_NAMESPACE = "http://jabber.org/protocol/commands"; private static final String DISCO_NAMESPACE = "http://jabber.org/protocol/commands";
@ -76,8 +77,7 @@ public class AdHocCommandManager {
* related to that connection. * related to that connection.
*/ */
static { static {
XMPPConnection XMPPConnection.addConnectionCreationListener(new ConnectionCreationListener() {
.addConnectionCreationListener(new ConnectionCreationListener() {
public void connectionCreated(XMPPConnection connection) { public void connectionCreated(XMPPConnection connection) {
new AdHocCommandManager(connection); new AdHocCommandManager(connection);
} }
@ -131,11 +131,12 @@ public class AdHocCommandManager {
* connection. The <code>node</code> is an unique identifier of that * connection. The <code>node</code> is an unique identifier of that
* command for the connection related to this command manager. The * command for the connection related to this command manager. The
* <code>name</name> is the human readable name of the command. * <code>name</name> is the human readable name of the command.
* The <code>class</code> is the class of the command * The <code>class</code> is the class of the command, which must extend
* {@link LocalCommand}.
* *
* @param node the unique identifier of the command. * @param node the unique identifier of the command.
* @param name the human readable name of the command. * @param name the human readable name of the command.
* @param clazz the class of the command. * @param clazz the class of the command, which must extend {@link LocalCommand}.
*/ */
public void registerCommand(String node, final String name, Class clazz) { public void registerCommand(String node, final String name, Class clazz) {
AdHocCommandInfo commandInfo = new AdHocCommandInfo(node, name, AdHocCommandInfo commandInfo = new AdHocCommandInfo(node, name,
@ -173,7 +174,7 @@ public class AdHocCommandManager {
/** /**
* Discover the commands of an specific JID. The <code>jid</code> is a * Discover the commands of an specific JID. The <code>jid</code> is a
* full JID * full JID.
* *
* @param jid the full JID to retrieve the commands for. * @param jid the full JID to retrieve the commands for.
* @return the discovered items. * @return the discovered items.

View file

@ -25,21 +25,20 @@ import org.jivesoftware.smackx.packet.AdHocCommandData;
/** /**
* Represents a command that can be executed locally from a remote location. This * Represents a command that can be executed locally from a remote location. This
* class must be extended to implement an specific ad-hoc command. This class * class must be extended to implement an specific ad-hoc command. This class
* provides some useful and common useful: * provides some useful tools:<ul>
* <li>Node code</li> * <li>Node</li>
* <li>Node name</li> * <li>Name</li>
* <li>Session ID</li> * <li>Session ID</li>
* <li>Current Stage</li> * <li>Current Stage</li>
* <li>Available actions</li> * <li>Available actions</li>
* <li>Default action</li> * <li>Default action</li>
* <p> * </ul><p/>
* To implement a new command extend this class and implement all the abstract * To implement a new command extend this class and implement all the abstract
* methods. When implementing the actions remember that they could be invoked * methods. When implementing the actions remember that they could be invoked
* several times, and that you must use the current stage number to know what to * several times, and that you must use the current stage number to know what to
* do. * do.
* *
* @author Gabriel Guardincerri * @author Gabriel Guardincerri
*
*/ */
public abstract class LocalCommand extends AdHocCommand { public abstract class LocalCommand extends AdHocCommand {
@ -73,8 +72,7 @@ public abstract class LocalCommand extends AdHocCommand {
* The sessionID is an unique identifier of an execution request. This is * The sessionID is an unique identifier of an execution request. This is
* automatically handled and should not be called. * automatically handled and should not be called.
* *
* @param sessionID * @param sessionID the unique session id of this execution
* the unique session id of this execution
*/ */
public void setSessionID(String sessionID) { public void setSessionID(String sessionID) {
this.sessionID = sessionID; this.sessionID = sessionID;
@ -114,20 +112,43 @@ public abstract class LocalCommand extends AdHocCommand {
return creationDate; return creationDate;
} }
/**
* Returns true if the current stage is the last one. If it is then the
* execution of some action will complete the execution of the command.
* Commands that don't have multiple stages can always return <tt>true</tt>.
*
* @return true if the command is in the last stage.
*/
public abstract boolean isLastStage();
/**
* Returns true if the specified requester has permission to execute all the
* stages of this action. This is checked when the first request is received,
* if the permission is grant then the requester will be able to execute
* all the stages of the command. It is not checked again during the
* execution.
*
* @param jid the JID to check permissions on.
* @return true if the user has permission to execute this action.
*/
public abstract boolean hasPermission(String jid);
/**
* Returns the currently executing stage number. The first stage number is
* 0. During the execution of the first action this method will answer 0.
*
* @return the current stage number.
*/
public int getCurrentStage() {
return currenStage;
}
@Override @Override
void setData(AdHocCommandData data) { void setData(AdHocCommandData data) {
data.setSessionID(sessionID); data.setSessionID(sessionID);
super.setData(data); super.setData(data);
} }
/**
* Returns true if the current stage is the last one. If it is then the
* execution of some action will complete the execution of the command.
*
* @return true if the command is in the last stage.
*/
public abstract boolean isLastStage();
/** /**
* Increase the current stage number. This is automatically handled and should * Increase the current stage number. This is automatically handled and should
* not be called. * not be called.
@ -145,26 +166,4 @@ public abstract class LocalCommand extends AdHocCommand {
void decrementStage() { void decrementStage() {
currenStage--; currenStage--;
} }
/**
* Returns the currently executing stage number. The first stage number is
* 0. During the execution of the first action this method will answer 0.
*
* @return the current stage number.
*/
public int getCurrentStage() {
return currenStage;
}
/**
* Returns true if the specified requester has permission to execute all the
* stages of this action. This is checked when the first request is received,
* if the permission is grant then the requester will be able to execute
* all the stages of the command. It is not checked again during the
* execution.
*
* @param jid the JID to check permissions on.
* @return true if the user has permission to execute this action
*/
public abstract boolean hasPermission(String jid);
} }