This closes #266

apache · Aug 30, 2018 · 97515cbc7650e805042f6a515e80e5f80c6021b4 · 97515cb
2 parents 740913f + fbc27ca
commit 97515cbc7650e805042f6a515e80e5f80c6021b4
Showing 21 changed files with 104 additions and 102 deletions.
diff --git a/guide/blueprints/entity-configuration.md b/guide/blueprints/entity-configuration.md
@@ -41,37 +41,13 @@ blueprint (i.e. inside the `brooklyn.config` block).
 It can also explicitly declare config keys, using the `brooklyn.parameters` block. The example 
 below illustrates the principle:
 
-```yaml
-brooklyn.catalog:
-  items:
-  - id: entity-config-example
-    itemType: entity
-    name: Entity Config Example
-    item:
-      type: org.apache.brooklyn.entity.software.base.VanillaSoftwareProcess
-      brooklyn.parameters:
-      - name: custom.message
-        type: string
-        description: Message to be displayed
-        default: Hello
-      brooklyn.config:
-        shell.env:
-          MESSAGE: $brooklyn:config("custom.message")
-        launch.command: |
-          echo "My example launch command: $MESSAGE"
-        checkRunning.command: |
-          echo "My example checkRunning command: $MESSAGE"
-```
+!CODEFILE "example_yaml/entity-config-catalog.yaml"
 
 Once added to the catalog, it can be used with the simple blueprint below (substituting the location
 of your choice). Because no configuration has been overridden, this will use the default value
 for `custom.message`, and will use the given values for `launch.command` and `checkRunning.command`:
 
-```yaml
-location: aws-ec2:us-east-1
-services:
-- type: entity-config-example
-```
+!CODEFILE "example_yaml/entity-config-app.yaml"
 
 For details of how to write and add catalog items, see [Catalog]({{book.path.docs}}/blueprints/catalog/index.md), 
 and for a complete reference on the syntax of `brooklyn.parameters` see that section of the [YAML Reference]({{book.path.docs}}/blueprints/yaml-reference.md). 
@@ -89,48 +65,11 @@ can be any of:
 
 This is illustrated in the example below:
 
-```yaml
-brooklyn.catalog:
-  items:
-  - id: entity-constraint-example
-    itemType: entity
-    name: Entity Config Example
-    item:
-      type: org.apache.brooklyn.entity.stock.BasicEntity
-      brooklyn.parameters:
-      - name: compulsoryExample
-        type: string
-        constraints:
-        - required
-      - name: addressExample
-        type: string
-        constraints:
-        - regex: ^(?:[0-9]{1,3}\.){3}[0-9]{1,3}$
-      - name: numberExample
-        type: double
-        constraints:
-        - $brooklyn:object:
-            type: org.apache.brooklyn.util.math.MathPredicates
-            factoryMethod.name: greaterThan
-            factoryMethod.args:
-            - 0.0
-        - $brooklyn:object:
-            type: org.apache.brooklyn.util.math.MathPredicates
-            factoryMethod.name: lessThan
-            factoryMethod.args:
-            - 256.0
-```
+!CODEFILE "example_yaml/entity-constraint-catalog.yaml"
 
 An example usage of this toy example, once added to the catalog, is shown below:
 
-```yaml
-services:
-- type: entity-constraint-example
-  brooklyn.config:
-    compulsoryExample: foo
-    addressExample: 1.1.1.1
-    numberExample: 2.0
-```
+!CODEFILE "example_yaml/entity-constraint-app.yaml"
 
 
 ### Inheriting Configuration
@@ -165,16 +104,7 @@ consider the `entity-config-example` added to the catalog in the section
 [Configuration in a Catalog Item](#configuration-in-a-catalog-item).
 We can override these values. If not overridden, then the existing values from the super-type will be used:
 
-```yaml
-location: aws-ec2:us-east-1
-services:
-- type: entity-config-example
-  brooklyn.config:
-    custom.message: Goodbye
-    launch.command: |
-      echo "Sub-type launch command: $MESSAGE"
-```
-
+!CODEFILE "example_yaml/entity-config-override-app.yaml"
 
 
 In this example, the `custom.message` overrides the default defined on the config key.

diff --git a/guide/blueprints/example_yaml/appserver-clustered-w-db-concise.yaml b/guide/blueprints/example_yaml/appserver-clustered-w-db-concise.yaml
@@ -12,4 +12,4 @@ services:
   name: DB HelloWorld Visitors
   brooklyn.config:
     creation.script.password: $brooklyn:external("brooklyn-demo-sample", "hidden-brooklyn-password")
-    datastore.creation.script.url: https://github.com/apache/brooklyn-library/blob/master/examples/simple-web-cluster/src/main/resources/visitors-creation-script.sql
+    datastore.creation.script.template.url: https://github.com/apache/brooklyn-library/blob/master/examples/simple-web-cluster/src/main/resources/visitors-creation-script.sql
diff --git a/guide/blueprints/example_yaml/appserver-clustered-w-db.yaml b/guide/blueprints/example_yaml/appserver-clustered-w-db.yaml
@@ -12,7 +12,7 @@ services:
           java.sysprops:
             brooklyn.example.db.url:
               $brooklyn:formatString:
-                - jdbc:%s%s?user=%s\\&password=%s
+                - "jdbc:%s%s?user=%s&password=%s"
                 - $brooklyn:component("db").attributeWhenReady("datastore.url")
                 - visitors
                 - brooklyn
@@ -22,5 +22,5 @@ services:
   name: DB HelloWorld Visitors
   brooklyn.config:
     creation.script.password: $brooklyn:external("brooklyn-demo-sample", "hidden-brooklyn-password")
-    datastore.creation.script.url: https://github.com/apache/brooklyn-library/blob/master/examples/simple-web-cluster/src/main/resources/visitors-creation-script.sql
+    datastore.creation.script.template.url: https://github.com/apache/brooklyn-library/blob/master/examples/simple-web-cluster/src/main/resources/visitors-creation-script.sql
 
diff --git a/guide/blueprints/example_yaml/appserver-w-db-other-flavor.yaml b/guide/blueprints/example_yaml/appserver-w-db-other-flavor.yaml
@@ -8,7 +8,7 @@ services:
     java.sysprops: 
       brooklyn.example.db.url:
         $brooklyn:formatString:
-          - jdbc:%s%s?user=%s\\&password=%s
+          - "jdbc:%s%s?user=%s&password=%s"
           - $brooklyn:component("db").attributeWhenReady("datastore.url")
           - visitors
           - brooklyn
@@ -18,6 +18,6 @@ services:
   name: DB HelloWorld Visitors
   brooklyn.config:
     creation.script.password: $brooklyn:external("brooklyn-demo-sample", "hidden-brooklyn-password")
-    datastore.creation.script.url: https://github.com/apache/brooklyn-library/raw/master/examples/simple-web-cluster/src/main/resources/visitors-creation-script.sql
+    datastore.creation.script.template.url: https://github.com/apache/brooklyn-library/raw/master/examples/simple-web-cluster/src/main/resources/visitors-creation-script.sql
     provisioning.properties:
       minRam: 8192
diff --git a/guide/blueprints/example_yaml/appserver-w-db.yaml b/guide/blueprints/example_yaml/appserver-w-db.yaml
@@ -8,7 +8,7 @@ services:
     java.sysprops: 
       brooklyn.example.db.url:
         $brooklyn:formatString:
-          - jdbc:%s%s?user=%s\\&password=%s
+          - "jdbc:%s%s?user=%s&password=%s"
           - $brooklyn:component("db").attributeWhenReady("datastore.url")
           - visitors
           - brooklyn
@@ -18,4 +18,4 @@ services:
   name: DB HelloWorld Visitors
   brooklyn.config:
     creation.script.password: $brooklyn:external("brooklyn-demo-sample", "hidden-brooklyn-password")
-    datastore.creation.script.url: https://github.com/apache/brooklyn-library/raw/master/examples/simple-web-cluster/src/main/resources/visitors-creation-script.sql
+    datastore.creation.script.template.url: https://github.com/apache/brooklyn-library/raw/master/examples/simple-web-cluster/src/main/resources/visitors-creation-script.sql
diff --git a/guide/blueprints/example_yaml/appserver-w-policy.yaml b/guide/blueprints/example_yaml/appserver-w-policy.yaml
@@ -12,7 +12,7 @@ services:
           java.sysprops:
             brooklyn.example.db.url:
               $brooklyn:formatString:
-              - jdbc:%s%s?user=%s\\&password=%s
+              - "jdbc:%s%s?user=%s&password=%s"
               - $brooklyn:component("db").attributeWhenReady("datastore.url")
               - visitors
               - brooklyn
@@ -30,4 +30,4 @@ services:
   name: DB HelloWorld Visitors
   brooklyn.config:
     creation.script.password: $brooklyn:external("brooklyn-demo-sample", "hidden-brooklyn-password")
-    datastore.creation.script.url: https://github.com/apache/brooklyn-library/raw/master/examples/simple-web-cluster/src/main/resources/visitors-creation-script.sql
+    datastore.creation.script.template.url: https://github.com/apache/brooklyn-library/raw/master/examples/simple-web-cluster/src/main/resources/visitors-creation-script.sql
diff --git a/guide/blueprints/example_yaml/entity-config-app.yaml b/guide/blueprints/example_yaml/entity-config-app.yaml
@@ -0,0 +1,4 @@
+location: aws-ec2:us-east-1
+name: entity-config-example
+services:
+- type: entity-config-example
diff --git a/guide/blueprints/example_yaml/entity-config-catalog.yaml b/guide/blueprints/example_yaml/entity-config-catalog.yaml
@@ -0,0 +1,19 @@
+brooklyn.catalog:
+  items:
+  - id: entity-config-example
+    itemType: entity
+    name: Entity Config Example
+    item:
+      type: org.apache.brooklyn.entity.software.base.VanillaSoftwareProcess
+      brooklyn.parameters:
+      - name: custom.message
+        type: string
+        description: Message to be displayed
+        default: Hello
+      brooklyn.config:
+        shell.env:
+          MESSAGE: $brooklyn:config("custom.message")
+        launch.command: |
+          echo "My example launch command: $MESSAGE"
+        checkRunning.command: |
+          echo "My example checkRunning command: $MESSAGE"
diff --git a/guide/blueprints/example_yaml/entity-config-override-app.yaml b/guide/blueprints/example_yaml/entity-config-override-app.yaml
@@ -0,0 +1,8 @@
+location: aws-ec2:us-east-1
+name: entity-config-override-example
+services:
+- type: entity-config-example
+  brooklyn.config:
+    custom.message: Goodbye
+    launch.command: |
+      echo "Sub-type launch command: $MESSAGE"
diff --git a/guide/blueprints/example_yaml/entity-constraint-app.yaml b/guide/blueprints/example_yaml/entity-constraint-app.yaml
@@ -0,0 +1,7 @@
+name: entity-constraint-example
+services:
+- type: entity-constraint-example
+  brooklyn.config:
+    compulsoryExample: foo
+    addressExample: 1.1.1.1
+    numberExample: 2.0
diff --git a/guide/blueprints/example_yaml/entity-constraint-catalog.yaml b/guide/blueprints/example_yaml/entity-constraint-catalog.yaml
@@ -0,0 +1,29 @@
+brooklyn.catalog:
+  items:
+  - id: entity-constraint-example
+    itemType: entity
+    name: Entity Config Example
+    item:
+      type: org.apache.brooklyn.entity.stock.BasicEntity
+      brooklyn.parameters:
+      - name: compulsoryExample
+        type: string
+        constraints:
+        - required
+      - name: addressExample
+        type: string
+        constraints:
+        - regex: ^(?:[0-9]{1,3}\.){3}[0-9]{1,3}$
+      - name: numberExample
+        type: double
+        constraints:
+        - $brooklyn:object:
+            type: org.apache.brooklyn.util.math.MathPredicates
+            factoryMethod.name: greaterThan
+            factoryMethod.args:
+            - 0.0
+        - $brooklyn:object:
+            type: org.apache.brooklyn.util.math.MathPredicates
+            factoryMethod.name: lessThan
+            factoryMethod.args:
+            - 256.0
diff --git a/guide/blueprints/example_yaml/fabric-with-multiple-locations.yaml b/guide/blueprints/example_yaml/fabric-with-multiple-locations.yaml
@@ -5,7 +5,7 @@ locations:
 services:
 - type: org.apache.brooklyn.entity.group.DynamicFabric
   brooklyn.config:
-    dynamiccfabric.memberspec:
+    dynamicfabric.memberspec:
       $brooklyn:entitySpec:
         type: org.apache.brooklyn.entity.group.DynamicCluster
         brooklyn.config:

diff --git a/guide/blueprints/example_yaml/vanilla-bash-netcat-file.yaml b/guide/blueprints/example_yaml/vanilla-bash-netcat-file.yaml
@@ -6,5 +6,6 @@ services:
   brooklyn.config:
     download.url: file:///tmp/netcat-server.tgz
     launch.command: |
+      chmod +x start.sh
       ./start.sh &
       echo $! > $PID_FILE
diff --git a/guide/blueprints/example_yaml/vanilla-bash-netcat-w-client.yaml b/guide/blueprints/example_yaml/vanilla-bash-netcat-w-client.yaml
@@ -66,7 +66,11 @@ services:
       name: sayHiNetcat
       description: Echo a small hello string to the netcat entity
       command: |
-        echo $message | nc $TARGET_HOSTNAME 4321
+        # Uncomment the appropriate command for your operating system
+        # for Linux:
+        # echo $message | nc -N $TARGET_HOSTNAME 4321
+        # for MacOS:
+        # echo $message | nc $TARGET_HOSTNAME 4321
       parameters:
         message:
           description: The string to pass to netcat

diff --git a/guide/blueprints/test/example_yaml/testcases/getting-started-test-example.yaml b/guide/blueprints/test/example_yaml/testcases/getting-started-test-example.yaml
@@ -21,7 +21,7 @@ services:
   name: My DB
   brooklyn.config:
     creation.script.password: $brooklyn:external("brooklyn-demo-sample", "hidden-brooklyn-password")
-    datastore.creation.script.url: https://bit.ly/brooklyn-visitors-creation-script
+    datastore.creation.script.template.url: https://bit.ly/brooklyn-visitors-creation-script
 - type: org.apache.brooklyn.test.framework.TestHttpCall
   name: Check HTTP Response Status Code
   brooklyn.config:

diff --git a/guide/ops/cli/cli-usage-guide.md b/guide/ops/cli/cli-usage-guide.md
@@ -109,29 +109,29 @@ command:
 
 ```text
 $ br app WebCluster entity thHnLFkP config
-Key                             Value   
-install.unique_label            MySqlNode_5.6.26   
-brooklyn.wrapper_app            true   
-datastore.creation.script.url   https://bit.ly/brooklyn-visitors-creation-script   
-camp.template.id                dnw3GqN0   
-camp.plan.id                    db   
-onbox.base.dir                  /home/vagrant/brooklyn-managed-processes   
-onbox.base.dir.resolved         true   
+Key                                      Value   
+install.unique_label                     MySqlNode_5.6.26   
+brooklyn.wrapper_app                     true   
+datastore.creation.script.template.url   https://bit.ly/brooklyn-visitors-creation-script   
+camp.template.id                         dnw3GqN0   
+camp.plan.id                             db   
+onbox.base.dir                           /home/vagrant/brooklyn-managed-processes   
+onbox.base.dir.resolved                  true   
 
 ```
 
 The value of a single configuration item can be displayed by using the configuration key
 as a parameter for the `config` command:
 
 ```text
-$ br app WebCluster entity thHnLFkP config datastore.creation.script.url
+$ br app WebCluster entity thHnLFkP config datastore.creation.script.template.url
 https://bit.ly/brooklyn-visitors-creation-script
 ```
 
 The value of a configuration item can be changed by using the `set` command:
 
 ```text
-$ br app WebCluster entity thHnLFkP config datastore.creation.script.url set \"https://bit.ly/new-script\"
+$ br app WebCluster entity thHnLFkP config datastore.creation.script.template.url set \"https://bit.ly/new-script\"
 ```
 
 ## Sensors

diff --git a/guide/ops/externalized-configuration.md b/guide/ops/externalized-configuration.md
@@ -31,7 +31,7 @@ services:
     java.sysprops:
       brooklyn.example.db.url: 
         $brooklyn:formatString:
-          - jdbc:postgresql://%s/myappdb?user=%s\\&password=%s
+          - "jdbc:postgresql://%s/myappdb?user=%s&password=%s"
           - $brooklyn:external("servers", "postgresql")
           - $brooklyn:external("credentials", "postgresql-user")
           - $brooklyn:external("credentials", "postgresql-password")

diff --git a/guide/ops/gui/_my-web-cluster.yaml b/guide/ops/gui/_my-web-cluster.yaml
@@ -21,4 +21,4 @@ services:
   id: db
   brooklyn.config:
     creation.script.password: $brooklyn:external("brooklyn-demo-sample", "hidden-brooklyn-password")
-    datastore.creation.script.url: https://bit.ly/brooklyn-visitors-creation-script
+    datastore.creation.script.template.url: https://bit.ly/brooklyn-visitors-creation-script
diff --git a/guide/ops/gui/_my-web-cluster2.yaml b/guide/ops/gui/_my-web-cluster2.yaml
@@ -29,4 +29,4 @@ services:
   name: My DB
   brooklyn.config:
     creation.script.password: $brooklyn:external("brooklyn-demo-sample", "hidden-brooklyn-password")
-    datastore.creation.script.url: https://bit.ly/brooklyn-visitors-creation-script
+    datastore.creation.script.template.url: https://bit.ly/brooklyn-visitors-creation-script
diff --git a/guide/start/_my-web-cluster.yaml b/guide/start/_my-web-cluster.yaml
@@ -21,4 +21,4 @@ services:
   id: db
   brooklyn.config:
     creation.script.password: $brooklyn:external("brooklyn-demo-sample", "hidden-brooklyn-password")
-    datastore.creation.script.url: https://bit.ly/brooklyn-visitors-creation-script
+    datastore.creation.script.template.url: https://bit.ly/brooklyn-visitors-creation-script
diff --git a/guide/start/_my-web-cluster2.yaml b/guide/start/_my-web-cluster2.yaml
@@ -29,4 +29,4 @@ services:
   name: My DB
   brooklyn.config:
     creation.script.password: $brooklyn:external("brooklyn-demo-sample", "hidden-brooklyn-password")
-    datastore.creation.script.url: https://bit.ly/brooklyn-visitors-creation-script
+    datastore.creation.script.template.url: https://bit.ly/brooklyn-visitors-creation-script