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:04 UTC
[1/4] incubator-brooklyn git commit: Docs: minor improvements
Repository: incubator-brooklyn
Updated Branches:
refs/heads/master 0ff4216a8 -> e8e0fced3
Docs: minor improvements
- Improve tests.md
- Fix formatting
Project: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/commit/8527d7e0
Tree: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/tree/8527d7e0
Diff: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/diff/8527d7e0
Branch: refs/heads/master
Commit: 8527d7e0ba8351d9afb1aee1550ec3e7ac8c12bf
Parents: fd22cc0
Author: Aled Sage <al...@gmail.com>
Authored: Tue Mar 10 16:54:52 2015 +0000
Committer: Aled Sage <al...@gmail.com>
Committed: Tue Mar 10 17:22:42 2015 +0000
----------------------------------------------------------------------
docs/guide/dev/code/tests.md | 11 ++++++++---
docs/guide/dev/tips/index.md | 1 +
docs/guide/java/entities.md | 17 +++++++++--------
3 files changed, 18 insertions(+), 11 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/8527d7e0/docs/guide/dev/code/tests.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/code/tests.md b/docs/guide/dev/code/tests.md
index 6d2bbab..460cc23 100644
--- a/docs/guide/dev/code/tests.md
+++ b/docs/guide/dev/code/tests.md
@@ -19,8 +19,13 @@ We have the following tests groups:
To run these from the command line, use something like the following:
* normal: `mvn clean install`
-* integration: `mvn clean verify -PEssentials,Locations,Entities,Integration -Dmaven.test.failure.ignore=true`
-* Live: `mvn clean verify -PEntities,Locations,Entities,Live -Dmaven.test.failure.ignore=true`
-* Live-sanity: `mvn clean verify -PEntities,Locations,Entities,Live-sanity -Dmaven.test.failure.ignore=true`
+* integration: `mvn clean verify -PEssentials,Locations,Entities,Integration -Dmaven.test.failure.ignore=true --fail-never`
+* Live: `mvn clean verify -PEntities,Locations,Entities,Live -Dmaven.test.failure.ignore=true --fail-never`
+* Live-sanity: `mvn clean verify -PEntities,Locations,Entities,Live-sanity -Dmaven.test.failure.ignore=true --fail-never`
+
+To run a single test, use something like the following:
+
+* run a single test class: `mvn -Dtest=brooklyn.enricher.EnrichersTest -DfailIfNoTests=false test`
+* run a single test method: `mvn -Dtest=brooklyn.enricher.EnrichersTest#testAdding -DfailIfNoTests=false test`
<!-- TODO describe how to run each of these, as a group, and individually; and profiles -->
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/8527d7e0/docs/guide/dev/tips/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/tips/index.md b/docs/guide/dev/tips/index.md
index ac173c0..8a45d46 100644
--- a/docs/guide/dev/tips/index.md
+++ b/docs/guide/dev/tips/index.md
@@ -23,6 +23,7 @@ title: Miscellaneous Tips and Tricks
<a name="EntityDesign"></a>
+
## Entity Design Tips
* Look at related entities and understand what they've done, in particular which
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/8527d7e0/docs/guide/java/entities.md
----------------------------------------------------------------------
diff --git a/docs/guide/java/entities.md b/docs/guide/java/entities.md
index aae674d..c7fc43e 100644
--- a/docs/guide/java/entities.md
+++ b/docs/guide/java/entities.md
@@ -16,13 +16,13 @@ What to Extend -- Implementation Classes
- entity implementation class hierarchy
- - ``SoftwareProcess`` as the main starting point for base entities (corresponding to software processes),
- and subclasses such as ``VanillaJavaApp``
- - ``DynamicCluster`` (multiple instances of the same entity in a location) and
- ``DynamicFabric`` (clusters in multiple location) for automatically creating many instances,
- supplied with an ``EntityFactory`` (e.g. ``BaseEntityFactory``) in the ``factory`` flag
- - abstract ``Group`` for collecting entities which are parented elsewhere in the hierachy
- - ``AbstractEntity`` if nothing else fits
+ - `SoftwareProcess` as the main starting point for base entities (corresponding to software processes),
+ and subclasses such as `VanillaJavaApp`
+ - `DynamicCluster` (multiple instances of the same entity in a location) and
+ `DynamicFabric` (clusters in multiple location) for automatically creating many instances,
+ supplied with an `EntityFactory` (e.g. `BaseEntityFactory`) in the `factory` flag
+ - `AbstractGroup` for collecting entities which are parented elsewhere in the hierachy
+ - `AbstractEntity` if nothing else fits
- traits (mixins, otherwise known as interfaces with statics) to define available config keys, sensors, and effectors;
and conveniences e.g. ``StartableMethods.{start,stop}`` is useful for entities which implement ``Startable``
@@ -123,4 +123,5 @@ TODO more drivers such as jmx, etc are planned
Testing
-------
-* Run in a mock ``SimulatedLocation``, defining new metaclass methods to be able to start there and assert the correct behaviour when that is invoked
+* Unit tests can make use of `SimulatedLocation` and `TestEntity`, and can extend `BrooklynAppUnitTestSupport`.
+* Integration tests and use a `LocalhostMachineProvisioningLocation`, and can also extend `BrooklynAppUnitTestSupport`.
[3/4] incubator-brooklyn git commit: Docs: persistence best practices
/ guidelines
Posted by he...@apache.org.
Docs: persistence best practices / guidelines
Project: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/commit/fe4668cc
Tree: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/tree/fe4668cc
Diff: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/diff/fe4668cc
Branch: refs/heads/master
Commit: fe4668ccc05eb6e953de1d4172014d63efa462bd
Parents: 4ae4e6a
Author: Aled Sage <al...@gmail.com>
Authored: Tue Mar 10 17:24:32 2015 +0000
Committer: Aled Sage <al...@gmail.com>
Committed: Tue Mar 10 17:24:32 2015 +0000
----------------------------------------------------------------------
docs/guide/ops/persistence/index.md | 75 +++++++++++++++++++++++++-------
1 file changed, 59 insertions(+), 16 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/fe4668cc/docs/guide/ops/persistence/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/ops/persistence/index.md b/docs/guide/ops/persistence/index.md
index 1a8fe55..ab8e724 100644
--- a/docs/guide/ops/persistence/index.md
+++ b/docs/guide/ops/persistence/index.md
@@ -250,33 +250,76 @@ Writing Persistable Code
The most common problem on rebind is that custom entity code has not been written in a way
that can be persisted and/or rebound.
-The rule of thumb when implementing new entities, locations and policies is that all state
-must be persistable. All state must be stored as config or as attributes, and must be
-serializable (e.g. avoid the use of anonymous inner classes).
+The rule of thumb when implementing new entities, locations, policies and enrichers is that
+all state must be persistable. All state must be stored as config or as attributes, and must be
+serializable. For making backwards compatibility simpler, the persisted state should be clean.
-Below is a guide for when implementing an entity in Java (or any other JVM language):
+Below are tips and best practices for when implementing an entity in Java (or any other
+JVM language).
-* Don't store state in artibrary fields - the field will not be persisted (this is a design
+How to store entity state:
+
+* Config keys and values are persisted.
+* Store an entity's runtime state as attributes.
+* Don't store state in arbitrary fields - the field will not be persisted (this is a design
decision, because Brooklyn cannot intercept the field being written to, so cannot know
when to persist).
-* Store runtime state as attributes.
+* Don't just modify the retrieved attribute value (e.g. `getAttribute(MY_LIST).add("a")` is bad).
+ The value may not be persisted unless setAttribute() is called.
+* For special cases, it is possible to call `entity.requestPerist()` which will trigger
+ asynchronous persistence of the entity.
+* Overriding (and customizing) of `getRebindSupport()` is discouraged - this will change
+ in a future version.
+
+
+How to store policy/enricher/location state:
+
+* Store values as config keys where applicable.
+* Unfortunately these (currently) do not have attributes. Normally the state of a policy
+ or enricher is transient - on rebind it starts afresh, for example with monitoring the
+ performance or health metrics rather than relying on the persisted values.
+* For special cases, you can annotate a field with `@SetFromFlag` for it be persisted.
+ When you call `requestPersist()` then values of these fields will be scheduled to be
+ persisted. *Warning: the `@SetFromFlag` functionality may change in future versions.*
+
+Persistable state:
+
* Ensure values can be serialized. This (currently) uses xstream, which means it does not
- need to implement `Serializable`. However, if declaring your own classes that are to be
- persisted as state of the entity then declare them as static (or top-level) classes
- rather than anonymous inner classes or non-static inner classes.
+ need to implement `Serializable`.
+* Always use static (or top-level) classes. Otherwise it will try to also persist the outer
+ instance!
+* Any reference to an entity or location will be automatically swapped out for marker, and
+ re-injected with the new entity/location instance on rebind. The same applies for policies,
+ enrichers, feeds, catalog items and `ManagementContext`.
+
+Behaviour on rebind:
+
* By extending `SoftwareProcess`, entities get a lot of the rebind logic for free. For
example, the default `rebind()` method will call `connectSensors()`.
+ See [`SoftwareProcess` Lifecycle]({{site.path.guide}}/java/entities.html#SoftwareProcess-lifecycle)
+ for more details.
* If necessary, implement rebind. The `entity.rebind()` is called automatically by the
Brooklyn framework on rebind, after configuring the entity's config/attributes but before
the entity is managed.
Note that `init()` will not be called on rebind.
-* For special cases, it is possible to call `entity.requestPerist()` which will trigger
- asynchronous persistence of the entity.
-
-For locations, policies and enrichers they (currently) do not have attributes. However,
-config is persisted automatically. Normally the state of a policy or enricher is transient -
-on rebind it starts afresh, for example with monitoring the performance or health metrics
-rather than relying on the persisted values.
+* Feeds will be persisted if and only if `entity.addFeed(...)` was called. Otherwise the
+ feed needs to be re-registered on rebind. *Warning: this behaviour may change in future version.*
+* All functions/predicates used with persisted feeds must themselves be persistable -
+ use of anonymous inner classes is strongly discouraged.
+* Subscriptions (e.g. from calls to `subscribe(...)` for sensor events) are not persisted.
+ They must be re-registered on rebind. *Warning: this behaviour may change in future version.*
+
+Below are tips to make backwards-compatibility easier for persisted state:
+
+* Never use anonymous inner classes - even in static contexts. The auto-generated class names
+ are brittle, making backwards compatibility harder.
+* Always use sensible field names (and use `transient` whenever you don't want it persisted).
+ The field names are part of the persisted state.
+* Consider using Value Objects for persisted values. This can give clearer separation of
+ responsibilities in your code, and clearer control of what fields are being persisted.
+* Consider writing transformers to handle backwards-incompatible code changes.
+ Brooklyn supports applying transformations to the persisted state, which can be done as
+ part of an upgrade process.
Persisted State Backup
[2/4] incubator-brooklyn git commit: Docs: describe SoftwareProcess
lifecycle
Posted by he...@apache.org.
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)
[4/4] incubator-brooklyn git commit: This closes #548
Posted by he...@apache.org.
This closes #548
Project: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/commit/e8e0fced
Tree: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/tree/e8e0fced
Diff: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/diff/e8e0fced
Branch: refs/heads/master
Commit: e8e0fced35005fee1407ae4129f412cf578ace37
Parents: 0ff4216 fe4668c
Author: Alex Heneveld <al...@cloudsoftcorp.com>
Authored: Fri Mar 13 09:19:24 2015 +0000
Committer: Alex Heneveld <al...@cloudsoftcorp.com>
Committed: Fri Mar 13 09:19:24 2015 +0000
----------------------------------------------------------------------
docs/guide/dev/code/tests.md | 11 +++-
docs/guide/dev/tips/index.md | 1 +
docs/guide/java/entities.md | 104 ++++++++++++++++++++++++++++---
docs/guide/ops/persistence/index.md | 75 +++++++++++++++++-----
4 files changed, 162 insertions(+), 29 deletions(-)
----------------------------------------------------------------------