brooklyn-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject [1/4] incubator-brooklyn git commit: Adding docs - stop/start/restart behaviour
Date Wed, 19 Aug 2015 12:43:33 GMT
Repository: incubator-brooklyn
Updated Branches:
  refs/heads/master 162b1d46a -> 0f6041e41

Adding docs - stop/start/restart behaviour


Branch: refs/heads/master
Commit: b8186deffb1f7b6331ab99d90e153f526caa5de7
Parents: ce5ddaf
Author: Yavor Yanchev <>
Authored: Wed Aug 19 13:50:36 2015 +0300
Committer: Yavor Yanchev <>
Committed: Wed Aug 19 14:38:47 2015 +0300

 docs/guide/concepts/                    |  1 +
 .../concepts/    | 65 ++++++++++++++++++++
 2 files changed, 66 insertions(+)
diff --git a/docs/guide/concepts/ b/docs/guide/concepts/
index 5c81c2d..b27ea8c 100644
--- a/docs/guide/concepts/
+++ b/docs/guide/concepts/
@@ -11,6 +11,7 @@ children:
 This introduces brooklyn and describes how it simplifies the deployment and management of
big applications. It is
diff --git a/docs/guide/concepts/ b/docs/guide/concepts/
new file mode 100644
index 0000000..916ea5c
--- /dev/null
+++ b/docs/guide/concepts/
@@ -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
+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

View raw message