Repository: incubator-brooklyn Updated Branches: refs/heads/master 162b1d46a -> 0f6041e41
Adding docs - stop/start/restart behaviour Project: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/commit/b8186def Tree: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/tree/b8186def Diff: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/diff/b8186def Branch: refs/heads/master Commit: b8186deffb1f7b6331ab99d90e153f526caa5de7 Parents: ce5ddaf Author: Yavor Yanchev <[email protected]> Authored: Wed Aug 19 13:50:36 2015 +0300 Committer: Yavor Yanchev <[email protected]> Committed: Wed Aug 19 14:38:47 2015 +0300 ---------------------------------------------------------------------- docs/guide/concepts/index.md | 1 + .../concepts/stop-start-restart-behaviour.md | 65 ++++++++++++++++++++ 2 files changed, 66 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/b8186def/docs/guide/concepts/index.md ---------------------------------------------------------------------- diff --git a/docs/guide/concepts/index.md b/docs/guide/concepts/index.md index 5c81c2d..b27ea8c 100644 --- a/docs/guide/concepts/index.md +++ b/docs/guide/concepts/index.md @@ -11,6 +11,7 @@ children: - location.md - policies.md - execution.md +- stop-start-restart-behaviour.md --- This introduces brooklyn and describes how it simplifies the deployment and management of big applications. It is http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/b8186def/docs/guide/concepts/stop-start-restart-behaviour.md ---------------------------------------------------------------------- diff --git a/docs/guide/concepts/stop-start-restart-behaviour.md b/docs/guide/concepts/stop-start-restart-behaviour.md new file mode 100644 index 0000000..916ea5c --- /dev/null +++ b/docs/guide/concepts/stop-start-restart-behaviour.md @@ -0,0 +1,65 @@ +--- +title: Stop/start/restart behaviour +layout: website-normal +toc: ../guide_toc.json +categories: [use, guide, defining-applications] +--- + +Many entities expose `start`, `stop` and `restart` effectors. The semantics of these operations (and the parameters they take) depends on the type of entity. + +## Top-level applications +A top-level application is a grouping of other entities, pulling them together into the "application" of your choice. This could range from a single app-server, to an app that is a composite of a no-sql cluster (e.g. MongoDB sharded cluster, or Cassandra spread over multiple datacenters), a cluster of load-balanced app-servers, message brokers, etc. + +### start(Collection<Location>) +This will start the application in the given location(s). Each child-entity within the application will be started concurrently, passing the location(s) to each child. +The start effector will be called automatically when the application is deployed through the catalog. +Is is strongly recommended to not call start again. + +### stop() +Stop will terminate the application and all its child entities (including releasing all their resources). +The application will also be unmanaged, **removing** it from Brooklyn. + +### restart() +This will invoke `restart()` on each child-entity concurrently (with the default values for the child-entity's restart effector parameters). +Is is strongly recommended to not call this, unless the application has been explicitly written to implement restart. + +## Software Process (e.g MySql, Tomcat, JBoss app-server, MongoDB) + +### start(Collection<Location>) +This will start the software process in the given location. +If a machine location is passed in, then the software process is started there. +If a cloud location is passed in, then a new VM will be created in that cloud - the software process will be **installed+launched** on that new VM. + +The start effector will have been called automatically when deploying an application through the catalog. +In normal usage, do not invoke start again. + +If calling `start()` a second time, with no locations passed in (e.g. an empty list), then it will go through the start sequence on the existing location from the previous call. +It will **install+customize+launch** the process. +For some entities, this could be *dangerous*. The customize step might execute a database initialisation script, which could cause data to be overwritten (depending how the initialisation script was written). + +If calling `start()` a second time with additional locations, then these additional locations will be added to the set of locations. +In normal usage it is not recommended. +This could be desired behaviour if the entity had previously been entirely stopped (including its VM terminated) - but for a simple one-entity app then you might as well have deleted the entire app and created a new one. + + +### stop(boolean stopMachine) +If `stopMachine==true`, this effector will stop the software process and then terminate the VM (if a VM had been created as part of `start()`). This behaviour is the inverse of the first `start()` effector call. +When stopping the software process, it does not uninstall the software packages / files. + +If `stopMachine==false`, this effector will stop just the software process (leaving the VM and all configuration files / install artifacts in place). + +### restart(boolean restartMachine, boolean restartChildren) +This will restart the software process. + +If `restartMachine==true`, it will also terminate the VM and create a new VM. It will then install+customize+launch the software process on the new VM. It is equivalent of invoking `stop(true)` and then `start(Collections.EMPTY_LIST)`. +If `restartMachine==false`, it will first attempt to stop the software process (which should be a no-op if the process is not running), and will then start the software process (without going through the **install+customize** steps). + +If `restartChildren==true`, then after restarting itself it will call `restart(restartMachine, restartChildren)` on each child-entity concurrently. + +## Recommended operations + +The recommended operations to invoke to stop just the software process, and then to restart it are: + +* Select the software process entity in the tree (*not* the parent application, but the child of that application). +* Invoke `stop(stopMachine=false)` +* Invoke `restart(restartMachine=false, restartChildren=false)` \ No newline at end of file
