Camel and SCR

Working with Camel using SCR

SCR stands for Service Component Runtime and is an implementation of OSGi Declarative Services specification (TODO: add a link to spec here). SCR enables any plain old Java object to expose and use OSGi services with no boilerplate code.

OSGi framework knows your object by looking at SCR descriptor files which are typically generated from annotations in your code by a plugin such as org.apache.felix:maven-scr-plugin (https://felix.apache.org/documentation/subprojects/apache-felix-maven-scr-plugin.html).

Running Camel in an SCR bundle is a great alternative for Spring DM and Blueprint based solutions having significantly fewer lines of code between you and the OSGi framework. Using SCR your bundle can remain completely in Java world; there is no need to edit XML or properties files. This offers you full control over everything and means your IDE of choice knows exactly what is going on in your project.

Camel SCR support

Available as of Camel 2.15.0

org.apache.camel/camel-scr bundle provides a base class, AbstractCamelRunner, which manages a Camel context for you and a helper class, ScrHelper, for using your SCR properties in unit tests. Camel-scr feature for Apache Karaf defines all features and bundles required for running Camel in SCR bundles.

AbstractCamelRunner ties CamelContext's lifecycle to Service Component's lifecycle and handles configuration with Camel's PropertiesComponent. All you have to do is extend a java class from AbstractCamelRunner and add the following org.apache.felix.scr.annotations on class level to make it a Service Component:

@Component
@References({
        @Reference(name = "camelComponent",referenceInterface = ComponentResolver.class,
                cardinality = ReferenceCardinality.MANDATORY_MULTIPLE, policy = ReferencePolicy.DYNAMIC,
                policyOption = ReferencePolicyOption.GREEDY, bind = "gotCamelComponent", unbind = "lostCamelComponent")
})

Then implement *getRouteBuilders()* which should return the Camel routes you want to run. And finally provide the default configuration with:

@Properties({
  @Property(name = "camelContextId", value = "my-test"),
  @Property(name = "active", value = "true"),
  @Property(name = "...", value = "..."),
  ...
})

That's all. And if you used camel-archetype-scr all this is already taken care of.

Properties camelContextId and active control the CamelContext's name (defaults to "camel-runner-default") and whether it will be started or not (defaults to "false"), respectively. In addition to these you can add and use as many properties as you like. Camel's PropertiesComponent handles recursive properties and prefixing with fallback without problem.

AbstractCamelRunner will make these properties available to your RouteBuilders through Camel's PropertiesComponent AND it will also inject these values into your Service Component's and RouteBuilder's fields when their names match. The fields can be declared with any visibility level, and many types are supported (String, int, boolean, URL, ...).

AbstractCamelRunner's lifecycle in SCR

1. When component's configuration policy and mandatory references are satisfied SCR calls activate(). This creates and sets up a CamelContext through the following call chain: activate() => prepare() -> createCamelContext() -> setupPropertiesComponent() -> configure() -> setupCamelContext(). Finally, the context is scheduled to start after a delay defined in AbstractCamelRunner.START_DELAY with runWithDelay().
2. When Camel components (ComponentResolver services, to be exact) are registered in OSGi, SCR calls gotCamelComponent() which reschedules/delays the CamelContext start further by the same AbstractCamelRunner.START_DELAY. This in effect makes CamelContext wait until all Camel components are loaded or there is a sufficient gap between them. The same logic will tell a failed-to-start CamelContext to try again whenever we add more Camel components.
3. When Camel components are unregistered SCR calls lostCamelComponent(). This call does nothing.
4. When one of the requirements that caused the call to activate() is lost SCR will call deactivate(). This will shutdown the CamelContext.

In (non-OSGi) unit tests you should use prepare() -> run() -> stop() instead of activate() -> deactivate() for more fine-grained control. Also, this allows us to avoid possible SCR specific operations in tests.

Example Camel SCR bundle

The easiest way to create an Camel SCR bundle is to use camel-archetype-scr Maven archetype.

# mvn archetype:generate -Dfilter=org.apache.camel.archetypes:camel-archetype-scr

Choose archetype:
1: local -> org.apache.camel.archetypes:camel-archetype-scr (Creates a new Camel SCR bundle project for Karaf)
Choose a number or apply filter (format: [groupId:]artifactId, case sensitive contains): : 1
Define value for property 'groupId': : my.example
[INFO] Using property: groupId = my.example
Define value for property 'artifactId': : my-test
Define value for property 'version': 1.0-SNAPSHOT: :
Define value for property 'package': my.example: :
[INFO] Using property: archetypeArtifactId = camel-archetype-scr
[INFO] Using property: archetypeGroupId = org.apache.camel.archetypes
[INFO] Using property: archetypeVersion = 2.15-SNAPSHOT
Define value for property 'className': : MyTest
Confirm properties configuration:
groupId: my.example
artifactId: my-test
version: 1.0-SNAPSHOT
package: my.example
archetypeArtifactId: camel-archetype-scr
archetypeGroupId: org.apache.camel.archetypes
archetypeVersion: 2.15-SNAPSHOT
className: MyTest
 Y: :

All done! Check ReadMe.txt in the generated project folder for the next steps.

To deploy a Camel SCR bundle project in Apache Karaf:

On Karaf command line:

# Add Camel feature repository
features:chooseurl camel 2.15-SNAPSHOT

# Install camel-scr feature
features:install camel-scr

# Install commons-lang, used in the example route to validate parameters
osgi:install mvn:commons-lang/commons-lang/2.6

# Install and start your bundle
osgi:install -s mvn:your.company/your-bundle/version

# See how it's running
log:tail -n 10

Press ctrl-c to stop watching the log.