Some minor formatting

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

ccm-core/src/com/arsdigita/templating/Templating.java

@@ -46,7 +46,8 @@ import org.apache.log4j.Level;
 import org.apache.log4j.Logger;
 
 /**
- * An entry-point class for the functions of the templating package.
+ * An entry-point class for the functions of the templating package. The class
+ * manages access to all theme files (XSL as well as css, pirctures, etc).
  *
  * This class maintains a cache of <code>XSLTemplate</code> objects, managed
  * via the <code>getTemplate</code> and <code>purgeTemplate</code> methods.
@@ -343,6 +344,12 @@ public class Templating {
      * the resource servlet. All other http:// URLs are transformed into file:// 
      * for XSLT validation to work for these resources. It has the added benefit 
      * of speeding up loading of XSL...
+     * 
+     * Currently the direct file access method is perferred! As soon as we
+     * refactor to directly access the published XSL files in the database and
+     * to avoid the unnecessary intermediate step via the file system, we have
+     * to use URL's instead to be able to redirect access to a specific address
+     * to a servlet which manages database retrieval.
      */
     static URL transformURL(URL url) {
         HttpHost self = Web.getConfig().getHost();
@@ -435,6 +442,10 @@ public class Templating {
     }
 }
 
+/**
+ * 
+ * @author pb
+ */
 class LoggingErrorListener implements ErrorListener {
 
     private static final Logger s_log =

ccm-core/src/com/arsdigita/web/Application.java

@@ -628,6 +628,12 @@ public class Application extends Resource {
      * ROOT context of CCM is resulting in a CCM application installed in its
      * own context (separate from the main CCM context) not allowed in ROOT.
      * 
+     * If all CCM applications are installed into the same webapp context,
+     * this method is quite useless and client classses may ever overwrite
+     * this method. If a CCM application is installed in its own separate
+     * webapp context, the client class must overwrite this method and 
+     * provide an appropriate context path.
+     * 
      * @return webapp context installed or "" if no specific context of it's
      *         own but executing in main CCM context.
      */

ccm-core/src/com/arsdigita/web/Web.java

@@ -173,45 +173,49 @@ public class Web {
 
     /**
      * Processes an URL String trying to identify a corresponding recource
-     * which is mapped to the given path String. The resource may be stored at 
+     * which is mapped to the given path String. The method ensures that the
-     * various sources (file system, jar file, database, etc) depending on the
+     * resource defiunitely exists (using the URL returned) or definitely not
-     * implementation of the URL handlers and URLConnection objects.
+     * (returning null).
+     * 
+     * The resourcePath may be stored at various sources (file system, jar file, 
+     * database, etc) depending on the implementation of the URL handlers and 
+     * URLConnection objects.
      * 
      * 
-     * @param resource Path to the resource as String. It may include the
+     * @param resourcePath Path to the resource as String. It may include the
-     *                 web context in its first part or may be relative to the
+     *           web context in its first part or may be relative to the
-     *                 current webapp document root (i.e. its context). 
+     *           current webapp document root (i.e. its context). 
-     *                 Additionally, the web application component (if any)
+     *           Additionally, the web application component (if any)
-     *                 may be a comma separate list of webapps to search for the
+     *           may be a comma separate list of webapps to search for the
-     *                 rest of the path String.
+     *           rest of the path String.
-     *                 So, if the 'resource' is:
+     *           So, if the 'resourcePath' is:
-     *                 <pre>
+     *           <pre>
      *                 /myproj,ccm-cms/themes/heirloom/admin/index.xsl
      *                 </pre>
-     *                 then this method will look for resources at
+     *           then this method will look for resourcePaths at
-     *                 <pre>
+     *           <pre>
      *                 /myproj/themes/heirloom/admin/index.xsl
      *                 /ccm-cms/themes/heirloom/admin/index.xsl
      *                 </pre>
      *
-     * @return the URL for the resource, or null if no resource is mapped to
+     * @return the URL for the resourcePath, or null if no resource is mapped
-     *                 to the resource String
+     *           to the resourcePath String
      */
-    public static URL findResource(String resource) {
+    public static URL findResource(String resourcePath) {
         
-        if (resource == null) {
+        if (resourcePath == null) {
             if (s_log.isDebugEnabled()) {
                 s_log.debug("Parameter resource is null. Giving up.");
             }
             return null;
         }
         // ensure a leading "/"
-        if (!resource.startsWith("/")) {
+        if (!resourcePath.startsWith("/")) {
-            resource = "/" + resource;
+            resourcePath = "/" + resourcePath;
         }
-        if (resource.length() < 2) {
+        if (resourcePath.length() < 2) {
             if (s_log.isDebugEnabled()) {
-                s_log.debug("Resource spec is too short: >" + resource + "<");
+                s_log.debug("Resource spec is too short: >" + resourcePath + "<");
             }
             return null;
         }
@@ -219,29 +223,29 @@ public class Web {
         // determine my own webapp context
         ServletContext myctx = getServletContext();
 
-        // Check for old style resource format including a comma seoarated list
+        // Check for old style resourcePath format including a comma seoarated list
         // of webapps
-        if(resource.indexOf(",") <= 0 ) {
+        if(resourcePath.indexOf(",") <= 0 ) {
             // no comma separated list found, process as normal
             
-            // just try to find the resource in my own context
+            // just try to find the resourcePath in my own context
             try {
-                URL url = myctx.getResource(resource);
+                URL url = myctx.getResource(resourcePath);
                     if (url != null) {
                         if (s_log.isDebugEnabled()) {
-                            s_log.debug("Got URL " + url + " for " + resource);
+                            s_log.debug("Got URL " + url + " for " + resourcePath);
                         }
-                        return url;   // Return adjusted resource url
+                        return url;   // Return adjusted resourcePath url
                     }
             } catch (IOException ex) {
                 if (s_log.isDebugEnabled()) {
-                    s_log.debug("Cannot get resource for " + resource);
+                    s_log.debug("Cannot get resource for " + resourcePath);
                 }
-                // Try the first part of resource as a webapp context path and
+                // Try the first part of resourcePath as a webapp context path and
-                // check far a resource there
+                // check far a resourcePath there
-                int offset = resource.indexOf("/", 1); // search for second "/"
+                int offset = resourcePath.indexOf("/", 1); // search for second "/"
-                String testPath = resource.substring(1, offset);
+                String testPath = resourcePath.substring(1, offset);
-                String path = resource.substring(offset);
+                String path = resourcePath.substring(offset);
 
                 if (s_log.isDebugEnabled()) {
                     s_log.debug("Try to find a context at " + testPath);
@@ -253,7 +257,7 @@ public class Web {
                                 " is " + ctx);
                 }
                 if (ctx != null) {
-                    // successs, try to finf a resource for the remaining
+                    // successs, try to finf a resourcePath for the remaining
                     // string as path
                     try {
                         URL url = ctx.getResource(path);
@@ -262,7 +266,7 @@ public class Web {
                                  s_log.debug("Got URL " + url + 
                                              " for " + path);
                             }
-                            return url;   // Return adjusted resource url
+                            return url;   // Return adjusted resourcePath url
                         } else {
                             if (s_log.isDebugEnabled()) {
                                 s_log.debug("No URL present for " + path);
@@ -281,9 +285,9 @@ public class Web {
         } else {
             // comma separated list found
             // processing old style, comma separated webapp list
-            int offset = resource.indexOf("/", 1); // search for second "/"
+            int offset = resourcePath.indexOf("/", 1); // search for second "/"
-            String webappList = resource.substring(1, offset);
+            String webappList = resourcePath.substring(1, offset);
-            String path = resource.substring(offset);
+            String path = resourcePath.substring(offset);
         
             String[] webapps = StringUtils.split(webappList, ',');
             if (s_log.isDebugEnabled()) {
@@ -314,7 +318,7 @@ public class Web {
                                     s_log.debug("Got URL " + url + 
                                                 " for " + path);
                                 }
-                                return url;   // Return adjusted resource url
+                                return url;   // Return adjusted resourcePath url
                             } else {
                                 if (s_log.isDebugEnabled()) {
                                     s_log.debug("No URL present for " + path);

ccm-sci-bundle/src/WEB-INF/resources/scientificCMS-stylesheet-paths.txt

@@ -4,9 +4,11 @@
 # the full story.
 
 # Currently the "resource" part is actually "short-circuited", see 
-# Templating#transformURL(url)
+# Templating#transformURL(url). As long as we store and synchronize all theme
+# files in each server's local file system, we use the direct file apprach to
+# avoid unnecessary http request and traffic between client (user) and server!
 # Additionally all modules are installed into one webapp context, so the
-# webapp tag is redundant.
+# webapp tag is redundant, but sort of required by some part of the code.
 
 
 # Theme with single entry point (e.g Mandalay) managed by themedirector