From 18d38845e9dc30bae3787aa6972036f69b8d0ac7 Mon Sep 17 00:00:00 2001 From: Matt Tucker Date: Thu, 13 Nov 2008 18:34:03 +0000 Subject: [PATCH] Javadoc cleanup. git-svn-id: http://svn.igniterealtime.org/svn/repos/smack/trunk@10879 b35dd754-fafc-0310-a699-88a17e54d16e --- .../smackx/commands/AdHocCommand.java | 10 +-- .../smackx/commands/AdHocCommandManager.java | 25 +++--- .../smackx/commands/LocalCommand.java | 83 +++++++++---------- 3 files changed, 59 insertions(+), 59 deletions(-) diff --git a/source/org/jivesoftware/smackx/commands/AdHocCommand.java b/source/org/jivesoftware/smackx/commands/AdHocCommand.java index 9c082a2ba..d4ea6cf6b 100755 --- a/source/org/jivesoftware/smackx/commands/AdHocCommand.java +++ b/source/org/jivesoftware/smackx/commands/AdHocCommand.java @@ -30,8 +30,8 @@ import java.util.List; * 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 * 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 - * users of a server is implemented. When the command is executed it gets that + * stored in it. For example suppose that a command that retrieves the list of + * 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 * getForm method retrieves a form with all the users. *

@@ -69,7 +69,7 @@ import java.util.List; * */ 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: 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 @@ -225,7 +225,7 @@ public abstract class AdHocCommand { /** * Completes the command execution with the information provided in the * response. 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 * 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 * 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 diff --git a/source/org/jivesoftware/smackx/commands/AdHocCommandManager.java b/source/org/jivesoftware/smackx/commands/AdHocCommandManager.java index 297825333..633f6c0b3 100755 --- a/source/org/jivesoftware/smackx/commands/AdHocCommandManager.java +++ b/source/org/jivesoftware/smackx/commands/AdHocCommandManager.java @@ -46,12 +46,13 @@ import java.util.concurrent.ConcurrentHashMap; /** * An AdHocCommandManager is responsible for keeping the list of available * 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 */ - public class AdHocCommandManager { private static final String DISCO_NAMESPACE = "http://jabber.org/protocol/commands"; @@ -76,12 +77,11 @@ public class AdHocCommandManager { * related to that connection. */ static { - XMPPConnection - .addConnectionCreationListener(new ConnectionCreationListener() { - public void connectionCreated(XMPPConnection connection) { - new AdHocCommandManager(connection); - } - }); + XMPPConnection.addConnectionCreationListener(new ConnectionCreationListener() { + public void connectionCreated(XMPPConnection connection) { + new AdHocCommandManager(connection); + } + }); } /** @@ -131,11 +131,12 @@ public class AdHocCommandManager { * connection. The node is an unique identifier of that * command for the connection related to this command manager. The * name is the human readable name of the command. - * The class is the class of the command + * The class is the class of the command, which must extend + * {@link LocalCommand}. * * @param node the unique identifier 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) { AdHocCommandInfo commandInfo = new AdHocCommandInfo(node, name, @@ -173,7 +174,7 @@ public class AdHocCommandManager { /** * Discover the commands of an specific JID. The jid is a - * full JID + * full JID. * * @param jid the full JID to retrieve the commands for. * @return the discovered items. diff --git a/source/org/jivesoftware/smackx/commands/LocalCommand.java b/source/org/jivesoftware/smackx/commands/LocalCommand.java index 132d474bb..36d51542d 100755 --- a/source/org/jivesoftware/smackx/commands/LocalCommand.java +++ b/source/org/jivesoftware/smackx/commands/LocalCommand.java @@ -25,21 +25,20 @@ import org.jivesoftware.smackx.packet.AdHocCommandData; /** * 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 - * provides some useful and common useful: - *

  • Node code
    • - *
  • Node name
    • - *
  • Session ID
    • - *
  • Current Stage
    • - *
  • Available actions
    • - *
  • Default action
    • - *

    + * provides some useful tools:

    * To implement a new command extend this class and implement all the abstract * 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 * do. * * @author Gabriel Guardincerri - * */ 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 * automatically handled and should not be called. * - * @param sessionID - * the unique session id of this execution + * @param sessionID the unique session id of this execution */ public void setSessionID(String sessionID) { this.sessionID = sessionID; @@ -114,20 +112,43 @@ public abstract class LocalCommand extends AdHocCommand { 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 true. + * + * @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 void setData(AdHocCommandData data) { data.setSessionID(sessionID); 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 * not be called. @@ -145,26 +166,4 @@ public abstract class LocalCommand extends AdHocCommand { void decrementStage() { 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); -} +} \ No newline at end of file