cocoon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From reinh...@apache.org
Subject svn commit: r740230 - in /cocoon/cocoon3/trunk/cocoon-pipeline/src: main/java/org/apache/cocoon/pipeline/ main/java/org/apache/cocoon/pipeline/component/ test/java/org/apache/cocoon/pipeline/
Date Tue, 03 Feb 2009 06:57:00 GMT
Author: reinhard
Date: Tue Feb  3 06:56:59 2009
New Revision: 740230

URL: http://svn.apache.org/viewvc?rev=740230&view=rev
Log:
COCOON3-24
Cleanup PipelineComponent#finish(): It's not the concern of a pipeline component to know about
exceptions that happen somewhere in the pipeline.

add javadocs to the setConfiguration methods of PipelineComponent and Pipeline

Modified:
    cocoon/cocoon3/trunk/cocoon-pipeline/src/main/java/org/apache/cocoon/pipeline/AbstractPipeline.java
    cocoon/cocoon3/trunk/cocoon-pipeline/src/main/java/org/apache/cocoon/pipeline/CachingPipeline.java
    cocoon/cocoon3/trunk/cocoon-pipeline/src/main/java/org/apache/cocoon/pipeline/Pipeline.java
    cocoon/cocoon3/trunk/cocoon-pipeline/src/main/java/org/apache/cocoon/pipeline/component/AbstractPipelineComponent.java
    cocoon/cocoon3/trunk/cocoon-pipeline/src/main/java/org/apache/cocoon/pipeline/component/PipelineComponent.java
    cocoon/cocoon3/trunk/cocoon-pipeline/src/test/java/org/apache/cocoon/pipeline/PipelineTest.java

Modified: cocoon/cocoon3/trunk/cocoon-pipeline/src/main/java/org/apache/cocoon/pipeline/AbstractPipeline.java
URL: http://svn.apache.org/viewvc/cocoon/cocoon3/trunk/cocoon-pipeline/src/main/java/org/apache/cocoon/pipeline/AbstractPipeline.java?rev=740230&r1=740229&r2=740230&view=diff
==============================================================================
--- cocoon/cocoon3/trunk/cocoon-pipeline/src/main/java/org/apache/cocoon/pipeline/AbstractPipeline.java
(original)
+++ cocoon/cocoon3/trunk/cocoon-pipeline/src/main/java/org/apache/cocoon/pipeline/AbstractPipeline.java
Tue Feb  3 06:56:59 2009
@@ -33,7 +33,8 @@
 import org.apache.commons.logging.LogFactory;
 
 /**
- * Basic pipeline implementation that collects the {@link PipelineComponent}s and connects
them with each other.
+ * Basic pipeline implementation that collects the {@link PipelineComponent}s
+ * and connects them with each other.
  */
 public abstract class AbstractPipeline<T extends PipelineComponent> implements Pipeline<T>
{
 
@@ -45,7 +46,7 @@
 
     /**
      * {@inheritDoc}
-     *
+     * 
      * @see org.apache.cocoon.pipeline.Pipeline#addComponent(org.apache.cocoon.pipeline.component.PipelineComponent)
      */
     public void addComponent(T pipelineComponent) {
@@ -63,7 +64,7 @@
 
     /**
      * {@inheritDoc}
-     *
+     * 
      * @see org.apache.cocoon.pipeline.Pipeline#execute()
      */
     public void execute() throws Exception {
@@ -77,7 +78,7 @@
 
     /**
      * {@inheritDoc}
-     *
+     * 
      * @see org.apache.cocoon.pipeline.Pipeline#getContentType()
      */
     public String getContentType() {
@@ -91,7 +92,7 @@
 
     /**
      * {@inheritDoc}
-     *
+     * 
      * @see org.apache.cocoon.pipeline.Pipeline#setConfiguration(java.util.Map)
      */
     public void setConfiguration(Map<String, ? extends Object> parameters) {
@@ -100,8 +101,9 @@
 
     /**
      * {@inheritDoc}
-     *
-     * @see org.apache.cocoon.pipeline.Pipeline#setup(java.io.OutputStream, java.util.Map)
+     * 
+     * @see org.apache.cocoon.pipeline.Pipeline#setup(java.io.OutputStream,
+     *      java.util.Map)
      */
     public void setup(OutputStream outputStream) {
         this.setup(outputStream, null);
@@ -109,8 +111,9 @@
 
     /**
      * {@inheritDoc}
-     *
-     * @see org.apache.cocoon.pipeline.Pipeline#setup(java.io.OutputStream, java.util.Map)
+     * 
+     * @see org.apache.cocoon.pipeline.Pipeline#setup(java.io.OutputStream,
+     *      java.util.Map)
      */
     public void setup(OutputStream outputStream, Map<String, Object> parameters) {
         if (outputStream == null) {
@@ -139,16 +142,12 @@
             this.logger.debug("Invoking first component of " + this);
         }
 
-        RuntimeException exception = null;
         try {
             Starter starter = (Starter) this.components.getFirst();
             starter.execute();
-        } catch (RuntimeException ex) {
-            exception = ex;
-            throw ex;
         } finally {
             for (PipelineComponent pipelineComponent : this.getComponents()) {
-                pipelineComponent.finish(exception);
+                pipelineComponent.finish();
             }
         }
     }

Modified: cocoon/cocoon3/trunk/cocoon-pipeline/src/main/java/org/apache/cocoon/pipeline/CachingPipeline.java
URL: http://svn.apache.org/viewvc/cocoon/cocoon3/trunk/cocoon-pipeline/src/main/java/org/apache/cocoon/pipeline/CachingPipeline.java?rev=740230&r1=740229&r2=740230&view=diff
==============================================================================
--- cocoon/cocoon3/trunk/cocoon-pipeline/src/main/java/org/apache/cocoon/pipeline/CachingPipeline.java
(original)
+++ cocoon/cocoon3/trunk/cocoon-pipeline/src/main/java/org/apache/cocoon/pipeline/CachingPipeline.java
Tue Feb  3 06:56:59 2009
@@ -37,9 +37,9 @@
 
 /**
  * <p>
- * A {@link Pipeline} implementation that returns a cached result if, and only if all its
components
- * support caching. A {@link PipelineComponent} is cacheable if it implements the interface
- * {@link CachingPipelineComponent}.
+ * A {@link Pipeline} implementation that returns a cached result if, and only
+ * if all its components support caching. A {@link PipelineComponent} is
+ * cacheable if it implements the interface {@link CachingPipelineComponent}.
  * </p>
  */
 public class CachingPipeline<T extends PipelineComponent> extends AbstractPipeline<T>
{
@@ -53,7 +53,10 @@
     /** Expires time in seconds */
     private String expires;
 
-    /** Expires pipelines that have non-cacheable pipeline components require an explicit
cache key */
+    /**
+     * Expires pipelines that have non-cacheable pipeline components require an
+     * explicit cache key
+     */
     private Serializable expiresCacheKey;
 
     private final Log logger = LogFactory.getLog(this.getClass());

Modified: cocoon/cocoon3/trunk/cocoon-pipeline/src/main/java/org/apache/cocoon/pipeline/Pipeline.java
URL: http://svn.apache.org/viewvc/cocoon/cocoon3/trunk/cocoon-pipeline/src/main/java/org/apache/cocoon/pipeline/Pipeline.java?rev=740230&r1=740229&r2=740230&view=diff
==============================================================================
--- cocoon/cocoon3/trunk/cocoon-pipeline/src/main/java/org/apache/cocoon/pipeline/Pipeline.java
(original)
+++ cocoon/cocoon3/trunk/cocoon-pipeline/src/main/java/org/apache/cocoon/pipeline/Pipeline.java
Tue Feb  3 06:56:59 2009
@@ -29,78 +29,100 @@
 
 /**
  * <p>
- * A pipeline expects one or more {@link PipelineComponent}s that passed by using
- * {@link #addComponent(PipelineComponent)}. Then these components get linked with each other
in the order they were
- * added. The {@link #setup(OutputStream, Map)} method, calls the setup method on all pipeline
components and assembles
- * the pipeline. Finally the {@link #execute()} method produces the result and writes it
to the {@link OutputStream}
- * which has been passed to the {@link #setup(OutputStream, Map)} method.
+ * A pipeline expects one or more {@link PipelineComponent}s that passed by
+ * using {@link #addComponent(PipelineComponent)}. Then these components get
+ * linked with each other in the order they were added. The
+ * {@link #setup(OutputStream, Map)} method, calls the setup method on all
+ * pipeline components and assembles the pipeline. Finally the
+ * {@link #execute()} method produces the result and writes it to the
+ * {@link OutputStream} which has been passed to the
+ * {@link #setup(OutputStream, Map)} method.
  * </p>
- *
+ * 
  * <p>
  * A pipeline works based on two fundamental concepts:
- *
+ * 
  * <ul>
- * <li>The first component of a pipeline is of type {@link Starter}. The last component
is of type {@link Finisher}.
- * </li>
- * <li>In order to link components with each other, the first has to be a {@link Producer},
the latter
- * {@link Consumer}. </li>
+ * <li>The first component of a pipeline is of type {@link Starter}. The last
+ * component is of type {@link Finisher}. </li>
+ * <li>In order to link components with each other, the first has to be a
+ * {@link Producer}, the latter {@link Consumer}. </li>
  * </ul>
- *
+ * 
  * <p>
- * When the pipeline links the components, it merely checks whether the above mentioned interfaces
are present. So the
- * pipeline does not know about the specific capabilities or the compatibility of the components.
It is the
- * responsibility of the {@link Producer} to decide whether a specific {@link Consumer} can
be linked to it or not (that
- * is, whether it can produce output in the desired format of the {@link Consumer} or not).
It is also conceivable that
- * a {@link Producer} is capable of accepting different types of {@link Consumer}s and adjust
the output format
- * according to the actual {@link Consumer}.
+ * When the pipeline links the components, it merely checks whether the above
+ * mentioned interfaces are present. So the pipeline does not know about the
+ * specific capabilities or the compatibility of the components. It is the
+ * responsibility of the {@link Producer} to decide whether a specific
+ * {@link Consumer} can be linked to it or not (that is, whether it can produce
+ * output in the desired format of the {@link Consumer} or not). It is also
+ * conceivable that a {@link Producer} is capable of accepting different types
+ * of {@link Consumer}s and adjust the output format according to the actual
+ * {@link Consumer}.
  * </p>
  */
-public interface Pipeline<T extends PipelineComponent>{
+public interface Pipeline<T extends PipelineComponent> {
 
     /**
-     * Add a {@link PipelineComponent} to the pipeline. The order of when the components
are passed is significant.
-     *
+     * Add a {@link PipelineComponent} to the pipeline. The order of when the
+     * components are passed is significant.
+     * 
      * @param pipelineComponent The {@link PipelineComponent}.
      */
     void addComponent(T pipelineComponent);
 
     /**
-     * After the pipeline has been setup ({@link #setup(OutputStream, Map)}, this method
can be invoked in order to
-     * produce the result.
-     *
-     * @throws Exception Any problem that might occur while processing the pipeline.
+     * After the pipeline has been setup ({@link #setup(OutputStream, Map)},
+     * this method can be invoked in order to produce the result.
+     * 
+     * @throws Exception Any problem that might occur while processing the
+     *             pipeline.
      */
     void execute() throws Exception;
 
     /**
-     * Get the mime-type {@linkref http://tools.ietf.org/html/rfc2046} of the content produced
by the pipeline.
-     *
+     * Get the mime-type {@linkref http://tools.ietf.org/html/rfc2046} of the
+     * content produced by the pipeline.
+     * 
      * @return The mime-type of the content.
      */
     String getContentType();
 
     /**
      * Get the time of the last modification.
-     *
+     * 
      * @return The last modification date
      */
     long getLastModified();
 
     /**
-     * After the pipeline has been prepared ({@link #addComponent(PipelineComponent)}, this
method can be invoked in
-     * order to setup and initialize the pipeline and its components.
-     *
-     * @param outputStream An {@link OutputStream} where the pipeline execution result is
written.
+     * After the pipeline has been prepared ({@link #addComponent(PipelineComponent)},
+     * this method can be invoked in order to setup and initialize the pipeline
+     * and its components.
+     * 
+     * @param outputStream An {@link OutputStream} where the pipeline execution
+     *            result is written.
      */
     void setup(OutputStream outputStream);
 
     /**
-     * The same as {@link #setup(OutputStream)} but also allows passing parameters to the
pipeline components.
-     *
-     * @param outputStream An {@link OutputStream} where the pipeline execution result is
written.
-     * @param parameters A {@link Map} of parameters that are available to all {@link PipelineComponent}s.
+     * The same as {@link #setup(OutputStream)} but also allows passing
+     * parameters to the pipeline components.
+     * 
+     * @param outputStream An {@link OutputStream} where the pipeline execution
+     *            result is written.
+     * @param parameters A {@link Map} of parameters that are available to all
+     *            {@link PipelineComponent}s.
      */
     void setup(OutputStream outputStream, Map<String, Object> parameters);
 
+    /**
+     * Pass pipeline specific configuration parameters to the pipeline component
+     * in a generic way. This is useful in environments that automatically
+     * assemble pipelines with their components and can't use the pipeline's
+     * constructors or setters.
+     * 
+     * @param configuration The {@link Map} of configuration parameters.
+     */
     void setConfiguration(Map<String, ? extends Object> parameters);
 }

Modified: cocoon/cocoon3/trunk/cocoon-pipeline/src/main/java/org/apache/cocoon/pipeline/component/AbstractPipelineComponent.java
URL: http://svn.apache.org/viewvc/cocoon/cocoon3/trunk/cocoon-pipeline/src/main/java/org/apache/cocoon/pipeline/component/AbstractPipelineComponent.java?rev=740230&r1=740229&r2=740230&view=diff
==============================================================================
--- cocoon/cocoon3/trunk/cocoon-pipeline/src/main/java/org/apache/cocoon/pipeline/component/AbstractPipelineComponent.java
(original)
+++ cocoon/cocoon3/trunk/cocoon-pipeline/src/main/java/org/apache/cocoon/pipeline/component/AbstractPipelineComponent.java
Tue Feb  3 06:56:59 2009
@@ -18,9 +18,13 @@
 
 import java.util.Map;
 
+/**
+ * A basic implementation of a {@link PipelineComponent} that provides empty
+ * implementations of all its methods.
+ */
 public abstract class AbstractPipelineComponent implements PipelineComponent {
 
-    public void finish(Exception exception) {
+    public void finish() {
         // do nothing
     }
 

Modified: cocoon/cocoon3/trunk/cocoon-pipeline/src/main/java/org/apache/cocoon/pipeline/component/PipelineComponent.java
URL: http://svn.apache.org/viewvc/cocoon/cocoon3/trunk/cocoon-pipeline/src/main/java/org/apache/cocoon/pipeline/component/PipelineComponent.java?rev=740230&r1=740229&r2=740230&view=diff
==============================================================================
--- cocoon/cocoon3/trunk/cocoon-pipeline/src/main/java/org/apache/cocoon/pipeline/component/PipelineComponent.java
(original)
+++ cocoon/cocoon3/trunk/cocoon-pipeline/src/main/java/org/apache/cocoon/pipeline/component/PipelineComponent.java
Tue Feb  3 06:56:59 2009
@@ -23,25 +23,37 @@
 /**
  * This is a component used in a pipeline.
  * 
- * If the environment has some configuration for this component {@link #setConfiguration(Map)}
is called as the first
- * step. After the component has been added to pipeline, {@link #setup(Map)} is called before
the pipeline is executed.
- * When the pipeline is finished or if any error occurred {@link #finish} is called.
+ * If the environment has some configuration for this component
+ * {@link #setConfiguration(Map)} is called as the first step. After the
+ * component has been added to pipeline, {@link #setup(Map)} is called before
+ * the pipeline is executed. When the pipeline is finished or if any error
+ * occurred {@link #finish} is called.
  */
 public interface PipelineComponent {
 
-    void setConfiguration(Map<String, ? extends Object> configuration);
+    /**
+     * This method is called after pipeline run - regardless if the run was
+     * successful or an exception was thrown.
+     * 
+     */
+    void finish();
 
     /**
-     * The shared object map for this pipeline run.
+     * Pass component specific configuration parameters to the pipeline
+     * component in a generic way. This is useful in environments that
+     * automatically assemble pipelines with their components and can't use the
+     * components constructors or setters.
      * 
-     * @param parameters A {@link Map} of parameters that are available to all {@link PipelineComponent}s.
This is a
-     *            modifiable map that can be changed by this pipeline component.
+     * @param configuration The {@link Map} of configuration parameters.
      */
-    void setup(Map<String, Object> parameters);
+    void setConfiguration(Map<String, ? extends Object> configuration);
 
     /**
-     * This method is called after pipeline run - regardless if the run was successful or
an exception was thrown.
+     * The shared object map for this pipeline run.
      * 
+     * @param parameters A {@link Map} of parameters that are available to all
+     *            {@link PipelineComponent}s. This is a modifiable map that can
+     *            be changed by this pipeline component.
      */
-    void finish(Exception exception);
+    void setup(Map<String, Object> parameters);
 }

Modified: cocoon/cocoon3/trunk/cocoon-pipeline/src/test/java/org/apache/cocoon/pipeline/PipelineTest.java
URL: http://svn.apache.org/viewvc/cocoon/cocoon3/trunk/cocoon-pipeline/src/test/java/org/apache/cocoon/pipeline/PipelineTest.java?rev=740230&r1=740229&r2=740230&view=diff
==============================================================================
--- cocoon/cocoon3/trunk/cocoon-pipeline/src/test/java/org/apache/cocoon/pipeline/PipelineTest.java
(original)
+++ cocoon/cocoon3/trunk/cocoon-pipeline/src/test/java/org/apache/cocoon/pipeline/PipelineTest.java
Tue Feb  3 06:56:59 2009
@@ -20,12 +20,13 @@
 
 import junit.framework.TestCase;
 
+import org.apache.cocoon.pipeline.component.PipelineComponent;
 import org.apache.cocoon.pipeline.component.sax.FileReaderComponent;
 
 public class PipelineTest extends TestCase {
 
     public void testCachingPipelineWithReader() throws Exception {
-        Pipeline pipeline = new CachingPipeline();
+        Pipeline<PipelineComponent> pipeline = new CachingPipeline<PipelineComponent>();
         pipeline.addComponent(new FileReaderComponent(this.getClass().getResource("/test.xml")));
         pipeline.setup(System.out);
         pipeline.execute();
@@ -35,7 +36,7 @@
      * A very simple pipeline that only uses a reader.
      */
     public void testPipelineWithReader() throws Exception {
-        Pipeline pipeline = new NonCachingPipeline();
+        Pipeline<PipelineComponent> pipeline = new NonCachingPipeline<PipelineComponent>();
         pipeline.addComponent(new FileReaderComponent(this.getClass().getResource("/test.xml")));
         pipeline.setup(System.out);
         pipeline.execute();



Mime
View raw message