You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@brooklyn.apache.org by bostko <gi...@git.apache.org> on 2017/04/06 13:09:21 UTC

[GitHub] brooklyn-docs pull request #162: BROOKLYN-460: Brooklyn Camp syntax guidance

GitHub user bostko opened a pull request:

    https://github.com/apache/brooklyn-docs/pull/162

    BROOKLYN-460: Brooklyn Camp syntax guidance

    

You can merge this pull request into a Git repository by running:

    $ git pull https://github.com/bostko/brooklyn-docs yaml-tags

Alternatively you can review and apply these changes as the patch at:

    https://github.com/apache/brooklyn-docs/pull/162.patch

To close this pull request, make a commit to your master/trunk branch
with (at least) the following in the commit message:

    This closes #162
    
----
commit c24e01c4097e516f973c8203094fca0289ad54e2
Author: Valentin Aitken <bo...@gmail.com>
Date:   2017-04-06T13:08:55Z

    BROOKLYN-460: Brooklyn Camp syntax guidance

----


---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

[GitHub] brooklyn-docs pull request #162: BROOKLYN-460: Brooklyn Camp syntax guidance

Posted by drigodwin <gi...@git.apache.org>.
Github user drigodwin commented on a diff in the pull request:

    https://github.com/apache/brooklyn-docs/pull/162#discussion_r110367262
  
    --- Diff: guide/yaml/yaml-reference.md ---
    @@ -79,38 +79,44 @@ the entity being defined, with these being the most common:
       * `default`: a default value; this will be coerced to the declared `type`
       * `pinned`: mark the parameter as pinned (always displayed) for the UI. The default is `true`
       * `constraints`: a list of constraints the parameter should meet;
    -    for details, see [Entity Configuration]({{ site.path.guide }}/yaml/entity-configuration.html#config-key-constraints). 
    +    for details, see [Entity Configuration]({{ site.path.guide }}/yaml/entity-configuration.html#config-key-constraints).
     
       A shorthand notation is also supported where just the name of the parameter is supplied
       as an item in the list, with the other values being unset or the default.
       See `displayName` in the following example for an illustration of this:
     
    -~~~ yaml
    -brooklyn.parameters:
    -# user.age parameter is required, pinned and fully specified
    -- name: user.age
    +  ~~~ yaml
    +  brooklyn.parameters:
    +  # user.age parameter is required, pinned and fully specified
    +  - name: user.age
       type: integer
       label: Age
       description: the age of the user
       pinned: true
       constraints:
       - required
    -# user.name is optional, is not pinned and has a default
    -- name: user.name
    +  # user.name is optional, is not pinned and has a default
    +  - name: user.name
       default: You
       pinned: false
    -# shorthand notation: displayName will be an optional config of type string with no default
    -- displayName
    -~~~
    -
    -Entities, policies, and initializers may accept additional key-value pairs,
    -usually documented in their documentation (e.g. javadoc), or in the case of Java
    -often as static fields in the underlying Java class.
    -Often there are config keys or flags (indicated by `@SetFromFlag`) declared on the class; 
    -these declared flags and config keys may be passed in at the root of the `ServiceSpecification` or in `brooklyn.config`.
    -(Undeclared config is only accepted in the `brooklyn.config` map.)
    -Referencing the parameters from within java classes is identical to using config keys. In yaml it's
    -usually referenced using `$brooklyn:scopeRoot().config("displayName")`. See below for more details on scopes.
    +  # shorthand notation: displayName will be an optional config of type string with no default
    +  - displayName
    +  ~~~
    +
    +  Entities, policies, and initializers may accept additional key-value pairs,
    +  usually documented in their documentation (e.g. javadoc), or in the case of Java
    +  often as static fields in the underlying Java class.
    +  Often there are config keys or flags (indicated by `@SetFromFlag`) declared on the class;
    +  these declared flags and config keys may be passed in at the root of the `ServiceSpecification` or in `brooklyn.config`.
    +  (Undeclared config is only accepted in the `brooklyn.config` map.)
    +  Referencing the parameters from within java classes is identical to using config keys. In yaml it's
    +  usually referenced using `$brooklyn:scopeRoot().config("displayName")`. See below for more details on scopes.
    +
    +* `brooklyn.tags`: documents list of tag objects which should be assigned to the entity.<br/>
    --- End diff --
    
    documents **a** list of tag objects


---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

[GitHub] brooklyn-docs pull request #162: BROOKLYN-460: Brooklyn Camp syntax guidance

Posted by asfgit <gi...@git.apache.org>.
Github user asfgit closed the pull request at:

    https://github.com/apache/brooklyn-docs/pull/162


---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

[GitHub] brooklyn-docs pull request #162: BROOKLYN-460: Brooklyn Camp syntax guidance

Posted by geomacy <gi...@git.apache.org>.
Github user geomacy commented on a diff in the pull request:

    https://github.com/apache/brooklyn-docs/pull/162#discussion_r110369079
  
    --- Diff: guide/yaml/yaml-reference.md ---
    @@ -79,38 +79,44 @@ the entity being defined, with these being the most common:
       * `default`: a default value; this will be coerced to the declared `type`
       * `pinned`: mark the parameter as pinned (always displayed) for the UI. The default is `true`
       * `constraints`: a list of constraints the parameter should meet;
    -    for details, see [Entity Configuration]({{ site.path.guide }}/yaml/entity-configuration.html#config-key-constraints). 
    +    for details, see [Entity Configuration]({{ site.path.guide }}/yaml/entity-configuration.html#config-key-constraints).
     
       A shorthand notation is also supported where just the name of the parameter is supplied
       as an item in the list, with the other values being unset or the default.
       See `displayName` in the following example for an illustration of this:
     
    -~~~ yaml
    -brooklyn.parameters:
    -# user.age parameter is required, pinned and fully specified
    -- name: user.age
    +  ~~~ yaml
    +  brooklyn.parameters:
    +  # user.age parameter is required, pinned and fully specified
    +  - name: user.age
       type: integer
       label: Age
       description: the age of the user
       pinned: true
       constraints:
       - required
    -# user.name is optional, is not pinned and has a default
    -- name: user.name
    +  # user.name is optional, is not pinned and has a default
    +  - name: user.name
       default: You
       pinned: false
    -# shorthand notation: displayName will be an optional config of type string with no default
    -- displayName
    -~~~
    -
    -Entities, policies, and initializers may accept additional key-value pairs,
    -usually documented in their documentation (e.g. javadoc), or in the case of Java
    -often as static fields in the underlying Java class.
    -Often there are config keys or flags (indicated by `@SetFromFlag`) declared on the class; 
    -these declared flags and config keys may be passed in at the root of the `ServiceSpecification` or in `brooklyn.config`.
    -(Undeclared config is only accepted in the `brooklyn.config` map.)
    -Referencing the parameters from within java classes is identical to using config keys. In yaml it's
    -usually referenced using `$brooklyn:scopeRoot().config("displayName")`. See below for more details on scopes.
    +  # shorthand notation: displayName will be an optional config of type string with no default
    +  - displayName
    +  ~~~
    +
    +  Entities, policies, and initializers may accept additional key-value pairs,
    +  usually documented in their documentation (e.g. javadoc), or in the case of Java
    +  often as static fields in the underlying Java class.
    +  Often there are config keys or flags (indicated by `@SetFromFlag`) declared on the class;
    +  these declared flags and config keys may be passed in at the root of the `ServiceSpecification` or in `brooklyn.config`.
    +  (Undeclared config is only accepted in the `brooklyn.config` map.)
    +  Referencing the parameters from within java classes is identical to using config keys. In yaml it's
    +  usually referenced using `$brooklyn:scopeRoot().config("displayName")`. See below for more details on scopes.
    +
    +* `brooklyn.tags`: documents list of tag objects which should be assigned to the entity.<br/>
    +  A tag can be an object which is not of type `org.apache.brooklyn.util.core.task.DeferredSupplier`.<br/>
    --- End diff --
    
    Better to explain from a user's point of view, i.e. say that only some DSL is allowed, where values can be resolved immediately, i.e. basically can't use `attributeWhenReady` or anything with the same `whenReady` semantics.


---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

[GitHub] brooklyn-docs pull request #162: BROOKLYN-460: Brooklyn Camp syntax guidance

Posted by drigodwin <gi...@git.apache.org>.
Github user drigodwin commented on a diff in the pull request:

    https://github.com/apache/brooklyn-docs/pull/162#discussion_r110367351
  
    --- Diff: guide/yaml/yaml-reference.md ---
    @@ -79,38 +79,44 @@ the entity being defined, with these being the most common:
       * `default`: a default value; this will be coerced to the declared `type`
       * `pinned`: mark the parameter as pinned (always displayed) for the UI. The default is `true`
       * `constraints`: a list of constraints the parameter should meet;
    -    for details, see [Entity Configuration]({{ site.path.guide }}/yaml/entity-configuration.html#config-key-constraints). 
    +    for details, see [Entity Configuration]({{ site.path.guide }}/yaml/entity-configuration.html#config-key-constraints).
     
       A shorthand notation is also supported where just the name of the parameter is supplied
       as an item in the list, with the other values being unset or the default.
       See `displayName` in the following example for an illustration of this:
     
    -~~~ yaml
    -brooklyn.parameters:
    -# user.age parameter is required, pinned and fully specified
    -- name: user.age
    +  ~~~ yaml
    +  brooklyn.parameters:
    +  # user.age parameter is required, pinned and fully specified
    +  - name: user.age
       type: integer
       label: Age
       description: the age of the user
       pinned: true
       constraints:
       - required
    -# user.name is optional, is not pinned and has a default
    -- name: user.name
    +  # user.name is optional, is not pinned and has a default
    +  - name: user.name
       default: You
       pinned: false
    -# shorthand notation: displayName will be an optional config of type string with no default
    -- displayName
    -~~~
    -
    -Entities, policies, and initializers may accept additional key-value pairs,
    -usually documented in their documentation (e.g. javadoc), or in the case of Java
    -often as static fields in the underlying Java class.
    -Often there are config keys or flags (indicated by `@SetFromFlag`) declared on the class; 
    -these declared flags and config keys may be passed in at the root of the `ServiceSpecification` or in `brooklyn.config`.
    -(Undeclared config is only accepted in the `brooklyn.config` map.)
    -Referencing the parameters from within java classes is identical to using config keys. In yaml it's
    -usually referenced using `$brooklyn:scopeRoot().config("displayName")`. See below for more details on scopes.
    +  # shorthand notation: displayName will be an optional config of type string with no default
    +  - displayName
    +  ~~~
    +
    +  Entities, policies, and initializers may accept additional key-value pairs,
    +  usually documented in their documentation (e.g. javadoc), or in the case of Java
    +  often as static fields in the underlying Java class.
    +  Often there are config keys or flags (indicated by `@SetFromFlag`) declared on the class;
    +  these declared flags and config keys may be passed in at the root of the `ServiceSpecification` or in `brooklyn.config`.
    +  (Undeclared config is only accepted in the `brooklyn.config` map.)
    +  Referencing the parameters from within java classes is identical to using config keys. In yaml it's
    +  usually referenced using `$brooklyn:scopeRoot().config("displayName")`. See below for more details on scopes.
    +
    +* `brooklyn.tags`: documents list of tag objects which should be assigned to the entity.<br/>
    --- End diff --
    
    I also do not think there should be `<br />`s throughout this.


---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

[GitHub] brooklyn-docs pull request #162: BROOKLYN-460: Brooklyn Camp syntax guidance

Posted by drigodwin <gi...@git.apache.org>.
Github user drigodwin commented on a diff in the pull request:

    https://github.com/apache/brooklyn-docs/pull/162#discussion_r110367663
  
    --- Diff: guide/yaml/yaml-reference.md ---
    @@ -79,38 +79,44 @@ the entity being defined, with these being the most common:
       * `default`: a default value; this will be coerced to the declared `type`
       * `pinned`: mark the parameter as pinned (always displayed) for the UI. The default is `true`
       * `constraints`: a list of constraints the parameter should meet;
    -    for details, see [Entity Configuration]({{ site.path.guide }}/yaml/entity-configuration.html#config-key-constraints). 
    +    for details, see [Entity Configuration]({{ site.path.guide }}/yaml/entity-configuration.html#config-key-constraints).
     
       A shorthand notation is also supported where just the name of the parameter is supplied
       as an item in the list, with the other values being unset or the default.
       See `displayName` in the following example for an illustration of this:
     
    -~~~ yaml
    -brooklyn.parameters:
    -# user.age parameter is required, pinned and fully specified
    -- name: user.age
    +  ~~~ yaml
    +  brooklyn.parameters:
    +  # user.age parameter is required, pinned and fully specified
    +  - name: user.age
       type: integer
       label: Age
       description: the age of the user
       pinned: true
       constraints:
       - required
    -# user.name is optional, is not pinned and has a default
    -- name: user.name
    +  # user.name is optional, is not pinned and has a default
    +  - name: user.name
       default: You
       pinned: false
    -# shorthand notation: displayName will be an optional config of type string with no default
    -- displayName
    -~~~
    -
    -Entities, policies, and initializers may accept additional key-value pairs,
    -usually documented in their documentation (e.g. javadoc), or in the case of Java
    -often as static fields in the underlying Java class.
    -Often there are config keys or flags (indicated by `@SetFromFlag`) declared on the class; 
    -these declared flags and config keys may be passed in at the root of the `ServiceSpecification` or in `brooklyn.config`.
    -(Undeclared config is only accepted in the `brooklyn.config` map.)
    -Referencing the parameters from within java classes is identical to using config keys. In yaml it's
    -usually referenced using `$brooklyn:scopeRoot().config("displayName")`. See below for more details on scopes.
    +  # shorthand notation: displayName will be an optional config of type string with no default
    +  - displayName
    +  ~~~
    +
    +  Entities, policies, and initializers may accept additional key-value pairs,
    +  usually documented in their documentation (e.g. javadoc), or in the case of Java
    +  often as static fields in the underlying Java class.
    +  Often there are config keys or flags (indicated by `@SetFromFlag`) declared on the class;
    +  these declared flags and config keys may be passed in at the root of the `ServiceSpecification` or in `brooklyn.config`.
    +  (Undeclared config is only accepted in the `brooklyn.config` map.)
    +  Referencing the parameters from within java classes is identical to using config keys. In yaml it's
    +  usually referenced using `$brooklyn:scopeRoot().config("displayName")`. See below for more details on scopes.
    +
    +* `brooklyn.tags`: documents list of tag objects which should be assigned to the entity.<br/>
    +  A tag can be an object which is not of type `org.apache.brooklyn.util.core.task.DeferredSupplier`.<br/>
    --- End diff --
    
    What does this mean? Why is it important it's not of that specific type?


---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

[GitHub] brooklyn-docs pull request #162: BROOKLYN-460: Brooklyn Camp syntax guidance

Posted by drigodwin <gi...@git.apache.org>.
Github user drigodwin commented on a diff in the pull request:

    https://github.com/apache/brooklyn-docs/pull/162#discussion_r110367803
  
    --- Diff: guide/yaml/yaml-reference.md ---
    @@ -79,38 +79,44 @@ the entity being defined, with these being the most common:
       * `default`: a default value; this will be coerced to the declared `type`
       * `pinned`: mark the parameter as pinned (always displayed) for the UI. The default is `true`
       * `constraints`: a list of constraints the parameter should meet;
    -    for details, see [Entity Configuration]({{ site.path.guide }}/yaml/entity-configuration.html#config-key-constraints). 
    +    for details, see [Entity Configuration]({{ site.path.guide }}/yaml/entity-configuration.html#config-key-constraints).
     
       A shorthand notation is also supported where just the name of the parameter is supplied
       as an item in the list, with the other values being unset or the default.
       See `displayName` in the following example for an illustration of this:
     
    -~~~ yaml
    -brooklyn.parameters:
    -# user.age parameter is required, pinned and fully specified
    -- name: user.age
    +  ~~~ yaml
    +  brooklyn.parameters:
    +  # user.age parameter is required, pinned and fully specified
    +  - name: user.age
       type: integer
       label: Age
       description: the age of the user
       pinned: true
       constraints:
       - required
    -# user.name is optional, is not pinned and has a default
    -- name: user.name
    +  # user.name is optional, is not pinned and has a default
    +  - name: user.name
       default: You
       pinned: false
    -# shorthand notation: displayName will be an optional config of type string with no default
    -- displayName
    -~~~
    -
    -Entities, policies, and initializers may accept additional key-value pairs,
    -usually documented in their documentation (e.g. javadoc), or in the case of Java
    -often as static fields in the underlying Java class.
    -Often there are config keys or flags (indicated by `@SetFromFlag`) declared on the class; 
    -these declared flags and config keys may be passed in at the root of the `ServiceSpecification` or in `brooklyn.config`.
    -(Undeclared config is only accepted in the `brooklyn.config` map.)
    -Referencing the parameters from within java classes is identical to using config keys. In yaml it's
    -usually referenced using `$brooklyn:scopeRoot().config("displayName")`. See below for more details on scopes.
    +  # shorthand notation: displayName will be an optional config of type string with no default
    +  - displayName
    +  ~~~
    +
    +  Entities, policies, and initializers may accept additional key-value pairs,
    +  usually documented in their documentation (e.g. javadoc), or in the case of Java
    +  often as static fields in the underlying Java class.
    +  Often there are config keys or flags (indicated by `@SetFromFlag`) declared on the class;
    +  these declared flags and config keys may be passed in at the root of the `ServiceSpecification` or in `brooklyn.config`.
    +  (Undeclared config is only accepted in the `brooklyn.config` map.)
    +  Referencing the parameters from within java classes is identical to using config keys. In yaml it's
    +  usually referenced using `$brooklyn:scopeRoot().config("displayName")`. See below for more details on scopes.
    +
    +* `brooklyn.tags`: documents list of tag objects which should be assigned to the entity.<br/>
    +  A tag can be an object which is not of type `org.apache.brooklyn.util.core.task.DeferredSupplier`.<br/>
    +  **Tags must be simple objects** which can be serialized in persistence state and when retrieved by the REST API.<br/>
    --- End diff --
    
    persisted state


---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---