org.apache.camel.FluentProducerTemplate Maven / Gradle / Ivy
The newest version!
/*
* 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;
import java.util.Map;
import java.util.concurrent.Future;
import java.util.function.Supplier;
import org.apache.camel.util.ObjectHelper;
/**
* Template for working with Camel and sending {@link Message} instances in an {@link Exchange} to an {@link Endpoint}
* using a fluent build style.
*
* Important: Read the javadoc of each method carefully to ensure the behavior of the method is understood. Some
* methods is for InOnly, others for InOut MEP. And some methods throws
* {@link org.apache.camel.CamelExecutionException} while others stores any thrown exception on the returned
* {@link Exchange}.
*
* The {@link FluentProducerTemplate} is thread safe with the assumption that its the same (single) thread that
* builds the message (via the fluent methods) that also sends the message.
*
* When using the fluent template its required to chain the methods such as:
*
*
* FluentProducerTemplate fluent = ...
* fluent.withHeader("foo", 123).withHeader("bar", 456).withBody("Hello World").to("kafka:cheese").send();
*
*
* The following code is wrong (do not do this)
*
*
* FluentProducerTemplate fluent = ...
* fluent.withHeader("foo", 123);
* fluent.withHeader("bar", 456);
* fluent.withBody("Hello World");
* fluent.to("kafka:cheese");
* fluent.send();
*
*
* If you do not want to chain fluent methods you can do as follows:
*
*
* FluentProducerTemplate fluent = ...
* fluent = fluent.withHeader("foo", 123);
* fluent = fluent.withHeader("bar", 456);
* fluent = fluent.withBody("Hello World");
* fluent = fluent.to("kafka:cheese")
* fluent.send();
*
*
* You can either only use either withExchange, or withProcessor or a combination of withBody/withHeaders to construct
* the message to be sent.
*
* All the methods which sends a message may throw {@link FailedToCreateProducerException} in case the {@link Producer}
* could not be created. Or a {@link NoSuchEndpointException} if the endpoint could not be resolved. There may be other
* related exceptions being thrown which occurs before the {@link Producer} has started sending the message.
*
* All the send or request methods will return the content according to this strategy:
*
* - throws {@link org.apache.camel.CamelExecutionException} if processing failed during routing with the
* caused exception wrapped
* - The fault.body if there is a fault message set and its not null
* - Either IN or OUT body according to the message exchange pattern. If the pattern is Out capable
* then the OUT body is returned, otherwise IN.
*
*
*
* Before using the template it must be started. And when you are done using the template, make sure to {@link #stop()}
* the template.
*
* Important note on usage: See this
* FAQ entry before
* using.
*
* @see ProducerTemplate
* @see ConsumerTemplate
*/
public interface FluentProducerTemplate extends Service {
/**
* Get the {@link CamelContext}
*
* @return camelContext the Camel context
*/
CamelContext getCamelContext();
// Configuration methods
// -----------------------------------------------------------------------
/**
* Gets the maximum cache size used in the backing cache pools.
*
* @return the maximum cache size
*/
int getMaximumCacheSize();
/**
* Sets a custom maximum cache size to use in the backing cache pools.
*
* @param maximumCacheSize the custom maximum cache size
*/
void setMaximumCacheSize(int maximumCacheSize);
/**
* Gets an approximated size of the current cached resources in the backing cache pools.
*
* @return the size of current cached resources
*/
int getCurrentCacheSize();
/**
* Get the default endpoint to use if none is specified
*
* @return the default endpoint instance
*/
Endpoint getDefaultEndpoint();
/**
* Sets the default endpoint to use if none is specified
*
* @param defaultEndpoint the default endpoint instance
*/
void setDefaultEndpoint(Endpoint defaultEndpoint);
/**
* Sets the default endpoint uri to use if none is specified
*
* @param endpointUri the default endpoint uri
*/
void setDefaultEndpointUri(String endpointUri);
/**
* Sets whether the {@link org.apache.camel.spi.EventNotifier} should be used by this {@link ProducerTemplate} to
* send events about the {@link Exchange} being sent.
*
* By default this is enabled.
*
* @param enabled true to enable, false to disable.
*/
void setEventNotifierEnabled(boolean enabled);
/**
* Whether the {@link org.apache.camel.spi.EventNotifier} should be used by this {@link ProducerTemplate} to send
* events about the {@link Exchange} being sent.
*
* @return true if enabled, false otherwise
*/
boolean isEventNotifierEnabled();
/**
* Cleanup the cache (purging stale entries)
*/
void cleanUp();
// Fluent methods
// -----------------------------------------------------------------------
/**
* Set the headers
*
* Important: You can either only use either withExchange, or withProcessor or a combination of
* withBody/withHeaders to construct the message to be sent.
*
* @param headers the headers
*/
FluentProducerTemplate withHeaders(Map headers);
/**
* Set the header
*
* Important: You can either only use either withExchange, or withProcessor or a combination of
* withBody/withHeaders to construct the message to be sent.
*
* @param key the key of the header
* @param value the value of the header
*/
FluentProducerTemplate withHeader(String key, Object value);
/**
* Set the exchange properties
*
* Important: You can either only use either withExchange, or withProcessor or a combination of
* withBody/withHeaders to construct the message to be sent.
*
* @param properties the exchange properties
*/
FluentProducerTemplate withExchangeProperties(Map properties);
/**
* Set the exchange property
*
* Important: You can either only use either withExchange, or withProcessor or a combination of
* withBody/withHeaders to construct the message to be sent.
*
* @param key the key of the exchange property
* @param value the value of the exchange property
*/
FluentProducerTemplate withExchangeProperty(String key, Object value);
/**
* Set the variables
*
* Important: You can either only use either withExchange, or withProcessor or a combination of
* withBody/withHeaders to construct the message to be sent.
*
* @param variables the variables
*/
FluentProducerTemplate withVariables(Map variables);
/**
* Set the exchange property
*
* Important: You can either only use either withExchange, or withProcessor or a combination of
* withBody/withHeaders to construct the message to be sent.
*
* @param key the key of the variable
* @param value the value of the variable
*/
FluentProducerTemplate withVariable(String key, Object value);
/**
* Set the message body
*
* Important: You can either only use either withExchange, or withProcessor or a combination of
* withBody/withHeaders to construct the message to be sent.
*
* @param body the body
*/
FluentProducerTemplate withBody(Object body);
/**
* Set the message body after converting it to the given type
*
* Important: You can either only use either withExchange, or withProcessor or a combination of
* withBody/withHeaders to construct the message to be sent.
*
* @param body the body
* @param type the type which the body should be converted to
*/
FluentProducerTemplate withBodyAs(Object body, Class type);
/**
* To customize the producer template for advanced usage like to set the executor service to use.
*
*
* {@code
* FluentProducerTemplate fluent = context.createFluentProducerTemplate();
* fluent.withTemplateCustomizer(
* t -> {
* t.setExecutorService(myExecutor);
* t.setMaximumCacheSize(10);
* }
* )
* .withBody("the body")
* .to("direct:start")
* .send()}
*
*
* Note that it is invoked only once.
*
* @param templateCustomizer the customizer
*/
FluentProducerTemplate withTemplateCustomizer(java.util.function.Consumer templateCustomizer);
/**
* Set the exchange to use for send.
*
* When using withExchange then you must use the send method (request is not supported).
*
* Important: You can either only use either withExchange, or withProcessor or a combination of
* withBody/withHeaders to construct the message to be sent.
*
* @param exchange the exchange
*/
FluentProducerTemplate withExchange(Exchange exchange);
/**
* Set the exchangeSupplier which will be invoke to get the exchange to be used for send.
*
* When using withExchange then you must use the send method (request is not supported).
*
* Important: You can either only use either withExchange, or withProcessor or a combination of
* withBody/withHeaders to construct the message to be sent.
*
* @param exchangeSupplier the supplier
*/
FluentProducerTemplate withExchange(Supplier exchangeSupplier);
/**
* Set the processor to use for send/request.
*
*
* {@code
* FluentProducerTemplate.on(context)
* .withProcessor(
* exchange -> {
* exchange.getIn().setHeader("Key1", "Val1");
* exchange.getIn().setHeader("Key2", "Val2");
* exchange.getIn().setBody("the body");
* })
* .to("direct:start")
* .request()
* }
*
*
* Important: You can either only use either withExchange, or withProcessor or a combination of
* withBody/withHeaders to construct the message to be sent.
*
* @param processor the processor
*/
FluentProducerTemplate withProcessor(Processor processor);
/**
* Set the processorSupplier which will be invoke to get the processor to be used for send/request.
*
* Important: You can either only use either withExchange, or withProcessor or a combination of
* withBody/withHeaders to construct the message to be sent.
*
* @param processorSupplier the supplier
*/
FluentProducerTemplate withProcessor(Supplier processorSupplier);
/**
* Sets the default endpoint
*
* @param endpointUri the endpoint URI to send to
*/
FluentProducerTemplate withDefaultEndpoint(String endpointUri);
/**
* Sets the default endpoint
*
* @param resolver the {@link EndpointProducerResolver} that supply the endpoint to send to.
*/
FluentProducerTemplate withDefaultEndpoint(EndpointProducerResolver resolver);
/**
* Sets the default endpoint
*
* @param endpoint the endpoint to send to
*/
FluentProducerTemplate withDefaultEndpoint(Endpoint endpoint);
/**
* Endpoint to send to
*
* @param endpointUri the endpoint URI to send to
*/
default FluentProducerTemplate to(String endpointUri) {
final CamelContext context = ObjectHelper.notNull(getCamelContext(), "camel context");
return to(context.getEndpoint(endpointUri));
}
/**
* Endpoint to send to.
*
* @param uri the String formatted endpoint uri to send to
* @param args arguments for the string formatting of the uri
*/
default FluentProducerTemplate toF(String uri, Object... args) {
return to(String.format(uri, args));
}
/**
* Endpoint to send to
*
* @param resolver the {@link EndpointProducerResolver} that supply the endpoint to send to.
*/
default FluentProducerTemplate to(EndpointProducerResolver resolver) {
final CamelContext context = ObjectHelper.notNull(getCamelContext(), "camel context");
final Endpoint endpoint = resolver.resolve(context);
return to(endpoint);
}
/**
* Endpoint to send to
*
* @param endpoint the endpoint to send to
*/
FluentProducerTemplate to(Endpoint endpoint);
/**
* Send to an endpoint (InOut) returning any result output body.
*
* @return the result
* @throws CamelExecutionException is thrown if error occurred
*/
Object request() throws CamelExecutionException;
/**
* Send to an endpoint (InOut).
*
* @param type the expected response type
* @return the result
* @throws CamelExecutionException is thrown if error occurred
*/
T request(Class type) throws CamelExecutionException;
/**
* Sends asynchronously to the given endpoint (InOut).
*
* @return a handle to be used to get the response in the future
*/
Future © 2015 - 2025 Weber Informatics LLC | Privacy Policy