Project: Pulsar (App Definition and Development / Streaming & Messaging)
File: pip-343.md

We use the to build the CLI tool, which is a good library, and is stable, but it misses modern CLI features likes autocompletion, flag/command suggestion, native image, etc. These features are very important because there are many commands in the CLI, but the jcommander doesn't give friendly hints when we use incorrect flags/commands, which makes the user experience not very friendly. In modern times, the supports these features, which is a popular library. The following is some comparison between jcommander and picocli: Error prompt: ``` bin/pulsar-admin clusters update cluster-a -b Need to provide just 1 parameter Unknown option: '-b' ``` Command suggestion: ``` bin/pulsar-admin cluste Expected a command, got cluste Unmatched argument at index 0: 'cluste' Did you mean: pulsar-admin clusters? ``` Use the picocli instead of the jcommander in our CLI tool: bin/pulsar bin/pulsar-admin bin/pulsar-client bin/pulsar-shell bin/pulsar-perf I'm sure this will greatly improve the user experience, and in the future we can also consider using native images to reduce runtime, and improve the CLI document based on picocli. This PR simply replaces jcommander and does not introduce any enhancements. In the CLI, is an important feature, and after this PIP is complete I will make a new PIP to support this feature. The jcommander and picocli have similar APIs, this will make the migration task very simple. This is : ``` utilityname[-c optionargument] ][operand...] ``` Use `@Command` instead of `@Parameters` to define the class as a command: ```java @Command(name = "my-command", description = "Operations on persistent topics") public class MyCommand { } ``` Use `@Option` instead of `@Parameter` to defined the option of command: ```java @Option(names = {"-r", "--role"}) private String role; ``` Use `@Parameters` to get the operand of command: ```java @Parameters(description = "persistent://tenant/namespace/topic", arity = "1") private String topicName; ``` Migrate jcommander converter to picocli converter: ```java public class TimeUnitToMillisConverter implements ITypeConverter<Long> { @Override public Long convert(String value) throws Exception { return TimeUnit.SECONDS.toMillis(RelativeTimeUtil.parseRelativeTimeInSeconds(value)); } } ``` Add the picocli entrypoint: ```java @Command public class MyCommand implements Callable<Integer> { // Picocli entrypoint. @Override public Integer call() throws Exception { // TODO // run(); return 0; } } ``` The above is a common migration approach, and then we need to consider pulsar-shell and custom command separately. pulsar-shell This is an interactive shell based on jline3 and jcommander, which includes pulsar-admin and pulsar-client commands. The jcommander does not provide autocompletion because we have implemented it ourselves. In picocli, they have to help us quickly build the interactive shell. custom command: This is an extension of pulsar-admin, and the plugin's implementation does not depend on jcommander. Since the bridge is used, we only need to change the generator code based on picocli. Fully compatible. Mailing List discussion thread: https://lists.apache.org/thread/ydg1q064cd11pxwz693frtk4by74q32f Mailing List voting thread: https://lists.apache.org/thread/1bpsr6tkgm00bb66dt2s74r15o4b37s3