001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017: package org.apache.cocoon.components.pipeline;
018:
019: import org.apache.avalon.framework.component.Component;
020: import org.apache.avalon.framework.component.Recomposable;
021: import org.apache.avalon.framework.parameters.Parameters;
022:
023: import org.apache.cocoon.ProcessingException;
024: import org.apache.cocoon.sitemap.SitemapErrorHandler;
025: import org.apache.cocoon.environment.Environment;
026: import org.apache.cocoon.generation.Generator;
027: import org.apache.cocoon.xml.XMLConsumer;
028:
029: import org.apache.excalibur.source.SourceValidity;
030:
031: /**
032: * A <code>ProcessingPipeline<code> produces the response for a given request.
033: * It is assembled according to the commands in the sitemap and can either
034: * <ul>
035: * <li>Collect a <code>Reader</code> and let it produce a byte stream,</li>
036: * <li>Or connect a <code>Generator</code> with zero or more
037: * <code>Transformer</code>s and a <code>Serializer</code>, and let them
038: * produce the byte stream. This pipeline uses SAX events for
039: * communication.
040: * </li>
041: * </ul>
042: *
043: * <p>A <code>ProcessingPipeline</code> is <code>Recomposable</code> since the
044: * <code>ComponentManager</code> used to get the generator, transformers, etc.
045: * depends on the pipeline assembly engine where they are defined (i.e. a given
046: * sitemap file).
047: *
048: * @author <a href="mailto:cziegeler@apache.org">Carsten Ziegeler</a>
049: * @author <a href="mailto:Giacomo.Pati@pwr.ch">Giacomo Pati</a>
050: * @version $Id: ProcessingPipeline.java 433543 2006-08-22 06:22:54Z crossley $
051: */
052: public interface ProcessingPipeline extends Component, Recomposable {
053:
054: String ROLE = ProcessingPipeline.class.getName();
055:
056: /**
057: * Setup this component.
058: */
059: void setup(Parameters params);
060:
061: /**
062: * Release this component.
063: * If you get an instance not by a component manager but for example
064: * by a processor, you have to release this component by calling
065: * this method and NOT by using a component manager!
066: */
067: void release();
068:
069: /**
070: * Set the generator that will be used as the initial step in the pipeline.
071: * The generator role is given : the actual <code>Generator</code> is fetched
072: * from the latest <code>ComponentManager</code> given by <code>compose()</code>
073: * or <code>recompose()</code>.
074: *
075: * @param role the generator role in the component manager.
076: * @param source the source where to produce XML from, or <code>null</code> if no
077: * source is given.
078: * @param param the parameters for the generator.
079: * @throws ProcessingException if the generator couldn't be obtained.
080: */
081: void setGenerator(String role, String source, Parameters param,
082: Parameters hintParam) throws ProcessingException;
083:
084: /**
085: * Get the generator - used for content aggregation
086: */
087: Generator getGenerator();
088:
089: /**
090: * Informs pipeline we have come across a branch point
091: */
092: void informBranchPoint();
093:
094: /**
095: * Add a transformer at the end of the pipeline.
096: * The transformer role is given : the actual <code>Transformer</code> is fetched
097: * from the latest <code>ComponentManager</code> given by <code>compose()</code>
098: * or <code>recompose()</code>.
099: *
100: * @param role the transformer role in the component manager.
101: * @param source the source used to setup the transformer (e.g. XSL file), or
102: * <code>null</code> if no source is given.
103: * @param param the parameters for the transfomer.
104: * @throws ProcessingException if the generator couldn't be obtained.
105: */
106: void addTransformer(String role, String source, Parameters param,
107: Parameters hintParam) throws ProcessingException;
108:
109: /**
110: * Set the serializer for this pipeline
111: * @param mimeType Can be null
112: */
113: void setSerializer(String role, String source, Parameters param,
114: Parameters hintParam, String mimeType)
115: throws ProcessingException;
116:
117: /**
118: * Set the reader for this pipeline
119: * @param mimeType Can be null
120: */
121: void setReader(String role, String source, Parameters param,
122: String mimeType) throws ProcessingException;
123:
124: /**
125: * Sets error handler for this pipeline.
126: * Used for handling errors in the internal pipelines.
127: */
128: void setErrorHandler(SitemapErrorHandler errorHandler)
129: throws ProcessingException;
130:
131: /**
132: * Process the given <code>Environment</code>, producing the output.
133: */
134: boolean process(Environment environment) throws ProcessingException;
135:
136: /**
137: * Prepare an internal processing
138: * @param environment The current environment.
139: * @throws ProcessingException
140: */
141: void prepareInternal(Environment environment)
142: throws ProcessingException;
143:
144: /**
145: * Process the given <code>Environment</code>, but do not use the
146: * serializer. Instead the sax events are streamed to the XMLConsumer.
147: * Make sure to call {@link #prepareInternal(Environment)} beforehand.
148: */
149: boolean process(Environment environment, XMLConsumer consumer)
150: throws ProcessingException;
151:
152: /**
153: * Return valid validity objects for the event pipeline
154: * If the "event pipeline" (= the complete pipeline without the
155: * serializer) is cacheable and valid, return all validity objects.
156: * Otherwise return <code>null</code>
157: */
158: SourceValidity getValidityForEventPipeline();
159:
160: /**
161: * Return the key for the event pipeline
162: * If the "event pipeline" (= the complete pipeline without the
163: * serializer) is cacheable and valid, return a key.
164: * Otherwise return <code>null</code>
165: */
166: String getKeyForEventPipeline();
167: }
|