HDDS-15596. Hide deprecated CLI options

[adoroszlai]

What changes were proposed in this pull request?

HDDS-7957 deprecated several command-line options. These are still accepted, but not shown in the help. It was achieved by splitting such options into two, the deprecated one being hidden=true:

ozone/hadoop-ozone/cli-admin/src/main/java/org/apache/hadoop/hdds/scm/cli/pipeline/ListPipelinesSubcommand.java

Lines 46 to 60 in c479e1e

	@CommandLine.Option(
	names = {"-s", "--state", "--filterByState", "--filter-by-state"},
	description = "Filter listed pipelines by State, eg OPEN, CLOSED",
	defaultValue = "")
	private String state;
	/** For backward compatibility. */
	@CommandLine.Option(
	names = {"-fst"},
	hidden = true,
	defaultValue = ""
	)
	@Deprecated
	@SuppressWarnings("DeprecatedIsStillUsed")
	private String deprecatedState;

Methods to get one of the options were needed:

ozone/hadoop-ozone/cli-admin/src/main/java/org/apache/hadoop/hdds/scm/cli/pipeline/ListPipelinesSubcommand.java

Lines 91 to 95 in c479e1e

	private String getState() {
	if (!Strings.isNullOrEmpty(state)) {
	return state;
	}
	return deprecatedState;

Also, default value had to be removed from primitive type options:

ozone/hadoop-ozone/cli-admin/src/main/java/org/apache/hadoop/ozone/admin/om/PrepareSubCommand.java

Lines 59 to 65 in c479e1e

	@CommandLine.Option(
	names = {"--transaction-apply-wait-timeout"},
	description = "Max time in SECONDS to wait for all transactions before" +
	"the prepare request to be applied to the OM DB.",
	hidden = true
	)
	private Long txnApplyWaitTimeSeconds;

This PR achieves the same result via a parameter preprocessor in GenericCli, replacing deprecated options with the real ones (e.g. -ffc with --filter-by-factor) before command execution.

ozone/hadoop-hdds/cli-common/src/main/java/org/apache/hadoop/hdds/cli/GenericCli.java

Lines 72 to 75 in 6eb8bdc

	cmd.getCommandSpec().preprocessor((args, commandSpec, argSpec, info) -> {
	args.replaceAll(arg -> DeprecatedCliOption.toNonDeprecated(arg, cmd.getErr()));
	return false;
	});

This avoids the need for boilerplate changes shown above and the default value problem.

Most of this PR is to undo the options split from 175e293.

https://issues.apache.org/jira/browse/HDDS-15596

How was this patch tested?

Verified that deprecated options are hidden in help, e.g.:

$ ozone admin pipeline list --help
Usage: ozone admin pipeline list [-hV] [--json] [--verbose]
                                 [--filterByFactor=<factor>] [-r=<replication>]
                                 [-s=<state>] [--scm=<scm>]
                                 [--service-id=<scmServiceId>]
                                 [-t=<replicationType>]
List all active pipelines
      --filterByFactor, --filter-by-factor=<factor>
                    [deprecated] Filter pipelines by factor (e.g. ONE, THREE)
                      (implies RATIS replication type)
...
  -s, --state, --filterByState, --filter-by-state=<state>
                    Filter listed pipelines by State, eg OPEN, CLOSED
...

but command accepts and handles them:

$ ozone admin pipeline list -ffc THREE -fst OPEN
Pipeline{ Id: 6b7a1780-a520-491b-afd3-e548538789a8, Nodes: [ {0e7511ea-3861-465f-97b4-0b4ebb900dd0(ozone-datanode-2.ozone_default/172.18.0.9), ReplicaIndex: 0}, {ee732661-3d27-498f-b807-fd9d0493ff8e(ozone-datanode-1.ozone_default/172.18.0.7), ReplicaIndex: 0}, {021b0f1e-5f0b-4311-8197-774c87160caf(ozone-datanode-3.ozone_default/172.18.0.8), ReplicaIndex: 0},], ReplicationConfig: RATIS/THREE, State:OPEN, leaderId:ee732661-3d27-498f-b807-fd9d0493ff8e, CreationTimestamp2026-06-18T11:55:50.710Z[Etc/UTC]}

$ ozone admin pipeline list -ffc ONE -fst OPEN
Pipeline{ Id: cdce37fc-36a4-4e96-85c2-85c9e414944b, Nodes: [ {0e7511ea-3861-465f-97b4-0b4ebb900dd0(ozone-datanode-2.ozone_default/172.18.0.9), ReplicaIndex: 0},], ReplicationConfig: RATIS/ONE, State:OPEN, leaderId:0e7511ea-3861-465f-97b4-0b4ebb900dd0, CreationTimestamp2026-06-18T11:55:50.656Z[Etc/UTC]}
Pipeline{ Id: e66555dd-9902-4d4d-8351-c140d7d811ab, Nodes: [ {ee732661-3d27-498f-b807-fd9d0493ff8e(ozone-datanode-1.ozone_default/172.18.0.7), ReplicaIndex: 0},], ReplicationConfig: RATIS/ONE, State:OPEN, leaderId:ee732661-3d27-498f-b807-fd9d0493ff8e, CreationTimestamp2026-06-18T11:55:50.715Z[Etc/UTC]}
Pipeline{ Id: 8e46649d-7d8f-47d2-8709-79738700c5ea, Nodes: [ {021b0f1e-5f0b-4311-8197-774c87160caf(ozone-datanode-3.ozone_default/172.18.0.8), ReplicaIndex: 0},], ReplicationConfig: RATIS/ONE, State:OPEN, leaderId:021b0f1e-5f0b-4311-8197-774c87160caf, CreationTimestamp2026-06-18T11:55:50.719Z[Etc/UTC]}

Same for interactive mode:

$ ozone admin --interactive
ozone admin> pipeline list -<TAB>
--filter-by-factor   --filterByFactor     --help               --replication        --service-id         --type               --version            -h                   -s
--filter-by-state    --filterByState      --json               --scm                --state              --verbose            -V                   -r                   -t

ozone admin> pipeline list -ffc THREE
WARNING: Option '-ffc' is deprecated. Use '--filter-by-factor' instead.
Pipeline{ Id: 6d989d02-f1c6-4009-a5f0-372b4135bd02, Nodes: [ {5f3ef100-5fb5-4b42-9364-c4f1149f8a9c(ozone-datanode-3.ozone_default/172.18.0.9), ReplicaIndex: 0}, {738917eb-d46f-4df2-979e-8fcff1aac502(ozone-datanode-1.ozone_default/172.18.0.8), ReplicaIndex: 0}, {6957c4f1-1bc7-47e3-92dc-c5d49cbd96ed(ozone-datanode-2.ozone_default/172.18.0.3), ReplicaIndex: 0},], ReplicationConfig: RATIS/THREE, State:OPEN, leaderId:6957c4f1-1bc7-47e3-92dc-c5d49cbd96ed, CreationTimestamp2026-06-18T12:56:51.917Z[Etc/UTC]}

Updated unit test.

CI:
https://github.com/adoroszlai/ozone/actions/runs/27765382504

[hani-fouladgar]

I believe we need to bring "-ffc" and all other deprecated ones back. We still need them for backward compatibility.

[adoroszlai]

No, the point of this change is that we can remove them from @Option (thus hiding them in help) but they still work via the parameter processor.

[hani-fouladgar]

I see! Got you!. What would happen if both --filter-by-factor and -ffc are provided in the command? How do we manage make the original --filter-by-factor to be the winner not the modified one?

[adoroszlai]

Error:

$ ozone admin pipeline list -ffc ONE --filter-by-factor THREE
WARNING: Option '-ffc' is deprecated. Use '--filter-by-factor' instead.
option '--filter-by-factor' (<factor>) should be specified only once
...

Same as if any of the option's other aliases were given twice:

$ ozone admin pipeline list --filter-by-factor THREE --filterByFactor ONE 
option '--filter-by-factor' (<factor>) should be specified only once

(Also matches behavior before HDDS-7957, except the warning.)

[hani-fouladgar]

Thank you!

[adoroszlai]

@sarvekshayr please take a look

[sarvekshayr]

Thanks @adoroszlai for the improvement.

[sarvekshayr]

Restore --nodeid and --node-host-address in customSynopsis.

[adoroszlai]

Thanks for catching this.

[sarvekshayr]

LGTM.

[sarvekshayr]

Thanks @adoroszlai for the patch and @hani-fouladgar for the review.

[adoroszlai]

Thanks @hani-fouladgar, @sarvekshayr for the review.