org.apache.camel.model.RecipientListDefinition Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of camel-core Show documentation
Show all versions of camel-core Show documentation
The Core Camel Java DSL based router
/**
* 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.camel.model;
import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.ExecutorService;
import javax.xml.bind.annotation.XmlAccessType;
import javax.xml.bind.annotation.XmlAccessorType;
import javax.xml.bind.annotation.XmlAttribute;
import javax.xml.bind.annotation.XmlRootElement;
import javax.xml.bind.annotation.XmlTransient;
import org.apache.camel.CamelContextAware;
import org.apache.camel.Expression;
import org.apache.camel.Processor;
import org.apache.camel.model.language.ExpressionDefinition;
import org.apache.camel.processor.EvaluateExpressionProcessor;
import org.apache.camel.processor.Pipeline;
import org.apache.camel.processor.RecipientList;
import org.apache.camel.processor.aggregate.AggregationStrategy;
import org.apache.camel.processor.aggregate.AggregationStrategyBeanAdapter;
import org.apache.camel.processor.aggregate.ShareUnitOfWorkAggregationStrategy;
import org.apache.camel.processor.aggregate.UseLatestAggregationStrategy;
import org.apache.camel.spi.Metadata;
import org.apache.camel.spi.RouteContext;
import org.apache.camel.util.CamelContextHelper;
/**
* Routes messages to a number of dynamically specified recipients (dynamic to)
*
* @version
*/
@Metadata(label = "eip,endpoint,routing")
@XmlRootElement(name = "recipientList")
@XmlAccessorType(XmlAccessType.FIELD)
public class RecipientListDefinition> extends NoOutputExpressionNode implements ExecutorServiceAwareDefinition> {
@XmlTransient
private AggregationStrategy aggregationStrategy;
@XmlTransient
private ExecutorService executorService;
@XmlAttribute @Metadata(defaultValue = ",")
private String delimiter;
@XmlAttribute
private Boolean parallelProcessing;
@XmlAttribute
private String strategyRef;
@XmlAttribute
private String strategyMethodName;
@XmlAttribute
private Boolean strategyMethodAllowNull;
@XmlAttribute
private String executorServiceRef;
@XmlAttribute
private Boolean stopOnException;
@XmlAttribute
private Boolean ignoreInvalidEndpoints;
@XmlAttribute
private Boolean streaming;
@XmlAttribute @Metadata(defaultValue = "0")
private Long timeout;
@XmlAttribute
private String onPrepareRef;
@XmlTransient
private Processor onPrepare;
@XmlAttribute
private Boolean shareUnitOfWork;
@XmlAttribute
private Integer cacheSize;
@XmlAttribute
private Boolean parallelAggregate;
public RecipientListDefinition() {
}
public RecipientListDefinition(ExpressionDefinition expression) {
super(expression);
}
public RecipientListDefinition(Expression expression) {
super(expression);
}
@Override
public String toString() {
return "RecipientList[" + getExpression() + "]";
}
@Override
public String getLabel() {
return "recipientList[" + getExpression() + "]";
}
@Override
public Processor createProcessor(RouteContext routeContext) throws Exception {
final Expression expression = getExpression().createExpression(routeContext);
boolean isParallelProcessing = getParallelProcessing() != null && getParallelProcessing();
boolean isStreaming = getStreaming() != null && getStreaming();
boolean isParallelAggregate = getParallelAggregate() != null && getParallelAggregate();
boolean isShareUnitOfWork = getShareUnitOfWork() != null && getShareUnitOfWork();
boolean isStopOnException = getStopOnException() != null && getStopOnException();
boolean isIgnoreInvalidEndpoints = getIgnoreInvalidEndpoints() != null && getIgnoreInvalidEndpoints();
RecipientList answer;
if (delimiter != null) {
answer = new RecipientList(routeContext.getCamelContext(), expression, delimiter);
} else {
answer = new RecipientList(routeContext.getCamelContext(), expression);
}
answer.setAggregationStrategy(createAggregationStrategy(routeContext));
answer.setParallelProcessing(isParallelProcessing);
answer.setParallelAggregate(isParallelAggregate);
answer.setStreaming(isStreaming);
answer.setShareUnitOfWork(isShareUnitOfWork);
answer.setStopOnException(isStopOnException);
answer.setIgnoreInvalidEndpoints(isIgnoreInvalidEndpoints);
if (getCacheSize() != null) {
answer.setCacheSize(getCacheSize());
}
if (onPrepareRef != null) {
onPrepare = CamelContextHelper.mandatoryLookup(routeContext.getCamelContext(), onPrepareRef, Processor.class);
}
if (onPrepare != null) {
answer.setOnPrepare(onPrepare);
}
if (getTimeout() != null) {
answer.setTimeout(getTimeout());
}
boolean shutdownThreadPool = ProcessorDefinitionHelper.willCreateNewThreadPool(routeContext, this, isParallelProcessing);
ExecutorService threadPool = ProcessorDefinitionHelper.getConfiguredExecutorService(routeContext, "RecipientList", this, isParallelProcessing);
answer.setExecutorService(threadPool);
answer.setShutdownExecutorService(shutdownThreadPool);
long timeout = getTimeout() != null ? getTimeout() : 0;
if (timeout > 0 && !isParallelProcessing) {
throw new IllegalArgumentException("Timeout is used but ParallelProcessing has not been enabled.");
}
// create a pipeline with two processors
// the first is the eval processor which evaluates the expression to use
// the second is the recipient list
List pipe = new ArrayList(2);
// the eval processor must be wrapped in error handler, so in case there was an
// error during evaluation, the error handler can deal with it
// the recipient list is not in error handler, as its has its own special error handling
// when sending to the recipients individually
Processor evalProcessor = new EvaluateExpressionProcessor(expression);
evalProcessor = super.wrapInErrorHandler(routeContext, evalProcessor);
pipe.add(evalProcessor);
pipe.add(answer);
// wrap in nested pipeline so this appears as one processor
// (threads definition does this as well)
return new Pipeline(routeContext.getCamelContext(), pipe) {
@Override
public String toString() {
return "RecipientList[" + expression + "]";
}
};
}
private AggregationStrategy createAggregationStrategy(RouteContext routeContext) {
AggregationStrategy strategy = getAggregationStrategy();
if (strategy == null && strategyRef != null) {
Object aggStrategy = routeContext.lookup(strategyRef, Object.class);
if (aggStrategy instanceof AggregationStrategy) {
strategy = (AggregationStrategy) aggStrategy;
} else if (aggStrategy != null) {
AggregationStrategyBeanAdapter adapter = new AggregationStrategyBeanAdapter(aggStrategy, getStrategyMethodName());
if (getStrategyMethodAllowNull() != null) {
adapter.setAllowNullNewExchange(getStrategyMethodAllowNull());
adapter.setAllowNullOldExchange(getStrategyMethodAllowNull());
}
strategy = adapter;
} else {
throw new IllegalArgumentException("Cannot find AggregationStrategy in Registry with name: " + strategyRef);
}
}
if (strategy == null) {
// default to use latest aggregation strategy
strategy = new UseLatestAggregationStrategy();
}
if (strategy instanceof CamelContextAware) {
((CamelContextAware) strategy).setCamelContext(routeContext.getCamelContext());
}
if (shareUnitOfWork != null && shareUnitOfWork) {
// wrap strategy in share unit of work
strategy = new ShareUnitOfWorkAggregationStrategy(strategy);
}
return strategy;
}
// Fluent API
// -------------------------------------------------------------------------
@Override
@SuppressWarnings("unchecked")
public Type end() {
// allow end() to return to previous type so you can continue in the DSL
return (Type) super.end();
}
/**
* Delimiter used if the Expression returned multiple endpoints. Can be turned off using the value false.
*
* The default value is ,
*
* @param delimiter the delimiter
* @return the builder
*/
public RecipientListDefinition delimiter(String delimiter) {
setDelimiter(delimiter);
return this;
}
/**
* Sets the AggregationStrategy to be used to assemble the replies from the recipients, into a single outgoing message from the RecipientList.
* By default Camel will use the last reply as the outgoing message. You can also use a POJO as the AggregationStrategy
*/
public RecipientListDefinition aggregationStrategy(AggregationStrategy aggregationStrategy) {
setAggregationStrategy(aggregationStrategy);
return this;
}
/**
* Sets a reference to the AggregationStrategy to be used to assemble the replies from the recipients, into a single outgoing message from the RecipientList.
* By default Camel will use the last reply as the outgoing message. You can also use a POJO as the AggregationStrategy
*/
public RecipientListDefinition aggregationStrategyRef(String aggregationStrategyRef) {
setStrategyRef(aggregationStrategyRef);
return this;
}
/**
* This option can be used to explicit declare the method name to use, when using POJOs as the AggregationStrategy.
*
* @param methodName the method name to call
* @return the builder
*/
public RecipientListDefinition aggregationStrategyMethodName(String methodName) {
setStrategyMethodName(methodName);
return this;
}
/**
* If this option is false then the aggregate method is not used if there was no data to enrich.
* If this option is true then null values is used as the oldExchange (when no data to enrich), when using POJOs as the AggregationStrategy
*
* @return the builder
*/
public RecipientListDefinition aggregationStrategyMethodAllowNull() {
setStrategyMethodAllowNull(true);
return this;
}
/**
* Ignore the invalidate endpoint exception when try to create a producer with that endpoint
*
* @return the builder
*/
public RecipientListDefinition ignoreInvalidEndpoints() {
setIgnoreInvalidEndpoints(true);
return this;
}
/**
* If enabled then sending messages to the recipients occurs concurrently.
* Note the caller thread will still wait until all messages has been fully processed, before it continues.
* Its only the sending and processing the replies from the recipients which happens concurrently.
*
* @return the builder
*/
public RecipientListDefinition parallelProcessing() {
setParallelProcessing(true);
return this;
}
/**
* If enabled then sending messages to the recipients occurs concurrently.
* Note the caller thread will still wait until all messages has been fully processed, before it continues.
* Its only the sending and processing the replies from the recipients which happens concurrently.
*
* @return the builder
*/
public RecipientListDefinition parallelProcessing(boolean parallelProcessing) {
setParallelProcessing(parallelProcessing);
return this;
}
/**
* If enabled then the aggregate method on AggregationStrategy can be called concurrently.
* Notice that this would require the implementation of AggregationStrategy to be implemented as thread-safe.
* By default this is false meaning that Camel synchronizes the call to the aggregate method.
* Though in some use-cases this can be used to archive higher performance when the AggregationStrategy is implemented as thread-safe.
*
* @return the builder
*/
public RecipientListDefinition parallelAggregate() {
setParallelAggregate(true);
return this;
}
/**
* If enabled then Camel will process replies out-of-order, eg in the order they come back.
* If disabled, Camel will process replies in the same order as defined by the recipient list.
*
* @return the builder
*/
public RecipientListDefinition streaming() {
setStreaming(true);
return this;
}
/**
* Will now stop further processing if an exception or failure occurred during processing of an
* {@link org.apache.camel.Exchange} and the caused exception will be thrown.
*
* Will also stop if processing the exchange failed (has a fault message) or an exception
* was thrown and handled by the error handler (such as using onException). In all situations
* the recipient list will stop further processing. This is the same behavior as in pipeline, which
* is used by the routing engine.
*
* The default behavior is to not stop but continue processing till the end
*
* @return the builder
*/
public RecipientListDefinition stopOnException() {
setStopOnException(true);
return this;
}
/**
* To use a custom Thread Pool to be used for parallel processing.
* Notice if you set this option, then parallel processing is automatic implied, and you do not have to enable that option as well.
*/
public RecipientListDefinition executorService(ExecutorService executorService) {
setExecutorService(executorService);
return this;
}
/**
* Refers to a custom Thread Pool to be used for parallel processing.
* Notice if you set this option, then parallel processing is automatic implied, and you do not have to enable that option as well.
*/
public RecipientListDefinition executorServiceRef(String executorServiceRef) {
setExecutorServiceRef(executorServiceRef);
return this;
}
/**
* Uses the {@link Processor} when preparing the {@link org.apache.camel.Exchange} to be used send.
* This can be used to deep-clone messages that should be send, or any custom logic needed before
* the exchange is send.
*
* @param onPrepare the processor
* @return the builder
*/
public RecipientListDefinition onPrepare(Processor onPrepare) {
setOnPrepare(onPrepare);
return this;
}
/**
* Uses the {@link Processor} when preparing the {@link org.apache.camel.Exchange} to be send.
* This can be used to deep-clone messages that should be send, or any custom logic needed before
* the exchange is send.
*
* @param onPrepareRef reference to the processor to lookup in the {@link org.apache.camel.spi.Registry}
* @return the builder
*/
public RecipientListDefinition onPrepareRef(String onPrepareRef) {
setOnPrepareRef(onPrepareRef);
return this;
}
/**
* Sets a total timeout specified in millis, when using parallel processing.
* If the Recipient List hasn't been able to send and process all replies within the given timeframe,
* then the timeout triggers and the Recipient List breaks out and continues.
* Notice if you provide a TimeoutAwareAggregationStrategy then the timeout method is invoked before breaking out.
* If the timeout is reached with running tasks still remaining, certain tasks for which it is difficult for Camel
* to shut down in a graceful manner may continue to run. So use this option with a bit of care.
*
* @param timeout timeout in millis
* @return the builder
*/
public RecipientListDefinition timeout(long timeout) {
setTimeout(timeout);
return this;
}
/**
* Shares the {@link org.apache.camel.spi.UnitOfWork} with the parent and each of the sub messages.
* Recipient List will by default not share unit of work between the parent exchange and each recipient exchange.
* This means each sub exchange has its own individual unit of work.
*
* @return the builder.
* @see org.apache.camel.spi.SubUnitOfWork
*/
public RecipientListDefinition shareUnitOfWork() {
setShareUnitOfWork(true);
return this;
}
/**
* Sets the maximum size used by the {@link org.apache.camel.impl.ProducerCache} which is used
* to cache and reuse producers when using this recipient list, when uris are reused.
*
* @param cacheSize the cache size, use 0 for default cache size, or -1 to turn cache off.
* @return the builder
*/
public RecipientListDefinition cacheSize(int cacheSize) {
setCacheSize(cacheSize);
return this;
}
// Properties
//-------------------------------------------------------------------------
/**
* Expression that returns which endpoints (url) to send the message to (the recipients).
* If the expression return an empty value then the message is not sent to any recipients.
*/
@Override
public void setExpression(ExpressionDefinition expression) {
// override to include javadoc what the expression is used for
super.setExpression(expression);
}
public String getDelimiter() {
return delimiter;
}
public void setDelimiter(String delimiter) {
this.delimiter = delimiter;
}
public Boolean getParallelProcessing() {
return parallelProcessing;
}
public void setParallelProcessing(Boolean parallelProcessing) {
this.parallelProcessing = parallelProcessing;
}
public String getStrategyRef() {
return strategyRef;
}
/**
* Sets a reference to the AggregationStrategy to be used to assemble the replies from the recipients, into a single outgoing message from the RecipientList.
* By default Camel will use the last reply as the outgoing message. You can also use a POJO as the AggregationStrategy
*/
public void setStrategyRef(String strategyRef) {
this.strategyRef = strategyRef;
}
public String getStrategyMethodName() {
return strategyMethodName;
}
/**
* This option can be used to explicit declare the method name to use, when using POJOs as the AggregationStrategy.
*/
public void setStrategyMethodName(String strategyMethodName) {
this.strategyMethodName = strategyMethodName;
}
public Boolean getStrategyMethodAllowNull() {
return strategyMethodAllowNull;
}
/**
* If this option is false then the aggregate method is not used if there was no data to enrich.
* If this option is true then null values is used as the oldExchange (when no data to enrich), when using POJOs as the AggregationStrategy
*/
public void setStrategyMethodAllowNull(Boolean strategyMethodAllowNull) {
this.strategyMethodAllowNull = strategyMethodAllowNull;
}
public String getExecutorServiceRef() {
return executorServiceRef;
}
public void setExecutorServiceRef(String executorServiceRef) {
this.executorServiceRef = executorServiceRef;
}
public Boolean getIgnoreInvalidEndpoints() {
return ignoreInvalidEndpoints;
}
public void setIgnoreInvalidEndpoints(Boolean ignoreInvalidEndpoints) {
this.ignoreInvalidEndpoints = ignoreInvalidEndpoints;
}
public Boolean getStopOnException() {
return stopOnException;
}
public void setStopOnException(Boolean stopOnException) {
this.stopOnException = stopOnException;
}
public AggregationStrategy getAggregationStrategy() {
return aggregationStrategy;
}
/**
* Sets the AggregationStrategy to be used to assemble the replies from the recipients, into a single outgoing message from the RecipientList.
* By default Camel will use the last reply as the outgoing message. You can also use a POJO as the AggregationStrategy
*/
public void setAggregationStrategy(AggregationStrategy aggregationStrategy) {
this.aggregationStrategy = aggregationStrategy;
}
public ExecutorService getExecutorService() {
return executorService;
}
public void setExecutorService(ExecutorService executorService) {
this.executorService = executorService;
}
public Boolean getStreaming() {
return streaming;
}
public void setStreaming(Boolean streaming) {
this.streaming = streaming;
}
public Long getTimeout() {
return timeout;
}
public void setTimeout(Long timeout) {
this.timeout = timeout;
}
public String getOnPrepareRef() {
return onPrepareRef;
}
public void setOnPrepareRef(String onPrepareRef) {
this.onPrepareRef = onPrepareRef;
}
public Processor getOnPrepare() {
return onPrepare;
}
public void setOnPrepare(Processor onPrepare) {
this.onPrepare = onPrepare;
}
public Boolean getShareUnitOfWork() {
return shareUnitOfWork;
}
public void setShareUnitOfWork(Boolean shareUnitOfWork) {
this.shareUnitOfWork = shareUnitOfWork;
}
public Integer getCacheSize() {
return cacheSize;
}
public void setCacheSize(Integer cacheSize) {
this.cacheSize = cacheSize;
}
public Boolean getParallelAggregate() {
return parallelAggregate;
}
public void setParallelAggregate(Boolean parallelAggregate) {
this.parallelAggregate = parallelAggregate;
}
}