KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > cocoon > components > pipeline > ProcessingPipeline


1 /*
2  * Copyright 1999-2005 The Apache Software Foundation.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 package org.apache.cocoon.components.pipeline;
17
18 import org.apache.avalon.framework.component.Component;
19 import org.apache.avalon.framework.component.Recomposable;
20 import org.apache.avalon.framework.parameters.Parameters;
21
22 import org.apache.cocoon.ProcessingException;
23 import org.apache.cocoon.sitemap.SitemapErrorHandler;
24 import org.apache.cocoon.environment.Environment;
25 import org.apache.cocoon.generation.Generator;
26 import org.apache.cocoon.xml.XMLConsumer;
27
28 import org.apache.excalibur.source.SourceValidity;
29
30 /**
31  * A <code>ProcessingPipeline<code> produces the response for a given request.
32  * It is assembled according to the commands in the sitemap and can either
33  * <ul>
34  * <li>Collect a <code>Reader</code> and let it produce a byte stream,</li>
35  * <li>Or connect a <code>Generator</code> with zero or more
36  * <code>Transformer</code>s and a <code>Serializer</code>, and let them
37  * produce the byte stream. This pipeline uses SAX events for
38  * communication.
39  * </li>
40  * </ul>
41  *
42  * <p>A <code>ProcessingPipeline</code> is <code>Recomposable</code> since the
43  * <code>ComponentManager</code> used to get the generator, transformers, etc.
44  * depends on the pipeline assembly engine where they are defined (i.e. a given
45  * sitemap file).
46  *
47  * @author <a HREF="mailto:cziegeler@apache.org">Carsten Ziegeler</a>
48  * @author <a HREF="mailto:Giacomo.Pati@pwr.ch">Giacomo Pati</a>
49  * @version $Id: ProcessingPipeline.java 157541 2005-03-15 14:26:31Z vgritsenko $
50  */
51 public interface ProcessingPipeline extends Component, Recomposable {
52
53     String JavaDoc ROLE = ProcessingPipeline.class.getName();
54
55     /**
56      * Setup this component.
57      */
58     void setup(Parameters params);
59
60     /**
61      * Release this component.
62      * If you get an instance not by a component manager but for example
63      * by a processor, you have to release this component by calling
64      * this method and NOT by using a component manager!
65      */
66     void release();
67
68     /**
69      * Set the generator that will be used as the initial step in the pipeline.
70      * The generator role is given : the actual <code>Generator</code> is fetched
71      * from the latest <code>ComponentManager</code> given by <code>compose()</code>
72      * or <code>recompose()</code>.
73      *
74      * @param role the generator role in the component manager.
75      * @param source the source where to produce XML from, or <code>null</code> if no
76      * source is given.
77      * @param param the parameters for the generator.
78      * @throws ProcessingException if the generator couldn't be obtained.
79      */
80     void setGenerator(String JavaDoc role, String JavaDoc source, Parameters param, Parameters hintParam)
81     throws ProcessingException;
82
83     /**
84      * Get the generator - used for content aggregation
85      */
86     Generator getGenerator();
87
88     /**
89      * Informs pipeline we have come across a branch point
90      */
91     void informBranchPoint();
92
93     /**
94      * Add a transformer at the end of the pipeline.
95      * The transformer role is given : the actual <code>Transformer</code> is fetched
96      * from the latest <code>ComponentManager</code> given by <code>compose()</code>
97      * or <code>recompose()</code>.
98      *
99      * @param role the transformer role in the component manager.
100      * @param source the source used to setup the transformer (e.g. XSL file), or
101      * <code>null</code> if no source is given.
102      * @param param the parameters for the transfomer.
103      * @throws ProcessingException if the generator couldn't be obtained.
104      */
105     void addTransformer(String JavaDoc role, String JavaDoc source, Parameters param, Parameters hintParam)
106     throws ProcessingException;
107
108     /**
109      * Set the serializer for this pipeline
110      * @param mimeType Can be null
111      */
112     void setSerializer(String JavaDoc role, String JavaDoc source, Parameters param, Parameters hintParam, String JavaDoc mimeType)
113     throws ProcessingException;
114
115     /**
116      * Set the reader for this pipeline
117      * @param mimeType Can be null
118      */
119     void setReader(String JavaDoc role, String JavaDoc source, Parameters param, String JavaDoc mimeType)
120     throws ProcessingException;
121
122     /**
123      * Sets error handler for this pipeline.
124      * Used for handling errors in the internal pipelines.
125      */
126     void setErrorHandler(SitemapErrorHandler errorHandler)
127     throws ProcessingException;
128
129     /**
130      * Process the given <code>Environment</code>, producing the output.
131      */
132     boolean process(Environment environment)
133     throws ProcessingException;
134
135     /**
136      * Prepare an internal processing
137      * @param environment The current environment.
138      * @throws ProcessingException
139      */
140     void prepareInternal(Environment environment)
141     throws ProcessingException;
142
143     /**
144      * Process the given <code>Environment</code>, but do not use the
145      * serializer. Instead the sax events are streamed to the XMLConsumer.
146      * Make sure to call {@link #prepareInternal(Environment)} beforehand.
147      */
148     boolean process(Environment environment, XMLConsumer consumer)
149     throws ProcessingException;
150
151     /**
152      * Return valid validity objects for the event pipeline
153      * If the "event pipeline" (= the complete pipeline without the
154      * serializer) is cacheable and valid, return all validity objects.
155      * Otherwise return <code>null</code>
156      */
157     SourceValidity getValidityForEventPipeline();
158
159     /**
160      * Return the key for the event pipeline
161      * If the "event pipeline" (= the complete pipeline without the
162      * serializer) is cacheable and valid, return a key.
163      * Otherwise return <code>null</code>
164      */
165     String JavaDoc getKeyForEventPipeline();
166 }
167
Popular Tags