Effector Parameters

[Andrew Kennedy <an...@cloudsoftcorp.com>]

> https://gist.github.com/grkvlt/96bcd7a057c9f9e4c568

The idiomatic definition of effectors in Brooklyn requires setting up some
naming conventions for various things. One of these is the arguments to a
method. In Java, compiled bytecode does not provide us with the symbol
names for these arguments, so a method is uniquely determined by it's
argument types and their order (and the return type) -- that is
`method(String a, Integer b)` and `method(String x, Integer z)` are
considered identical. This can be seen in many IDEs where Javadoc comments
are not available on interfaces, and the method arguments are listed as
`arg0`, `arg1` and so on.

In a Brooklyn effector declaration, we usually annotate each parameter with
the `@EffectorParam` annotation, which takes `name`, `description` and
`defaultValue` properties. These are defined as Strings, due to the
restrictions inherent in the Java type annotation specification, which can
cause problems for the `defaultValue` property. The `description` is
normally a 'Sentence case' fragment (i.e. *not* a fully punctuated
sentence) that is visible in a tool-tip in the Console UI. This sometimes
has parenthetical comments describing the default value, but since that too
is displayed in the tool-tip if present, these should normally be omitted
for clarity. The `name` property is usually chosen to match the text of the
argument variable in the source code, although this is not enforced.

@Effector(description = "Example effector")
public void effector(@EffectorParam(name = "minSize", defaultValue = "50",
        description = "Minimum size of payload, i.e. document body (the
min-size argument)") Integer minSize);

*The property matches the Java argument name.*

@Effector(description = "Example effector")
public void effector(@EffectorParam(name = "min-size", defaultValue = "50",
        description = "Minimum size of payload, i.e. document body")
Integer minSize);

*The property matches the external function argument.*

The two conventions for the `name` property are ilustrated in the examples
above. In the first case, the `name` matches the argument symbol text.
However, in cases where the name is sematically significant, such as if the
effector is exercising an external function with well-defined argument
names that are *not* Java symbols, there can be issues. For example, the
external arguments may derive from languages that permit characters that
are not allowed in Java identifiers (initial numerals and so on) or are
simply idiomatically formatted according to different rules: *UpperCamel*,
*lower-hyphen* or *UPPER_UNDERSCORE* rather than *lowerCamel* as is usual
for Java. In this case, it is important to preserve the original name for
ease of use and user friendliness, so the question arises of how to format
the effector definition.

The options would seem to be to change the `name` property to use the
underlying argument name's original definition, or to include the
underlying argument name from the external function in the description. The
first has the benefit of immediate clarity whem viewing the effector in the
Brooklyn console UI, since the name is displayed next to the input field
for the value, wheras the description is hidden until the tool-tip id
displayed by mousing over the name. The second method seems more in keeping
with idiomatic Java code, and appears to have been the norm for most
Brooklyn effector definitions until now.

Pull request #1383 [1] illustrates this problem, and both @Nakomis and
myself would appreciate some advice as to which method of defining effector
parameters should be used. We can then record this as part of the
documentation on writing effective and idiomatic Brooklyn entities.

[1] https://github.com/brooklyncentral/brooklyn/pull/1383/files#r12645337

Andrew.
-- 
-- andrew kennedy ? engineer : http://cloudsoftcorp.com/developers/ ;