You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@cocoon.apache.org by st...@locus.apache.org on 2000/09/15 00:30:55 UTC
cvs commit: xml-cocoon/xdocs how-it-works.xml
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 " document point of view " while the <source>javadoc</source> documentation describes it from a " procedural point of view". 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 " document point of view " while the <code>javadoc</code> documentation describes it from a " procedural point of view". 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 "main" 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 "dirty hack" implemented in order to wrap methods that allow the engine to be called from commandline.The code "is a hack" 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 "dirty hack" implemented in order to wrap methods that allow the engine to be called from commandline.The code "is a hack" 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 "chaining" 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 "pass-through" 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= "text/plain"</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="text/html"</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>