HADOOP-18830. S3 select. final review comments

+update doc with explicit consequences of removal,
including the "hadoop s3guard select" command

Change-Id: Ica3ffb33d803f8a03e0d733447e4f026d547f8c1

Author: steveloughran

hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/select/SelectConstants.java

@@ -31,7 +31,8 @@
  * so that any application which imports the dependencies will still link.
  */
 @InterfaceAudience.Public
-@InterfaceStability.Unstable
+@InterfaceStability.Stable
+@Deprecated
 public final class SelectConstants {
 
   public static final String SELECT_UNSUPPORTED = "S3 Select is no longer supported";
@@ -46,13 +47,18 @@ private SelectConstants() {
 
   /**
    * This is the big SQL expression: {@value}.
-   * When used in an open() call, switch to a select operation.
-   * This is only used in the open call, never in a filesystem configuration.
+   * When used in an open() call:
+   * <ol>
+   *   <li>if the option is set in a {@code .may()} clause: warn and continue</li>
+   *   <li>if the option is set in a {@code .must()} clause:
+   *        {@code UnsupportedOperationException}.</li>
+   *  </ol>
    */
   public static final String SELECT_SQL = FS_S3A_SELECT + "sql";
 
   /**
    * Does the FS Support S3 Select?
+   * This is false everywhere.
    * Value: {@value}.
    */
   public static final String S3_SELECT_CAPABILITY = "fs.s3a.capability.select.sql";

hadoop-tools/hadoop-aws/src/site/markdown/tools/hadoop-aws/s3_select.md

@@ -24,4 +24,52 @@ Any Hadoop release built on the [AWS V2 SDK](./aws_sdk_upgrade.html)
 will reject calls to open files using the select APIs.
 
 If a build of Hadoop with S3 Select is desired, the relevant
-classes can be found in hadoop trunk commit `8bf72346a59c`.
+classes can be found in hadoop trunk commit `8bf72346a59c`.
+
+## Consequences of the removal
+
+The path capabilities probe `fs.s3a.capability.select.sql` returns "false" for any and all
+`s3a://` paths.
+
+Any `openFile()` call where a SQL query is passed in as a `must()` clause
+SHALL raise `UnsupportedOperationException`:
+```java
+// fails
+openFile("s3a://bucket/path")
+  .must("fs.s3a.select.sql", "SELECT ...")
+  .get();
+```
+
+Any `openFile()` call to an S3A Path where a SQL query is passed in as a `may()`
+clause SHALL be logged at WARN level the first time it is invoked, then ignored.
+```java
+// ignores the option after printing a warning.
+openFile("s3a://bucket/path")
+  .may("fs.s3a.select.sql", "SELECT ...")
+  .get();
+```
+
+The `hadoop s3guard select` command is no longer supported.
+
+Previously, the command would either generate an S3 select or a error (with exit code 42 being
+the one for not enough arguments):
+
+```
+hadoop s3guard select
+select [OPTIONS] [-limit rows] [-header (use|none|ignore)] [-out path] [-expected rows]
+  [-compression (gzip|bzip2|none)] [-inputformat csv] [-outputformat csv] <PATH> <SELECT QUERY>
+        make an S3 Select call
+
+[main] INFO  util.ExitUtil (ExitUtil.java:terminate(241)) - Exiting with status 42:
+       42: Too few arguments
+```
+
+Now it will fail with exit code 55 always:
+
+```
+hadoop s3guard select
+
+[main] INFO  util.ExitUtil (ExitUtil.java:terminate(241)) - Exiting with status 55:
+       55: S3 Select is no longer supported
+
+```

hadoop-tools/hadoop-aws/src/test/java/org/apache/hadoop/fs/s3a/select/ITestSelectUnsupported.java

@@ -47,23 +47,23 @@ public class ITestSelectUnsupported extends AbstractS3ATestBase {
       " WHERE s._1 = 'foo'";
 
   /**
-   * A {@code .must(SELECT_SQL, _)} option MSUT not fail the build.
+   * A {@code .must(SELECT_SQL, _)} option MUST raise {@code UnsupportedOperationException}.
    */
   @Test
-  public void testSelectOpenFileMust() throws Throwable {
+  public void testSelectOpenFileMustFailure() throws Throwable {
 
     intercept(UnsupportedOperationException.class, SELECT_UNSUPPORTED, () ->
         getFileSystem().openFile(methodPath())
             .must(SELECT_SQL, STATEMENT)
             .build()
-            /**/.get());
+            .get());
   }
 
   /**
-   * A {@code .opt(SELECT_SQL, _)} option does not fail the build.
+   * A {@code .opt(SELECT_SQL, _)} option is ignored..
    */
   @Test
-  public void testSelectOpenFileMay() throws Throwable {
+  public void testSelectOpenFileMayIsIgnored() throws Throwable {
 
     final Path path = methodPath();
     final S3AFileSystem fs = getFileSystem();