Stop/start/restart behaviour

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 AMP.

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)