[GitHub] [brooklyn-docs] iuliana commented on a diff in pull request #351: Concepts improvements

[GitBox <gi...@apache.org>]

iuliana commented on code in PR #351:
URL: https://github.com/apache/brooklyn-docs/pull/351#discussion_r869968154


##########
guide/concepts/_stop-start-restart-behaviour.camp.md:
##########
@@ -0,0 +1,56 @@
+## 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.

Review Comment:
   @algairim `pulling them` ? Is this intended? I don't understand where they are pulled from. Myabe rephrase. also replace n-sql with NoSQL, I think that is the correct acronym.



##########
guide/concepts/_stop-start-restart-behaviour.camp.md:
##########
@@ -0,0 +1,56 @@
+## 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.
+It 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.

Review Comment:
   Maybe put a **Note** in front of this affirmation, since this is important for the user to read.



##########
guide/concepts/_stop-start-restart-behaviour.camp.md:
##########
@@ -0,0 +1,56 @@
+## 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.
+It 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.

Review Comment:
   Maybe put a **Note** in front of this affirmation, since this is important for the user to read.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@brooklyn.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org