content: /*
   * 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 regarding copyright ownership.
   * The ASF licenses this file to You under the Apache License, Version 2.0
   * (the "License"); you may not use this file except in compliance with
   * the License. You may obtain a copy of the License at
   *
   *    http://www.apache.org/licenses/LICENSE-2.0
   *
   * Unless required by applicable law or agreed to in writing, software
   * distributed under the License is distributed on an "AS IS" BASIS,
   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   * See the License for the specific language governing permissions and
   * limitations under the License.
   */
  package org.apache.kafka.connect.sink;
  
  import org.apache.kafka.common.TopicPartition;
  import org.apache.kafka.common.metrics.PluginMetrics;
  
  import java.util.Map;
  import java.util.Set;
  
  /**
   * Context passed to {@link SinkTask}s, allowing them to access utilities in the Kafka Connect runtime.
   */
  public interface SinkTaskContext {
  
      /**
       * Get the Task configuration. This is the latest configuration and may differ from that passed on startup.
       * <p>
       * For example, this method can be used to obtain the latest configuration if an external secret has changed,
       * and the configuration is using variable references such as those compatible with
       * {@link org.apache.kafka.common.config.ConfigTransformer}.
       */
      Map<String, String> configs();
  
      /**
       * Reset the consumer offsets for the given topic partitions. SinkTasks should use this if they manage offsets
       * in the sink data store rather than using Kafka consumer offsets. For example, an HDFS connector might record
       * offsets in HDFS to provide exactly once delivery. When the SinkTask is started or a rebalance occurs, the task
       * would reload offsets from HDFS and use this method to reset the consumer to those offsets.
       * <p>
       * SinkTasks that do not manage their own offsets do not need to use this method.
       *
       * @param offsets map of offsets for topic partitions
       */
      void offset(Map<TopicPartition, Long> offsets);
  
      /**
       * Reset the consumer offsets for the given topic partition. SinkTasks should use this if they manage offsets
       * in the sink data store rather than using Kafka consumer offsets. For example, an HDFS connector might record
       * offsets in HDFS to provide exactly once delivery. When the topic partition is recovered the task
       * would reload offsets from HDFS and use this method to reset the consumer to the offset.
       * <p>
       * SinkTasks that do not manage their own offsets do not need to use this method.
       *
       * @param tp the topic partition to reset offset.
       * @param offset the offset to reset to.
       */
      void offset(TopicPartition tp, long offset);
  
      /**
       * Set the timeout in milliseconds. SinkTasks should use this to indicate that they need to retry certain
       * operations after the timeout. SinkTasks may have certain operations on external systems that may need
       * to be retried in case of failures. For example, appending a record to an HDFS file may fail due to temporary
       * network issues. SinkTasks can use this method to set how long to wait before retrying.
       * @param timeoutMs the backoff timeout in milliseconds.
       */
      void timeout(long timeoutMs);
  
      /**
       * Get the current set of assigned TopicPartitions for this task.
       * @return the set of currently assigned TopicPartitions
       */
      Set<TopicPartition> assignment();
  
      /**
       * Pause consumption of messages from the specified TopicPartitions.
       * @param partitions the partitions which should be paused
       */
      void pause(TopicPartition... partitions);
  
      /**
       * Resume consumption of messages from previously paused TopicPartitions.
       * @param partitions the partitions to resume
       */
      void resume(TopicPartition... partitions);
  
      /**
       * Request an offset commit. Sink tasks can use this to minimize the potential for redelivery
       * by requesting an offset commit as soon as they flush data to the destination system.
       * <p>
       * It is only a hint to the runtime and no timing guarantee should be assumed.
       */
      void requestCommit();
  
      /**
       * Get the reporter to which the sink task can report problematic or failed {@link SinkRecord records}
       * passed to the {@link SinkTask#put(java.util.Collection)} method. When reporting a failed record,
       * the sink task will receive a {@link java.util.concurrent.Future} that the task can optionally use to wait until
       * the failed record and exception have been written to Kafka. Note that the result of
       * this method may be null if this connector has not been configured to use a reporter.
       * <p>
       * This method was added in Apache Kafka 2.6. Sink tasks that use this method but want to
       * maintain backward compatibility so they can also be deployed to older Connect runtimes
       * should guard the call to this method with a try-catch block, since calling this method will result in a
       * {@link NoSuchMethodError} or {@link NoClassDefFoundError} when the sink connector is deployed to
       * Connect runtimes older than Kafka 2.6. For example:
       * <pre>
       *     ErrantRecordReporter reporter;
       *     try {
       *         reporter = context.errantRecordReporter();
       *     } catch (NoSuchMethodError | NoClassDefFoundError e) {
       *         reporter = null;
       *     }
       * </pre>
       *
       * @return the reporter; null if no error reporter has been configured for the connector
       * @since 2.6
       */
      default ErrantRecordReporter errantRecordReporter() {
          return null;
      }
  
      /**
       * Get a {@link PluginMetrics} that can be used to define metrics
       *
       * <p>This method was added in Apache Kafka 4.1. Tasks that use this method but want to
       * maintain backward compatibility so they can also be deployed to older Connect runtimes
       * should guard the call to this method with a try-catch block, since calling this method will result in a
       * {@link NoSuchMethodError} or {@link NoClassDefFoundError} when the connector is deployed to
       * Connect runtimes older than Kafka 4.1. For example:
       * <pre>
       *     PluginMetrics pluginMetrics;
       *     try {
       *         pluginMetrics = context.pluginMetrics();
       *     } catch (NoSuchMethodError | NoClassDefFoundError e) {
       *         pluginMetrics = null;
       *     }
       * </pre>
       *
       * @return the PluginMetrics instance
       * @since 4.1
       */
      PluginMetrics pluginMetrics();
  
  }
  