Apache » Cocoon »

  Cocoon Core
      2.2
   homepage

Cocoon Core 2.2

SitemapOutputComponent Contracts

SitemapOutputComponent Contracts

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 java.io.OutputStream so you can send the bytes directly to the user.

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 (page/image/etc.).

The Mime Type

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.

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.

Setting the Content Length

Most types of documents don't really care what the content length is, so it is usually safe to leave the results of the shouldSetContentLength() call to false.  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:

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

The Output Stream

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.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.The last thing to say here is to remember to close the output stream when you are done.