Docs: describe SoftwareProcess lifecycle Project: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/commit/4ae4e6af Tree: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/tree/4ae4e6af Diff: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/diff/4ae4e6af
Branch: refs/heads/master Commit: 4ae4e6af1b4e7dfae8b898c9b4faff33aee48d7e Parents: 8527d7e Author: Aled Sage <[email protected]> Authored: Tue Mar 10 17:24:07 2015 +0000 Committer: Aled Sage <[email protected]> Committed: Tue Mar 10 17:24:07 2015 +0000 ---------------------------------------------------------------------- docs/guide/java/entities.md | 87 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 85 insertions(+), 2 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/4ae4e6af/docs/guide/java/entities.md ---------------------------------------------------------------------- diff --git a/docs/guide/java/entities.md b/docs/guide/java/entities.md index c7fc43e..b83c61a 100644 --- a/docs/guide/java/entities.md +++ b/docs/guide/java/entities.md @@ -32,8 +32,6 @@ What to Extend -- Implementation Classes A common lifecycle pattern is that the ``start`` effector (see more on effectors below) is invoked, often delegating either to a driver (for software processes) or children entities (for clusters etc). -See ``JBoss7Server`` and ``MySqlNode`` for exemplars. - Configuration ------------- @@ -125,3 +123,88 @@ Testing * Unit tests can make use of `SimulatedLocation` and `TestEntity`, and can extend `BrooklynAppUnitTestSupport`. * Integration tests and use a `LocalhostMachineProvisioningLocation`, and can also extend `BrooklynAppUnitTestSupport`. + + +<a name="SoftwareProcess-lifecycle"></a> + +SoftwareProcess Lifecycle +------------------------- + +`SoftwareProcess` is the common super-type of most integration components (when implementing in Java). + +See ``JBoss7Server`` and ``MySqlNode`` for exemplars. + +The methods called in a `SoftwareProcess` entity's lifecycle are described below. The most important steps are shown in bold (when writing a new entity, these are the methods most often implemented). + +* Initial creation (via `EntitySpec` or YAML): + * **no-arg constructor** + * **init** + * add locations + * apply initializers + * add enrichers + * add policies + * add children + * manages entity (so is discoverable by other entities) + +* Start: + * provisions new machine, if the location is a `MachineProvisioningLocation` + * creates new driver + * **calls `getDriverInterface`** + * Infers the concrete driver class from the machine-type, + e.g. by default it adds "Ssh" before the word "Driver" in "JBoss7Driver". + * instantiates the driver, **calling the constructor** to pass in the entity itself and the machine location + * sets attributes from config (e.g. for ports being used) + * calls `entity.preStart()` + * calls `driver.start()`, which: + * runs pre-install command (see config key `pre.install.command`) + * uploads install resources (see config keys `files.install` and `templates.install`) + * **calls `driver.install()`** + * runs post-install command (see config key `post.install.command`) + * **calls `driver.customize()`** + * uploads runtime resources (see config keys `files.runtime` and `templates.runtime`) + * runs pre-launch command (see config key `pre.launch.command`) + * **calls `driver.launch()`** + * runs post-launch command (see config key `post.launch.command`) + * calls `driver.postLaunch()` + * calls `entity.postDriverStart()`, which: + * calls `enity.waitForEntityStart()` - **waits for `driver.isRunning()` to report true** + * **calls `entity.connectSensors()`** + * calls `entity.waitForServicUp()` + * calls `entity.postStart()` + +* Restart: + * If restarting machine... + * calls `entity.stop()`, with `stopMachine` set to true. + * calls start + * restarts children (if configured to do so) + * Else (i.e. not restarting machine)... + * calls `entity.preRestart()` + * calls `driver.restart()` + * **calls `driver.stop()`** + * **calls `driver.launch()`** + * calls `driver.postLaunch()` + * restarts children (if configured to do so) + * calls `entity.postDriverStart()`, which: + * calls `enity.waitForEntityStart()` - **polls `driver.isRunning()`**, waiting for true + * calls `entity.waitForServicUp()` + * calls `entity.postStart()` + +* Stop: + * calls `entity.preStopConfirmCustom()` - aborts if exception. + * calls `entity.preStop()` + * stops the process: + * stops children (if configured to do so) + * **calls `driver.stop()`** + * stops the machine (if configured to do so) + * calls `entity.postStop()` + +* Rebind (i.e. when Brooklyn is restarted): + * **no-arg constructor** + * reconstitutes entity (e.g. setting config and attributes) + * If entity was running... + * calls `entity.rebind()`; if previously started then: + * creates the driver (same steps as for start) + * calls `driver.rebind()` + * **calls `entity.connectSensors()`** + * attaches policies, enrichers and persisted feeds + * manages the entity (so is discoverable by other entities)
