crossley 2002/08/16 20:26:16
Modified: src/documentation/xdocs/tutorial Tag: cocoon_2_0_3_branch
tutorial-generator.xml
Log:
Added more content.
Submitted by: Geoff Howard <[EMAIL PROTECTED]>
Revision Changes Path
No revision
No revision
1.1.2.2 +55 -30
xml-cocoon2/src/documentation/xdocs/tutorial/tutorial-generator.xml
Index: tutorial-generator.xml
===================================================================
RCS file:
/home/cvs/xml-cocoon2/src/documentation/xdocs/tutorial/tutorial-generator.xml,v
retrieving revision 1.1.2.1
retrieving revision 1.1.2.2
diff -u -r1.1.2.1 -r1.1.2.2
--- tutorial-generator.xml 13 Aug 2002 05:02:58 -0000 1.1.2.1
+++ tutorial-generator.xml 17 Aug 2002 03:26:16 -0000 1.1.2.2
@@ -421,9 +421,9 @@
}
}]]></source>
<s3 title="Compile and Test">
- <p>Save this code as
- <code>RequestExampleGenerator.java</code> and compile
- as before. You will need to add both
+ <p>Save this code as
+ <code>RequestExampleGenerator.java</code>
+ and compile as before. You will need to add both
<code>avalon-framework.jar</code> and
<code>avalon-excalibur.jar</code> to your classpath
this time. Besides finding the exact name of the jar
@@ -442,7 +442,7 @@
</source>
<p>At this point, you should be able to access the
example at
-<code>http://localhost:8080/cocoon/howYouDoin.xml?anyParameters=OK&themore=thebetter</code></p>
+<code>http://localhost:8080/cocoon/howYouDoin.xml?anyParam=OK&more=better</code></p>
</s3>
<s3 title="New Concepts">
<s4 title="Lifecycle">
@@ -512,17 +512,19 @@
</s4>
<s4 title="Nested Elements">
<p>In this example, nested elements are created simply
- by nesting complete
- <code>startElement()</code>/<code>endElement</code>
- pairs within each other. If we had a logic failure in
- our code and sent non-wellformed xml events down the
- pipeline, nothing in our process would complain (try it!).
- Of course, any transformers later in the pipeline would
- behave in an unpredictable manner.</p>
+ by nesting complete
+ <code>startElement()</code>/<code>endElement</code>
+ pairs within each other. If we had a logic failure in our code and
+ sent non-wellformed xml events down the pipeline, nothing in our
+ process would complain (try it!). Of course, any transformers later
+ in the pipeline would behave in an unpredictable manner.</p>
</s4>
<s4 title="Attributes">
- <p>Finally, we've introduced the use of attributes. We chose
to employ one <code>attributesImpl</code>, clearing it before each element.
- Multiple attributes for an element would simply be added by
repeated calls to <code>addAttribute</code>.</p>
+ <p>Finally, we've introduced the use of attributes.
+ We chose to
+ employ one <code>attributesImpl</code>, clearing it before each
+ element. Multiple attributes for an element would simply be added
+ by repeated calls to <code>addAttribute</code>.</p>
</s4>
</s3>
<s3 title="A Lesson">
@@ -550,7 +552,7 @@
this specific task is handled in the ESQL XSP example in just a few
lines of code. If your task is really this simple, there may be no
need to create your own generator.</p>
- <source xml:space="preserve"><![CDATA[import
org.apache.cocoon.generation.ComposerGenerator;
+<source xml:space="preserve"><![CDATA[import
org.apache.cocoon.generation.ComposerGenerator;
import org.apache.avalon.framework.component.ComponentManager;
import org.apache.avalon.framework.component.ComponentException;
import org.apache.avalon.framework.component.ComponentSelector;
@@ -708,8 +710,8 @@
<code>avalon-excalibur.jar, avalon-framework.jar, cocoon.jar,
xml-apis.jar</code> (using whatever names they have in your
distribution). When you compile this, you may receive some
- deprecation warnings. Do not worry about them - we will discuss that
- later.</p>
+ deprecation warnings. Do not worry about them - we will discuss
+ that later.</p>
<p>To test it, copy it over to your <code>WEB-INF\classes\</code>
directory as before and add something like the following to your
<code>sitemap.xmap</code> ...</p>
@@ -724,24 +726,47 @@
</s3>
<s3 title="New Concepts">
-<fixme author="open">Need more content here, or links to other docs.</fixme>
-<note>FIXME: We need more content here, or links to other docs.</note>
<s4 title="Composable and Disposable">
- <p>Discussion of Composable and Disposable</p>
+ <p>We've implemented the Avalon lifecycle interfaces Composable and
+ Disposable. When Cocoon starts up (which happens when the servlet
+ container starts up) the <code>ComponentManager</code> will call
+ <code>compose(ComponentManager m)</code> for our component as it works
+ its way through all the components declared in the sitemap. The handle
+ to <code>ComponentManager</code> is used to look up any other Avalon
+ components that we need. Lookups happen in an abstracted way using a
+ ROLE which enables us to change out implementations of each component
+ without affecting previously written code. Our generator's ROLE by the
+ way was defined in the <code>Generator</code> interface. </p>
+ <p>Similarly, when this instance of our generator is disposed of by the
+ container, it will call the <code>dispose()</code> method to allow us to
+ clean up any resources we held on to between invocations. Note that
+ components can be pooled by the container. If we thought that our employee
+ generator was going to see a lot of traffic, we might change its definition
+ at the top of sitemap.xmap to include attributes like <code>pool-grow="2"
+ pool-max="16" pool-min="2"</code> so that multiple overlapping requests
+ could be serviced without a log jam.</p>
</s4>
-
<s4 title="Datasource">
- <p>Discussion of Looking up and using a Datasource/Avalon Component.
- Include discussion of current lack of support for persistent
- PreparedStatements in Excalibur Datasource, per discussion with Berin.
- </p></s4>
-
+ <p>We look up our HSQL database here by its name given in cocoon.xconf.
+ If we had multiple datasources (say a backup development database and
+ a live one), we could determine which one to use based on a simple
+ configuration parameter in sitemap.xmap. We could get at configuration
+ parameters using the Avalon interface <code>Configurable</code>.</p>
+ <note>Notice that we wait until generate() to request our connection
+ from the pool - as we should. The problem is that we lose the benefit
+ of using prepared statements since they would be destroyed when we
+ returned the instance to the pool. At present, the implementation of
+ org.apache.avalon.excalibur.datasource.DataSourceComponent does not
+ support the pooling of statements.</note>
+ </s4>
<s4 title="Caching">
- <p>Introduce new code to implement Caching, discuss basic logic, and
- deprecation/move to Avalon. I could use some help here from Carsten,
- or someone who can quickly give an overview of the changes and plan.
- </p>
- </s4>
+<fixme author="open">Need more content here, or links to other docs.</fixme>
+<note>FIXME: This is still coming.</note>
+ <p>Introduce new code to implement Caching, discuss basic logic, and
+ deprecation/move to Avalon. I could use some help here from Carsten,
+ or someone who can quickly give an overview of the changes and plan.
+ </p>
+ </s4>
</s3>
</s2>
</s1>
----------------------------------------------------------------------
In case of troubles, e-mail: [EMAIL PROTECTED]
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
