Class KnoluxS3ClientFactory

java.lang.Object
com.knolux.s3.KnoluxS3ClientFactory
All Implemented Interfaces:
AutoCloseable
public class KnoluxS3ClientFactory extends Object implements AutoCloseable
S3AsyncClient 工廠，以 KnoluxS3ConnectionDetails 的快取鍵管理 client 實例。

快取策略

以 KnoluxS3ConnectionDetails.toCacheKey() 為鍵，相同連線參數共用同一個 S3AsyncClient 實例，避免重複建立 Netty EventLoopGroup。 HTTP client 與 S3AsyncClient 分開快取，以便 close() 能正確釋放所有資源。

支援情境

  • K8s 內部直連（HTTP） — 直接對 SeaweedFS 發送請求
  • 自簽 HTTPS — trustSelfSigned=true 略過憑證鏈驗證（非正式環境）
  • Nginx 反向代理 — removePathPrefix=true； pathPrefix 附加至 endpoint URI，使 Nginx 可正確 route； KnoluxNoPathPrefixSigner 在計算簽章時移除前綴
  • 標準 AWS S3 — endpoint 留空、forcePathStyle=false

生命週期

本類別實作 AutoCloseable，Spring 容器關閉時透過 @Bean(destroyMethod = "close") 自動呼叫 close()， 依序釋放 S3AsyncClient 再釋放 Netty HTTP client。 注意：close() 不等待進行中的非同步 I/O 完成； 呼叫方應在關閉前確認所有 CompletableFuture 已完成或取消。

See Also:

  • Constructor Details

    • KnoluxS3ClientFactory

      public KnoluxS3ClientFactory(KnoluxS3ConnectionDetails defaultDetails)
      Parameters:
      defaultDetails - 靜態模式（getClient()）使用的預設連線參數

  • Method Details

    • getClient

      public software.amazon.awssdk.services.s3.S3AsyncClient getClient(KnoluxS3ConnectionDetails details)
      取得與指定連線參數對應的 S3AsyncClient。

      相同 KnoluxS3ConnectionDetails.toCacheKey() 的參數會回傳同一個快取實例。 details 為 null 時使用建構時注入的預設連線（靜態模式）。

      Parameters:
      details - 連線參數；null 代表使用預設連線
      Returns:
      對應的 S3AsyncClient（已快取，不可自行 close）
      Throws:
      IllegalStateException - 若 accessKey 或 secretKey 為 null

    • getClient

      public software.amazon.awssdk.services.s3.S3AsyncClient getClient()
      使用預設連線取得 S3AsyncClient（靜態模式捷徑）。
      Returns:
      預設連線的 S3AsyncClient

    • close

      public void close()
      關閉所有快取的 S3AsyncClient 與 Netty HTTP client，釋放執行緒資源。

      可安全多次呼叫（冪等）。關閉順序：S3AsyncClient 先、HTTP client 後。 注意：此方法不等待進行中的 I/O 完成，未完成的 CompletableFuture 可能收到 ClosedChannelException。

      Specified by:
      close in interface AutoCloseable