You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@cocoon.apache.org by bl...@apache.org on 2005/09/08 19:38:02 UTC
svn commit: r279591 - in /cocoon/trunk/src/java/org/apache/cocoon/sitemap:
SitemapModelComponent.java SitemapOutputComponent.java
Author: bloritsch
Date: Thu Sep 8 10:37:58 2005
New Revision: 279591
URL: http://svn.apache.org/viewcvs?rev=279591&view=rev
Log:
bolster the sitemap component contract information
Modified:
cocoon/trunk/src/java/org/apache/cocoon/sitemap/SitemapModelComponent.java
cocoon/trunk/src/java/org/apache/cocoon/sitemap/SitemapOutputComponent.java
Modified: cocoon/trunk/src/java/org/apache/cocoon/sitemap/SitemapModelComponent.java
URL: http://svn.apache.org/viewcvs/cocoon/trunk/src/java/org/apache/cocoon/sitemap/SitemapModelComponent.java?rev=279591&r1=279590&r2=279591&view=diff
==============================================================================
--- cocoon/trunk/src/java/org/apache/cocoon/sitemap/SitemapModelComponent.java (original)
+++ cocoon/trunk/src/java/org/apache/cocoon/sitemap/SitemapModelComponent.java Thu Sep 8 10:37:58 2005
@@ -24,9 +24,20 @@
import java.util.Map;
/**
- * This interface marks a component as a sitemap component that is used
- * in the processing phase, like a generator, a transformer, a serializer
- * or a reader.
+ * The SitemapModelComponent identifies the contract between the Sitemap and
+ * 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 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 still need to
+ * keep them synchronized because the order of SAX events affects the validity
+ * of your XML document.
*
* @author <a href="mailto:pier@apache.org">Pierpaolo Fumagalli</a>
* (Apache Software Foundation)
@@ -34,8 +45,19 @@
*/
public interface SitemapModelComponent {
/**
- * Set the <code>SourceResolver</code>, objectModel <code>Map</code>,
- * the source and sitemap <code>Parameters</code> used to process the request.
+ * The Sitemap will call the setup() method to prepare the component for
+ * use. This is where you start the process of getting your information
+ * ready to generate your results. See {@link org.apache.cocoon.environment.ObjectModelHelper} for help with the <code>objectModel</code>.
+ *
+ * @param resolver The <code>SourceResolver</code> to find resources within your context.
+ * @param objectModel A <code>java.util.Map</code> that contains the request and session information.
+ * @param src The value of the "src" attribute in the sitemap.
+ * @param par The sitemap parameters passed into your component.
+ *
+ * @throws SAXException if there is a problem reading a SAX stream.
+ * @throws IOException if there is a problem reading files.
+ * @throws ResourceNotFoundException if the resource to be rendered cannot be found.
+ * @throws ProcessingException if there is any other unexpected problem.
*/
void setup(SourceResolver resolver, Map objectModel, String src, Parameters par)
throws ProcessingException, SAXException, IOException;
Modified: cocoon/trunk/src/java/org/apache/cocoon/sitemap/SitemapOutputComponent.java
URL: http://svn.apache.org/viewcvs/cocoon/trunk/src/java/org/apache/cocoon/sitemap/SitemapOutputComponent.java?rev=279591&r1=279590&r2=279591&view=diff
==============================================================================
--- cocoon/trunk/src/java/org/apache/cocoon/sitemap/SitemapOutputComponent.java (original)
+++ cocoon/trunk/src/java/org/apache/cocoon/sitemap/SitemapOutputComponent.java Thu Sep 8 10:37:58 2005
@@ -19,8 +19,24 @@
import java.io.OutputStream;
/**
- * This interface marks a component as a sitemap component that produces
- * a response, like a serializer or a reader.
+ * 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 <code>SitemapOutputComponent</code>. Just like the
+ * <code>SitemapModelComponent</code>, 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
+ * <code>java.io.OutputStream</code> so you can send the bytes directly to the
+ * user.
+ * <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 (page/image/etc.).
+ * </p>
*
* @author <a href="mailto:Giacomo.Pati@pwr.ch">Giacomo Pati</a>
* @author <a href="mailto:cziegeler@apache.org">Carsten Ziegeler</a>
@@ -31,16 +47,63 @@
/**
* Set the {@link OutputStream} where the requested resource should
* be serialized.
+ *
+ * @param out The <code>OutputStream</code> target for the rendered results.
+ *
+ * @throws IOException if the stream can't be used.
*/
void setOutputStream(OutputStream out) throws IOException;
/**
- * Get the mime-type of the output of this <code>Component</code>.
+ * Obtain the mime type for the results being serialized. It helps
+ * responsible browsers to identify how to show the information to the
+ * user.
+ * <p>
+ * <strong>Warning:</strong>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.
+ * </p>
+ * <p>
+ * 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.
+ *
+ * @return the mime-type for the results.
*/
String getMimeType();
/**
- * Test if the component wants to set the content length
+ * Test if the component needs the content length set.
+ * <p>
+ * 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 seting the content length is:
+ * </p>
+ * <ul>
+ * <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>
+ * </ul>
+ *
+ * @return <code>true</code> if the content length needs to be set.
*/
boolean shouldSetContentLength();
}