feat: support client-side hints for tags and priority (#3005)

Supports including a hint in the SQL string to set a statement tag or an RPC priority for a single SQL statement in the Connection API. This makes it easier to use these features from frameworks and tools that only support SQL statements.

Replaces #2978

Author: olavloite

google-cloud-spanner/src/main/java/com/google/cloud/spanner/Statement.java

@@ -178,6 +178,11 @@ public String getSql() {
     return sql;
   }
 
+  /** Returns a copy of this statement with the SQL string replaced by the given SQL string. */
+  public Statement withReplacedSql(String sql) {
+    return new Statement(sql, this.parameters, this.queryOptions);
+  }
+
   /** Returns the {@link QueryOptions} that will be used with this {@link Statement}. */
   public QueryOptions getQueryOptions() {
     return queryOptions;

google-cloud-spanner/src/main/java/com/google/cloud/spanner/connection/AbstractStatementParser.java

@@ -16,9 +16,13 @@
 
 package com.google.cloud.spanner.connection;
 
+import static com.google.cloud.spanner.connection.SimpleParser.isValidIdentifierChar;
+import static com.google.cloud.spanner.connection.StatementHintParser.convertHintsToOptions;
+
 import com.google.api.core.InternalApi;
 import com.google.cloud.spanner.Dialect;
 import com.google.cloud.spanner.ErrorCode;
+import com.google.cloud.spanner.Options.ReadQueryUpdateTransactionOption;
 import com.google.cloud.spanner.SpannerException;
 import com.google.cloud.spanner.SpannerExceptionFactory;
 import com.google.cloud.spanner.Statement;
@@ -169,6 +173,7 @@ public static class ParsedStatement {
     private final Statement statement;
     private final String sqlWithoutComments;
     private final boolean returningClause;
+    private final ReadQueryUpdateTransactionOption[] optionsFromHints;
 
     private static ParsedStatement clientSideStatement(
         ClientSideStatementImpl clientSideStatement,
@@ -182,15 +187,27 @@ private static ParsedStatement ddl(Statement statement, String sqlWithoutComment
     }
 
     private static ParsedStatement query(
-        Statement statement, String sqlWithoutComments, QueryOptions defaultQueryOptions) {
+        Statement statement,
+        String sqlWithoutComments,
+        QueryOptions defaultQueryOptions,
+        ReadQueryUpdateTransactionOption[] optionsFromHints) {
       return new ParsedStatement(
-          StatementType.QUERY, null, statement, sqlWithoutComments, defaultQueryOptions, false);
+          StatementType.QUERY,
+          null,
+          statement,
+          sqlWithoutComments,
+          defaultQueryOptions,
+          false,
+          optionsFromHints);
     }
 
     private static ParsedStatement update(
-        Statement statement, String sqlWithoutComments, boolean returningClause) {
+        Statement statement,
+        String sqlWithoutComments,
+        boolean returningClause,
+        ReadQueryUpdateTransactionOption[] optionsFromHints) {
       return new ParsedStatement(
-          StatementType.UPDATE, statement, sqlWithoutComments, returningClause);
+          StatementType.UPDATE, statement, sqlWithoutComments, returningClause, optionsFromHints);
     }
 
     private static ParsedStatement unknown(Statement statement, String sqlWithoutComments) {
@@ -208,18 +225,20 @@ private ParsedStatement(
       this.statement = statement;
       this.sqlWithoutComments = Preconditions.checkNotNull(sqlWithoutComments);
       this.returningClause = false;
+      this.optionsFromHints = EMPTY_OPTIONS;
     }
 
     private ParsedStatement(
         StatementType type,
         Statement statement,
         String sqlWithoutComments,
-        boolean returningClause) {
-      this(type, null, statement, sqlWithoutComments, null, returningClause);
+        boolean returningClause,
+        ReadQueryUpdateTransactionOption[] optionsFromHints) {
+      this(type, null, statement, sqlWithoutComments, null, returningClause, optionsFromHints);
     }
 
     private ParsedStatement(StatementType type, Statement statement, String sqlWithoutComments) {
-      this(type, null, statement, sqlWithoutComments, null, false);
+      this(type, null, statement, sqlWithoutComments, null, false, EMPTY_OPTIONS);
     }
 
     private ParsedStatement(
@@ -228,33 +247,37 @@ private ParsedStatement(
         Statement statement,
         String sqlWithoutComments,
         QueryOptions defaultQueryOptions,
-        boolean returningClause) {
+        boolean returningClause,
+        ReadQueryUpdateTransactionOption[] optionsFromHints) {
       Preconditions.checkNotNull(type);
       this.type = type;
       this.clientSideStatement = clientSideStatement;
       this.statement = statement == null ? null : mergeQueryOptions(statement, defaultQueryOptions);
       this.sqlWithoutComments = Preconditions.checkNotNull(sqlWithoutComments);
       this.returningClause = returningClause;
+      this.optionsFromHints = optionsFromHints;
     }
 
     private ParsedStatement copy(Statement statement, QueryOptions defaultQueryOptions) {
       return new ParsedStatement(
           this.type,
           this.clientSideStatement,
-          statement,
+          statement.withReplacedSql(this.statement.getSql()),
           this.sqlWithoutComments,
           defaultQueryOptions,
-          this.returningClause);
+          this.returningClause,
+          this.optionsFromHints);
     }
 
     private ParsedStatement forCache() {
       return new ParsedStatement(
           this.type,
           this.clientSideStatement,
-          null,
+          Statement.of(this.statement.getSql()),
           this.sqlWithoutComments,
           null,
-          this.returningClause);
+          this.returningClause,
+          this.optionsFromHints);
     }
 
     @Override
@@ -287,6 +310,11 @@ public boolean hasReturningClause() {
       return this.returningClause;
     }
 
+    @InternalApi
+    public ReadQueryUpdateTransactionOption[] getOptionsFromHints() {
+      return this.optionsFromHints;
+    }
+
     /**
      * @return true if the statement is a query that will return a {@link
      *     com.google.cloud.spanner.ResultSet}.
@@ -480,14 +508,23 @@ ParsedStatement parse(Statement statement, QueryOptions defaultQueryOptions) {
   }
 
   private ParsedStatement internalParse(Statement statement, QueryOptions defaultQueryOptions) {
+    StatementHintParser statementHintParser =
+        new StatementHintParser(getDialect(), statement.getSql());
+    ReadQueryUpdateTransactionOption[] optionsFromHints = EMPTY_OPTIONS;
+    if (statementHintParser.hasStatementHints()
+        && !statementHintParser.getClientSideStatementHints().isEmpty()) {
+      statement =
+          statement.toBuilder().replace(statementHintParser.getSqlWithoutClientSideHints()).build();
+      optionsFromHints = convertHintsToOptions(statementHintParser.getClientSideStatementHints());
+    }
     String sql = removeCommentsAndTrim(statement.getSql());
     ClientSideStatementImpl client = parseClientSideStatement(sql);
     if (client != null) {
       return ParsedStatement.clientSideStatement(client, statement, sql);
     } else if (isQuery(sql)) {
-      return ParsedStatement.query(statement, sql, defaultQueryOptions);
+      return ParsedStatement.query(statement, sql, defaultQueryOptions, optionsFromHints);
     } else if (isUpdateStatement(sql)) {
-      return ParsedStatement.update(statement, sql, checkReturningClause(sql));
+      return ParsedStatement.update(statement, sql, checkReturningClause(sql), optionsFromHints);
     } else if (isDdlStatement(sql)) {
       return ParsedStatement.ddl(statement, sql);
     }
@@ -621,6 +658,10 @@ public String removeCommentsAndTrim(String sql) {
   /** Removes any statement hints at the beginning of the statement. */
   abstract String removeStatementHint(String sql);
 
+  @VisibleForTesting
+  static final ReadQueryUpdateTransactionOption[] EMPTY_OPTIONS =
+      new ReadQueryUpdateTransactionOption[0];
+
   /** Parameter information with positional parameters translated to named parameters. */
   @InternalApi
   public static class ParametersInfo {
@@ -697,9 +738,10 @@ public boolean checkReturningClause(String sql) {
     return checkReturningClauseInternal(sql);
   }
 
+  abstract Dialect getDialect();
+
   /**
-   * <<<<<<< HEAD Returns true if this dialect supports nested comments. ======= <<<<<<< HEAD
-   * Returns true if this dialect supports nested comments. >>>>>>> main
+   * Returns true if this dialect supports nested comments.
    *
    * <ul>
    *   <li>This method should return false for dialects that consider this to be a valid comment:
@@ -757,18 +799,6 @@ public boolean checkReturningClause(String sql) {
   /** Returns the query parameter prefix that should be used for this dialect. */
   abstract String getQueryParameterPrefix();
 
-  /**
-   * Returns true for characters that can be used as the first character in unquoted identifiers.
-   */
-  boolean isValidIdentifierFirstChar(char c) {
-    return Character.isLetter(c) || c == UNDERSCORE;
-  }
-
-  /** Returns true for characters that can be used in unquoted identifiers. */
-  boolean isValidIdentifierChar(char c) {
-    return isValidIdentifierFirstChar(c) || Character.isDigit(c) || c == DOLLAR;
-  }
-
   /** Reads a dollar-quoted string literal from position index in the given sql string. */
   String parseDollarQuotedString(String sql, int index) {
     // Look ahead to the next dollar sign (if any). Everything in between is the quote tag.
@@ -812,9 +842,9 @@ int skip(String sql, int currentIndex, @Nullable StringBuilder result) {
     } else if (currentChar == HYPHEN
         && sql.length() > (currentIndex + 1)
         && sql.charAt(currentIndex + 1) == HYPHEN) {
-      return skipSingleLineComment(sql, currentIndex, result);
+      return skipSingleLineComment(sql, /* prefixLength = */ 2, currentIndex, result);
     } else if (currentChar == DASH && supportsHashSingleLineComments()) {
-      return skipSingleLineComment(sql, currentIndex, result);
+      return skipSingleLineComment(sql, /* prefixLength = */ 1, currentIndex, result);
     } else if (currentChar == SLASH
         && sql.length() > (currentIndex + 1)
         && sql.charAt(currentIndex + 1) == ASTERISK) {
@@ -826,44 +856,31 @@ int skip(String sql, int currentIndex, @Nullable StringBuilder result) {
   }
 
   /** Skips a single-line comment from startIndex and adds it to result if result is not null. */
-  static int skipSingleLineComment(String sql, int startIndex, @Nullable StringBuilder result) {
-    int endIndex = sql.indexOf('\n', startIndex + 2);
-    if (endIndex == -1) {
-      endIndex = sql.length();
-    } else {
-      // Include the newline character.
-      endIndex++;
+  int skipSingleLineComment(
+      String sql, int prefixLength, int startIndex, @Nullable StringBuilder result) {
+    return skipSingleLineComment(getDialect(), sql, prefixLength, startIndex, result);
+  }
+
+  static int skipSingleLineComment(
+      Dialect dialect,
+      String sql,
+      int prefixLength,
+      int startIndex,
+      @Nullable StringBuilder result) {
+    SimpleParser simpleParser = new SimpleParser(dialect, sql, startIndex, false);
+    if (simpleParser.skipSingleLineComment(prefixLength)) {
+      appendIfNotNull(result, sql.substring(startIndex, simpleParser.getPos()));
     }
-    appendIfNotNull(result, sql.substring(startIndex, endIndex));
-    return endIndex;
+    return simpleParser.getPos();
   }
 
   /** Skips a multi-line comment from startIndex and adds it to result if result is not null. */
   int skipMultiLineComment(String sql, int startIndex, @Nullable StringBuilder result) {
-    // Current position is start + '/*'.length().
-    int pos = startIndex + 2;
-    // PostgreSQL allows comments to be nested. That is, the following is allowed:
-    // '/* test /* inner comment */ still a comment */'
-    int level = 1;
-    while (pos < sql.length()) {
-      if (supportsNestedComments()
-          && sql.charAt(pos) == SLASH
-          && sql.length() > (pos + 1)
-          && sql.charAt(pos + 1) == ASTERISK) {
-        level++;
-      }
-      if (sql.charAt(pos) == ASTERISK && sql.length() > (pos + 1) && sql.charAt(pos + 1) == SLASH) {
-        level--;
-        if (level == 0) {
-          pos += 2;
-          appendIfNotNull(result, sql.substring(startIndex, pos));
-          return pos;
-        }
-      }
-      pos++;
+    SimpleParser simpleParser = new SimpleParser(getDialect(), sql, startIndex, false);
+    if (simpleParser.skipMultiLineComment()) {
+      appendIfNotNull(result, sql.substring(startIndex, simpleParser.getPos()));
     }
-    appendIfNotNull(result, sql.substring(startIndex));
-    return sql.length();
+    return simpleParser.getPos();
   }
 
   /** Skips a quoted string from startIndex. */