From Inside the Code: Camel Routing Engine, Part I

so i’ve recently re-kindled my interest in how apache camel works. camel is such a powerful integration tool and is very widely used, but anytime i put it to work, i can’t help but think “well, how the hell does it do all that!!” … guess i just have knack for not just accepting that it’s wonderful... i want to know why.

if you’ve followed some of my posts in the past, you’ll remember i do have a blog post that dives into how the camel dsl api works . more specifically, how can you just magically type “from(..)” “choice(..)” “simple(..)” etc and the dsl is just smart enough to know what you mean and how to string everything together. if you’re interested in how that all works, please take a peak at that post. be forewarned, there is a couple uml class diagrams in there that are quite verbose and long.

so if you recall from the previous post, the dsl (whether it’s the java dsl, or xml, or scala, or any others) has a very specific role. it helps the author of the integration route express very clearly his/her intent and then build that into an abstraction called a routedefinition . the routedefinition is kind of the “blueprint” of your route, and knows about all of your processors , eips , and components . you can consider any time you call from(..) to be the start of a new routedefinition . the rest of the route gives it its shape. so for every from(..) there is a one-to-one mapping to routedefinition .

so when the camelcontext starts up, it gathers up all of the routedefinition (s) and begins to build a route from them. take a look at defaultcamelcontext#dostartcamel for the entry point to all of this. among other important things, like putting together the registry, endpoints, starting basic services, management, etc, etc.. you’ll see a call to defaultcamelcontext#startroutedefinitions . this tells the routedefinitions to build route objects, which are the actual consumers (input) + pipeline of processors (output) that route exchanges.

the next block goes into a little more detail about how this all works. just like in previous blog posts about the internal workings of camel, this detail is mostly for me: i.e., in the future when i have forgotten half of this, i want a refresher. and some people who’d like to contribute to camel may find this interesting. for all others.. feel free to skip this block.

– start detailed section –

the defaultcamelcontext will loop through each routedefinition and will try to build a list of route s and routecontext s.

quick detour:
what is a routecontext though? in simple terms, you can think of it as the brains of the route, and a place where the route-specific configurations live (stream caching? tracing? handle faults? etc, etc). it knows about the “from” consumer, the rest of the pipeline, the intercept strategies, route policy, and is able to construct the route that will operate on exchanges.

it can be kind of confusing because there are a chain of calls to methods named “addroutes()” when really they are building routecontexts and building routes. but look that aside for a moment. so the call to routedefinition#addroutes(..) will return a list of routecontext objects. it will also populate a list of (initially empty) routes. the multiplicity here is basically n to n. because you can have multiple inputs to a routedefinition (e.g., by stringing together multiple from(..).from(..)), a single 1-to-1 routecontext to route can be expected, with a single pair per from(). so in the previous example, there would be two routecontexts and two routes in the list. in the call to addroutes(..) it also tries to turn the output definitions into real processors. the processors are the meat of the route object. each processor is built based on its respective definition (e.g., choicedefinition, logdefinition), but ultimately gets wrapped in a channel object and added to the routecontext.

so to wrap this up, the routedefinition will create the route, routecontext, and will also turn the individual output definitions into processors. after these are created, a routeservice is created from the newly minted route + routecontext pairs, and this is established with the camelcontext for later starting and controlling the lifecycle of the route.

– end detailed section –

so …once we have the routeservice initialized, we need to start the routes, depending on whether they are auto-start up or not and their order. take a look at defaultcamelcontext#dostartcamel once more, and toward the bottom is the call to defaultcamelcontext#dostartorresumeroutes . this will loop through our routeservice s and identify the correct startup order for the routes and then start them.

routes are started in two phases:

• warmup
  in warm up phase, we look through all of the routes and start all of the “outputs” or processors/eips. camel takes care to make sure
  this happens first, because we do not want to have the “inputs” or consumers started before all of the “outputs” are available.
• start/resume
  start the consumer! this is endpoint/component specific. for example, the jms consumer will begin listening to a destination.

note, at all parts of these stages in the lifecycle, there are callbacks that can be invoked so that you can plug in to this lifecycle and add your own custom startup code to coordinate with your application. take a look at the camel api for the type of callbacks available lifecylcestrategy

and there you have it. this is how route definitions are converted to actual routes and then started.

in part ii, i hope to go into how the processors are chained together, including a little more advanced chaining with the asyncprocessor.

stay tuned!