Added Camel lifecycle docs to Gitbook
Project: http://git-wip-us.apache.org/repos/asf/camel/repo Commit: http://git-wip-us.apache.org/repos/asf/camel/commit/72a6ab42 Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/72a6ab42 Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/72a6ab42 Branch: refs/heads/master Commit: 72a6ab42828fc858b90928ed9040589494748d36 Parents: fe94f55 Author: Andrea Cosentino <[email protected]> Authored: Sun Jul 31 11:24:25 2016 +0200 Committer: Andrea Cosentino <[email protected]> Committed: Sun Jul 31 11:24:25 2016 +0200 ---------------------------------------------------------------------- docs/user-manual/en/SUMMARY.md | 3 +- docs/user-manual/en/lifecycle.adoc | 117 +++++++++++++++++++ .../en/lifecycle.data/service_lifecycle.png | Bin 0 -> 35951 bytes 3 files changed, 118 insertions(+), 2 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/camel/blob/72a6ab42/docs/user-manual/en/SUMMARY.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md index 27a2798..842c71a 100644 --- a/docs/user-manual/en/SUMMARY.md +++ b/docs/user-manual/en/SUMMARY.md @@ -37,13 +37,12 @@ * [Injector](injector.adoc) * [Intercept](intercept.adoc) * [Inversion Of Control With Smart Defaults](inversion-of-control-with-smart-defaults.adoc) + * [Lifecycle](lifecycle.adoc) * [Registry](registry.adoc) * [RX](rx.adoc) * [Scala DSL](scala-dsl.adoc) <!-- - * [Languages](.adoc) - * [Lifecycle](.adoc) * [OnCompletion](.adoc) * [Pluggable Class Resolvers](.adoc) * [Predicate](.adoc) http://git-wip-us.apache.org/repos/asf/camel/blob/72a6ab42/docs/user-manual/en/lifecycle.adoc ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/lifecycle.adoc b/docs/user-manual/en/lifecycle.adoc new file mode 100644 index 0000000..c86f2eb --- /dev/null +++ b/docs/user-manual/en/lifecycle.adoc @@ -0,0 +1,117 @@ +[[Lifecycle-CamelLifecycle]] +Camel Lifecycle +~~~~~~~~~~~~~~~ + +Camel uses a simple _lifecycle_ interface called +http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/Service.html[Service] +which has a single start() and stop() method. + +Various classes implement Service such as +link:camelcontext.html[CamelContext] along with a number of +link:component.html[Component] and link:endpoint.html[Endpoint] classes. + +When you use Camel you typically have to start the +link:camelcontext.html[CamelContext] which will start all the various +components and endpoints and activate the routing rules until the +context is stopped again. + +If you are working with Spring you may wish to read the +link:spring.html[Camel Spring documentation]. + +[[Lifecycle-CamelContextLifecycle]] +CamelContext Lifecycle +^^^^^^^^^^^^^^^^^^^^^^ + +The `CamelContext` provides methods to control its lifecycle: + +* `start` +* `stop` +* `suspend` *Camel 2.5* +* `resume` *Camel 2.5* + +The operations is paired: start/stop and suspend/resume. + +Stop is performing a link:graceful-shutdown.html[Graceful shutdown] +which means all its internal state, cache, etc is cleared. And the +routes is being stopped in a graceful manner to ensure messages is given +time to complete. If you start a `CamelContext` after a stop, then its +performing a _cold_ start, recreating all the state, cache etc. again. + +Instead you can use the suspend/resume operations. They will keep the +`CamelContext` _warm_ and only suspend/stop routes using the same +link:graceful-shutdown.html[Graceful shutdown] feature. This ensures +messages is given time to complete. + +End users is encouraged to use suspend/resume if you are temporary +stopping a Camel application. + +All these operations is available in link:camel-jmx.html[JMX] as well, +so you can control Camel from a management console. + +If you write unit tests and perform _cold_ restarts using stop/start +then any previously looked up link:endpoint.html[Endpoint]s etc. is +obsolete, and therefore you need to re-lookup those endpoints again. + +Instead use suspend/resume which keeps these +link:endpoint.html[Endpoint]s and therefore you can still use them after +resuming. + +[[Lifecycle-Servicelifecycle]] +Service lifecycle +^^^^^^^^^^^^^^^^^ + +A service (`org.apache.camel.Service`) in Camel adheres to the following +lifecycle states as illustrated in the diagram below: + +image:lifecycle.data/service_lifecycle.png[image] + +*Notice:* A service can optimally support suspend/resume by the +`org.apache.camel.SuspendableService`. This means not all services in +Camel supports suspension. It's encouraged that consumers support +suspension which allows to suspend/resume routes. + +The `org.apache.camel.impl.ServiceSupport` is a good base class to +extend for custom services as it offers the basic functionally to keep +track of state. You implement your custom logic in the `doStart`, +`doStop`, `doSuspend`, `doResume` methods. + +[[Lifecycle-Routeslifecycle]] +Routes lifecycle +^^^^^^^^^^^^^^^^ + +Routes in Camel have the following operations to control its lifecycle + +* `start` +* `stop` +* `suspend` +* `resume` +* `remove` (previously named shutdown) + +The `remove` operation will *remove* the route, for example in +link:camel-jmx.html[JMX] the route will then be unregistered and its +gone. So only use remove if you really want to remove the route. The +route must have been stopped before you can remove. + +The `start` and `resume` operations in link:camel-jmx.html[JMX] checks +the state beforehand. So if a route is stopped and you click `resume`, +it will know to invoke `start`. And likewise if a route has been +suspended and you click `start` it knows to `resume` instead. This makes +management a bit easier. + +If a route is suspended then it keeps its resources and all their JMX +metrics alive. Where as stopping a route will graceful stop the route, +and clear its resources, and as well their JMX metrics. If you want to +temporary "pause" a route, then consider using suspend/resume over +stop/start. + +If a route consumer does not support suspension, it will fallback and +stop the route instead. + +[[Lifecycle-SeeAlso]] +See Also +^^^^^^^^ + +* link:camelcontext.html[CamelContext] +* link:architecture.html[Architecture] +* link:camel-jmx.html[JMX] + http://git-wip-us.apache.org/repos/asf/camel/blob/72a6ab42/docs/user-manual/en/lifecycle.data/service_lifecycle.png ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/lifecycle.data/service_lifecycle.png b/docs/user-manual/en/lifecycle.data/service_lifecycle.png new file mode 100644 index 0000000..41a90b4 Binary files /dev/null and b/docs/user-manual/en/lifecycle.data/service_lifecycle.png differ
