Java docs: incorporate review comments from #24 Project: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/repo Commit: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/commit/15898db2 Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/tree/15898db2 Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/diff/15898db2
Branch: refs/heads/master Commit: 15898db2c7f0aa519dd3d0c24cf392e74c28366d Parents: 44e812b Author: Aled Sage <aled.s...@gmail.com> Authored: Thu Mar 10 13:22:51 2016 +0000 Committer: Aled Sage <aled.s...@gmail.com> Committed: Thu Mar 10 13:22:51 2016 +0000 ---------------------------------------------------------------------- guide/java/common-usage.md | 8 +++--- guide/java/defining-and-deploying.md | 19 ++++++++------ guide/java/feeds.md | 4 ++- guide/java/java_app/ExampleWebApp.java | 40 ++++++++++++++++++++++++++--- guide/java/topology-dependencies.md | 10 +++++--- 5 files changed, 62 insertions(+), 19 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/15898db2/guide/java/common-usage.md ---------------------------------------------------------------------- diff --git a/guide/java/common-usage.md b/guide/java/common-usage.md index d0f7ec5..ccafd9b 100644 --- a/guide/java/common-usage.md +++ b/guide/java/common-usage.md @@ -39,9 +39,11 @@ public static final ConfigKey<String> ROOT_WAR = new ConfigKeys.newStringConfigK "WAR file to deploy as the ROOT, as URL (supporting file: and classpath: prefixes)"); {% endhighlight %} -One can optional define a `@SetFromFlag("war")`. This defines a short-hand for configuring the -entity. However, it should be used with caution - the long form defined in the constructor should -be meaningful and sufficient. Its use may be deprecated in a future release. +One can optionally define a `@SetFromFlag("war")`. This defines a short-hand for configuring the +entity. However, it should be used with caution - when using configuration set on a parent entity +(and thus inherited), the `@SetFromFlag` short-form names are not checked. The long form defined +in the constructor should be meaningful and sufficient. The usage of `@SetFromFlag` is therefore +discouraged. The type `AttributeSensorAndConfigKey<?>` can be used to indicate that a config key should be resolved, and its value set as a sensor on the entity (when `ConfigToAttributes.apply(entity)` is called). http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/15898db2/guide/java/defining-and-deploying.md ---------------------------------------------------------------------- diff --git a/guide/java/defining-and-deploying.md b/guide/java/defining-and-deploying.md index fda711b..d754c82 100644 --- a/guide/java/defining-and-deploying.md +++ b/guide/java/defining-and-deploying.md @@ -51,14 +51,15 @@ To describe each part of this: have extended one of the other sub-types of Entity. * The `OAUTH_KEY` is a configuration key - it is configuration that can be set on the entity when it is being instantiated. -* The `@Effector` annotation indicates the the given method is an effector, so should be presented +* The `@Effector` annotation indicates that the given method is an effector, so should be presented and tracked as such. Execution of the effector is intercepted, to track it as a task and show its execution in the Activity view. -* The `@EffectorParam` annotations give metadata about the effector's parameters. These will be - presented in users of the entity, e.g. when invoking the effector via the web-console. +* The `@EffectorParam` annotations give metadata about the effector's parameters. This metadata, + such as the parameter description, is available to those using the client CLI, rest API and + web-console. Note there is an alternative way of defining effectors - adding them to the entity dynamically, -discussed in the section [Dynamic Effectors](dynamic_effectors.html). +discussed in the section [Dynamically Added Effectors](common-usage.html#dynamically-added-effectors). Next lets add the implementation. Create a new Java class named `GistGeneratorImpl`. @@ -128,9 +129,9 @@ for how to store these credentials more securely. ## Building the OSGi Bundle -We will build this as an [OSGi Bundle](https://www.osgi.org/developer/architecture/) so that it -can be added to the Apache Brooklyn server at runtime, and so multiple versions of the blueprint -can be managed. +Next we will build this example as an [OSGi Bundle](https://www.osgi.org/developer/architecture/) +so that it can be added to the Apache Brooklyn server at runtime, and so multiple versions of the +blueprint can be managed. The `mvn clean install` will automatically do this, creating a jar inside the `target/` sub-directory of the project. This works by using the @@ -156,7 +157,9 @@ available for test purposes.* The command below will use the REST api to add this to the catalog of a running Brooklyn instance. Substitute the credentials, URL and port for those of your server. - curl -u admin:pa55w0rd https://127.0.0.1:8443/v1/catalog --data-binary @gist_generator.bom +{% highlight bash %} +$ curl -u admin:pa55w0rd https://127.0.0.1:8443/v1/catalog --data-binary @gist_generator.bom +{% endhighlight %} ## Using the blueprint http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/15898db2/guide/java/feeds.md ---------------------------------------------------------------------- diff --git a/guide/java/feeds.md b/guide/java/feeds.md index 88e005d..2395b16 100644 --- a/guide/java/feeds.md +++ b/guide/java/feeds.md @@ -7,7 +7,9 @@ layout: website-normal ### Feeds -A `Feed` is used to populate an entity's sensors. A variety of feed types are available. +`Feed`s within Apache Brooklyn are used to populate an entity's sensors. There are a variety of +feed types, which commonly poll to retrieve the raw metrics of the entity (for example polling an +HTTP management API, or over JMX). #### Persistence http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/15898db2/guide/java/java_app/ExampleWebApp.java ---------------------------------------------------------------------- diff --git a/guide/java/java_app/ExampleWebApp.java b/guide/java/java_app/ExampleWebApp.java index 97b6910..525a2bd 100644 --- a/guide/java/java_app/ExampleWebApp.java +++ b/guide/java/java_app/ExampleWebApp.java @@ -1,30 +1,62 @@ package com.acme.autobrick; import org.apache.brooklyn.api.entity.EntitySpec; +import org.apache.brooklyn.api.policy.PolicySpec; +import org.apache.brooklyn.api.sensor.AttributeSensor; +import org.apache.brooklyn.api.sensor.EnricherSpec; import org.apache.brooklyn.core.entity.AbstractApplication; import org.apache.brooklyn.core.sensor.DependentConfiguration; +import org.apache.brooklyn.core.sensor.Sensors; +import org.apache.brooklyn.enricher.stock.Enrichers; import org.apache.brooklyn.entity.database.mysql.MySqlNode; import org.apache.brooklyn.entity.group.DynamicCluster; import org.apache.brooklyn.entity.proxy.nginx.NginxController; import org.apache.brooklyn.entity.webapp.tomcat.TomcatServer; +import org.apache.brooklyn.policy.autoscaling.AutoScalerPolicy; +import org.apache.brooklyn.policy.ha.ServiceFailureDetector; +import org.apache.brooklyn.policy.ha.ServiceReplacer; +import org.apache.brooklyn.policy.ha.ServiceRestarter; +import org.apache.brooklyn.util.time.Duration; public class ExampleWebApp extends AbstractApplication { @Override public void init() { + AttributeSensor<Double> reqsPerSecPerNodeSensor = Sensors.newDoubleSensor( + "webapp.reqs.perSec.perNode", + "Reqs/sec averaged over all nodes"); + MySqlNode db = addChild(EntitySpec.create(MySqlNode.class) .configure(MySqlNode.CREATION_SCRIPT_URL, "https://bit.ly/brooklyn-visitors-creation-script";)); DynamicCluster cluster = addChild(EntitySpec.create(DynamicCluster.class) + .displayName("Cluster") .configure(DynamicCluster.MEMBER_SPEC, EntitySpec.create(TomcatServer.class) .configure(TomcatServer.ROOT_WAR, - "wars.root: http://search.maven.org/remotecontent?filepath=org/apache/brooklyn/example/brooklyn-example-hello-world-sql-webapp/0.8.0-incubating/brooklyn-example-hello-world-sql-webapp-0.8.0-incubating.war";) + "http://search.maven.org/remotecontent?filepath=org/apache/brooklyn/example/brooklyn-example-hello-world-sql-webapp/0.8.0-incubating/brooklyn-example-hello-world-sql-webapp-0.8.0-incubating.war";) .configure(TomcatServer.JAVA_SYSPROPS.subKey("brooklyn.example.db.url"), DependentConfiguration.formatString("jdbc:%s%s?user=%s&password=%s", DependentConfiguration.attributeWhenReady(db, MySqlNode.DATASTORE_URL), - "visitors", "brooklyn", "br00k11n")))); - + "visitors", "brooklyn", "br00k11n")) + .policy(PolicySpec.create(ServiceRestarter.class) + .configure(ServiceRestarter.FAIL_ON_RECURRING_FAILURES_IN_THIS_DURATION, Duration.minutes(5))) + .enricher(EnricherSpec.create(ServiceFailureDetector.class) + .configure(ServiceFailureDetector.ENTITY_FAILED_STABILIZATION_DELAY, Duration.seconds(30)))) + .policy(PolicySpec.create(ServiceReplacer.class)) + .policy(PolicySpec.create(AutoScalerPolicy.class) + .configure(AutoScalerPolicy.METRIC, reqsPerSecPerNodeSensor) + .configure(AutoScalerPolicy.METRIC_LOWER_BOUND, 1) + .configure(AutoScalerPolicy.METRIC_UPPER_BOUND, 3) + .configure(AutoScalerPolicy.RESIZE_UP_STABILIZATION_DELAY, Duration.seconds(2)) + .configure(AutoScalerPolicy.RESIZE_DOWN_STABILIZATION_DELAY, Duration.minutes(1)) + .configure(AutoScalerPolicy.MAX_POOL_SIZE, 3)) + .enricher(Enrichers.builder().aggregating(TomcatServer.REQUESTS_PER_SECOND_IN_WINDOW) + .computingAverage() + .fromMembers() + .publishing(reqsPerSecPerNodeSensor) + .build())); addChild(EntitySpec.create(NginxController.class) - .configure(NginxController.SERVER_POOL, cluster)); + .configure(NginxController.SERVER_POOL, cluster) + .configure(NginxController.STICKY, false)); } } http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/15898db2/guide/java/topology-dependencies.md ---------------------------------------------------------------------- diff --git a/guide/java/topology-dependencies.md b/guide/java/topology-dependencies.md index a1b86ca..93bbce3 100644 --- a/guide/java/topology-dependencies.md +++ b/guide/java/topology-dependencies.md @@ -10,7 +10,9 @@ recommended. ## Define your Application Blueprint The example below creates a three tier web service, composed of an Nginx load-balancer, -a cluster of Tomcat app-servers, and a MySQL database: +a cluster of Tomcat app-servers, and a MySQL database. It is similar to the [YAML policies +example]({{ site.path.guide }}/start/policies.html), but also includes the MySQL database +to demonstrate the use of dependent configuration. {% highlight java %} {% readj java_app/ExampleWebApp.java %} @@ -25,9 +27,11 @@ To describe each part of this: its type and its configuration. * The `brooklyn.example.db.url` is a system property that will be passed to each `TomcatServer` instance. Its value is the database's URL (discussed below). +* The policies and enrichers provide in-life management of the application, to restart failed + instances and to replace those components that repeatedly fail. * The `NginxController` is the load-balancer and reverse-proxy: by default, it round-robins to the ip:port of each member of the cluster configured as the `SERVER_POOL`. - + ## Dependent Configuration @@ -36,7 +40,7 @@ information is only available at runtime (e.g. it requires the IP of a dynamical component). For example, the app-servers in the example above require the database URL to be injected. -The "DependentConfiguration" methods returns a return a future (or a "promise" in the language of +The "DependentConfiguration" methods returns a future (or a "promise" in the language of some other programming languages): when the value is needed, the caller will block to wait for the future to resolve. It will block only "at the last moment" when the value is needed (e.g. after the VMs have been provisioned and the software is installed, thus optimising the
