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 */
017package org.apache.camel.spi;
018
019import java.util.Map;
020
021import org.apache.camel.CamelContext;
022import org.apache.camel.NamedNode;
023import org.apache.camel.Processor;
024
025/**
026 * A factory to create {@link Processor} based on the {@link org.apache.camel.model.ProcessorDefinition definition}.
027 * <p/>
028 * This allows you to implement a custom factory in which you can control the creation of the processors.
029 * It also allows you to manipulate the {@link org.apache.camel.model.ProcessorDefinition definition}s for example to
030 * configure or change options. Its also possible to add new steps in the route by adding outputs to
031 * {@link org.apache.camel.model.ProcessorDefinition definition}s.
032 * <p/>
033 * <b>Important:</b> By returning <tt>null</tt> from the create methods you fallback to let the default implementation in Camel create
034 * the {@link Processor}. You want to do this if you <i>only</i> want to manipulate the
035 * {@link org.apache.camel.model.ProcessorDefinition definition}s.
036 */
037public interface ProcessorFactory {
038
039    /**
040     * Creates the child processor.
041     * <p/>
042     * The child processor is an output from the given definition, for example the sub route in a splitter EIP.
043     *
044     * @param routeContext  the route context
045     * @param definition    the definition which represents the processor
046     * @param mandatory     whether or not the child is mandatory
047     * @return the created processor, or <tt>null</tt> to let the default implementation in Camel create the processor.
048     * @throws Exception can be thrown if error creating the processor
049     */
050    Processor createChildProcessor(RouteContext routeContext, NamedNode definition, boolean mandatory) throws Exception;
051
052    /**
053     * Creates the processor.
054     *
055     * @param routeContext  the route context
056     * @param definition    the definition which represents the processor
057     * @return the created processor, or <tt>null</tt> to let the default implementation in Camel create the processor.
058     * @throws Exception can be thrown if error creating the processor
059     */
060    Processor createProcessor(RouteContext routeContext, NamedNode definition) throws Exception;
061
062    /**
063     * Creates a processor by the name of the definition. This should only be used in some special situations
064     * where the processor is used internally in some features such as camel-cloud.
065     *
066     * @param camelContext     the camel context
067     * @param definitionName   the name of the definition that represents the processor
068     * @param args             arguments for creating the processor (name=vale pairs)
069     * @return the created processor, or <tt>null</tt> if this situation is not yet implemented.
070     * @throws Exception can be thrown if error creating the processor
071     */
072    Processor createProcessor(CamelContext camelContext, String definitionName, Map<String, Object> args) throws Exception;
073
074}