cocoon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From stef...@locus.apache.org
Subject cvs commit: xml-cocoon/xdocs how-it-works.xml
Date Thu, 14 Sep 2000 22:30:55 GMT
stefano     00/09/14 15:30:55

  Modified:    xdocs    how-it-works.xml
  Log:
  fixed how-it-works validation and removed doclet docs
  
  Revision  Changes    Path
  1.2       +39 -36    xml-cocoon/xdocs/how-it-works.xml
  
  Index: how-it-works.xml
  ===================================================================
  RCS file: /home/cvs/xml-cocoon/xdocs/how-it-works.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- how-it-works.xml	2000/08/30 22:28:42	1.1
  +++ how-it-works.xml	2000/09/14 22:30:55	1.2
  @@ -12,14 +12,15 @@
    <s1 title="How Cocoon 1.7.4. works">
     <p>
     From hereafter and unless otherwise specified, for sake of brevity any class name
  -is assumed to be prepended the <source>org.apache.cocoon</source> prefix. The
description hereafter tries to follow the operations of Cocoon from a &quot; document
point of view &quot; while the <source>javadoc</source> documentation describes
it from a &quot; procedural point of view&quot;. Therefore, this documentation tries
to be complementary to the <source>javadoc</source> one and not to repeat parts
therein. Furthermore, since the ultimate documentation is the <source>code</source>
itself, this document tries not to go too deep but eventually integrates the comments in the
code.
  +is assumed to be prepended the <code>org.apache.cocoon</code> prefix. The description
hereafter tries to follow the operations of Cocoon from a &quot; document point of view
&quot; while the <code>javadoc</code> documentation describes it from a &quot;
procedural point of view&quot;. Therefore, this documentation tries to be complementary
to the <code>javadoc</code> one and not to repeat parts therein. Furthermore,
since the ultimate documentation is the <code>code</code> itself, this document
tries not to go too deep but eventually integrates the comments in the code.
     </p>
     </s1>
  +  
     <s1 title="Cocoon">
      <p>
      This is the &quot;main&quot; class either at commandline use or from the
  -   servlet environment. Clearly, it contains the methods <source>init</source>
  -   for the first case as well as <source>main</source> for the latter case.
  +   servlet environment. Clearly, it contains the methods <code>init</code>
  +   for the first case as well as <code>main</code> for the latter case.
      </p>
      <p>
      Hereafter are described the operations in the two common cases of commandline (
  @@ -27,37 +28,38 @@
      </p>
       <s2 title="from the commandline">
       <p>
  -       When <source>Cocoon</source> is invoked from the commandline, it requires
the information for the location of the <source>cocoon.properties</source> and
then the name of the file containing the information to be processed. Upon loading of the
properties,
  -it creates a new <source>EngineWrapper</source> initialized with the above
mentioned properties and then handles to it <source>output</source> as well as
<source>input</source> streams.
  +       When <code>Cocoon</code> is invoked from the commandline, it requires
the information for the location of the <code>cocoon.properties</code> and then
the name of the file containing the information to be processed. Upon loading of the properties,
  +it creates a new <code>EngineWrapper</code> initialized with the above mentioned
properties and then handles to it <code>output</code> as well as <code>input</code>
streams.
       </p>
        <s3 title="EngineWrapper">
         <p>
  -       This is a &quot;dirty hack&quot; implemented in order to wrap methods that
allow the engine to be called from commandline.The code &quot;is a hack&quot; since
it tries to work around the problem that servlet API <cite>are not that easy to deal
when you enter other modes of operation</cite>. Likely, when the code will be adopt
<code>Stylebook</code>, this class will as well be cleaned up.
  +       This is a &quot;dirty hack&quot; implemented in order to wrap methods that
allow the engine to be called from commandline.The code &quot;is a hack&quot; since
it tries to work around the problem that servlet API <em>are not that easy to deal when
you enter other modes of operation</em>. Likely, when the code will be adopt <code>Stylebook</code>,
this class will as well be cleaned up.
         </p>
         <p>
  -       Basically, this class instantiates a <code>Engine</code> class and handles
to it the <source>output</source> as well as <source>input</source>
streams.
  +       Basically, this class instantiates a <code>Engine</code> class and handles
to it the <code>output</code> as well as <code>input</code> streams.
         </p>
        </s3>
       </s2>
       <s2 title="from the servlet">
        <s3 title="startup phase">
         <p>
  -       As any well behaving servlet, upon startup the <source>init</source>
method is invocated, which upon successful load of configuration information creates the <source>Engine</source>
  +       As any well behaving servlet, upon startup the <code>init</code> method
is invocated, which upon successful load of configuration information creates the <code>Engine</code>
         </p>
        </s3>
        <s3 title="production phase">
        <p>
  -      According to the servlet specification, a <source>service</source> method
is as-well provided by this <source>Class</source>. This method is the one which
is called by the servlet (e.g. Tomcat) and gets both the <source>HttpServletRequest</source>
as wellas will return (to the servlet, e.g. to Tomcat) the <source>HttpServletResponse</source>.
Basically, what happens is that the
  +      According to the servlet specification, a <code>service</code> method
is as-well provided by this <code>Class</code>. This method is the one which is
called by the servlet (e.g. Tomcat) and gets both the <code>HttpServletRequest</code>
as wellas will return (to the servlet, e.g. to Tomcat) the <code>HttpServletResponse</code>.
Basically, what happens is that the
        </p>
        </s3>
  -    </s2>
  +   </s2>
     </s1>
  -  <s2 title="Engine" >
  -   <cite>This class implements the engine that does all the document processing.</cite>
  +  
  +  <s1 title="Engine" >
  +   <source>This class implements the engine that does all the document processing.</source>
      <p>
  -   What a better definition of the function of this class than the words of its Author
(Stfano Mazzocchi) ? From this otherwise lapidary definition, one should realize the importance
of this Class in the context of the Cocoon operations and thus carefuly read should be performed
and thorough understanding of it be assured.
  +   What a better definition of the function of this class than the words of its Author
(Stefano Mazzocchi) ? From this otherwise lapidary definition, one should realize the importance
of this Class in the context of the Cocoon operations and thus carefuly read should be performed
and thorough understanding of it be assured.
      </p>
  -   <s3 title="startup phase">
  +   <s2 title="startup phase">
       <p>
       Either from commandline or from the servlet, upon startup of the cocoon servlet the
<code>Engine</code> is instantiated by the <code>private Engine</code>
method. For the sake of understanding the Cocoon operations, it is important to know that
at this point in time (and only this time in the whole lifespan of the Cocoon servlet) the
objects performing the initialization of the various components 
       </p>
  @@ -66,8 +68,8 @@
      
        </ul> 
       <p>are instantiated with the parameters contained by the Configuration object.
This is the reason why if changes are applied to the cocoon.properties file, these cannot
be exploited by the Cocoon engine unless the engine is stopped and restarted.</p>
  -   </s3>
  -   <s3 title="production phase">
  +   </s2>
  +   <s2 title="production phase">
       <p>
       The <code>handle</code> method has been already mentioned previously and
is indeed the main actor of the runtime operations of Cocoon. It gets invocated with two handles,
one for the input <code>HttpServletRequest</code> and one for the output <code>HttpServletResponse</code>.
       </p>
  @@ -96,12 +98,13 @@
        Now I suggest you to take a deep breath and read again the above steps since
   this is so beautiful the simplicity of the algorithm exploited that it make sense to appreciate
i tin depth and breath.
       </p>
  -   </s3>
  +   </s2>
      <p>
       At this point the key elements are therefore the processors and the formatters, which
directly operate upon the content of the Document. We are going to investigate them in detail.
Should be already clear that indeed one can have more than one <code>Processor</code>
in one <code>Document</code> and that these are going to be applied sequentially
one on top of the previous. Namely, this is how is implemented the &quot;chaining&quot;
of various <code>Processors</code>: in five lines of code (including debugging
information). Again, simplicity and good coding style are assets of this implementation. Let
us have a look then at what <code>Processors</code> and <code>Formatters</code>
are, since these could be leveraged further and indeed these are going to be likely extended
with new components for specific needs .
      </p>
  -  </s2>
  -  <s2 title="ProducerFactory">
  +  </s1>
  +  
  +  <s1 title="ProducerFactory">
     <p>
     For each source there must be an appropriate Producer implemented. Currently (version
1.7.4) the following ones are implemented:
     </p>
  @@ -109,10 +112,10 @@
       <li>from File</li>
       <li>from HttpServletRequest</li>
      </ul>
  -  Certainly one could think of more producer types, such as CORBA, RMI, SMTP, etc..
  -  </s2>
  +  <p>Certainly one could think of more producer types, such as CORBA, RMI, SMTP,
etc..</p>
  +  </s1>
   
  -  <s2 title="ProcessorFactory">
  +  <s1 title="ProcessorFactory">
      <p>
      For each processing instruction type  there must be an appropriate Processor implemented.
Currently (version 1.7.4) the following ones are implemented:
      </p>
  @@ -124,9 +127,9 @@
        <li>xinclude</li>
        <li>xslt</li>
       </ul>
  -  </s2>
  +  </s1>
   
  -  <s2 title="FormatterFactory">
  +  <s1 title="FormatterFactory">
      <p>
      For each format in which the output should be delivered (e.g. PDF, TEXT, HTML, XML,
XHTML ), there must be an appropriate Formatter implemented. Currently (version 1.7.4 ) the
following ones are distributed:
      </p>
  @@ -159,7 +162,7 @@
      <p>
       Due to the empyrical nature of the operations, we will follow a couple of examples
of growing complexity in order to identify common programming paradigms and coding patterns
which could then be used as guidelines for further formatters.
      </p>
  -  <s3 title="XMLFormatter">
  +  <s2 title="XMLFormatter">
      <p>
       Likely the easiest of the tasks, since is mostly a &quot;pass-through&quot;
method. Its tasks are:
      </p>
  @@ -171,18 +174,18 @@
     The <code>format</code> method is implemented by simply making use of 
   <code>org.apache.xml.serialize.SerializerFactory</code> 
      </p>   
  -  </s3>
  -  <s3 title="TextFormatter">
  -   <p>
  -    Another simple implementation of a Formatter, as stated in the code notes from the
Author (Stefano Mazzocchi, surprised?) <cite>This formatter is used to serialize non-marked-up
results such as plain text outputs, VRML, CSS etc.</cite>. Its biggest tasks are:
  -   </p>
  +  </s2>
  +  <s2 title="TextFormatter">
  +   <p>Another simple implementation of a Formatter, as stated in the code notes from
the Author (Stefano Mazzocchi, surprised?)</p>
  +   <source>This formatter is used to serialize non-marked-up results such as plain
text outputs, VRML, CSS etc.</source>
  +   <p>Its biggest tasks are:</p>
      <ul>
       <li>set the MIMEtype= &quot;text/plain&quot;</li>
       <li>convert the XML to text, removing the XML declarations and using TEXT method</li>
      </ul>
  -  </s3>
  +  </s2>
   
  -   <s3 title="HTMLFormatter">
  +   <s2 title="HTMLFormatter">
       <p>
       Here the difficult task of mapping between XML and HTML tags is exploited as above
by the SerializerFactory methods and thus is simply passed through to that. Very little coding
as well. Mostly focused on:
       </p>
  @@ -190,9 +193,9 @@
        <li>set the MIMEtype=&quot;text/html&quot;</li>
        <li>convert XML to HTML, removing the XML declaration and using HTML method</li>
       </ul>
  -   </s3>
  +   </s2>
   
  -   <s3 title="FO2PDFFormatter">
  +   <s2 title="FO2PDFFormatter">
       <p>
       Certainly the most complex of the Formatters so far implemented. It does not make use
of the
   SerializerFactory but instead of PDFRenderer from the FOP engine. 
  @@ -202,9 +205,9 @@
        <li>instantiate a new org.apache.fop.apps.Driver class</li>
        <li>follow the example use of such class by setting the Writer to the cocoon's
writer and then feeding the buildFooTree with the DOM</li>
       </ul>
  -   </s3>
  +   </s2>
   
  -  </s2>
  +  </s1>
   
   </body>
   </document>
  
  
  

Mime
View raw message