You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@brooklyn.apache.org by GitBox <gi...@apache.org> on 2022/06/27 12:06:44 UTC
[GitHub] [brooklyn-docs] ahgittin opened a new pull request, #358: add docs for new predicates dsl
ahgittin opened a new pull request, #358:
URL: https://github.com/apache/brooklyn-docs/pull/358
documentation for brooklyn server PR (reference to follow)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@brooklyn.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [brooklyn-docs] ahgittin commented on pull request #358: add docs for new predicates dsl
Posted by GitBox <gi...@apache.org>.
ahgittin commented on PR #358:
URL: https://github.com/apache/brooklyn-docs/pull/358#issuecomment-1167536156
thanks for fixing!
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@brooklyn.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [brooklyn-docs] algairim merged pull request #358: add docs for new predicates dsl
Posted by GitBox <gi...@apache.org>.
algairim merged PR #358:
URL: https://github.com/apache/brooklyn-docs/pull/358
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@brooklyn.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [brooklyn-docs] iuliana commented on a diff in pull request #358: add docs for new predicates dsl
Posted by GitBox <gi...@apache.org>.
iuliana commented on code in PR #358:
URL: https://github.com/apache/brooklyn-docs/pull/358#discussion_r907528444
##########
guide/blueprints/yaml-reference.md:
##########
@@ -323,3 +327,145 @@ These are:
including `config-widgets` (setting custom widgets to render fields) and `config-quick-fixes` (proposals for fixing common errors);
see the code for the Blueprint Composer for more details
+## Predicate DSL
+
+In contexts where a `DslPredicate` or `DslEntityPredicate` is expected, the `$brooklyn:object`
+DSL can be used to construct any suitable implementation, such as using factory methods from `EntityPredicates`.
+In many cases, however, a simplified YAML DSL can be used,
+as defined by the Jackson deserialization rules on the `DslPredicate`.
+
+In its simplest form this can be a map containing the test or tests, e.g.:
+
+```
+equals: north
+```
+
+This will result in a `Predicate` which returns true if asked to `test("north")`,
+and false otherwise. The full set of individual tests are:
+
+* `equals: <object>`, to test java object equality, attempting type coercion if necessary
+* `regex: <string|number>`
+* `glob: <string|number>`
+* `when: <presence>`, where `<presence>` is one of the values described below
+* `less-than: <object>`, for strings and primitives, computed using "natural ordering",
+ numeric order for numbers and digit sequences within numbers (`"9" < "10"`),
+ and ASCII-lexicographic comparison elsewhere (`"a" < "b"`);
+ otherwise if both arguments are the same type, or one a subtype of the other, and both comparable,
+ it will use that type's compare method;
+ otherwise if one side side is JSON, it will attempt coercion to the other argument's type;
+ and otherwise it will return false
+* `greater-than: <object>`, as above
+* `less-than-or-equal-to: <object>` as above
+* `greater-than-or-equal-to: <object>, as above
+* `in-range: <range>`, where `<range>` is a list of two numbers, e.g. `[0,100]` (always inclusive)
+* `java-instance-of: <string>`, where the `<string>` is a registered type name, to test
+ type assignment of the underlying java class of the value being tested with the
+ underlying java class of the registered type referenced
+* `java-type-name: <test>`, where the `<test>` is a `DslPredicate` tested against the
+ underlying java class name of the value
+
+Two composite tests are supported, both taking a list of other `<test>` objects
+(as a list of YAML maps):
+
+* `any: <list of tests>`, testing that any of the tests in the list are true (logical "or")
+* `all: <list of tests>`, testing that all of the tests in the list are true (logical "and")
+
+
+
+### Presence
+
+The `when` test allows for testing of edge cases, to distinguish between values which are unavailable
+(e.g. a sensor which has not been published, or a config which is unset), those which are null,
+and those which are "truthy" (non-empty, non-false, per `$brooklyn:attributeWhenReady`).
+Permitted values for this test are:
+
+* `absent`: value cannot be resolved (not even as null)
+* `absent_or_null`: value is null or cannot be resolved
+* `present`: value is available, but might be null
+* `present_non_null`: value is available and non-null (but might be 0 or empty)
+* `truthy`: value is available and ready/truthy (eg not false or empty)
+* `falsy`: value is unavailable or not ready/truthy (eg not false or empty)
+* `always`: always returns true
+* `never`: always returns false
+
+
+### Entity Tests
+
+To assist with tests on an `Entity` or `Location`, additional keys are supported on
+the `DslPredicate` via `DslEntityPredicate`:
+
+* `target: <expression>`: to specify a value to test, resolved relative to the "context entity"
+ (the one being tested, if appropriate, or otherwise the evaluating entity where the predicate is defined);
+ this can be a DSL expression such as `$brooklyn:config("key")`
+ or a keyword, currently `location` or `children`, to evaluate
+ against the location(s) or children of that entity
+* `config: <string>`: indicates that the tests should be applied to the value of config key
+ `<string> on the context entity, location, or policy
Review Comment:
missing closing oblique quote
##########
guide/blueprints/yaml-reference.md:
##########
@@ -323,3 +327,145 @@ These are:
including `config-widgets` (setting custom widgets to render fields) and `config-quick-fixes` (proposals for fixing common errors);
see the code for the Blueprint Composer for more details
+## Predicate DSL
+
+In contexts where a `DslPredicate` or `DslEntityPredicate` is expected, the `$brooklyn:object`
+DSL can be used to construct any suitable implementation, such as using factory methods from `EntityPredicates`.
+In many cases, however, a simplified YAML DSL can be used,
+as defined by the Jackson deserialization rules on the `DslPredicate`.
+
+In its simplest form this can be a map containing the test or tests, e.g.:
+
+```
+equals: north
+```
+
+This will result in a `Predicate` which returns true if asked to `test("north")`,
+and false otherwise. The full set of individual tests are:
+
+* `equals: <object>`, to test java object equality, attempting type coercion if necessary
+* `regex: <string|number>`
+* `glob: <string|number>`
+* `when: <presence>`, where `<presence>` is one of the values described below
+* `less-than: <object>`, for strings and primitives, computed using "natural ordering",
+ numeric order for numbers and digit sequences within numbers (`"9" < "10"`),
+ and ASCII-lexicographic comparison elsewhere (`"a" < "b"`);
+ otherwise if both arguments are the same type, or one a subtype of the other, and both comparable,
+ it will use that type's compare method;
+ otherwise if one side side is JSON, it will attempt coercion to the other argument's type;
+ and otherwise it will return false
+* `greater-than: <object>`, as above
+* `less-than-or-equal-to: <object>` as above
+* `greater-than-or-equal-to: <object>, as above
Review Comment:
missing closing oblique quote
##########
guide/blueprints/yaml-reference.md:
##########
@@ -323,3 +327,145 @@ These are:
including `config-widgets` (setting custom widgets to render fields) and `config-quick-fixes` (proposals for fixing common errors);
see the code for the Blueprint Composer for more details
+## Predicate DSL
+
+In contexts where a `DslPredicate` or `DslEntityPredicate` is expected, the `$brooklyn:object`
+DSL can be used to construct any suitable implementation, such as using factory methods from `EntityPredicates`.
+In many cases, however, a simplified YAML DSL can be used,
+as defined by the Jackson deserialization rules on the `DslPredicate`.
+
+In its simplest form this can be a map containing the test or tests, e.g.:
+
+```
+equals: north
+```
+
+This will result in a `Predicate` which returns true if asked to `test("north")`,
+and false otherwise. The full set of individual tests are:
+
+* `equals: <object>`, to test java object equality, attempting type coercion if necessary
+* `regex: <string|number>`
+* `glob: <string|number>`
+* `when: <presence>`, where `<presence>` is one of the values described below
+* `less-than: <object>`, for strings and primitives, computed using "natural ordering",
+ numeric order for numbers and digit sequences within numbers (`"9" < "10"`),
+ and ASCII-lexicographic comparison elsewhere (`"a" < "b"`);
+ otherwise if both arguments are the same type, or one a subtype of the other, and both comparable,
+ it will use that type's compare method;
+ otherwise if one side side is JSON, it will attempt coercion to the other argument's type;
+ and otherwise it will return false
+* `greater-than: <object>`, as above
+* `less-than-or-equal-to: <object>` as above
+* `greater-than-or-equal-to: <object>, as above
+* `in-range: <range>`, where `<range>` is a list of two numbers, e.g. `[0,100]` (always inclusive)
+* `java-instance-of: <string>`, where the `<string>` is a registered type name, to test
+ type assignment of the underlying java class of the value being tested with the
+ underlying java class of the registered type referenced
+* `java-type-name: <test>`, where the `<test>` is a `DslPredicate` tested against the
+ underlying java class name of the value
+
+Two composite tests are supported, both taking a list of other `<test>` objects
+(as a list of YAML maps):
+
+* `any: <list of tests>`, testing that any of the tests in the list are true (logical "or")
+* `all: <list of tests>`, testing that all of the tests in the list are true (logical "and")
+
+
+
+### Presence
+
+The `when` test allows for testing of edge cases, to distinguish between values which are unavailable
+(e.g. a sensor which has not been published, or a config which is unset), those which are null,
+and those which are "truthy" (non-empty, non-false, per `$brooklyn:attributeWhenReady`).
+Permitted values for this test are:
+
+* `absent`: value cannot be resolved (not even as null)
+* `absent_or_null`: value is null or cannot be resolved
+* `present`: value is available, but might be null
+* `present_non_null`: value is available and non-null (but might be 0 or empty)
+* `truthy`: value is available and ready/truthy (eg not false or empty)
+* `falsy`: value is unavailable or not ready/truthy (eg not false or empty)
+* `always`: always returns true
+* `never`: always returns false
+
+
+### Entity Tests
+
+To assist with tests on an `Entity` or `Location`, additional keys are supported on
+the `DslPredicate` via `DslEntityPredicate`:
+
+* `target: <expression>`: to specify a value to test, resolved relative to the "context entity"
+ (the one being tested, if appropriate, or otherwise the evaluating entity where the predicate is defined);
+ this can be a DSL expression such as `$brooklyn:config("key")`
+ or a keyword, currently `location` or `children`, to evaluate
+ against the location(s) or children of that entity
+* `config: <string>`: indicates that the tests should be applied to the value of config key
+ `<string> on the context entity, location, or policy
+* `sensor: <string>`: indicates that the tests should be applied to the value of sensor
+ `<string> on the context entity
Review Comment:
missing closing oblique quote
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@brooklyn.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org