Javadoc cleanup.

git-svn-id: http://svn.igniterealtime.org/svn/repos/smack/trunk@10879 b35dd754-fafc-0310-a699-88a17e54d16e

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
+ * 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
  * <code>getForm</code> method retrieves a form with all the users.
  * <p>
@@ -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
      * <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
      * 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

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
+        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
      * command for the connection related to this command manager. The
      * <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 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 <code>jid</code> is a
-     * full JID
+     * full JID.
      *
      * @param jid the full JID to retrieve the commands for.
      * @return the discovered items.

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:
+ * 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
  * 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
+     * @param sessionID the unique session id of this execution
-     *            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 <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
     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);
 }