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 two properties defined for the @AllowedValues annotation: values and exclude. 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.

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.

Listing 1. Use cases for allowed values for a variable of type String
/**
 * @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.

AllowedValues String dropdown
Figure 1. Dropdown with allowed values
AllowedValues String
Figure 2. User documentation

3.2. Enum Variable

Listing 2 shows the different available use cases for the @AllowedValues annotation and an enum variable.

Listing 2. Use cases for allowed values for a variable of type enum
/**
 * 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.

AllowedValues Enum dropdown
Figure 3. Dropdown with allowed values
AllowedValues Enum
Figure 4. User documentation