Java Command Annotations – @AllowedValues
Java command annotations are used for the developing Java commands in PAK.
This chapter describes the functionality of the @AllowedValues annotation.
It also gives an example of how you can use this annotation in your implementation.
1. Basics
The @AllowedValues annotation restricts the values that can be set to a command variable.
It only works together with the @Persistent annotation and is only applicable to variables of type String and enum.
This annotation is evaluated at runtime and raises an exception at the latest.
This annotation does only works in combination with the @Persistent annotation.
|
2. Properties
There are three properties defined for the @AllowedValues annotation: values, exclude and isSuggestion.
As there are some differences between the behaviour of the properties per type (String and enum) which will be defined in the following.
2.1. String Field
The values property for String variables define those values that are allowed to be set.
The list must not be empty as this would defeat the purpose of the property.
The usage for String variables is shown in Listing 1.
| Please pay attention to upper and lower case of the values. |
The property exclude is not allowed for variables with the type String.Compilation errors will be thrown in case you use this property for a String variable. |
Additionally, it’s possible to use the boolean field isSuggestion, which is set to false by default.
It gives the user the opportunity to allow suggestions. If set to true the @AllowedValues annotation is less restrictive and allows more values apart from the entries
in the values array.
Please consider, that this variable can only be set to true if values contains string variables, it’s not applicable for enums.
|
2.2. Enum Variable
On the one hand, the values properties for enum variables define the values that are allowed.
On the other hand, you can define enum values that should be excluded from the allowed values list.
The different use cases are described in the following.
For the values property of variable with type enum you have to enter the enum value name.Thus, pay attention to upper and lower case of the enum value names. |
By default, the values property is empty and the exclude variable is false.
This means that all enum values are allowed for the variable that is annotated with @AllowedValues.
2.2.1. Allow all enum values
If the default configuration is used, i.e. @AllowedValues, all enum values will be allowed, see Listing 2.
2.2.2. Allow only specific enum values
In case you want to allow only some available enum values you can define these in the values property.
To do this you must add the names of all enum values that should be allowed to the list of values.
For example, @AllowedValues(values = { "ENUM_TO_ALLOW" }) only allows ENUM_TO_ALLOW for the annotated variable.
Another concrete example can be seen in , see Listing 2.
2.2.3. Exclude values
To exclude values from the allowed values list, you must assign exclude = true and list all enum values to be excluded in the values property.
For example, @AllowedValues(values = { "EXCLUDE_ENUM" }, exclude = true) allows all enum values except the EXCLUDE_ENUM values to be set for the annotated variable.
Another concrete example can be seen in , see Listing 2.
3. Usage
In the following examples are given on how to use the @AllowedValues annotation for String and enum variables.
3.1. String Variable
Listing 1 shows how to use the @AllowedValues annotation for a String variable.
/**
* @workflowDocu This command gets an element by its id.
*/
@JavaCommand
@CommandGroup("Element")
public class GetElement {
[...]
/**
* @workflowDocu Type of the element with restricted allowed values
*/
@AllowedValues(values = { "issue", "bug" }) (1)
@Persistent
private String type;
[...]
}| 1 | Allowed values: issue and bug |
The single command executor in the Workflow Executor offers the allowed values in a drop-down menu, see Figure 1.
Additionally, further information is given in the user documentation, see Figure 2. If isSuggestion was set to true
in the Listing above, the user could enter any string he/ she desires. Therefore, „issue“ and „bug“ would only be regarded as suggestions.
3.2. Enum Variable
Listing 2 shows the different available use cases for the @AllowedValues annotation and an enum variable.
/**
* Types available for an element.
*/
public enum ElementType {
STORY, SUB_TASK, TASK, BUG
}
/**
* @workflowDocu This command gets an element by its id.
*/
@JavaCommand
@CommandGroup("Element")
public class GetElement {
/**
* @workflowDocu Example where any enum value is allowed
*/
@AllowedValues (1)
@Persistent
private ElementType everyType;
/**
* @workflowDocu Example where some values are allowed
*/
@AllowedValues(values = { "STORY", "TASK" }) (2)
@Persistent
private ElementType someType;
/**
* @workflowDocu Example where enum values are excluded
*/
@AllowedValues(values = { "BUG" }, exclude = true) (3)
@Persistent
private ElementType excludeType;
[...]
}| 1 | Allowed values: STORY, SUB_TASK, TASK, BUG |
| 2 | Allowed values: STORY, TASK |
| 3 | Allowed values: STORY, SUB_TASK, TASK |
Analogous to String variables, the single command executor in the Workflow Executor offers the allowed values in a drop-down menu for enum values as well, see Figure 3.
Additionally, further information is given in the user documentation, see Figure 4.
