From fdc4191c25bf53a23d5ed6987f9b29c3ee0060be Mon Sep 17 00:00:00 2001
From: pb <pb@8810af33-2d31-482b-a856-94f89814c4df>
Date: Sun, 6 Jan 2013 19:36:43 +0000
Subject: [PATCH] Enhanced various formatting, added various documentation.

git-svn-id: https://svn.libreccm.org/ccm/trunk@2028 8810af33-2d31-482b-a856-94f89814c4df
---
 .../src/com/arsdigita/cms/Initializer.java    |  1 -
 ccm-core/src/ccm-core.checklist               |  1 +
 ccm-core/src/ccm-core.load                    |  1 +
 ccm-core/src/ccm-core.upgrade                 |  1 +
 ccm-core/src/com/arsdigita/core/Loader.java   | 33 ++++++++++++++++-
 .../com/arsdigita/aplaws/AplawsConfig.java    |  2 +-
 .../src/com/arsdigita/aplaws/Loader.java      | 11 +++---
 .../src/com/arsdigita/navigation/Loader.java  | 35 ++++++++++++-------
 .../src/com/arsdigita/bundle/Loader.java      | 15 +++++---
 9 files changed, 75 insertions(+), 25 deletions(-)

diff --git a/ccm-cms/src/com/arsdigita/cms/Initializer.java b/ccm-cms/src/com/arsdigita/cms/Initializer.java
index 8984bec9a..30a9f2e99 100755
--- a/ccm-cms/src/com/arsdigita/cms/Initializer.java
+++ b/ccm-cms/src/com/arsdigita/cms/Initializer.java
@@ -95,7 +95,6 @@ public class Initializer extends CompoundInitializer {
     /** Creates a s_logging category with name = to the full name of class */
     private static Logger s_log = Logger.getLogger(Initializer.class);
     /** Configuration object for the CMS module     */
-    /** Configuration object for the CMS module     */
     private static final CMSConfig s_conf = CMSConfig.getInstance();
 
     /**
diff --git a/ccm-core/src/ccm-core.checklist b/ccm-core/src/ccm-core.checklist
index f535ca906..720f1177b 100755
--- a/ccm-core/src/ccm-core.checklist
+++ b/ccm-core/src/ccm-core.checklist
@@ -1,3 +1,4 @@
+<?xml version="1.0" encoding="utf-8"?>
 <!-- Specification file for additional checks during the
      installation process by the packaging tools
      (see com/arsdigita/packaging/Check.java for details) -->
diff --git a/ccm-core/src/ccm-core.load b/ccm-core/src/ccm-core.load
index bd0502d38..0c92acf3c 100755
--- a/ccm-core/src/ccm-core.load
+++ b/ccm-core/src/ccm-core.load
@@ -1,3 +1,4 @@
+<?xml version="1.0" encoding="utf-8"?>
 <load>
   <provides>
     <table name="inits"/>
diff --git a/ccm-core/src/ccm-core.upgrade b/ccm-core/src/ccm-core.upgrade
index ae38c1834..587c4b9c5 100755
--- a/ccm-core/src/ccm-core.upgrade
+++ b/ccm-core/src/ccm-core.upgrade
@@ -1,3 +1,4 @@
+<?xml version="1.0" encoding="utf-8"?>
 <upgrade>
   <version from="6.0.0" to="6.0.1">
     <script sql="ccm-core/upgrade/::database::-6.0.0-6.0.1.sql"/>
diff --git a/ccm-core/src/com/arsdigita/core/Loader.java b/ccm-core/src/com/arsdigita/core/Loader.java
index efc86b94a..7470949d9 100755
--- a/ccm-core/src/com/arsdigita/core/Loader.java
+++ b/ccm-core/src/com/arsdigita/core/Loader.java
@@ -82,7 +82,12 @@ import org.apache.log4j.Logger;
 
 
 /**
- * Core Loader
+ * Core Loader executes nonrecurring at install time and loads (installs
+ * and initializes) the Core packages persistently into database.
+ * 
+ * NOTE: Configuration parameters used at load time MUST be part of Loader 
+ * class and can not delegated to a Config object (derived from AbstractConfig).
+ * They will (and can) not be persisted into an registry object (file).
  *
  * @author Rafael H. Schloming &lt;rhs@mit.edu&gt;
  * @version $Revision: #15 $ $Date: 2004/08/16 $
@@ -90,8 +95,13 @@ import org.apache.log4j.Logger;
  */
 public class Loader extends PackageLoader {
 
+    /** Logger instance for debugging  */
     private static final Logger s_log = Logger.getLogger(Loader.class);
 
+// /////////////////////////////////////////////////////////////////////////////
+// Parameter Section
+// /////////////////////////////////////////////////////////////////////////////
+
     private EmailParameter m_email = new EmailParameter("waf.admin.email");
 
     private StringParameter m_screen = new StringParameter
@@ -172,7 +182,17 @@ public class Loader extends PackageLoader {
                                  }
                     );
 
+// /////////////////////////////////////////////////////////////////////////////
+// Parameter Section END
+// /////////////////////////////////////////////////////////////////////////////
+
+    /**
+     * Constructor, just registers parameters.
+     */
     public Loader() {
+
+        // Register defined parameters to the context by adding 
+        // the parameter to a map of parameters
         register(m_email);
         register(m_screen);
         register(m_given);
@@ -185,9 +205,15 @@ public class Loader extends PackageLoader {
         register(m_charsets);
         register(m_locales);
 
+        // Probably not used anyway, because Loader parameters are not
+        // persistent! (see note above)
         loadInfo();
     }
 
+// /////////////////////////////////////////////////////////////////////////////
+// Getter Section for Parameter Values
+// /////////////////////////////////////////////////////////////////////////////
+
     private String getEmail() {
         return ((InternetAddress) get(m_email)).toString();
     }
@@ -258,6 +284,11 @@ public class Loader extends PackageLoader {
         }
     }
 
+// /////////////////////////////////////////////////////////////////////////////
+// Getter Section for Parameter Values END
+// /////////////////////////////////////////////////////////////////////////////
+
+
     public void run(final ScriptContext ctx) {
         s_log.debug("CoreLoader run method started.");
         new KernelExcursion() {
diff --git a/ccm-ldn-aplaws/src/com/arsdigita/aplaws/AplawsConfig.java b/ccm-ldn-aplaws/src/com/arsdigita/aplaws/AplawsConfig.java
index fd1cd2bcd..c9a865792 100755
--- a/ccm-ldn-aplaws/src/com/arsdigita/aplaws/AplawsConfig.java
+++ b/ccm-ldn-aplaws/src/com/arsdigita/aplaws/AplawsConfig.java
@@ -18,8 +18,8 @@
 package com.arsdigita.aplaws;
 
 import com.arsdigita.runtime.AbstractConfig;
-import com.arsdigita.util.parameter.Parameter;
 import com.arsdigita.util.parameter.BooleanParameter;
+import com.arsdigita.util.parameter.Parameter;
 import com.arsdigita.util.parameter.StringParameter;
 
 import org.apache.log4j.Logger;
diff --git a/ccm-ldn-aplaws/src/com/arsdigita/aplaws/Loader.java b/ccm-ldn-aplaws/src/com/arsdigita/aplaws/Loader.java
index ff7533031..1b9794baa 100755
--- a/ccm-ldn-aplaws/src/com/arsdigita/aplaws/Loader.java
+++ b/ccm-ldn-aplaws/src/com/arsdigita/aplaws/Loader.java
@@ -27,6 +27,11 @@ import com.arsdigita.kernel.Role;
 import com.arsdigita.kernel.RoleCollection;
 import com.arsdigita.kernel.permissions.PrivilegeDescriptor;
 import com.arsdigita.loader.PackageLoader;
+import com.arsdigita.london.terms.Domain;
+import com.arsdigita.london.terms.importer.Parser;
+import com.arsdigita.navigation.Navigation;
+import com.arsdigita.navigation.Template;
+import com.arsdigita.navigation.TemplateMapping;
 import com.arsdigita.persistence.DataQuery;
 import com.arsdigita.runtime.ScriptContext;
 import com.arsdigita.util.Assert;
@@ -37,12 +42,6 @@ import com.arsdigita.util.parameter.StringParameter;
 import com.arsdigita.util.parameter.URLParameter;
 import com.arsdigita.web.Application;
 
-import com.arsdigita.navigation.Navigation;
-import com.arsdigita.navigation.Template;
-import com.arsdigita.navigation.TemplateMapping;
-import com.arsdigita.london.terms.Domain;
-import com.arsdigita.london.terms.importer.Parser;
-
 import java.net.URL;
 import java.net.MalformedURLException;
 import java.util.Date;
diff --git a/ccm-navigation/src/com/arsdigita/navigation/Loader.java b/ccm-navigation/src/com/arsdigita/navigation/Loader.java
index 14617e953..e617bb93f 100755
--- a/ccm-navigation/src/com/arsdigita/navigation/Loader.java
+++ b/ccm-navigation/src/com/arsdigita/navigation/Loader.java
@@ -21,6 +21,10 @@ package com.arsdigita.navigation;
 import com.arsdigita.kernel.Kernel;
 import com.arsdigita.kernel.KernelExcursion;
 import com.arsdigita.loader.PackageLoader;
+import com.arsdigita.navigation.portlet.ItemListPortlet;
+import com.arsdigita.navigation.portlet.NavigationTreePortlet;
+import com.arsdigita.navigation.portlet.ObjectListPortlet;
+import com.arsdigita.portal.PortletType;
 import com.arsdigita.runtime.ScriptContext;
 import com.arsdigita.util.UncheckedWrapperException;
 import com.arsdigita.util.parameter.Parameter;
@@ -28,12 +32,6 @@ import com.arsdigita.util.parameter.StringParameter;
 import com.arsdigita.web.Application;
 import com.arsdigita.web.ApplicationType;
 
-import com.arsdigita.navigation.portlet.ObjectListPortlet;
-import com.arsdigita.navigation.portlet.ItemListPortlet;
-import com.arsdigita.navigation.portlet.NavigationTreePortlet;
-
-import com.arsdigita.portal.PortletType;
-
 import java.io.BufferedReader;
 import java.io.InputStream;
 import java.io.InputStreamReader;
@@ -44,7 +42,12 @@ import org.apache.log4j.Logger;
 
 
 /**
- * Loader.
+ * Loader executes nonrecurring at install time and loads (installs and
+ * initializes) the Navigation module persistently into database.
+ *
+ * NOTE: Configuration parameters used at load time MUST be part of Loader 
+ * class and can not delegated to a Config object (derived from AbstractConfig).
+ * They will (and can) not be persisted into an registry object (file).
  *
  * @author Justin Ross &lt;jross@redhat.com&gt;
  * @version $Id: Loader.java 2070 2010-01-28 08:47:41Z pboy $
@@ -60,7 +63,7 @@ public class Loader extends PackageLoader {
         "WEB-INF/navigation/templates.txt");
 
     /**
-     * Constructor
+     * Constructor, just registers parameters.
      */
     public Loader() {
         register( m_templatesFile );
@@ -83,8 +86,9 @@ public class Loader extends PackageLoader {
                 loadObjectListPortlet();
                 NavigationTreePortlet.loadPortletType();
 
+                String templatesFile = (String)get(m_templatesFile);
                 try {
-                    setupTemplates();
+                    setupTemplates(templatesFile);
                 } catch( IOException ex ) {
                     throw new UncheckedWrapperException( ex );
                 }
@@ -177,13 +181,20 @@ public class Loader extends PackageLoader {
         app.save();
     }
 
-    public void setupTemplates() throws IOException {
+    /**
+     * Processes a file with Navigation template specificatgions and
+     * registers JSP templates with Navigation.
+     * 
+     * @param templatesFile file containing templates specification
+     * @throws IOException 
+     */
+    public static void setupTemplates(String templatesFile) throws IOException {
         
-        String templatesFile = (String)get(m_templatesFile);
         InputStream file = Thread.currentThread().getContextClassLoader()
                                  .getResourceAsStream(templatesFile);
         if (file == null) {
-            throw new UncheckedWrapperException(String.format("Failed to open templates files %s.", templatesFile));
+            throw new UncheckedWrapperException(String.format(
+                         "Failed to open templates files %s.", templatesFile));
         }
         BufferedReader templates =
             new BufferedReader( new InputStreamReader( file ) );
diff --git a/ccm-sci-bundle/src/com/arsdigita/bundle/Loader.java b/ccm-sci-bundle/src/com/arsdigita/bundle/Loader.java
index d819941ea..7fc8bd622 100644
--- a/ccm-sci-bundle/src/com/arsdigita/bundle/Loader.java
+++ b/ccm-sci-bundle/src/com/arsdigita/bundle/Loader.java
@@ -18,18 +18,18 @@
 
 package com.arsdigita.bundle;
 
-import com.arsdigita.london.terms.Domain;
-import com.arsdigita.london.terms.importer.Parser;
 
 import com.arsdigita.categorization.Category;
 import com.arsdigita.categorization.RootCategoryCollection;
 import com.arsdigita.cms.ContentSection;
 import com.arsdigita.cms.SecurityManager;
 import com.arsdigita.cms.ui.role.RoleFactory;
-import com.arsdigita.loader.PackageLoader;
 import com.arsdigita.kernel.Role;
 import com.arsdigita.kernel.RoleCollection;
 import com.arsdigita.kernel.permissions.PrivilegeDescriptor;
+import com.arsdigita.loader.PackageLoader;
+import com.arsdigita.london.terms.Domain;
+import com.arsdigita.london.terms.importer.Parser;
 import com.arsdigita.persistence.DataQuery;
 import com.arsdigita.runtime.ScriptContext;
 import com.arsdigita.util.parameter.Parameter;
@@ -63,6 +63,10 @@ public class Loader extends PackageLoader {
     /** Logger instance for debugging  */
     private static final Logger s_log = Logger.getLogger(Loader.class);
     
+
+// /////////////////////////////////////////////////////////////////////////////
+// Parameter Section
+// /////////////////////////////////////////////////////////////////////////////
     /**
      * List of comma separated sets of application instance specifications,
      * optionally used to create arbitrary custom application instances 
@@ -118,10 +122,13 @@ public class Loader extends PackageLoader {
                                                  "STD-NAV:/content/",
                                                  "STD-NAV:/portal/"      }
                 );
+// /////////////////////////////////////////////////////////////////////////////
+// Parameter Section END
+// /////////////////////////////////////////////////////////////////////////////
 
     
     /**
-     * Constructor
+     * Constructor, just registers parameters.
      */
     public Loader() {