[Update]

Mainly addition of java-doc in MasterTool and some small other changes.

git-svn-id: https://svn.libreccm.org/ccm/trunk@3320 8810af33-2d31-482b-a856-94f89814c4df

ccm-core/src/com/arsdigita/packaging/Command.java

@@ -39,7 +39,7 @@ abstract class Command {
     private boolean m_verbose;
 
     /**
-     * Represetents basic components of a command (command line interface).
+     * Represents basic components of a command (command line interface).
      *  
      * @param name  Name of the command to execute as string
      * @param summary Short Description of the command as string
@@ -75,7 +75,7 @@ abstract class Command {
         usage(options, out, "ccm " + getName(), args);
     }
 
-    static void usage(Options options, PrintStream out, String command,String args) {
+    static void usage(Options options, PrintStream out, String command, String args) {
         String str;
         final String debugVar = 
               "To show debugging output set the CCM_TOOLS_DEBUG environmental variable";

ccm-core/src/com/arsdigita/packaging/MasterTool.java

@@ -44,6 +44,13 @@ import java.util.Map;
  */
 public class MasterTool {
 
+    /**
+     * Prints an usage-info message with a given list of possible commands into
+     * the given output-stream.
+     * 
+     * @param cmds The list of possible commands
+     * @param out The output-stream
+     */
     private static void usage(Commands cmds, PrintStream out) {
         out.println("usage: ccm [OPTIONS | COMMAND]");
         out.println();
@@ -62,14 +69,18 @@ public class MasterTool {
      * Entry point for the the ccm command line tool.
      * 
      * Available commands:
-     * - load:    loads the database schema and initial content
+     * - help:     generic help overview
-     * - hostinit:populates the applications directors (jsp, classes, etc)
+     * - usage:    *no idea of the functionality*
-     * - get:     retrieves a configuration parameter
+     * - load:     loads the database schema and initial content
-     * - set:     stores a configuration parameeter
+     * - unload:   unloads the database schema and initial content
-     * - upgrade: upgrades database (schema & content) and/or application files
+     * - upgrade:  upgrades database (schema & content) and/or application files
-     * - status:  execution status of the application
+     * - get:      retrieves a configuration parameter
-     * - which:   searches for a resource or class
+     * - set:      stores a configuration parameter
-     * - unload:
+     * - clear:    *no idea of the functionality*
+     * - status:   execution status of the application
+     * - which:    searches for a resource or class
+     * 
+     * - hostinit: populates the applications directors (jsp, classes, etc)
      *
      * @param args the command line arguments
      */
@@ -78,16 +89,15 @@ public class MasterTool {
         final PrintStream out = System.out;
         final PrintStream err = System.err;
 
-        // nolonger needed
+        //Creates a list of all possible command-classes, against which
-        // com.arsdigita.runtime.Startup.startup();
+        //the command of the given argument will be matched later.
-
         Commands cmds = new Commands();
         Command help = new Help();
         Command usage = new Usage();
         cmds.add(help, true);
         cmds.add(usage, true);
         cmds.add(new Load());
-        cmds.add(new Unload(), true);
+        cmds.add(new Unload()); //hidden-flag used to be true
         cmds.add(new Upgrade());
         cmds.add(new Get());
         cmds.add(new Set());
@@ -100,6 +110,8 @@ public class MasterTool {
             System.exit(1);
         }
 
+        //Takes the command from the given argument and 
+        //matches it against the list of command-classes
         String name = args[0].trim();
         Command cmd = cmds.get(name);
 
@@ -114,6 +126,8 @@ public class MasterTool {
             command[i] = command[i].trim();
         }
 
+        //Runs the matching command with the remaining 
+        //arguments as the parameters
         boolean result = cmd.run(command);
         if (cmd == help || cmd == usage) {
             usage(cmds, out);
@@ -126,7 +140,9 @@ public class MasterTool {
     }
 
     /**
-     * 
+     * Internal class that represents a collection of command-classes. This 
+     * class is used for matching a given argument to a real command or listing
+     * all possible commands in an output. 
      */
     private static final class Commands {
 
@@ -135,8 +151,18 @@ public class MasterTool {
         private int m_maxName = 0;
         private HashSet m_hidden = new HashSet();
 
+        /**
+         * Constructor.
+         */
         public Commands() {}
 
+        /**
+         * Adds a command-class to the list of possible commands.
+         * 
+         * @param command The command-class to be added
+         * @param hidden If the command shall be excluded from the listing of
+         *               possible commands
+         */
         public void add(Command command, boolean hidden) {
             m_commands.add(command);
             String name = command.getName();
@@ -150,14 +176,33 @@ public class MasterTool {
             }
         }
 
+        /**
+         * Shortcut-function for adding a command-class to the list, if the
+         * hidden-flag shall be false. Calls the add-function above.
+         * 
+         * @param command The command-class to be added
+         */
         public void add(Command command) {
             add(command, false);
         }
 
+        /**
+         * Returns the command-class matching to the given name from the
+         * arguments.
+         * 
+         * @param name The name from the arguments
+         * @return The command-class.
+         */
         public Command get(String name) {
             return (Command) m_map.get(name);
         }
 
+        /**
+         * Returns a list of all possible commands, which are not flagged as
+         * hidden.
+         * 
+         * @return A list of commands.
+         */
         public String getCommands() {
             StringBuffer result = new StringBuffer();
             for (Iterator it = m_commands.iterator(); it.hasNext(); ) {

ccm-core/src/com/arsdigita/packaging/Unload.java

@@ -35,11 +35,25 @@ import org.apache.commons.cli.PosixParser;
 import org.apache.log4j.Logger;
 
 /**
- * Unload
+ * PackageTool worker class, implements the "load" command.
+ *  
+ * It is called by class MasterTols and unloads the database schema and initial 
+ * content.
+ * 
+ * MasterTool provides the following parameters (usually provided by an
+ * invokation script 'ccm')
+ * 
+ * ccm unload   PACKAGE-KEYS    [options]
+ * PACKAGE-KEYS one or more space separated names of modules (package-key, e.g.
+ *              ccm-cms-types-event) which should be loaded into database and
+ *              configuration registry
+ * Options:     [--config]  Removes entries in the registry (configuration repo)
+ *                          if set prevents any of the three data load steps
+ *                          described before to be executed!
  *
- * @author Rafael H. Schloming <rhs@mit.edu>
+ * @author Rafael H. Schloming <rhs@mit.edu> tosmers;
- * @version $Revision: #6 $ $Date: 2004/08/16 $
+ * @version $Revision: #7 $ $Date: 2015/03/29 $
- * @version $Id: Unload.java 736 2005-09-01 10:46:05Z sskracic $
+ * @version $Id: Unload.java 736 2015-03-29 14:22:20Z tosmers $
  */
 class Unload extends Command {
 
@@ -67,14 +81,19 @@ class Unload extends Command {
     }
 
     /**
-     * Constructor
+     * Standard constructor, super class provides basic functions as name, 
+     * short description, usage and help message.
+     * 
      */
     public Unload() {
         super("unload", "Unload configuration");
     }
 
     /**
-     * Invoked from the central tool "MasterTool" to perform the unload process.
+     * Invoked from the central tool "MasterTool" to execute the load process.
+     * 
+     * @param args
+     * @return
      */
     public boolean run(String[] args) {
         CommandLine line;

ccm-core/src/com/arsdigita/packaging/Upgrade.java

@@ -61,12 +61,23 @@ class Upgrade extends Command {
 
     static {
         logger.debug("Static initalizer starting...");
-        s_options.addOption(OptionBuilder.isRequired().hasArg().withLongOpt("from-version").withDescription(
+        s_options.addOption(OptionBuilder
-                "Upgrade from version VERSION").create());
+                .isRequired()
-        s_options.addOption(OptionBuilder.isRequired().hasArg().withLongOpt("to-version").withDescription(
+                .hasArg()
-                "Upgrade to version VERSION").create());
+                .withLongOpt("from-version")
-        s_options.addOption(OptionBuilder.hasArg().withLongOpt("parameters").withDescription(
+                .withDescription("Upgrade from version VERSION")
-                "Parameters to pass to upgrade scripts").create());
+                .create());
+        s_options.addOption(OptionBuilder
+                .isRequired()
+                .hasArg()
+                .withLongOpt("to-version")
+                .withDescription("Upgrade to version VERSION")
+                .create());
+        s_options.addOption(OptionBuilder
+                .hasArg()
+                .withLongOpt("parameters")
+                .withDescription("Parameters to pass to upgrade scripts")
+                .create());
         logger.debug("Static initalizer finished.");
     }
 
@@ -74,8 +85,7 @@ class Upgrade extends Command {
      * Constructor
      */
     public Upgrade() {
-        super("upgrade",
+        super("upgrade", "Upgrade a CCM package");
-              "Upgrade a CCM package");
 
         m_scripts = new ArrayList();
     }

ccm-core/src/com/arsdigita/runtime/AbstractScript.java

@@ -42,7 +42,7 @@ public abstract class AbstractScript extends AbstractParameterContext
     protected AbstractScript() {}
 
     /**
-     * The run method is inoked to execute the script. Before calling
+     * The run method is invoked to execute the script. Before calling
      * this method any required parameters registered by the noargs
      * constructer should be set.
      *