chore: add clirr ignores + additional comments

clirr-ignored-differences.xml

@@ -16,4 +16,46 @@
     <className>com/google/cloud/spanner/jdbc/CloudSpannerJdbcConnection</className>
     <method>void setSavepointSupport(com.google.cloud.spanner.connection.SavepointSupport)</method>
   </difference>
+
+  <difference>
+    <differenceType>7012</differenceType>
+    <className>com/google/cloud/spanner/jdbc/CloudSpannerJdbcConnection</className>
+    <method>int getMaxPartitionedParallelism()</method>
+  </difference>
+  <difference>
+    <differenceType>7012</differenceType>
+    <className>com/google/cloud/spanner/jdbc/CloudSpannerJdbcConnection</className>
+    <method>int getMaxPartitions()</method>
+  </difference>
+  <difference>
+    <differenceType>7012</differenceType>
+    <className>com/google/cloud/spanner/jdbc/CloudSpannerJdbcConnection</className>
+    <method>boolean isAutoPartitionMode()</method>
+  </difference>
+  <difference>
+    <differenceType>7012</differenceType>
+    <className>com/google/cloud/spanner/jdbc/CloudSpannerJdbcConnection</className>
+    <method>boolean isDataBoostEnabled()</method>
+  </difference>
+  <difference>
+    <differenceType>7012</differenceType>
+    <className>com/google/cloud/spanner/jdbc/CloudSpannerJdbcConnection</className>
+    <method>void setAutoPartitionMode(boolean)</method>
+  </difference>
+  <difference>
+    <differenceType>7012</differenceType>
+    <className>com/google/cloud/spanner/jdbc/CloudSpannerJdbcConnection</className>
+    <method>void setDataBoostEnabled(boolean)</method>
+  </difference>
+  <difference>
+    <differenceType>7012</differenceType>
+    <className>com/google/cloud/spanner/jdbc/CloudSpannerJdbcConnection</className>
+    <method>void setMaxPartitionedParallelism(int)</method>
+  </difference>
+  <difference>
+    <differenceType>7012</differenceType>
+    <className>com/google/cloud/spanner/jdbc/CloudSpannerJdbcConnection</className>
+    <method>void setMaxPartitions(int)</method>
+  </difference>
+
 </differences>

src/main/java/com/google/cloud/spanner/jdbc/AbstractJdbcStatement.java

@@ -118,10 +118,12 @@ private StatementTimeout(long timeout, TimeUnit unit) {
     }
   }
 
+  /** Functional interface that throws {@link SQLException}. */
   interface JdbcFunction<T, R> {
     R apply(T t) throws SQLException;
   }
 
+  /** Runs the given function with the timeout that has been set on this statement. */
   protected <T> T runWithStatementTimeout(JdbcFunction<Connection, T> function)
       throws SQLException {
     checkClosed();

src/main/java/com/google/cloud/spanner/jdbc/CloudSpannerJdbcConnection.java

@@ -341,14 +341,18 @@ default Dialect getDialect() {
    * CloudSpannerJdbcStatement#partitionQuery(String, PartitionOptions, QueryOption...)} and {@link
    * CloudSpannerJdbcPreparedStatement#partitionQuery(PartitionOptions, QueryOption...)}.
    */
-  void setDataBoostEnabled(boolean dataBoostEnabled) throws SQLException;
+  default void setDataBoostEnabled(boolean dataBoostEnabled) throws SQLException {
+    throw new UnsupportedOperationException();
+  }
 
   /**
    * Returns whether data boost is enabled for partitioned queries. See also {@link
    * CloudSpannerJdbcStatement#partitionQuery(String, PartitionOptions, QueryOption...)} and {@link
    * CloudSpannerJdbcPreparedStatement#partitionQuery(PartitionOptions, QueryOption...)}.
    */
-  boolean isDataBoostEnabled() throws SQLException;
+  default boolean isDataBoostEnabled() throws SQLException {
+    throw new UnsupportedOperationException();
+  }
 
   /**
    * Sets whether this connection should always use partitioned queries when a query is executed on
@@ -357,35 +361,47 @@ default Dialect getDialect() {
    * flag in combination with {@link #setDataBoostEnabled(boolean)} to force all queries on this
    * connection to use data boost.
    */
-  void setAutoPartitionMode(boolean alwaysUsePartitionedQueries) throws SQLException;
+  default void setAutoPartitionMode(boolean alwaysUsePartitionedQueries) throws SQLException {
+    throw new UnsupportedOperationException();
+  }
 
   /** Returns whether this connection will execute all queries as partitioned queries. */
-  boolean isAutoPartitionMode() throws SQLException;
+  default boolean isAutoPartitionMode() throws SQLException {
+    throw new UnsupportedOperationException();
+  }
 
   /**
    * Sets the maximum number of partitions that should be included as a hint to Cloud Spanner when
    * partitioning a query on this connection. Note that this is only a hint and Cloud Spanner might
    * choose to ignore the hint.
    */
-  void setMaxPartitions(int maxPartitions) throws SQLException;
+  default void setMaxPartitions(int maxPartitions) throws SQLException {
+    throw new UnsupportedOperationException();
+  }
 
   /**
    * Gets the maximum number of partitions that should be included as a hint to Cloud Spanner when
    * partitioning a query on this connection. Note that this is only a hint and Cloud Spanner might
    * choose to ignore the hint.
    */
-  int getMaxPartitions() throws SQLException;
+  default int getMaxPartitions() throws SQLException {
+    throw new UnsupportedOperationException();
+  }
 
   /**
    * Sets the maximum degree of parallelism that is used when executing a partitioned query. A
    * partitioned query will use up to <code>maxThreads</code> to execute and retrieve the results
    * from Cloud Spanner. Set this value to <code>0</code>> to use the number of available processors
    * as returned by {@link Runtime#availableProcessors()}.
    */
-  void setMaxPartitionedParallelism(int maxThreads) throws SQLException;
+  default void setMaxPartitionedParallelism(int maxThreads) throws SQLException {
+    throw new UnsupportedOperationException();
+  }
 
   /** Returns the maximum degree of parallelism that is used for partitioned queries. */
-  int getMaxPartitionedParallelism() throws SQLException;
+  default int getMaxPartitionedParallelism() throws SQLException {
+    throw new UnsupportedOperationException();
+  }
 
   /**
    * @see

src/main/java/com/google/cloud/spanner/jdbc/CloudSpannerJdbcPreparedStatement.java

@@ -22,6 +22,10 @@
 import java.sql.ResultSet;
 import java.sql.SQLException;
 
+/**
+ * This interface is implemented by {@link PreparedStatement}s that are created on Cloud Spanner
+ * JDBC connections.
+ */
 public interface CloudSpannerJdbcPreparedStatement extends PreparedStatement {
 
   /**

src/main/java/com/google/cloud/spanner/jdbc/CloudSpannerJdbcStatement.java

@@ -22,6 +22,10 @@
 import java.sql.SQLException;
 import java.sql.Statement;
 
+/**
+ * This interface is implemented by {@link Statement}s that are created on Cloud Spanner JDBC
+ * connections.
+ */
 public interface CloudSpannerJdbcStatement extends Statement {
 
   /**

src/main/java/com/google/cloud/spanner/jdbc/JdbcConnection.java

@@ -581,6 +581,10 @@ public void bufferedWrite(Iterable<Mutation> mutations) throws SQLException {
     }
   }
 
+  /**
+   * Convenience method for calling a setter and translating any {@link SpannerException} to a
+   * {@link SQLException}.
+   */
   private <T> void set(BiConsumer<Connection, T> setter, T value) throws SQLException {
     checkClosed();
     try {
@@ -590,6 +594,10 @@ private <T> void set(BiConsumer<Connection, T> setter, T value) throws SQLExcept
     }
   }
 
+  /**
+   * Convenience method for calling a getter and translating any {@link SpannerException} to a
+   * {@link SQLException}.
+   */
   private <R> R get(Function<Connection, R> getter) throws SQLException {
     checkClosed();
     try {

src/main/java/com/google/cloud/spanner/jdbc/JdbcPartitionedQueryResultSet.java

@@ -20,6 +20,10 @@
 import com.google.common.base.Preconditions;
 import java.sql.Statement;
 
+/**
+ * {@link java.sql.ResultSet} implementation that is returned for queries that are executed with
+ * `RUN PARTITIONED QUERY ...`.
+ */
 class JdbcPartitionedQueryResultSet extends JdbcResultSet
     implements CloudSpannerJdbcPartitionedQueryResultSet {
   static JdbcPartitionedQueryResultSet of(

src/main/java/com/google/cloud/spanner/jdbc/JdbcResultSet.java

@@ -56,6 +56,8 @@ static JdbcResultSet of(com.google.cloud.spanner.ResultSet resultSet) {
   }
 
   static JdbcResultSet of(Statement statement, com.google.cloud.spanner.ResultSet resultSet) {
+    // Return a JDBC version of a PartitionedQueryResultSet if the Cloud Spanner Java client
+    // returned a PartitionedQueryResultSet.
     if (resultSet instanceof PartitionedQueryResultSet) {
       return JdbcPartitionedQueryResultSet.of(statement, (PartitionedQueryResultSet) resultSet);
     }