This is an automated email from the ASF dual-hosted git repository. heneveld pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/brooklyn-docs.git
commit 45106b497fbcea04db45759d63046bd327a31f49 Merge: 33c4b051 9f71de4d Author: Alex Heneveld <[email protected]> AuthorDate: Mon Jun 27 15:23:24 2022 +0100 Merge branch 'master' into effector-hints guide/blueprints/yaml-reference.md | 150 ++++++++++++++++++++++++++++++++++++- 1 file changed, 149 insertions(+), 1 deletion(-) diff --cc guide/blueprints/yaml-reference.md index 19cf70b1,dbcbf440..3fc0e88a --- a/guide/blueprints/yaml-reference.md +++ b/guide/blueprints/yaml-reference.md @@@ -323,7 -327,145 +327,151 @@@ 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 +* `ui-effector-hints`: a tag containing a single-entry map with this key will constrain how effectors are + presented in the UI. The value should be a map containing one or more of the following keys: + * `exclude-regex`: a regex string matched against effector names to exclude them from listing in the "Effectors" tag + * `include-regex`: a regex string per above to explicitly include matching names which would be excluded by the above ++ ++ + ## 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 + * `tag: <test>`: indicates that `<test>` should be applied to the tags on the context entity, location, or policy + + + ### Lists and Flattening Behaviour + + To facilitate testing against collections (e.g. `target: location` or `target: children`, or `tags`, + or a config key which is a collection), the default behaviour for testing against any `Iterable` + is to perform the tests against the `Iterable` itself and, if that fails, against each + element therein (and any element in nested `Iterable` elements, recursively. + The predicate will pass if the `Iterable` or any such member passes all the tests defined. + + This makes it easy to test for the presence of a specific tag of location, + and is chosen as the default because the majority of test predicates are not + applicable to collections. + + However there may be cases where the predicate needs to run against the `Iterable` + and _not_ the nested values. This can be indicated with the special test: + + * `unflattened: <test>`: Performs the test against the value prior to enumeration of + members, and if supplied must pass in order for the predicate to return true + + + ### Examples + + ##### Location Config + + The following will test whether an entity has any location with config `region` + starting with `us-`, for example to filter within a `DynamicGroup`: + + ``` + target: location + config: region + glob: us-* + ``` + + (Instead of the `glob`, writing `regex: us-.*` would be equivalent.) + + + ##### Date Comparison + + Given a config `expiry` of type `Instant` (or related date/time type), + this will check that the date is on or after Jan 1 2000: + + ``` + config: expiry + greater-than-or-equal-to: 2000-01-01 + ``` + + + ##### Missing Sensor + + This will select entities which have _not_ published the sensor "ready": + + ``` + sensor: ready + when: absent + ``` + + And this will select entities where that sensor is present but null, false, or empty: + + ``` + sensor: ready + all: + - when: present + - when: falsy + ```
