/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.cocoon.components.pipeline;
import org.apache.avalon.framework.component.Component;
import org.apache.avalon.framework.component.Recomposable;
import org.apache.avalon.framework.parameters.Parameters;
import org.apache.cocoon.ProcessingException;
import org.apache.cocoon.sitemap.SitemapErrorHandler;
import org.apache.cocoon.environment.Environment;
import org.apache.cocoon.generation.Generator;
import org.apache.cocoon.xml.XMLConsumer;
import org.apache.excalibur.source.SourceValidity;
/**
* A <code>ProcessingPipeline<code> produces the response for a given request.
* It is assembled according to the commands in the sitemap and can either
* <ul>
* <li>Collect a <code>Reader</code> and let it produce a byte stream,</li>
* <li>Or connect a <code>Generator</code> with zero or more
* <code>Transformer</code>s and a <code>Serializer</code>, and let them
* produce the byte stream. This pipeline uses SAX events for
* communication.
* </li>
* </ul>
*
* <p>A <code>ProcessingPipeline</code> is <code>Recomposable</code> since the
* <code>ComponentManager</code> used to get the generator, transformers, etc.
* depends on the pipeline assembly engine where they are defined (i.e. a given
* sitemap file).
*
* @author <a href="mailto:cziegeler@apache.org">Carsten Ziegeler</a>
* @author <a href="mailto:Giacomo.Pati@pwr.ch">Giacomo Pati</a>
* @version $Id$
*/
public interface ProcessingPipeline extends Component, Recomposable {
String ROLE = ProcessingPipeline.class.getName();
/**
* Setup this component.
*/
void setup(Parameters params);
/**
* Release this component.
* If you get an instance not by a component manager but for example
* by a processor, you have to release this component by calling
* this method and NOT by using a component manager!
*/
void release();
/**
* Set the generator that will be used as the initial step in the pipeline.
* The generator role is given : the actual <code>Generator</code> is fetched
* from the latest <code>ComponentManager</code> given by <code>compose()</code>
* or <code>recompose()</code>.
*
* @param role the generator role in the component manager.
* @param source the source where to produce XML from, or <code>null</code> if no
* source is given.
* @param param the parameters for the generator.
* @throws ProcessingException if the generator couldn't be obtained.
*/
void setGenerator(String role, String source, Parameters param, Parameters hintParam)
throws ProcessingException;
/**
* Get the generator - used for content aggregation
*/
Generator getGenerator();
/**
* Informs pipeline we have come across a branch point
*/
void informBranchPoint();
/**
* Add a transformer at the end of the pipeline.
* The transformer role is given : the actual <code>Transformer</code> is fetched
* from the latest <code>ComponentManager</code> given by <code>compose()</code>
* or <code>recompose()</code>.
*
* @param role the transformer role in the component manager.
* @param source the source used to setup the transformer (e.g. XSL file), or
* <code>null</code> if no source is given.
* @param param the parameters for the transfomer.
* @throws ProcessingException if the generator couldn't be obtained.
*/
void addTransformer(String role, String source, Parameters param, Parameters hintParam)
throws ProcessingException;
/**
* Set the serializer for this pipeline
* @param mimeType Can be null
*/
void setSerializer(String role, String source, Parameters param, Parameters hintParam, String mimeType)
throws ProcessingException;
/**
* Set the reader for this pipeline
* @param mimeType Can be null
*/
void setReader(String role, String source, Parameters param, String mimeType)
throws ProcessingException;
/**
* Sets error handler for this pipeline.
* Used for handling errors in the internal pipelines.
*/
void setErrorHandler(SitemapErrorHandler errorHandler)
throws ProcessingException;
/**
* Process the given <code>Environment</code>, producing the output.
*/
boolean process(Environment environment)
throws ProcessingException;
/**
* Prepare an internal processing
* @param environment The current environment.
* @throws ProcessingException
*/
void prepareInternal(Environment environment)
throws ProcessingException;
/**
* Process the given <code>Environment</code>, but do not use the
* serializer. Instead the sax events are streamed to the XMLConsumer.
* Make sure to call {@link #prepareInternal(Environment)} beforehand.
*/
boolean process(Environment environment, XMLConsumer consumer)
throws ProcessingException;
/**
* Return valid validity objects for the event pipeline
* If the "event pipeline" (= the complete pipeline without the
* serializer) is cacheable and valid, return all validity objects.
* Otherwise return <code>null</code>
*/
SourceValidity getValidityForEventPipeline();
/**
* Return the key for the event pipeline
* If the "event pipeline" (= the complete pipeline without the
* serializer) is cacheable and valid, return a key.
* Otherwise return <code>null</code>
*/
String getKeyForEventPipeline();
}