Interface SdkPlugin

All Superinterfaces:
AutoCloseable, SdkAutoCloseable
All Known Implementing Classes:
DpopAuthPlugin, LegacyMd5Plugin, S3DisableChunkEncodingIfConfiguredPlugin, S3ExpressPlugin, S3OverrideAuthSchemePropertiesPlugin
Functional Interface:
This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.
@SdkPublicApi @ThreadSafe @FunctionalInterface public interface SdkPlugin extends SdkAutoCloseable
A plugin that modifies SDK client configuration at client creation time or per-request execution time.

Plugins provide an extensibility mechanism for customizing SDK client behavior without modifying core SDK code. They can modify configuration such as retry policies, timeouts, execution interceptors, endpoints, and authentication schemes.

Plugins can be applied at two levels:

  • Client-level: Applied once during client creation and affects all requests made by that client
  • Request-level: Applied per-request and can override client-level configuration for specific requests

When to use plugins vs direct configuration:

  • Use direct configuration for simple, one-time client setup specific to your application
  • Use plugins when you need to:
    • Reuse the same configuration across multiple SDK clients
    • Package configuration as a library or module for distribution
    • Apply conditional or dynamic configuration logic
    • Compose multiple configuration strategies together

Client-level plugin example: 

  // Create a reusable plugin with multiple configuration settings
  SdkPlugin standardPlugin = config -> {
      config.endpointOverride(URI.create("https://127.0.0.1"))
            .overrideConfiguration(c -> c
                .apiCallTimeout(Duration.ofSeconds(30))
                .addExecutionInterceptor(new LoggingInterceptor()));
  };

  // Apply to multiple clients
  S3Client s3Client = S3Client.builder()
      .addPlugin(standardPlugin)
      .build();

  DynamoDbClient dynamoClient = DynamoDbClient.builder()
      .addPlugin(standardPlugin)
      .build();

Composing multiple plugins: 

  // Core plugin always applied
  SdkPlugin corePlugin = config -> {
      config.overrideConfiguration(c -> c.apiCallTimeout(Duration.ofSeconds(30)));
  };

  // Optional feature plugins
  SdkPlugin compressionPlugin = config -> {
      config.overrideConfiguration(c -> c.compressionConfiguration(
          CompressionConfiguration.builder().requestCompressionEnabled(true).build()));
  };

  SdkPlugin tracingPlugin = config -> {
      config.overrideConfiguration(c -> c.addExecutionInterceptor(new TracingInterceptor()));
  };

  // Conditionally compose plugins based on feature flags
  S3Client.Builder builder = S3Client.builder().addPlugin(corePlugin);
  if (compressionEnabled) {
      builder.addPlugin(compressionPlugin);
  }
  if (tracingEnabled) {
      builder.addPlugin(tracingPlugin);
  }
  S3Client client = builder.build();

Plugins are invoked after default configuration is applied, allowing them to override SDK defaults. Multiple plugins can be registered and are executed in the order they were added.

Configuration precedence (highest to lowest):

  1. Plugin settings (applied last, highest precedence)
  2. Direct client builder settings (e.g., .overrideConfiguration())
  3. Service-specific defaults
  4. Global SDK defaults

Note: Request-level plugins have different precedence behavior. Request-level override configuration takes precedence over request-level plugin settings, meaning direct request configuration will override plugin settings for that request.

See Also:

  • Method Details

    • configureClient

      void configureClient(SdkServiceClientConfiguration.Builder config)
      Modifies the provided client configuration.

      This method is invoked by the SDK to allow the plugin to customize the client configuration. Implementations can modify any aspect of the configuration exposed through the builder, including override configuration, endpoints, and authentication schemes.

      Parameters:
      config - the configuration builder to modify

    • close

      default void close()
      Description copied from interface: SdkAutoCloseable
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface SdkAutoCloseable