Chapter 1. Getting Started with Camel Spring Boot 3.18

The curated camel-spring-boot-dependencies BOM, which is generated, contains the adjusted JARs that both Spring Boot and Apache Camel use to avoid any conflicts. This BOM is used to test camel-spring-boot itself.

Spring Boot users may choose to use pure Camel dependencies by using the camel-spring-boot-bom that only has the Camel starter JARs as managed dependencies. However, this may lead to a classpath conflict if a third-party JAR from Spring Boot is not compatible with a particular Camel component.

Each starter lists configuration parameters you can configure in the standard application.properties or application.yml files. These parameters have the form of camel.component.[component-name].[parameter]. For example to configure the URL of the ActiveMQ broker you can set:

camel.component.activemq.broker-url=tcp://localhost:61616

Camel routes are detected in the Spring application context, for example a route annotated with org.springframework.stereotype.Component will be loaded, added to the Camel context and run.

import org.apache.camel.builder.RouteBuilder;
import org.springframework.stereotype.Component;

@Component
public class MyRoute extends RouteBuilder {

    @Override
    public void configure() throws Exception {
        from("...")
            .to("...");
    }

}

Apache Camel ships a Spring Boot Starter module that allows you to develop Spring Boot applications using starters. There is a sample application in the source code also.

To use the starter, add the following to your spring boot pom.xml file:

<dependency>
    <groupId>org.apache.camel.springboot</groupId>
    <artifactId>camel-spring-boot-bom</artifactId>
    <version>3.18.3.redhat-00042</version> <!-- use the same version as your Camel core version -->
</dependency>

Then you can just add classes with your Camel routes such as:

package com.example;

import org.apache.camel.builder.RouteBuilder;
import org.springframework.stereotype.Component;

@Component
public class MyRoute extends RouteBuilder {

    @Override
    public void configure() throws Exception {
        from("timer:foo").to("log:bar");
    }
}

Then these routes will be started automatically.

You can customize the Camel application in the application.properties or application.yml file.

When using spring-boot with Spring Boot make sure to use the following Maven dependency to have support for auto configuration:

<dependency>
  <groupId>org.apache.camel.springboot</groupId>
  <artifactId>camel-spring-boot-starter</artifactId>
  <version>3.18.3.redhat-00042</version> <!-- use the same version as your Camel core version -->
</dependency>

The most important piece of functionality provided by the Camel auto-configuration is the CamelContext instance. Camel auto-configuration creates a SpringCamelContext for you and takes care of the proper initialization and shutdown of that context. The created Camel context is also registered in the Spring application context (under the camelContext bean name), so you can access it like any other Spring bean.

@Configuration
public class MyAppConfig {

  @Autowired
  CamelContext camelContext;

  @Bean
  MyService myService() {
    return new DefaultMyService(camelContext);
  }

}

Camel auto-configuration collects all the RouteBuilder instances from the Spring context and automatically injects them into the provided CamelContext. This means that creating new Camel routes with the Spring Boot starter is as simple as adding the @Component annotated class to your classpath:

@Component
public class MyRouter extends RouteBuilder {

  @Override
  public void configure() throws Exception {
    from("jms:invoices").to("file:/invoices");
  }

}

Or creating a new route RouteBuilder bean in your @Configuration class:

@Configuration
public class MyRouterConfiguration {

  @Bean
  RoutesBuilder myRouter() {
    return new RouteBuilder() {

      @Override
      public void configure() throws Exception {
        from("jms:invoices").to("file:/invoices");
      }

    };
  }

}

Spring Boot auto-configuration automatically connects to Spring Boot external configuration (which may contain properties placeholders, OS environment variables or system properties) with the Camel properties support. It basically means that any property defined in application.properties file:

route.from = jms:invoices

Or set via system property:

java -Droute.to=jms:processed.invoices -jar mySpringApp.jar

can be used as placeholders in Camel route:

@Component
public class MyRouter extends RouteBuilder {

  @Override
  public void configure() throws Exception {
    from("{{route.from}}").to("{{route.to}}");
  }

}

If you want to perform some operations on CamelContext bean created by Camel auto-configuration, register CamelContextConfiguration instance in your Spring context:

@Configuration
public class MyAppConfig {

  @Bean
  CamelContextConfiguration contextConfiguration() {
    return new CamelContextConfiguration() {
      @Override
      void beforeApplicationStart(CamelContext context) {
        // your custom configuration goes here
      }
    };
  }

}

The method beforeApplicationStart will be called just before the Spring context is started, so the CamelContext instance passed to this callback is fully auto-configured. If you add multiple instances of CamelContextConfiguration into your Spring context, each instance is executed.

Camel auto-configuration provides pre-configured ConsumerTemplate and ProducerTemplate instances. You can simply inject them into your Spring-managed beans:

@Component
public class InvoiceProcessor {

  @Autowired
  private ProducerTemplate producerTemplate;

  @Autowired
  private ConsumerTemplate consumerTemplate;

  public void processNextInvoice() {
    Invoice invoice = consumerTemplate.receiveBody("jms:invoices", Invoice.class);
    ...
    producerTemplate.sendBody("netty-http:http://invoicing.com/received/" + invoice.id());
  }

}

By default, consumer templates and producer templates come with the endpoint cache sizes set to 1000. You can change these values by modifying the following Spring properties:

camel.springboot.consumer-template-cache-size = 100
camel.springboot.producer-template-cache-size = 200

Camel auto-configuration registers a TypeConverter instance named typeConverter in the Spring context.

@Component
public class InvoiceProcessor {

  @Autowired
  private TypeConverter typeConverter;

  public long parseInvoiceValue(Invoice invoice) {
    String invoiceValue = invoice.grossValue();
    return typeConverter.convertTo(Long.class, invoiceValue);
  }

}

@Component
public class InvoiceProcessor {

  @Autowired
  private TypeConverter typeConverter;

  public UUID parseInvoiceId(Invoice invoice) {
    // Using Spring's StringToUUIDConverter
    UUID id = invoice.typeConverter.convertTo(UUID.class, invoice.getId());
  }

}

Camel applications which have this feature enabled launch a new thread on startup for the sole purpose of keeping the application alive by preventing JVM termination. This means that after you start a Camel application with Spring Boot, your application waits for a Ctrl+C signal and does not exit immediately.

The controller thread can be activated using the camel.springboot.main-run-controller to true.

camel.springboot.main-run-controller = true

Applications using web modules (for example, applications that import the org.springframework.boot:spring-boot-web-starter module), usually don’t need to use this feature because the application is kept alive by the presence of other non-daemon threads.

By default, you can put Camel XML routes in the classpath under the directory camel, which camel-spring-boot will auto-detect and include. You can configure the directory name or turn this off using the configuration option:

# turn off
camel.springboot.routes-include-pattern = false

# scan only in the com/foo/routes classpath
camel.springboot.routes-include-pattern = classpath:com/foo/routes/*.xml

The XML files should be Camel XML routes (not <CamelContext>) such as:

<routes xmlns="http://camel.apache.org/schema/spring">
    <route id="test">
        <from uri="timer://trigger"/>
        <transform>
            <simple>ref:myBean</simple>
        </transform>
        <to uri="log:out"/>
    </route>
</routes>

For testing, Maven users will need to add the following dependencies to their pom.xml:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test</artifactId>
    <version>2.7.12</version> <!-- Use the same version as your Spring Boot version -->
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-test-spring-junit5</artifactId>
    <version>3.18.3.redhat-00034</version> <!-- use the same version as your Camel core version -->
    <scope>test</scope>
</dependency>

To test a Camel Spring Boot application, annotate your test class(es) with @CamelSpringBootTest. This brings Camel’s Spring Test support to your application, so that you can write tests using Spring Boot test conventions.

To get the CamelContext or ProducerTemplate, you can inject them into the class in the normal Spring manner, using @Autowired.

You can also use camel-test-spring-junit5 to configure tests declaratively. This example uses the @MockEndpoints annotation to auto-mock an endpoint:

@CamelSpringBootTest
@SpringBootApplication
@MockEndpoints("direct:end")
public class MyApplicationTest {

    @Autowired
    private ProducerTemplate template;

    @EndpointInject("mock:direct:end")
    private MockEndpoint mock;

    @Test
    public void testReceive() throws Exception {
        mock.expectedBodiesReceived("Hello");
        template.sendBody("direct:start", "Hello");
        mock.assertIsSatisfied();
    }

}

Internally, every starter is configured through Spring Boot’s ConfigurationProperties. Each configuration parameter can be set in various ways (application.[properties|json|yaml] files, command line arguments, environments variables etc.). Parameters have the form of camel.[component|language|dataformat].[name].[parameter]

For example to configure the URL of the ActiveMQ broker you can set:

camel.component.activemq.broker-url=tcp://localhost:61616

Or to configure the delimeter of the CSV dataformat to be a semicolon(;) you can set:

camel.dataformat.csv.delimiter=;

Camel will use the Type Converter mechanism when setting properties to the desired type.

You can refer to beans in the Registry using the #bean:name:

camel.component.jms.transactionManager=#bean:myjtaTransactionManager

The Bean would be typically created in Java:

@Bean("myjtaTransactionManager")
public JmsTransactionManager myjtaTransactionManager(PooledConnectionFactory pool) {
    JmsTransactionManager manager = new JmsTransactionManager(pool);
    manager.setDefaultTimeout(45);
    return manager;
}

Beans can also be created in configuration files but this is not recommended for complex use cases.

Starters can also be created and configured via Spring Beans. Before creating a starter , Camel will first lookup it up in the Registry by it’s name if it already exists. For example to configure a Kafka component:

@Bean("kafka")
public KafkaComponent kafka(KafkaConfiguration kafkaconfiguration){
    return ComponentsBuilderFactory.kafka()
                        .brokers("{{kafka.host}}:{{kafka.port}}")
                        .build();
}

The Bean name has to be equal to that of the Component, Dataformat or Language that you are configuring. If the Bean name isn’t specified in the annotation it will be set to the method name.

Typical Camel Spring Boot projects will use a combination of external configuration and Beans to configure an application. For more examples on how to configure your Camel Spring Boot project, please see the example repository.