[DAISY] Updated: SitemapModelComponent Contracts

[da...@cocoon.zones.apache.org]

A document has been updated:

http://cocoon.zones.apache.org/daisy/documentation/673.html

Document ID: 673
Branch: main
Language: default
Name: SitemapModelComponent Contracts (unchanged)
Document Type: Document (unchanged)
Updated on: 9/11/05 12:03:42 PM
Updated by: Geoff Howard

A new version has been created, state: publish

Parts
=====
Content
-------
This part has been updated.
Mime type: text/xml (unchanged)
File name:  (unchanged)
Size: 5719 bytes (previous version: 5784 bytes)
Content diff:
(3 equal lines skipped)
    <h1>The SitemapModelComponent</h1>
    
    <p>The SitemapModelComponent identifies the contract between the Sitemap and
--- your pipeline components that create or transform information.  The types of
+++ your pipeline components that create or transform information. The types of
    components that fit within this umbrella are your Generators, Transformers, and
--- your Readers.  It is very important to note that all components impementing this
--- interface must be pooled or created on demand.  This is due to the separation
--- between the setup and the execution.  If you don't ensure every instance of the
--- component is unique within a pipeline, or accross pipelines, then the setup
+++ your Readers. It is very important to note that all components implementing this
+++ interface must be pooled or created on demand. This is due to the separation
+++ between the setup and the execution. If you don't ensure every instance of the
+++ component is unique within a pipeline, or across pipelines, then the setup
    process will start killing all the other setups and you will end up with serious
--- race conditions.  It's not that they need synchronized keywords applied to the
--- methods, its that the methods have to be called in a certain order.  This is by
--- design.  If you really think about it, due to the SAX infrastructure we would
+++ race conditions. It's not that they need synchronized keywords applied to the
+++ methods, its that the methods have to be called in a certain order. This is by
+++ design. If you really think about it, due to the SAX infrastructure we would
    still need to keep them synchronized because the order of SAX events affects the
    validity of your XML document.</p>
    
    <h2>Setup</h2>
    
    <p>The Sitemap will call the <tt>setup()</tt> method to prepare the component
--- for use.  This is where you start the process of getting your information ready
--- to generate your results.  The Sitemap provides the following information:</p>
+++ for use. This is where you start the process of getting your information ready
+++ to generate your results. The Sitemap provides the following information:</p>
    
    <ul>
    <li>SourceResolver--to find resources within your context.</li>
(4 equal lines skipped)
    </ul>
    
    <p>The setup method can throw one of three different types of exceptions which
--- would abort the processing of the pipeline.  These exceptions are:</p>
+++ would abort the processing of the pipeline. These exceptions are:</p>
    
    <ul>
--- <li>ProcessingException--the preferred type of exception.  Essentially wrap
+++ <li>ProcessingException--the preferred type of exception. Essentially wrap
    anything with one of these.</li>
    <li>SAXException--a problem reading an XML document will generate one of these.
    </li>
(4 equal lines skipped)
    <h2>Finding Resources</h2>
    
    <p>The SourceResolver passed into your SitemapModelComponent is used to find
--- other resources.  It will behave with the same properties as your sitemap.  So
--- if you are in a mounted sitemap handling a certain segment of requests, any
--- relative URLs resolved by the SourceResolver will be relative to that sitemap. 
--- However, the real fun comes with the types of requests we can make.  Cocoon
+++ other resources. It will behave with the same properties as your sitemap. So if
+++ you are in a mounted sitemap handling a certain segment of requests, any
+++ relative URLs resolved by the SourceResolver will be relative to that sitemap.
+++ However, the real fun comes with the types of requests we can make. Cocoon
    understands several different protocols, including embedding a call to another
    pipeline within your generated document.</p>
    
(2 equal lines skipped)
    <h2>Working with the Object Model</h2>
    
    <p>The object model that your component gets to use is essentially a
--- <tt>java.util.Map</tt>.  So how do we find what we need to get our job done? 
--- After all a key for a Java Map is just an Object--it could be anything. 
+++ <tt>java.util.Map</tt>. So how do we find what we need to get our job done?
+++ After all a key for a Java Map is just an Object--it could be anything.
    Thankfully, Cocoon provides a class to help you find your information:
--- <a href="http://cocoon.apache.org/2.1/apidocs/org/apache/cocoon/environment/ObjectModelHelper.html">org.apache.cocoon.environment.ObjectModelHelper</a>. 
+++ <a href="http://cocoon.apache.org/2.1/apidocs/org/apache/cocoon/environment/ObjectModelHelper.html">org.apache.cocoon.environment.ObjectModelHelper</a>.
    You will be able to find the Cocoon Context, Request, and Response objects.</p>
    
    <p>The Context and Request objects are simplified forms of the ServletContext
    and ServletRequest objects--however they do allow Cocoon to be invoked from the
--- command line as well.  The Response object follows the same veign, and does not
--- provide any access to the output stream.  That is because it is only the
+++ command line as well. The Response object follows the same vein, and does not
+++ provide any access to the output stream. That is because it is only the
    responsibility of a SitemapOutputComponent to send the results down the output
--- stream.  So why provide access to the Response object at all?  It is for two
--- reasons:  so that you can add or modify response headers before the pipeline is
+++ stream. So why provide access to the Response object at all? It is for two
+++ reasons: so that you can add or modify response headers before the pipeline is
    executed, or that you can signal a redirect.</p>
    
    <h2>The Source</h2>
    
    <p>The source provided by the Sitemap is the value of the attribute "src" in the
--- sitemap.  For example:</p>
+++ sitemap. For example:</p>
    
    <pre>&lt;map:transformer type="custom" src="{1}.xsl"/&gt;
    </pre>
    
    <p>Will resolve the name based on the substitution values and then pass the
--- resolved name to the component.  Let's say we matched on the pattern "status/*"
--- with the url "status/printfriendly".  The Sitemap will resolve the source to
--- "printfriendly.xsl" using the definition above.  The source is not necessary all
+++ resolved name to the component. Let's say we matched on the pattern "status/*"
+++ with the url "status/printfriendly". The Sitemap will resolve the source to
+++ "printfriendly.xsl" using the definition above. The source is not necessary all
    the time, although you may find it much more convenient than retrieving
    information from a request object or the parameters.</p>
    
    <h2>Working with the Parameters</h2>
    
    <p>The parameters object allows you to pull information in much the same way as
--- you would in the sitemap.  The
+++ you would in the sitemap. The
    <a href="http://excalibur.apache.org/apidocs/org/apache/avalon/framework/parameters/Parameters.html">org.apache.avalon.framework.parameters.Parameters</a>
    object is the same as the one from the Excalibur project, and you have the same
    interface there.</p>
    
--- <p class="note">You can get parent parameters using paths in the name.  For
+++ <p class="note">You can get parent parameters using paths in the name. For
    example, <tt>getParameter("../mrn")</tt> will get the "mrn" value from a parent
    Parameters object.</p>
    
    <p>The parameters are set in the sitemap using the <tt>&lt;map:parameter
    name="foo" value="bar"/&gt;</tt> to set the parameter "foo" with the value
--- "bar".  An example would look like this:</p>
+++ "bar". An example would look like this:</p>
    
    <pre>&lt;map:generator type="myspecialgen" src="foo"&gt;
      &lt;!-- these parameters are passed in --&gt;
(3 equal lines skipped)
    </pre>
    
    <p>Sometimes you may find some weirdness with parameters if you are setting some
--- values in flowscript and expecting to see them in your generator.  In that case
+++ values in flowscript and expecting to see them in your generator. In that case
    you may find it much more convenient to pass values within the Request
    attributes.</p>
    
(2 equal lines skipped)


Fields
======
no changes

Links
=====
no changes

Custom Fields
=============
no changes

Collections
===========
no changes