Skip to content

Latest commit

 

History

History
143 lines (99 loc) · 4.03 KB

pip-343.md

File metadata and controls

143 lines (99 loc) · 4.03 KB
Raw

PIP-343: Use picocli instead of jcommander

Motivation

We use the jcommander 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 picocli 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

# jcommander
Need to provide just 1 parameter

# picocli
Unknown option: '-b'

  • Command suggestion:

    bin/pulsar-admin cluste

# jcommander
Expected a command, got cluste

# picocli
Unmatched argument at index 0: 'cluste'
Did you mean: pulsar-admin clusters?

Goals

In Scope

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.

Out Scope

This PR simply replaces jcommander and does not introduce any enhancements.

In the CLI, autocomplete is an important feature, and after this PIP is complete I will make a new PIP to support this feature.

Detailed Design

Design & Implementation Details

The jcommander and picocli have similar APIs, this will make the migration task very simple.

This is utility argument syntax:

utility_name[-a][-b][-c option_argument]
    [-d|-e][-f[option_argument]][operand...]
  1. Use @Command instead of @Parameters to define the class as a command:
@Command(name = "my-command", description = "Operations on persistent topics")
public class MyCommand {
  
}
  1. Use @Option instead of @Parameter to defined the option of command:
@Option(names = {"-r", "--role"})
private String role;
  1. Use @Parameters to get the operand of command:
@Parameters(description = "persistent://tenant/namespace/topic", arity = "1")
private String topicName;
  1. Migrate jcommander converter to picocli converter:
public class TimeUnitToMillisConverter implements ITypeConverter<Long> {
  @Override
  public Long convert(String value) throws Exception {
    return TimeUnit.SECONDS.toMillis(RelativeTimeUtil.parseRelativeTimeInSeconds(value));
  }
}
  1. Add the picocli entrypoint:
@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 picocli-shell-jline3 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.

Backward & Forward Compatibility

Fully compatible.

Links