svn commit: r703380 - /forrest/branches/dispatcher_rewrite/plugins/org.apache.forrest.plugin.internal.dispatcher/src/java/org/apache/forrest/dispatcher/transformation/DispatcherTransformer.java

[th...@apache.org]

Author: thorsten
Date: Fri Oct 10 03:14:01 2008
New Revision: 703380

URL: http://svn.apache.org/viewvc?rev=703380&view=rev
Log:
Adding more javadoc comments

Modified:
    forrest/branches/dispatcher_rewrite/plugins/org.apache.forrest.plugin.internal.dispatcher/src/java/org/apache/forrest/dispatcher/transformation/DispatcherTransformer.java

Modified: forrest/branches/dispatcher_rewrite/plugins/org.apache.forrest.plugin.internal.dispatcher/src/java/org/apache/forrest/dispatcher/transformation/DispatcherTransformer.java
URL: http://svn.apache.org/viewvc/forrest/branches/dispatcher_rewrite/plugins/org.apache.forrest.plugin.internal.dispatcher/src/java/org/apache/forrest/dispatcher/transformation/DispatcherTransformer.java?rev=703380&r1=703379&r2=703380&view=diff
==============================================================================
--- forrest/branches/dispatcher_rewrite/plugins/org.apache.forrest.plugin.internal.dispatcher/src/java/org/apache/forrest/dispatcher/transformation/DispatcherTransformer.java (original)
+++ forrest/branches/dispatcher_rewrite/plugins/org.apache.forrest.plugin.internal.dispatcher/src/java/org/apache/forrest/dispatcher/transformation/DispatcherTransformer.java Fri Oct 10 03:14:01 2008
@@ -231,13 +231,31 @@
       }
 
   }
-
+  
+/*
+ * Here we just start recording to use them later on.
+ * 
+ * In the future we may want to implement a sax based 
+ * structurer implementation again.
+ * 
+ * old transformer link @see
+ * http://svn.apache.org/viewvc?view=rev&revision=694101
+ * 
+ * @see org.apache.cocoon.transformation.AbstractSAXTransformer#startDocument()
+ */
   public void startDocument() throws SAXException {
     // just start the recording
     startSerializedXMLRecording(null);
   }
 
+  /*
+   * Here we pick up the recoreder result and start the
+   * processing on it.
+   * 
+   * @see org.apache.cocoon.transformation.AbstractSAXTransformer#endDocument()
+   */
   public void endDocument() throws SAXException {
+    // the recorded document we just streamed
     String document = null;
     try {
       // request the information from the recorder
@@ -257,17 +275,31 @@
     HashMap<String, Object> map = new HashMap<String, Object>();
     String propertyURI = "cocoon://" + requestId + ".props";
     try {
+      // get the source representation of the propertyURI
       Source propsSource = m_resolver.resolveURI(propertyURI);
       if (propsSource != null) {
+        // get the stream 
         InputStream stream = new BufferedInputStream(propsSource
             .getInputStream());
+        /*
+         * we need either just the bytes of the stream (if we allow
+         * xml properties) or we need to process it extracting the 
+         * properties.  
+         */
         if (config.isAllowXmlProperties()) {
           // get the bytes from the stream
           byte[] properties = IOUtils.getStreamAsByteArray(stream);
+          /*
+           *  add the bytes to the properties map
+           *  later on they will be picked up and
+           *  parsed to a dom node.
+           */
           map.put(DEFAULT_VARIABLES, properties);
         } else {
+          // extract the properties of the in coming stream
           XMLProperties.parseProperties(stream, map);
         }
+        // release source - you need to ALWAYS do this! 
         release(propsSource);
       }
     } catch (Exception e) {
@@ -275,10 +307,25 @@
     }
     // which implementation do we want
     if (xpathSupport.equals("enhanced")) {
+      /*
+       * The axiom implementation is an object model
+       * approach to StAX. It allows you a dom like navigation
+       * (allocate xpath nodes), adding of child elements in
+       * this xpath statement and many more. 
+       */
       structurer = new XMLStructurerAxiom(config, map);
     } else {
+      /*
+       * The stax implementationis 100% StAX even the generation 
+       * of the resulting document is done with StAX.
+       * However it does not offer real support of xpath expressions.
+       */
       structurer = new XMLStructurer(config, map);
     }
+    /*
+     * preparing the parser that will pick up the result and
+     * pass it to the consumer again. 
+     */
     SAXParser parser = null;
     try {
       // get the result of the structurer as stream
@@ -294,6 +341,7 @@
       throw new SAXException(e);
     } finally {
       if (null != parser) {
+     // release parser - you need to ALWAYS do this! 
         manager.release(parser);
       }
     }
@@ -372,7 +420,10 @@
 
   }
 
-  // From URIResolver, copied from TraxProcessor
+  /* 
+   * From URIResolver, copied from TraxProcessor
+   * @see javax.xml.transform.URIResolver#resolve(java.lang.String, java.lang.String)
+   */
   public javax.xml.transform.Source resolve(String href, String base)
       throws TransformerException {
     if (getLogger().isDebugEnabled()) {