You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@brooklyn.apache.org by he...@apache.org on 2015/03/13 10:20:05 UTC
[2/4] incubator-brooklyn git commit: Docs: describe SoftwareProcess
lifecycle
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 <al...@gmail.com>
Authored: Tue Mar 10 17:24:07 2015 +0000
Committer: Aled Sage <al...@gmail.com>
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)