Clarify the meaning of retryMode in ConnectorMetadata JavaDoc

trinodb · May 13, 2022 · 342a15f · 342a15f
1 parent 98f4957
commit 342a15f
Showing 1 changed file with 42 additions and 0 deletions.
diff --git a/core/trino-spi/src/main/java/io/trino/spi/connector/ConnectorMetadata.java b/core/trino-spi/src/main/java/io/trino/spi/connector/ConnectorMetadata.java
@@ -95,6 +95,13 @@ default ConnectorTableHandle getTableHandleForStatisticsCollection(ConnectorSess
     /**
      * Create initial handle for execution of table procedure. The handle will be used through planning process. It will be converted to final
      * handle used for execution via @{link {@link ConnectorMetadata#beginTableExecute}
+     *
+     * <p/>
+     * If connector does not support execution with retries, the method should throw:
+     * <pre>
+     *     new TrinoException(NOT_SUPPORTED, "This connector does not support query retries")
+     * </pre>
+     * unless {@code retryMode} is set to {@code NO_RETRIES}.
      */
     default Optional<ConnectorTableExecuteHandle> getTableHandleForExecute(
             ConnectorSession session,
@@ -464,6 +471,13 @@ default void finishStatisticsCollection(ConnectorSession session, ConnectorTable
 
     /**
      * Begin the atomic creation of a table with data.
+     *
+     * <p/>
+     * If connector does not support execution with retries, the method should throw:
+     * <pre>
+     *     new TrinoException(NOT_SUPPORTED, "This connector does not support query retries")
+     * </pre>
+     * unless {@code retryMode} is set to {@code NO_RETRIES}.
      */
     default ConnectorOutputTableHandle beginCreateTable(ConnectorSession session, ConnectorTableMetadata tableMetadata, Optional<ConnectorTableLayout> layout, RetryMode retryMode)
     {
@@ -491,6 +505,13 @@ default void cleanupQuery(ConnectorSession session) {}
 
     /**
      * Begin insert query.
+     *
+     * <p/>
+     * If connector does not support execution with retries, the method should throw:
+     * <pre>
+     *     new TrinoException(NOT_SUPPORTED, "This connector does not support query retries")
+     * </pre>
+     * unless {@code retryMode} is set to {@code NO_RETRIES}.
      */
     default ConnectorInsertTableHandle beginInsert(ConnectorSession session, ConnectorTableHandle tableHandle, List<ColumnHandle> columns, RetryMode retryMode)
     {
@@ -531,6 +552,13 @@ default CompletableFuture<?> refreshMaterializedView(ConnectorSession session, S
 
     /**
      * Begin materialized view query.
+     *
+     * <p/>
+     * If connector does not support execution with retries, the method should throw:
+     * <pre>
+     *     new TrinoException(NOT_SUPPORTED, "This connector does not support query retries")
+     * </pre>
+     * unless {@code retryMode} is set to {@code NO_RETRIES}.
      */
     default ConnectorInsertTableHandle beginRefreshMaterializedView(ConnectorSession session, ConnectorTableHandle tableHandle, List<ConnectorTableHandle> sourceTableHandles, RetryMode retryMode)
     {
@@ -573,6 +601,13 @@ default ColumnHandle getUpdateRowIdColumnHandle(ConnectorSession session, Connec
 
     /**
      * Begin delete query.
+     *
+     * <p/>
+     * If connector does not support execution with retries, the method should throw:
+     * <pre>
+     *     new TrinoException(NOT_SUPPORTED, "This connector does not support query retries")
+     * </pre>
+     * unless {@code retryMode} is set to {@code NO_RETRIES}.
      */
     default ConnectorTableHandle beginDelete(ConnectorSession session, ConnectorTableHandle tableHandle, RetryMode retryMode)
     {
@@ -593,6 +628,13 @@ default void finishDelete(ConnectorSession session, ConnectorTableHandle tableHa
      * Do whatever is necessary to start an UPDATE query, returning the {@link ConnectorTableHandle}
      * instance that will be passed to split generation, and to the {@link #finishUpdate} method.
      *
+     * <p/>
+     * If connector does not support execution with retries, the method should throw:
+     * <pre>
+     *     new TrinoException(NOT_SUPPORTED, "This connector does not support query retries")
+     * </pre>
+     * unless {@code retryMode} is set to {@code NO_RETRIES}.
+     *
      * @param session The session in which to start the update operation.
      * @param tableHandle A ConnectorTableHandle for the table to be updated.
      * @param updatedColumns A list of the ColumnHandles of columns that will be updated by this UPDATE