The idiomatic definition of effectors in Brooklyn requires setting up some naming conventions for various tings. 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.*
> ```Java
@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 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.