org.apache.cocoon.sitemap
Interface SitemapOutputComponent

All Known Subinterfaces:

Reader, Serializer

public interface SitemapOutputComponent

The SitemapOutputComponents are responsible for taking the results of a pipeline to the end user. Current examples are the Serializer and the Reader. 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.).

Version:

$Id: SitemapOutputComponent.html 1304280 2012-03-23 11:18:01Z ilgrosso $

Method Summary

String	getMimeType() Obtain the media type for the results being serialized.
void	setOutputStream(OutputStream out) Set the OutputStream where the requested resource should be serialized.
boolean	shouldSetContentLength() Test if the component needs the content length set.

Method Detail

setOutputStream

public void setOutputStream(OutputStream out)
                     throws IOException

Set the OutputStream where the requested resource should be serialized.

Parameters:

out - The OutputStream target for the rendered results.

Throws:

IOException - if the stream can't be used.

getMimeType

public String getMimeType()

Obtain the media type for the results being serialized. The returned value is used to set Content-Type header in the response, unless it was overwritten in the sitemap. It helps responsible browsers to identify how to show the information to the user.

Example content type value: text/html; charset=utf-8.

Warning:Microsoft Internet Explorer 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.

You may have some incorrectly configured servers that will work for one browser and not the other because the mime-type and file extension do not agree. 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.

Returns:

the media type for the results.

shouldSetContentLength

public boolean shouldSetContentLength()

Test if the component needs the content length set.

Most types of documents don't really care what the content length is, so it is usually safe to leave the results of this method to false. It should be noted that the Adobe Acrobat Reader plugin for Microsoft Internet Explorer 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 setting 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 length, set it.
• Otherwise it is safe to return false here.

Returns:

true if the content length needs to be set.