refactor deprecated methods and some code documentation

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

ccm-core/src/com/arsdigita/loader/CoreLoader.java

@@ -53,7 +53,7 @@ import com.arsdigita.ui.sitemap.SiteMap;
 import com.arsdigita.util.Assert;
 import com.arsdigita.util.StringUtils;
 import com.arsdigita.util.UncheckedWrapperException;
-import com.arsdigita.util.csv.CSVParameterLoader;
+import com.arsdigita.util.parameter.CSVParameterLoader;
 import com.arsdigita.util.parameter.EmailParameter;
 import com.arsdigita.util.parameter.Parameter;
 import com.arsdigita.util.parameter.StringParameter;
@@ -72,7 +72,9 @@ import com.arsdigita.web.Web;
 
 public class CoreLoader extends PackageLoader {
 
-    public final static String versionId = "$Id: CoreLoader.java 1841 2009-03-05 07:52:42Z terry $ by $Author: terry $, $DateTime: 2004/08/16 18:10:38 $";
+    public final static String versionId = 
+            "$Id: CoreLoader.java 1841 2009-03-05 07:52:42Z terry $" +
+            "  by $Author: terry $, $DateTime: 2004/08/16 18:10:38 $";
 
     private static final Logger s_log = Logger.getLogger(CoreLoader.class);
 
@@ -423,8 +425,14 @@ public class CoreLoader extends PackageLoader {
         type.setDescription("A Portal!");
     }
 
+    /**
+     * Reads supported mime types from a file and ???.
+     * 
+     * Run once during initial load.
+     */
     private void loadMimeTypes() {
         ClassLoader cload = Thread.currentThread().getContextClassLoader();
+        // get filename containing supported mime types as comma separated list
         String resource = getResource();
         InputStream is = cload.getResourceAsStream(resource);
         if (is == null) {
@@ -435,7 +443,9 @@ public class CoreLoader extends PackageLoader {
             MimeTypeRow row = new MimeTypeRow();
             CSVParameterLoader loader = new CSVParameterLoader
                 (new InputStreamReader(is), row.getParameters());
+
             while (loader.next()) {
+                
                 row.load(loader);
 
                 s_log.info("Adding mimetype: " + row.getType() + " (" +

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

@@ -38,12 +38,25 @@ import org.apache.commons.cli.PosixParser;
 import org.apache.log4j.Logger;
 
 /**
- * PackageTool worker class, implements the "hostinit" command.
+ * Implements the "hostinit" command.
+ *
+ * Called by the ccm hostinit / ccm hostinit-bundle command
  * 
  * Populates the CCM application directory in webapps.
  * Does not create the database nor the config registry.
  *
- * Called by the ccm hostinit / ccm hostinit-bundle command
+ * Options:
+ *  --help           Display help
+ *  --usage          Print this message
+ *  --container      Specify the servlet container to initialize
+ *  --clean          REQUIRED: Delete the existing webapp directories
+ *                   before performing file copy.
+ *
+ * Command line call of hostinit via ccm scripts (shell, perl) 
+ * root@localhost# ccm hostinit­bundle   \
+ *                     ­­clean \
+ *                     ­­name aplaws­plus­standard ­­container=tomcat \
+ *                     http­port=8080 shutdown­port=8081 ajp­port=8009
  *
  * @author Rafael H. Schloming <rhs@mit.edu>
  * @version $Revision: #16 $ $Date: 2004/08/16 $
@@ -103,6 +116,7 @@ public class HostInit {
             System.exit(1);
         }
 
+        // Register custom protocol handlers
         com.arsdigita.runtime.Startup.startup();
 
         CommandLine line;
@@ -118,9 +132,14 @@ public class HostInit {
         String destination = line.getOptionValue("destination");
         boolean clean = line.hasOption("clean");
 
+        // base dir for all webapps, same as CATALINA_HOME
+        // same as CCM_HOME
         File dest = new File(destination);
+        // Currently: non-standard location of lib and classes
         File inf = new File(dest, "WEB-INF");
+        // Currentliy: non-standard location of lib
         File lib = new File(inf, "lib");
+        // currently: non-standard, special URL:resource handler, to be discarded
         File system = new File(inf, "system");
 
         if (!dest.exists()) {
@@ -163,6 +182,13 @@ public class HostInit {
         }
     }
 
+    /**
+     * 
+     * @param pathfile
+     * @param packages
+     * @param dest
+     * @throws java.io.IOException
+     */
     private static void copy(String pathfile, List packages, File dest)
         throws IOException {
         BufferedReader reader = new BufferedReader(new FileReader(pathfile));
@@ -199,6 +225,19 @@ public class HostInit {
         reader.close();
     }
 
+    /**
+     * Copies the ccm-core-6.y.z-system.jar (java extension for URL:resource
+     * protocol handler) to its special location. 
+     * 
+     * Will not be used as soon as the resource protocol is replaced by a 
+     * standard compliant mechanism.
+     * 
+     * @param pathfile
+     * @param packages
+     * @param dest
+     * @throws java.io.IOException
+     * @deprecated 
+     */
     private static void copySystem(String pathfile, List packages, File dest)
         throws IOException {
         BufferedReader reader = new BufferedReader(new FileReader(pathfile));
@@ -220,6 +259,14 @@ public class HostInit {
         reader.close();
     }
 
+    /**
+     * Copies all files in a given directory (dir) to a 
+     * destination directory (dest).
+     * 
+     * @param dir
+     * @param dest
+     * @throws java.io.IOException
+     */
     private static void copyDirectory(File dir, File dest) throws IOException {
         if (s_log.isInfoEnabled()) {
             s_log.info("Copying directory " + dir.toString());
@@ -236,6 +283,13 @@ public class HostInit {
         }
     }
 
+    /**
+     * Copies .....   (currently not used.)
+     * 
+     * @param file
+     * @param dest
+     * @throws java.io.IOException
+     */
     private static void copyJar(File file, File dest) throws IOException {
         if (s_log.isInfoEnabled()) {
             s_log.info("Copying JAR " + file.toString());

ccm-core/src/com/arsdigita/util/parameter/AbstractParameterContext.java

@@ -76,7 +76,7 @@ public abstract class AbstractParameterContext implements ParameterContext {
 
         if (Assert.isEnabled()) {
             Assert.exists(param, Parameter.class);
-            Assert.truth(!m_param.contains(param),
+            Assert.isTrue(!m_param.contains(param),
                          param + " is already registered");
         }
 
@@ -125,7 +125,7 @@ public abstract class AbstractParameterContext implements ParameterContext {
     public Object get(final Parameter param, final Object dephault) {
         if (Assert.isEnabled()) {
             Assert.exists(param, Parameter.class);
-            Assert.truth(m_param.contains(param),
+            Assert.isTrue(m_param.contains(param),
                          param + " has not been registered");
         }
 

ccm-core/src/com/arsdigita/util/parameter/CSV.java.example

@@ -29,7 +29,7 @@ import java.util.ArrayList;
 import javax.mail.internet.InternetAddress;
 
 /**
- * Subject to change.
+ * Demonstrates how to use the CSVParameterLoader class.
  *
  * @author Justin Ross <jross@redhat.com>
  * @version $Id: CSV.java 287 2005-02-22 00:29:02Z sskracic $
@@ -49,6 +49,7 @@ public final class CSV {
         Object[] row;
         ParameterValue value;
 
+        // step through each unit (line) of the input stream
         while (loader.next()) {
             row = new Object[params.length];
 

ccm-core/src/com/arsdigita/util/parameter/CSVParameterLoader.java

@@ -16,13 +16,13 @@
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
  *
  */
-package com.arsdigita.util.csv;
+package com.arsdigita.util.parameter;
 
 import com.arsdigita.util.UncheckedWrapperException;
-import com.arsdigita.util.parameter.ErrorList;
+// import com.arsdigita.util.parameter.ErrorList;
-import com.arsdigita.util.parameter.Parameter;
+// import com.arsdigita.util.parameter.Parameter;
-import com.arsdigita.util.parameter.ParameterLoader;
+// import com.arsdigita.util.parameter.ParameterLoader;
-import com.arsdigita.util.parameter.ParameterValue;
+// import com.arsdigita.util.parameter.ParameterValue;
 import java.io.IOException;
 import java.io.LineNumberReader;
 import java.io.Reader;
@@ -31,12 +31,13 @@ import java.util.HashMap;
 import java.util.List;
 
 /**
- * Subject to change.
+ * Processes an input stream (a set of lines, each containing a comma separated
+ * list of parameter values) and ....
  *
  * @author Justin Ross <jross@redhat.com>
  * @version $Id: CSVParameterLoader.java 287 2005-02-22 00:29:02Z sskracic $
  */
-public final class CSVParameterLoader implements ParameterLoader {
+public final class CSVParameterLoader implements ParameterReader {
     public final static String versionId =
         "$Id: CSVParameterLoader.java 287 2005-02-22 00:29:02Z sskracic $" +
         "$Author: sskracic $" +
@@ -46,16 +47,31 @@ public final class CSVParameterLoader implements ParameterLoader {
     private final Parameter[] m_params;
     private final HashMap m_line;
 
+    /**
+     * Constructor
+     * 
+     * @param reader: input stream to read values
+     * @param params: array of parameter objects to store procecced values
+     */
     public CSVParameterLoader(final Reader reader, final Parameter[] params) {
-        m_reader = new LineNumberReader(reader);
+        m_reader = new LineNumberReader(reader);  // input stream
-        m_params = params;
+        m_params = params;                        // array of parameters
-        m_line = new HashMap(params.length);
+        m_line = new HashMap(params.length);      //
     }
 
+    /**
+     * read
+     * 
+     * 
+     * 
+     * @param param
+     * @param errors
+     * @return
+     */
     public final String read(final Parameter param, final ErrorList errors) {
         return (String) m_line.get(param);
     }
-
+/*
     public final ParameterValue load(final Parameter param) {
         final ParameterValue value = new ParameterValue();
 
@@ -66,7 +82,13 @@ public final class CSVParameterLoader implements ParameterLoader {
 
         return value;
     }
-
+*/
+    /**
+     * Just a public visible entry point into internalNext, used to process
+     * an exception if thrown.
+     * 
+     * @return: boolean true if any values could be processed.
+     */
     public final boolean next() {
         try {
             return internalNext();
@@ -75,6 +97,14 @@ public final class CSVParameterLoader implements ParameterLoader {
         }
     }
 
+    /**
+     * Internally used worker method which processes the next() method.
+     * 
+     * Reads in a line from input stream and asks parseLine to process it. The
+     * resulting array of strings  (each containing a value) 
+     * @return
+     * @throws java.io.IOException
+     */
     private boolean internalNext() throws IOException {
         final String line = m_reader.readLine();
 
@@ -83,8 +113,13 @@ public final class CSVParameterLoader implements ParameterLoader {
         } else {
             final String[] elems = parseLine(line);
 
+            // m_params: array of parameters to store the comma separated values
+            // used to determine the max. number of values which can be processed.
             for (int i = 0; i < m_params.length; i++) {
                 if (i < elems.length) {
+                    // If for the given index into the array of parametes a
+                    // corresponding element in the array of strings exist,
+                    // store it in a hash map (a hash map per line)
                     m_line.put(m_params[i], elems[i]);
                 } else {
                     m_line.put(m_params[i], null);
@@ -99,6 +134,12 @@ public final class CSVParameterLoader implements ParameterLoader {
     private static final char QUOTE = '"';
     private static final char SEPARATOR = ',';
 
+    /**
+     * Internal used helper method of method parseLine.
+     *  
+     * @param c
+     * @return
+     */
     private char escape(char c) {
         switch (c) {
         case 'n':
@@ -112,6 +153,15 @@ public final class CSVParameterLoader implements ParameterLoader {
         }
     }
 
+    /**
+     * Takes a string and analyses it as a list of comma separated values.
+     * 
+     * Internally used to store each value found in a new string and add it
+     * to an array of strings.
+     * 
+     * @param line: string containing a comma separated list of values
+     * @return : array of strings, each containing a value of the list
+     */
     private String[] parseLine(final String line) {
         int length = line.length();
 
@@ -128,8 +178,8 @@ public final class CSVParameterLoader implements ParameterLoader {
 
         // The characters between seperators.
         StringBuffer buf = new StringBuffer(length);
-        // Marks the begining of the field relative to buf, -1
+        // Marks the begining of the field relative to buf,
-        // indicates the beginning of buf.
+        // -1 indicates the beginning of buf.
         int begin = -1;
         // Marks the end of the field relative to buf.
         int end = 0;
@@ -195,6 +245,14 @@ public final class CSVParameterLoader implements ParameterLoader {
         return fields;
     }
 
+    /**
+     * internal helper method for method parseLine
+     * 
+     * @param field
+     * @param begin
+     * @param end
+     * @return
+     */
     private String field(StringBuffer field, int begin, int end) {
         if (begin < 0) {
             return field.substring(0, end);

ccm-core/src/com/arsdigita/util/parameter/StringArrayParameter.java

@@ -18,8 +18,8 @@
  */
 package com.arsdigita.util.parameter;
 
-import com.arsdigita.util.parameter.StringParameter;
+// import com.arsdigita.util.parameter.StringParameter;
-import com.arsdigita.util.parameter.ErrorList;
+// import com.arsdigita.util.parameter.ErrorList;
 import com.arsdigita.util.StringUtils;
 
 /**