Mailing-List: contact svn-help@forrest.apache.org; run by ezmlm
Precedence: bulk
Reply-To: "Forrest Developers List" <dev@forrest.apache.org>
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: svn commit: r701317 -
 /forrest/branches/dispatcher_rewrite/plugins/org.apache.forrest.plugin.internal.dispatcher/src/java/org/apache/forrest/dispatcher/transformation/DispatcherTransformer.java
Date: Fri, 03 Oct 2008 07:41:01 -0000
To: svn@forrest.apache.org
From: thorsten@apache.org
Message-Id: <20081003074101.4DC95238889E@eris.apache.org>

Author: thorsten
Date: Fri Oct  3 00:41:00 2008
New Revision: 701317

URL: http://svn.apache.org/viewvc?rev=701317&view=rev
Log:
FOR-1118
Adding more javadocs comments to the transformer and commenting some code that I am not 100% sure whether we may need it.

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=701317&r1=701316&r2=701317&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  3 00:41:00 2008
@@ -47,13 +47,36 @@
 import org.xml.sax.InputSource;
 import org.xml.sax.SAXException;
 
+/**
+ * A cocoon transformer wrapper class for the dispatcher.
+ * 
+ * The actual work will be done in the core code of the 
+ * dispatcher which is based on StAX and AXIOM.
+ * 
+ * <li>In this transformer we doing principal configuration 
+ *  to adopt the dispatcher to the cocoon environment 
+ *  ({@link #configure(Configuration)} and 
+ *  ({@link #setup(SourceResolver, Map, String, Parameters)}
+ * <li>We reusing cocoon caching mechanism ({@link #getKey()}
+ *  and {@link #getValidity()} to cache the dispatcher.  
+ * <li>We record the SAX events ({@link #startDocument()} 
+ *  to later {@link #endDocument()} passing them as  
+ *  Stream to the Structurer implementation we
+ *  have chosen. 
+ * 
+ * @version 1.0
+ *
+ */
 public class DispatcherTransformer extends AbstractSAXTransformer implements
     Disposable, CacheableProcessingComponent {
 
   /**
    * The requested format.
    */
-  private String requestedFormat, requestId;
+  private String requestedFormat;
+  
+  // I am not 100% sure whether we really need this information.
+  // private String requestId;
 
   /**
    * Caching and validity properties
@@ -65,29 +88,59 @@
   private String validityOverride;
 
   private org.apache.excalibur.source.SourceResolver m_resolver;
-
-  private DispatcherBean config;
-
+  
   /**
-   * basic | enhanced
+   * The caption for the cache parameter
    */
-  private String xpathSupport;
-
-  private Logger log;
-
-  public static final String PATH_PARAMETER = "path";
-
-  public static final String DISPATCHER_REQUEST_ATTRIBUTE = "request";
-
   public static final String CACHE_PARAMETER = "cacheKey";
 
+  /**
+   * The caption for the validity parameter
+   */
   public static final String VALIDITY_PARAMETER = "validityFile";
 
+  /**
+   * The caption for the validity override parameter
+   */
   public static final String VALIDITY_OVERRIDE_PARAMETER = "dispatcher.caching";
 
+  /**
+   * The caption for the condition that caching is turned off
+   */
   public static final String CACHING_OFF = "off";
 
+  /**
+   * The caption for the condition that caching is turned on
+   */
   public static final String CACHING_ON = "on";
+  
+  /**
+   * Logger
+   */
+  private Logger log;
+  
+  /**
+   * Main configuration bean of the dispatcher.
+   * This config will control things like 
+   * <li>contract prefixes/suffixes
+   * <li>resolver to use
+   */
+  private DispatcherBean config;
+
+  /**
+   * The level of xpath support we need.
+   * If you choose enhanced you can inject/create node
+   * with enhanced xpath expression like e.g. 
+   * /root/child[id='test']
+   * 
+   * Supported values are: basic | enhanced
+   */
+  private String xpathSupport;
+
+   // I am not 100% sure whether we really need this information.
+  /*
+  public static final String DISPATCHER_REQUEST_ATTRIBUTE = "request";*/
+
 
   /*
    * @see
@@ -96,6 +149,7 @@
    */
   public void configure(Configuration configuration)
       throws ConfigurationException {
+    // creating a new config and store the general not request specific parameters here
     config = new DispatcherBean();
     boolean allowXml = configuration.getChild("allowXml").getValueAsBoolean(
         false);
@@ -103,6 +157,7 @@
     String contractUriPrefix = configuration.getChild("contractUriPrefix")
         .getValue("cocoon://resolve.contract");
     config.setContractUriPrefix(contractUriPrefix);
+    config.setContractUriSufix("");
     xpathSupport = configuration.getChild("xpathSupport").getValue("basic");
   }
 
@@ -112,8 +167,9 @@
       Parameters par) throws ProcessingException, SAXException, IOException {
     super.setup(resolver, objectModel, src, par);
 
-    this.requestId = parameters
-        .getParameter(DISPATCHER_REQUEST_ATTRIBUTE, null);
+    // I am not 100% sure whether we really need this information.
+   /* this.requestId = parameters
+        .getParameter(DISPATCHER_REQUEST_ATTRIBUTE, null);*/
     this.cacheKey = parameters.getParameter(CACHE_PARAMETER, null);
     log = getLogger();
     if (null == this.cacheKey)
@@ -123,13 +179,14 @@
     this.validityOverride = parameters.getParameter(
         VALIDITY_OVERRIDE_PARAMETER, "");
     this.cacheKey += validityOverride;
-
+ // I am not 100% sure whether we really need this information.
+    /*
     if (requestId == null) {
       String error = "dispatcherError:\n"
           + "You have to set the \"request\" parameter in the sitemap!";
       log.error(error);
       throw new ProcessingException(error);
-    }
+    }*/
     this.requestedFormat = parameters.getParameter(Captions.TYPE_ATT, null);
     if (requestedFormat == null) {
       String error = "dispatcherError:\n"
@@ -149,12 +206,14 @@
   }
 
   public void startDocument() throws SAXException {
+    // just start the recording 
     startSerializedXMLRecording(null);
   }
 
   public void endDocument() throws SAXException {
     String document = null;
     try {
+      // request the information from the recorder
       document = super.endSerializedXMLRecording();
     } catch (ProcessingException e) {
       throw new SAXException(e);