cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject [DAISY] Created: SitemapOutputComponent Contracts
Date Tue, 16 Aug 2005 15:04:38 GMT
A new document has been created.

Document ID: 674
Branch: main
Language: default
Name: SitemapOutputComponent Contracts
Document Type: Document
Created: 8/16/05 3:04:32 PM
Creator (owner): Berin Loritsch
State: publish


Mime type: text/xml
Size: 3977 bytes

<h1>SitemapOutputComponent Contracts</h1>

<p>The SitemapOutputComponents are responsible for taking the results of a
pipeline to the end user.  The Sitemap will terminate the pipeline when it
encounters the first instance of a SitemapOutputComponent.  Just like the
SitemapModelComponent, all implementations of this contract must be pooled for
the same reasons.  The sitemap will query the output component for the mime type
and whether the sitemap should set the content length in the response.  It will
then provide the output component the <tt></tt> so you can
send the bytes directly to the user.</p>

<p>It should be noted that there is no way to access any of the request,
response, or context objects within a component that just implements this
interface like the Serializer.  The idea is to keep things simple.  All your
response attributes should have been already set, and the only responsibility at
this point in time is to give the user what he wants--the rendered object

<h2>The Mime Type</h2>

<p>You should always provide a mime type for the results you are serializing. 
It helps responsible browsers to identify how to show the information to the
user.  Do keep in mind that one of the most common browsers is a poor netizen
and does not always respect this information.  I am talking about Microsoft's
InternetExplorer.  It will first try to use the file extension of the resource
to determine the mime type, and then if that fails it will fall back to
respecting the mime type.  For that reason it is essential that you also
practice good netizen habits and make the file extension and the mime type
agree.  One example is the PDF document.  In order for Microsoft to treat a
result set as a PDF document you must have the url end with ".pdf" as well as
set the mime type to "application/pdf".  Internet Explorer will fail if you try
to send the document "badhabit.xml?view=pdf" rendered as a PDF document.  It is
because the file extension ".xml" will be remapped to "text/xml" even if you set
the mime type correctly.</p>

<p>It is for this reason that you may have some incorrectly configured servers
that will work for one browser and not the other.  The world would be much
simpler if all browsers blindly accepted the mime type.  Just be aware of this
issue when you are creating your sitemap and serializing your results.</p>

<h2>Setting the Content Length</h2>

<p>Most types of documents don't really care what the content length is, so it
is usually safe to leave the results of the <tt>shouldSetContentLength()</tt>
call to <tt>false</tt>.  It should be noted that the Adobe Acrobat Reader plugin
for Microsoft InternetExplorer has a bug that wasn't fixed until version 7.  The
bug prevents the PDF document from displaying correctly.  It will look like an
empty document or something similar.  So the general rule of thumb for
explicitly seting the content length is:</p>

<li>If it is a PDF document, always set content length (might require the
document to be cached to get the number of bytes)</li>
<li>If you are writing a Reader and you have the content lenght, set it.</li>
<li>Otherwise it is safe to return false here.</li>

<h2>The Output Stream</h2>

<p>There's not much to say here other than use the stream responsibly.  If you
are outputing text, ensure that it is properly encoded.  If you are outputing
binary information don't do any encoding.</p>

<p>There is so much that can be done with a raw OutputStream, but try to keep
things simple.  Things such as zipping the results as they are sent are
possibilities as long as the browser can handle it.  There is also overhead with
doing anything other than simply outputting your results.  The more complex your
processing the less it will be able to scale nicely.</p>

<p>The last thing to say here is to remember to close the output stream when you
are done.</p>


The document belongs to the following collections: documentation

View raw message