From 228ddfcdb708f21e4d84adf895cb03e49db57ae4 Mon Sep 17 00:00:00 2001
From: Ariel Backenroth <bounce@alfresco.com>
Date: Wed, 25 Oct 2006 06:58:54 +0000
Subject: [PATCH] adding documentation for rendering engines.

git-svn-id: https://svn.alfresco.com/repos/alfresco-enterprise/alfresco/BRANCHES/WCM-DEV2/root@4219 c4b6b30b-aa2e-2d43-bbcb-ca4b014f7261
---
 .../web/forms/AbstractRenderingEngine.java    | 25 ++++++++++++++++---
 .../web/forms/XSLTRenderingEngine.java        | 24 +++++++++++++++++-
 2 files changed, 44 insertions(+), 5 deletions(-)

diff --git a/source/java/org/alfresco/web/forms/AbstractRenderingEngine.java b/source/java/org/alfresco/web/forms/AbstractRenderingEngine.java
index 6b514e25f4..22d3399702 100644
--- a/source/java/org/alfresco/web/forms/AbstractRenderingEngine.java
+++ b/source/java/org/alfresco/web/forms/AbstractRenderingEngine.java
@@ -33,8 +33,6 @@ import org.springframework.web.jsf.FacesContextUtils;
 /**
  * Provides helper functions for form data renderers.
  */
-// XXXarielb this class is probably temporary - but useful to
-// reduce redundant code until i find a better place to put this stuff
 public abstract class AbstractRenderingEngine
    implements RenderingEngine
 {
@@ -56,11 +54,21 @@ public abstract class AbstractRenderingEngine
       this.contentService = contentService;
    }
 
+   /**
+    * Returns the node ref for the rendering engine template.
+    *
+    * @return the node ref for the rendering engine template.
+    */
    public NodeRef getNodeRef()
    {
       return this.nodeRef;
    }
 
+   /**
+    * Returns the file extension to use for generated assets.
+    *
+    * @return the file extension to use for generated assets.
+    */
    public String getFileExtension()
    {
       return (String)
@@ -82,6 +90,17 @@ public abstract class AbstractRenderingEngine
       return new FormDataFunctions(AbstractRenderingEngine.getAVMRemote());
    }
 
+   /**
+    * Converts the provided path to an absolute path within the avm.
+    *
+    * @param parentAVMPath used as the parent path if the provided path
+    * is relative, otherwise used to extract the parent path portion up until
+    * the webapp directory.
+    * @param path a path relative to the parentAVMPath path, or if it is
+    * absolute, it is relative to the webapp used in the parentAVMPath.
+    *
+    * @return an absolute path within the avm using the paths provided.
+    */
    protected static String toAVMPath(final String parentAVMPath, final String path)
    {
       String parent = parentAVMPath;
@@ -93,7 +112,6 @@ public abstract class AbstractRenderingEngine
          return parentAVMPath;
       }
 
-
       if (path.charAt(0) == '/')
       {
          final Pattern p = Pattern.compile("([^:]+:/" + AVMConstants.DIR_APPBASE +
@@ -115,5 +133,4 @@ public abstract class AbstractRenderingEngine
                    " and request path " + path);
       return result;
    }
-
 }
\ No newline at end of file
diff --git a/source/java/org/alfresco/web/forms/XSLTRenderingEngine.java b/source/java/org/alfresco/web/forms/XSLTRenderingEngine.java
index f75ae06f52..ba3044e6c2 100644
--- a/source/java/org/alfresco/web/forms/XSLTRenderingEngine.java
+++ b/source/java/org/alfresco/web/forms/XSLTRenderingEngine.java
@@ -76,6 +76,12 @@ public class XSLTRenderingEngine
       return o == null ? null : XSLTRenderingEngine.toAVMPath(o.toString(), path);
    }
 
+   /**
+    * Adapter function used by the xsl tempalte to retrieve an xml asset at the given
+    * path.
+    *
+    * @return the document element for the xml asset at the given path.
+    */
    public static Node parseXMLDocument(final ExpressionContext ec, final String path)
       throws TransformerException,
       IOException,
@@ -86,6 +92,10 @@ public class XSLTRenderingEngine
       return d != null ? d.getDocumentElement() : null;
    }
 
+   /**
+    * Adapter function used by the xsl tempalte to retrieve a xml assets in the
+    * current directory.
+    */
    public static NodeIterator parseXMLDocuments(final ExpressionContext ec, 
                                                 final String formName)
       throws TransformerException,
@@ -95,6 +105,15 @@ public class XSLTRenderingEngine
       return XSLTRenderingEngine.parseXMLDocuments(ec, formName, "");
    }
 
+   /**
+    * Adapter function used by the xsl tempalte to retrieve a xml assets at 
+    * the given path.
+    *
+    * @return an iterator of the document elements for each of the xml
+    * assets at the given path.  In order to enable xpath expressions to
+    * properly access siblings, each root element is rooted at a node named
+    * file-list in the alfresco namespace.
+    */
    public static NodeIterator parseXMLDocuments(final ExpressionContext ec, 
                                                 final String formName, 
                                                 String path)
@@ -194,7 +213,10 @@ public class XSLTRenderingEngine
       };
    }
 
-   // for debugging
+   /**
+    * for debugging only.  provides the absolute avm path for the given
+    * path.
+    */
    public static String _getAVMPath(final ExpressionContext ec, 
                                     final String path)
       throws TransformerException,