Skip to content
This repository has been archived by the owner on Dec 3, 2021. It is now read-only.

Annotation API

Jump to bottom
Yevgeny Krasik edited this page Apr 14, 2016 · 7 revisions

General Info

  • Methods annotated with @Command are commands. They may receive any amount of parameters of the types {String, Enum, int, double, boolean} and their boxed versions. Commands may return a value, but it will be ignored.
  • Command parameters may optionally be annotated with any of {@BoolParam, @IntParam, @DoubleParam, @StringParam, @EnumPara} to customize the parameter behavior, like making it optional. If a parameter isn't annotated, it will be considered mandatory and use a default configuration.
  • By default, non-primitive parameters are nullable, meaning they accept the value null. If this is not desirable, annotate the parameter and set nullable = false in the annotation.
  • Methods annotated with @ToggleCommand must return a ToggleCommandStateAccessor and will create a toggle command - a special type of command that take a single optional boolean parameter and toggle the state of some boolean component on and off. This is a common use-case, which is why it has it's own annotation.
  • Classes are analogous to directories, grouping commands together. This structure is very similar to a unit test - a "command class" for each unit that you would like to be able to call from your application.
  • Paths - Any class (directory) annotated with @CommandPath can set a '/' delimited path under which it will be located in the hierarchy. Any commands defined within this class will inherit it's path. Commands may extend (but not overwrite) this path - any command annotated with @CommandPath can also specify a '/' delimited path and the command will be added to the path specified by the class's path appended with the command's path.
  • Nested classes can also be annotated with @CommandPath and any commands under the inner classes will be appended to the outer class's @CommandPath.
  • Output can be written to a CommandOutput. Each class with commands should have a private, non-final uninitialized field of that type that will be injected by the library when the class is processed.

Annotation API

@Command

Annotation Target: Methods.

Description: Annotated methods are considered commands and will be included in the hierarchy built from the class.

Optional: No, if a method is not annotated, it will not be processed.

Properties:

  • value Command name. If absent or empty, method name will be used.
  • description Command description. Should a brief description to help you understand what the command does.
    If empty or absent, a default non-informative description will be used.

Typical Usage:

@Command(description = "Description goes here")
public void command() {
    ...
}

##@ToggleCommand Annotation Target: Methods.

Description: Replaces @Command. Annotated methods are considered toggle commands, which are a special type of command that takes a single optional boolean parameter and toggles the state of some boolean component on or off.
Annotated methods must comply with the following constraints:

If a value for the command's parameter is passed, the state of the component will be set to it. If a value isn't passed, the state of the component will be set to the inverse of it's current state.

Optional: No, if a method is not annotated, it will not be processed.

Properties:

  • value Toggle command name. If absent or empty, method name will be used.
  • description Toggle command description. Should a brief description to help you understand what the command does.
    If empty or absent, a default non-informative description will be used.
  • paramName Toggle command's single optional boolean parameter name. If absent or empty, a default name will be used.
  • paramDescription Toggle command's single optional boolean parameter description. If absent or empty, a default non-informative description will be used.

Typical Usage:

@ToggleCommand(description = "Toggles something")
public ToggleCommandStateAccessor toggle() {
    return new ToggleCommandStateAccessor() {
        @Override
        public void set(boolean value) {
            GlobalState.SOME_VALUE = value;
        }

        @Override
        public boolean get() {
            return GlobalState.SOME_VALUE;
        }
    };
}

CommandOutput

Target: Each class with commands should have a private, non-final uninitialized field of this type. When the class is processed by the library, this field will be injected.

Description: Can display messages and error messages. Commands are expected to reference their class's field when they want to output anything.

Optional: Yes, if a class doesn't have this field, it's commands won't be able to output anything.

Typical Usage:

public class HelloWorld {
    private CommandOutput output;

    @Command
    public void helloWorld() {
        output.message("Hello, World!");
    }
}

@CommandPath

Annotation Target: Classes & Methods.

Description: Defines the 'mount path' for directories and commands. The path can be delimited by '/'.
Annotated classes (aka directories) will mount all their commands under the annotated path.
Annotated commands will be mounted under the path resulting from appending the class's path (if any) with the command's annotated path.

Optional: Yes, if a class isn't annotated it will be mounted under 'root', if a command isn't annotated it will be mounted under the class's mount path.

Properties:

  • value A possibly '/' delimited path under which the command or directory should be mounted.

Typical Usage:
For a class:

@CommandPath("all/commands/under/this/class/will/be/placed/here")
public class SomeClass {
    ...
}

For a nested class:

@CommandPath("outer")
public class OuterClass {
    @CommandPath("inner")
    public class InnerClass {
        // Any commands here will be under 'outer/inner/'
    }
}

For a command:

@CommandPath("base")
public class SomeClass {
    @CommandPath("appended/to/base")
    @Command
    public void command() {
        // This command will be under 'base/appended/to/base'
    }
}

@StringParam

Annotation Target: String parameters.

Description: Parameters should be annotated if control over the parameter's name, description, the parameter's acceptable values or whether the parameter is mandatory or optional is desired.

Optional: Yes, if a parameter is not annotated it will be considered a mandatory parameter, have a default name and accept all String values.

Properties:

  • value Parameter name. If absent or empty, a default name will be used.
  • description Parameter description. Should a brief description to help you understand what the parameter does.
    If empty or absent, a default non-informative description will be used.
  • nullable Whether the parameter accepts the value null. Defaults to true.
  • acceptsSupplier The name of a (possibly private) method in the same class as the command defining this parameter that takes no arguments and returns an array of String - String[]. If the name is not empty, it will override the values returned by accepts. This sets the parameter's accepted value supplier - this method will be invoked when parsing the parameter's argument and only arguments that are present in the returned String[] will be accepted. If the returned String[] is empty, all arguments will be accepted.
  • accepts The parameter's accepted values. When parsing the parameter's argument, only arguments that are present in this array will be accepted. If this is empty, all arguments will be accepted. Only has effect if acceptsSupplier is empty.
  • optional If true, the parameter is considered optional and it's default value will be calculated as follows:
    1. If defaultValueSupplier is not empty, the parameter's default value will be the value returned by a method in the same class specified by defaultValueSupplier.
    2. If defaultValueSupplier is empty, the parameter's default value will be the value returned by the defaultValue property.
  • defaultValueSupplier If the parameter is optional, this is the name of a (possibly private) method in the same class as the command defining this parameter that takes no arguments and returns a String value that will be invoked to supply the parameter with a default value if it is not explicitly passed.
  • defaultValue If the parameter is optional and defaultValueSupplier is empty, this is the default value that the parameter will use if it is not explicitly passed.

The parameter's nullability, acceptable values and whether it's mandatory or optional are unrelated properties that can be combined.

Typical Usage:
Mandatory parameter that accepts all values:

@Command
public void command(@StringParam("string") String str) {
    ...
}

Mandatory parameter that only accepts certain, pre-determined values:

@Command
public void command(@StringParam(value = "string", accepts = {"a", "b", "c"}) String str) {
    ...
}

Mandatory parameter that only accepts certain values returned by a supplier:

@Command
public void command(@StringParam(value = "string", acceptSupplier = "supplier") String str) {
    ...
}

private String[] supplier() {
    return new String[] { "a", "b", "c" };
    // Ideally, this should return a value calculated out of the program's state.
}

Optional parameter with constant default value:

@Command
public void command(@StringParam(optional = true, defaultValue = "default") String str) {
    ...
}

Optional parameter with default value supplier:

@Command
public void command(@StringParam(optional = true, defaultValueSupplier = "supplier") String str) {
    ...
}

private String supplier() {
    // Ideally, this should return a value calculated out of the program's state.
    return "default";
}

@EnumParam

Annotation Target: Enum parameters.

Description: Parameters should be annotated if control over the parameter's name, description, the parameter's acceptable values or whether the parameter is mandatory or optional is desired.

Optional: Yes, if a parameter is not annotated it will be considered a mandatory parameter, have a default name and accept all String values.

Properties:

  • value Parameter name. If absent or empty, a default name will be used.
  • description Parameter description. Should a brief description to help you understand what the parameter does.
    If empty or absent, a default non-informative description will be used.
  • nullable Whether the parameter accepts the value null. Defaults to true.
  • optional If true, the parameter is considered optional and it's default value will be calculated as follows:
    1. If defaultValueSupplier is not empty, the parameter's default value will be the value returned by a method in the same class specified by defaultValueSupplier.
    2. If defaultValueSupplier is empty, the parameter's default value will be the value returned by the defaultValue property.
  • defaultValueSupplier If the parameter is optional, this is the name of a (possibly private) method in the same class as the command defining this parameter that takes no arguments and returns a String value that will be invoked to supply the parameter with a default value if it is not explicitly passed.
  • defaultValue If the parameter is optional and defaultValueSupplier is empty, this is the default value that the parameter will use if it is not explicitly passed.

The parameter's nullability and whether it's mandatory or optional are unrelated properties that can be combined.

Typical Usage:

public enum SomeEnum {
    ONE, TWO;
}

Mandatory parameter:

@Command
public void command(@EnumParam("enum") SomeEnum enumParam) {
    ...
}

Optional parameter with constant default value:

@Command
public void command(@EnumParam(optional = true, defaultValue = "ONE") SomeEnum enumParam) {
    ...
}

Optional parameter with default value supplier:

@Command
public void command(@EnumParam(optional = true, defaultValueSupplier = "supplier") SomeEnum enumParam) {
    ...
}

private SomeEnum supplier() {
    // Ideally, this should return a value calculated out of the program's state.
    return SomeEnum.TWO;
}

@BoolParam

Annotation Target: Boolean parameters (Both primitive and boxed).

Description: Parameters should be annotated if control over the parameter's name, description, or whether the parameter is mandatory or optional is desired.

Optional: Yes, if a parameter is not annotated it will be considered a mandatory parameter and have a default name.

Properties:

  • value Parameter name. If absent or empty, a default name will be used.
  • description Parameter description. Should a brief description to help you understand what the parameter does.
    If empty or absent, a default non-informative description will be used.
  • nullable Whether the parameter accepts the value null. Defaults to true.
  • optional If true, the parameter is considered optional and it's default value will be calculated as follows:
    1. If defaultValueSupplier is not empty, the parameter's default value will be the value returned by a method in the same class specified by defaultValueSupplier.
    2. If defaultValueSupplier is empty, the parameter's default value will be the value returned by the defaultValue property.
  • defaultValueSupplier If the parameter is optional, this is the name of a (possibly private) method in the same class as the command defining this parameter that takes no arguments and returns a boolean value (either primitive or boxed) that will be invoked to supply the parameter with a default value if it is not explicitly passed.
  • defaultValue If the parameter is optional and defaultValueSupplier is empty, this is the default value that the parameter will use if it is not explicitly passed.

The parameter's nullability and whether it's mandatory or optional are unrelated properties that can be combined.

Typical Usage:
We will use the primitive type for convenience, but the boxed type can be used as well.
Mandatory parameter:

@Command
public void command(@BoolParam("bool") boolean bool) {
    ...
}

Optional parameter with constant default value:

@Command
public void command(@BoolParam(optional = true, defaultValue = true) boolean bool) {
    ...
}

Optional parameter with default value supplier:

@Command
public void command(@BoolParam(optional = true, defaultValueSupplier = "supplier") boolean bool) {
    ...
}

private boolean supplier() {
    // Ideally, this should return a value calculated out of the program's state.
    return true;
}

@IntParam

Annotation Target: Integer parameters (Both primitive and boxed).

Description: Parameters should be annotated if control over the parameter's name, description, or whether the parameter is mandatory or optional is desired.

Optional: Yes, if a parameter is not annotated it will be considered a mandatory parameter and have a default name.

Properties:

  • value Parameter name. If absent or empty, a default name will be used.
  • description Parameter description. Should a brief description to help you understand what the parameter does.
    If empty or absent, a default non-informative description will be used.
  • nullable Whether the parameter accepts the value null. Defaults to true.
  • optional If true, the parameter is considered optional and it's default value will be calculated as follows:
    1. If defaultValueSupplier is not empty, the parameter's default value will be the value returned by a method in the same class specified by defaultValueSupplier.
    2. If defaultValueSupplier is empty, the parameter's default value will be the value returned by the defaultValue property.
  • defaultValueSupplier If the parameter is optional, this is the name of a (possibly private) method in the same class as the command defining this parameter that takes no arguments and returns an int value (either primitive or boxed) that will be invoked to supply the parameter with a default value if it is not explicitly passed.
  • defaultValue If the parameter is optional and defaultValueSupplier is empty, this is the default value that the parameter will use if it is not explicitly passed.

The parameter's nullability and whether it's mandatory or optional are unrelated properties that can be combined.

Typical Usage:
We will use the primitive type for convenience, but the boxed type can be used as well.
Mandatory parameter:

@Command
public void command(@IntParam("int") int i) {
    ...
}

Optional parameter with constant default value:

@Command
public void command(@IntParam(optional = true, defaultValue = 10) int i) {
    ...
}

Optional parameter with default value supplier:

@Command
public void command(@IntParam(optional = true, defaultValueSupplier = "supplier") int i) {
    ...
}

private int supplier() {
    // Ideally, this should return a value calculated out of the program's state.
    return 10;
}

@DoubleParam

Annotation Target: Double parameters (Both primitive and boxed).

Description: Parameters should be annotated if control over the parameter's name, description, or whether the parameter is mandatory or optional is desired.

Optional: Yes, if a parameter is not annotated it will be considered a mandatory parameter and have a default name.

Properties:

  • value Parameter name. If absent or empty, a default name will be used.
  • description Parameter description. Should a brief description to help you understand what the parameter does.
    If empty or absent, a default non-informative description will be used.
  • nullable Whether the parameter accepts the value null. Defaults to true.
  • optional If true, the parameter is considered optional and it's default value will be calculated as follows:
    1. If defaultValueSupplier is not empty, the parameter's default value will be the value returned by a method in the same class specified by defaultValueSupplier.
    2. If defaultValueSupplier is empty, the parameter's default value will be the value returned by the defaultValue property.
  • defaultValueSupplier If the parameter is optional, this is the name of a (possibly private) method in the same class as the command defining this parameter that takes no arguments and returns a double value (either primitive or boxed) that will be invoked to supply the parameter with a default value if it is not explicitly passed.
  • defaultValue If the parameter is optional and defaultValueSupplier is empty, this is the default value that the parameter will use if it is not explicitly passed.

The parameter's nullability and whether it's mandatory or optional are unrelated properties that can be combined.

Typical Usage:
We will use the primitive type for convenience, but the boxed type can be used as well.
Mandatory parameter:

@Command
public void command(@DoubleParam("double") double d) {
    ...
}

Optional parameter with constant default value:

@Command
public void command(@DoubleParam(optional = true, defaultValue = 1.0) double d) {
    ...
}

Optional parameter with default value supplier:

@Command
public void command(@DoubleParam(optional = true, defaultValueSupplier = "supplier") double d) {
    ...
}

private double supplier() {
    // Ideally, this should return a value calculated out of the program's state.
    return 1.0;
}
Clone this wiki locally