Cassandra 13947 Add some clarifying examples of nodetool usage

.build/build-rat.xml

@@ -56,6 +56,7 @@
                  <exclude name="test/conf/sstableloader_with_encryption.yaml"/>
                  <exclude name="test/conf/unit-test-conf/test-native-port.yaml"/>
                  <exclude name="test/resources/data/config/YamlConfigurationLoaderTest/*.yaml"/>
+                 <exclude name="test/resources/nodetool/help/**"/>
                  <exclude name="tools/cqlstress-*.yaml"/>
                  <!-- test data -->
                  <exclude name="pylib/cqlshlib/test/test_authproviderhandling_config/*"/>

.build/cassandra-deps-template.xml

@@ -120,6 +120,10 @@
       <groupId>io.airlift</groupId>
       <artifactId>airline</artifactId>
     </dependency>
+    <dependency>
+      <groupId>info.picocli</groupId>
+      <artifactId>picocli</artifactId>
+    </dependency>
     <dependency>
       <groupId>io.dropwizard.metrics</groupId>
       <artifactId>metrics-core</artifactId>

.build/parent-pom-template.xml

@@ -726,6 +726,11 @@
           </exclusion>
         </exclusions>
       </dependency>
+      <dependency>
+        <groupId>info.picocli</groupId>
+        <artifactId>picocli</artifactId>
+        <version>4.7.5</version>
+      </dependency>
       <dependency>
         <groupId>io.netty</groupId>
         <artifactId>netty-all</artifactId>

build.xml

@@ -27,7 +27,7 @@
     </fail>
 
     <property environment="env"/>
-    <property file="build.properties" />
+    <property file="build.propert+ies" />
     <property file="build.properties.default" />
     <property file="${user.home}/.ant/build.properties"/>
     <property name="debuglevel" value="source,lines,vars"/>

conf/logback.xml

@@ -1,4 +1,4 @@
-<!--
+    <!--
  Licensed to the Apache Software Foundation (ASF) under one
  or more contributor license agreements.  See the NOTICE file
  distributed with this work for additional information

doc/modules/cassandra/pages/getting-started/configuring.adoc

@@ -14,7 +14,7 @@ to various Cassandra configuration files. Some examples that require
 non-default configuration are deploying a multi-node cluster or using
 clients that are not running on a cluster node.
 
-* `cassandra.yaml`: the main configuration file for Cassandra
+* `cassandra.yaml`: the main configuration file for Cassandra contains sensitive settings and therefore should not be accessed or modified by untrusted users
 * `cassandra-env.sh`: environment variables can be set
 * `cassandra-rackdc.properties` OR `cassandra-topology.properties`: set
 rack and datacenter information for a cluster
@@ -79,4 +79,4 @@ The default logger is [.title-ref]#logback#. By default it will log:
 
 When running in the foreground, it will also log at INFO level to the
 console. You can change logging properties by editing `logback.xml` or
-by running the [.title-ref]#nodetool setlogginglevel# command.
+by running the [.title-ref]#nodetool setlogginglevel# command.

src/java/org/apache/cassandra/tools/nodetool/AbstractCommand.java

@@ -0,0 +1,69 @@
+package org.apache.cassandra.tools.nodetool;
+
+import javax.inject.Inject;
+
+import org.apache.cassandra.tools.NodeProbe;
+import org.apache.cassandra.tools.Output;
+import picocli.CommandLine.ExecutionException;
+
+/**
+ * Abstract class for all nodetool commands, which provides common methods and fields.
+ * <p>
+ * The command is executed by calling {@link #execute(NodeProbe)}, in all other cases
+ * it should not contain any fields or methods that are specific to a particular API
+ * being executed, or common methods that are shared across multiple commands.
+ * <p>
+ * Commands must be API-agnostic and work only with the {@link NodeProbe} API, or a
+ * wrapper around MBean classes (as a primary entry point), which do not need to be
+ * initialized or used with JMX.
+ */
+public abstract class AbstractCommand implements Runnable
+{
+    @Inject
+    protected Output output;
+
+    private NodeProbe probe;
+
+    public void probe(NodeProbe probe)
+    {
+        this.probe = probe;
+    }
+
+    public NodeProbe probe()
+    {
+        return probe;
+    }
+
+    public void logger(Output output)
+    {
+        this.output = output;
+    }
+
+    @Override
+    public void run()
+    {
+        execute(probe());
+    }
+
+    /**
+     * Prepare a command for execution. This method is called before the command is executed and
+     * can be used to perform any necessary setup or validation. If this method returns {@code false},
+     * the command will not initiate connection and will be executed locally. The default implementation
+     * returns {@code true} so that the command initiates connection to the node before execution.
+     *
+     * @return {@code true} if the command is required to connect to the node, {@code false} otherwise.
+     * @throws ExecutionException if an error occurs during preparation and execution must be aborted.
+     */
+    protected boolean prepareAndConnect() throws ExecutionException
+    {
+        return true;
+    }
+
+    /**
+     * Execute the command using the supplied {@link NodeProbe} instance, which is already connected
+     * to the node and ready to use. This method is called after the connection.
+     *
+     * @param probe The {@link NodeProbe} instance to use, or {@code null} if no connection is required.
+     */
+    protected abstract void execute(NodeProbe probe);
+}

src/java/org/apache/cassandra/tools/nodetool/CassandraUsage.java

@@ -0,0 +1,20 @@
+package org.apache.cassandra.tools.nodetool;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Argument annotation for Cassandra commands, used to provide a message
+ * for command-line arguments for backward compatibility when help is requested.
+ * <p>
+ * Used only once in the command class hierarchy.
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ ElementType.FIELD })
+public @interface CassandraUsage
+{
+    String description() default "";
+    String usage() default "";
+}