comments

git-svn-id: https://svn.alfresco.com/repos/alfresco-enterprise/alfresco/BRANCHES/WCM-DEV2/root@3605 c4b6b30b-aa2e-2d43-bbcb-ca4b014f7261

source/java/org/alfresco/web/bean/ajax/XFormsBean.java

@@ -43,6 +43,8 @@ import org.w3c.dom.events.EventTarget;
 import org.chiba.xml.xforms.connector.http.AbstractHTTPConnector;
 
 /**
+ * Bean for interacting with the chiba processor from the ui using ajax requests.
+ * Manages the chiba bean lifecycle.
  */
 public class XFormsBean
     implements EventListener
@@ -53,21 +55,28 @@ public class XFormsBean
     private InstanceData instanceData = null;
     private ChibaBean chibaBean;
 
+    /** @return the template type */
     public TemplateType getTemplateType()
     {
 	return this.tt;
     }
 
+    /** @param tt the template type */
     public void setTemplateType(final TemplateType tt)
     {
 	this.tt = tt;
     }
 
+    /** @param instanceData the instance data being modified. */
     public void setInstanceData(final InstanceData instanceData)
     {
 	this.instanceData = instanceData;
     }
 
+    /**
+     * Initializes the chiba process with the xform and registers any necessary
+     * event listeners.
+     */
     public void init()
 	throws XFormsException
     {
@@ -81,6 +90,7 @@ public class XFormsBean
         {
 	    LOGGER.debug("initializing " + this + 
 			 " with tt " + tt.getName());
+	    //XXXarielb generalize this
 	    final XFormsInputMethod tim = (XFormsInputMethod)
 		tt.getInputMethods().get(0);
 	    final Document form = tim.getXForm(instanceData.getContent(), tt);
@@ -88,6 +98,8 @@ public class XFormsBean
 	    this.chibaBean.init();
 	    EventTarget et = (EventTarget)
 		this.chibaBean.getXMLContainer().getDocumentElement();
+	    //XXXarielb register more listener for to do validation and do something
+	    //with the results.
 	    et.addEventListener(XFormsEventFactory.SUBMIT_ERROR, this, true);
 	}
 	catch (FormBuilderException fbe)
@@ -96,6 +108,10 @@ public class XFormsBean
 	}
     }
 
+    /**
+     * Writes the xform out to the http servlet response.  This allows
+     * us to use the browser to parse the xform using XMLHttpRequest.
+     */
     public void getXForm() 
 	throws IOException,
 	       XFormsException
@@ -133,11 +149,9 @@ public class XFormsBean
     }
 
     /**
-     * sets the value of a control in the processor.
+     * fires an action associated with a trigger.
      *
      * @param id the id of the control in the host document
-     * @param value the new value
-     * @return the list of events that may result through this action
      */
     public void fireAction() 
 	throws XFormsException, IOException
@@ -154,11 +168,7 @@ public class XFormsBean
     }
 
     /**
-     * sets the value of a control in the processor.
+     * handles submits and sets the instance data.
-     *
-     * @param id the id of the control in the host document
-     * @param value the new value
-     * @return the list of events that may result through this action
      */
     public void handleAction() 
 	throws Exception
@@ -175,6 +185,7 @@ public class XFormsBean
 	out.close();
     }
 
+    //XXXarielb placeholder for error handling
     public void handleEvent(Event e)
     {
 	LOGGER.debug("handleEvent " + e);
@@ -184,9 +195,6 @@ public class XFormsBean
      * stores cookies that may exist in request and passes them on to processor for usage in
      * HTTPConnectors. Instance loading and submission then uses these cookies. Important for
      * applications using auth.
-     *
-     * @param request the servlet request
-     * @param adapter the Chiba adapter instance
      */
     private static void storeCookies(final javax.servlet.http.Cookie[] cookiesIn,
 				     final ChibaBean chibaBean){

source/java/org/alfresco/web/templating/InstanceData.java

@@ -18,6 +18,10 @@ package org.alfresco.web.templating;
 
 import org.w3c.dom.Document;
 
+/**
+ * An abstraction layer around the xml content which allows
+ * for reseting the xml content being collected by the input method.
+ */
 public interface InstanceData
 {
     public Document getContent();

source/java/org/alfresco/web/templating/OutputUtil.java

@@ -52,6 +52,11 @@ import org.alfresco.service.cmr.repository.NodeService;
 import org.w3c.dom.Document;
 import org.alfresco.repo.avm.*;
 
+/**
+ * temporary home of generate and regenerate functionality until i figure
+ * out a more general way of triggering generate in TemplateOutputMethod
+ * every time the xml file is saved.
+ */
 public class OutputUtil
 {
     private static final Log LOGGER = LogFactory.getLog(OutputUtil.class);

source/java/org/alfresco/web/templating/TemplateInputMethod.java

@@ -20,12 +20,21 @@ import org.w3c.dom.Document;
 import java.io.Serializable;
 import java.io.Writer;
 
+/**
+ * Generates a user interface for inputing data into a template.
+ */
 public interface TemplateInputMethod
     extends Serializable
 {
+
+    /**
+     * Generates a user interface for inputing data into this template.
+     *
+     * @param instanceData provides the xml instance data if available.
+     * @param tt the template type to generate for
+     * @param out the writer to write the output to.
+     */
     public void generate(final InstanceData instanceData,
 			 final TemplateType tt,
 			 final Writer out);
-
-    //    public String getSchemaInputURL(final TemplateType tt);
 }

source/java/org/alfresco/web/templating/TemplateOutputMethod.java

@@ -20,10 +20,20 @@ import java.io.Serializable;
 import java.io.Writer;
 import org.w3c.dom.Document;
 
+/**
+ * Serializes the xml data to a writer.
+ */
 public interface TemplateOutputMethod
     extends Serializable
 {
 
+    /**
+     * Serializes the xml data in to a presentation format.
+     *
+     * @param xmlContent the xml content to serialize
+     * @param tt the template type that collected the xml content.
+     * @param out the writer to serialize to.
+     */
     public void generate(final Document xmlContent,
 			 final TemplateType tt,
 			 final Writer out)

source/java/org/alfresco/web/templating/TemplateType.java

@@ -21,23 +21,41 @@ import java.util.List;
 import java.io.Serializable;
 //import org.alfresco.service.cmr.repository.NodeRef;
 
+/**
+ * Encapsulation of a template type.
+ */
 public interface TemplateType
     extends Serializable
 {
 
+    /** the name of the template, which must be unique within the TemplatingService */
     public String getName();
 
+    /** the xml schema for this template type */
     public Document getSchema();
 
 //    public void setSchemaNodeRef(final NodeRef nodeRef);
 //    
 //    public NodeRef getSchemaNodeRef();
 
+    /** Provides a sample xml file for the schema */
     public Document getSampleXml(final String rootTagName);
 
+    //XXXarielb not used currently and not sure if it's necessary...
+    //    public void addInputMethod(final TemplateInputMethod in);
+
+    /**
+     * Provides a set of input methods for this template.
+     */
     public List<TemplateInputMethod> getInputMethods();
 
+    /**
+     * adds an output method to this template type.
+     */
     public void addOutputMethod(TemplateOutputMethod output);
 
+    /**
+     * Provides the set of output methods for this template.
+     */
     public List<TemplateOutputMethod> getOutputMethods();
 }

source/java/org/alfresco/web/templating/TemplatingService.java

@@ -47,19 +47,31 @@ import javax.faces.context.FacesContext;
 import org.alfresco.web.app.Application;
 import org.alfresco.web.bean.repository.Repository;
 
+/**
+ * Provides management of template types.
+ */
 public final class TemplatingService
     implements Serializable
 {
 
     ////////////////////////////////////////////////////////////////////////////
 
+    /**
+     * Encapsulation of configuration file management.
+     */
     private static class Configuration
     {
-	private final static File CONFIG_FILE  = 
-	    new File(TempFileProvider.getTempDir(), "templating_configuration.xml");
 	
+	/** indicates whether or not the configuration file has been loaded */
 	public static boolean loaded = false;
 
+	/**
+	 * locate the configuration file.  currently it is stored as 
+	 * <tt>templating_config.xml</tt> at the root of the data dictionary.
+	 *
+	 * @return the configuration file, which is currently all the
+	 * <tt>TemplateTypes</tt> serialized using object serialization.
+	 */
 	private static NodeRef getConfigFile()
 	{
 	    final TemplatingService ts = TemplatingService.INSTANCE;
@@ -98,13 +110,18 @@ public final class TemplatingService
 	    return configFileNodeRef;
 	}
 
+	/**
+	 * Load the configuration file into the templating service.
+	 */
 	public static void load()
 	    throws IOException
 	{
 	    final TemplatingService ts = TemplatingService.INSTANCE;
 	    final NodeRef configFileNodeRef = getConfigFile();
 	    FacesContext fc = FacesContext.getCurrentInstance();
-	    final InputStream contentIn = ts.contentService.getReader(configFileNodeRef, ContentModel.TYPE_CONTENT).getContentInputStream();
+	    final InputStream contentIn = 
+		ts.contentService.getReader(configFileNodeRef, 
+					    ContentModel.TYPE_CONTENT).getContentInputStream();
 	    final ObjectInputStream in = new ObjectInputStream(contentIn);
 	    try
 	    {
@@ -125,12 +142,14 @@ public final class TemplatingService
 	    }
 	    catch (ClassNotFoundException cnfe)
 	    {
-	    assert false : cnfe;
 		TemplatingService.LOGGER.error(cnfe);
 	    }
 	    loaded = true;
 	}
 	
+        /**
+	 * Save the current state of the templating service to the configuration file.
+	 */
 	public static void save()
 	    throws IOException
 	{
@@ -138,8 +157,6 @@ public final class TemplatingService
 	    FacesContext fc = FacesContext.getCurrentInstance();
 	    final NodeRef configFileNodeRef = getConfigFile();
 	    final OutputStream contentOut = ts.contentService.getWriter(configFileNodeRef, ContentModel.TYPE_CONTENT, true).getContentOutputStream();
-	    if (!CONFIG_FILE.exists())
-		CONFIG_FILE.createNewFile();
 	    final ObjectOutputStream out = new ObjectOutputStream(contentOut);
 	    for (TemplateType tt : TemplatingService.INSTANCE.getTemplateTypes())
 	    {
@@ -151,18 +168,28 @@ public final class TemplatingService
 
     ////////////////////////////////////////////////////////////////////////////
 
-
+    /**
+     * temporary location of the property on nodes that are xml files created
+     * by templating.
+     */
     public static final org.alfresco.service.namespace.QName TT_QNAME = 
 	org.alfresco.service.namespace.QName.createQName(org.alfresco.service.namespace.NamespaceService.CONTENT_MODEL_1_0_URI, "tt");
 
+    /**
+     * temporary location of the property on nodes generated from xml assets.
+     */
     public static final org.alfresco.service.namespace.QName TT_GENERATED_OUTPUT_QNAME = 
 	org.alfresco.service.namespace.QName.createQName(org.alfresco.service.namespace.NamespaceService.CONTENT_MODEL_1_0_URI, "tt_generated_output");
 
     private static final Log LOGGER = LogFactory.getLog(TemplatingService.class);
+
+    /** the single instance initialized using spring */
     private static TemplatingService INSTANCE;
 
+    /** internal storage of template types, keyed by the template name */
     private HashMap<String, TemplateType> templateTypes = 
 	new HashMap<String, TemplateType>();
+
     private final ContentService contentService;
     private final NodeService nodeService;
     private final FileFolderService fileFolderService;
@@ -170,6 +197,7 @@ public final class TemplatingService
     private final NamespaceService namespaceService;
     private final SearchService searchService;
 
+    /** instantiated using spring */
     public TemplatingService(final ContentService contentService,
 			     final NodeService nodeService,
 			     final FileFolderService fileFolderService,
@@ -184,11 +212,10 @@ public final class TemplatingService
 	this.namespaceService = namespaceService;
 	this.searchService = searchService;
 	if (INSTANCE == null)
-	{
 	    INSTANCE = this;
-	}
     }
 
+    /** Provides the templating service instance, loads config if necessary */
     public static TemplatingService getInstance()
     {
 	if (!Configuration.loaded)
@@ -208,16 +235,19 @@ public final class TemplatingService
 	return TemplatingService.INSTANCE;
     }
 
+    /** returns all registered template types */
     public Collection<TemplateType> getTemplateTypes()
     {
 	return this.templateTypes.values();
     }
 
+    /** return the template type by name or <tt>null</tt> if not found */
     public TemplateType getTemplateType(final String name)
     {
 	return this.templateTypes.get(name);
     }
 
+    /** registers a template type.  if one exists with the same name, it is replaced */
     public void registerTemplateType(final TemplateType tt)
     {
 	this.templateTypes.put(tt.getName(), tt);
@@ -231,12 +261,19 @@ public final class TemplatingService
 	}
     }
 
+    /** 
+     * instantiate a template type.  for now this will always generate the
+     * xforms implementation, but will at some point be configurable such that
+     * the template type implementation can be configured for the system,
+     * or specified in the gui.
+     */
     public TemplateType newTemplateType(final String name,
 					final NodeRef schemaNodeRef)
     {
 	return new TemplateTypeImpl(name, schemaNodeRef);
     }
 
+    /** utility function for creating a document */
     public Document newDocument()
     {
 	try
@@ -263,6 +300,7 @@ public final class TemplatingService
 //	}
     }
 
+    /** utility function for serializing a node */
     public void writeXML(final Node n, final Writer output)
     {
 	try 
@@ -280,12 +318,14 @@ public final class TemplatingService
 	}
     }
 
+    /** utility function for serializing a node */
     public void writeXML(final Node n, final File output)
 	throws IOException
     {
 	this.writeXML(n, new FileWriter(output));
     }
 
+    /** utility function for serializing a node */
     public String writeXMLToString(final Node n)
     {
 	final StringWriter result = new StringWriter();
@@ -293,6 +333,7 @@ public final class TemplatingService
 	return result.toString();
     }
 
+    /** utility function for parsing xml */
     public Document parseXML(final String source)
 	throws ParserConfigurationException,
 	SAXException,
@@ -301,6 +342,7 @@ public final class TemplatingService
 	return this.parseXML(new ByteArrayInputStream(source.getBytes()));
     }
 
+    /** utility function for parsing xml */
     public Document parseXML(final NodeRef nodeRef)
 	throws ParserConfigurationException,
 	SAXException,
@@ -312,6 +354,7 @@ public final class TemplatingService
 	return this.parseXML(in);
     }
 
+    /** utility function for parsing xml */
     public Document parseXML(final File source)
 	throws ParserConfigurationException,
 	SAXException,
@@ -320,6 +363,7 @@ public final class TemplatingService
 	return this.parseXML(new FileInputStream(source));
     }
 
+    /** utility function for parsing xml */
     public Document parseXML(final InputStream source)
 	throws ParserConfigurationException,
 	SAXException,

source/java/org/alfresco/web/templating/xforms/XFormsInputMethod.java

@@ -43,12 +43,17 @@ public class XFormsInputMethod
     {
     }
 
+    /**
+     * Generates html text which bootstraps the JavaScript code that will
+     * call back into the XFormsBean and get the xform and build the ui.
+     */
     public void generate(final InstanceData instanceData, 
 			 final TemplateType tt,
 			 final Writer out)
     {
 	final TemplatingService ts = TemplatingService.getInstance();
 	final FacesContext fc = FacesContext.getCurrentInstance();
+	//make the XFormsBean available for this session
 	final XFormsBean xforms = (XFormsBean)
 	    FacesHelper.getManagedBean(fc, "XFormsBean");
 	xforms.setInstanceData(instanceData);
@@ -65,16 +70,20 @@ public class XFormsInputMethod
 	final String cp = fc.getExternalContext().getRequestContextPath();
 
 	final Document result = ts.newDocument();
+
+	// this div is where the ui will write to
 	final Element div = result.createElement("div");
 	div.setAttribute("id", "alf-ui");
 	div.setAttribute("style", "width: 100%; border: solid 0px orange;");
 	result.appendChild(div);
 
+	// a script with config information and globals.
 	Element e = result.createElement("script");
 	e.appendChild(result.createTextNode("djConfig = { isDebug: false };\n" +
 					    "var WEBAPP_CONTEXT = \"" + cp + "\";\n"));
 	div.appendChild(e);
 
+	// include all our scripts, order is significant
 	e = result.createElement("script");
 	e.setAttribute("type", "text/javascript");
 	e.setAttribute("src", cp + "/scripts/tiny_mce/tiny_mce_src.js");
@@ -107,6 +116,9 @@ public class XFormsInputMethod
 //	return name.replaceAll(".+\\:", "");
     }
  
+    /**
+     * Generates the xforms based on the schema.
+     */
     public Document getXForm(Document xmlContent, final TemplateType tt) 
 	throws FormBuilderException
     {