Record Class EmailConfig

java.lang.Object
java.lang.Record
cloud.opencode.base.email.EmailConfig
public record EmailConfig(String host, int port, String username, String password, String oauth2Token, boolean ssl, boolean starttls, String defaultFrom, String defaultFromName, Duration timeout, Duration connectionTimeout, int maxRetries, int poolSize, Duration poolIdleTimeout, boolean debug, DkimConfig dkim) extends Record
Email Configuration Record 邮件配置记录

Immutable configuration for email sending.

邮件发送的不可变配置。

Features | 主要功能:

  • SMTP/SMTPS configuration - SMTP/SMTPS配置
  • SSL/TLS support - SSL/TLS支持
  • OAuth2 authentication (Gmail, Outlook) - OAuth2认证
  • Connection pool settings - 连接池设置
  • Retry configuration - 重试配置
  • DKIM signing support - DKIM签名支持

Usage Examples | 使用示例:

// Basic configuration
EmailConfig config = EmailConfig.builder()
    .host("smtp.example.com")
    .port(587)
    .username("user@example.com")
    .password("password")
    .starttls(true)
    .defaultFrom("noreply@example.com", "System")
    .build();

// SSL configuration (port 465)
EmailConfig config = EmailConfig.builder()
    .host("smtp.example.com")
    .port(465)
    .ssl(true)
    .username("user")
    .password("pass")
    .build();

// OAuth2 configuration (Gmail)
EmailConfig config = EmailConfig.builder()
    .host("smtp.gmail.com")
    .port(587)
    .username("user@gmail.com")
    .oauth2Token(accessToken)
    .starttls(true)
    .build();

Security | 安全性:

  • Thread-safe: Yes (immutable) - 线程安全: 是（不可变）
  • password / oauth2Token are stored as String, which the JVM cannot clear (interning + immutability). Heap dumps (post-mortem, hot dumps from jcmd GC.heap_dump, or container OOM dumps) expose the credential verbatim. After authentication completes, callers retaining a long-lived configuration object should call withCleared() to obtain a redacted copy and drop the original reference, bounding the retention window. The credential will still be visible on the wire (SMTP/IMAP authentication is not E2E) and in any GC-rooted intermediate buffers inside the Mail/Net stack, so this is mitigation, not elimination. A future char[]-throughout redesign is tracked for V1.0.5+.
  • password 与 oauth2Token 以 String 存储，JVM 无法清零（intern + 不可变）。 堆 dump（事后、jcmd GC.heap_dump 热 dump、容器 OOM dump）会原文暴露凭证。 认证完成后，长期持有配置对象的调用方应调 withCleared() 取脱敏副本并释放原引用， 缩短凭证驻留窗口。凭证在 SMTP/IMAP 认证线缆上、Mail/Net 栈中间缓冲里仍可见，所以这只是 缓解而非消除；char[] 全链路重设计列入 V1.0.5+ 跟踪。
Since:
JDK 25, opencode-base-email V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    EmailConfig.Builder
    Email Configuration Builder 邮件配置构建器

  • Constructor Summary

    Constructors
    Constructor
    Description
    EmailConfig(String host, int port, String username, String password, String oauth2Token, boolean ssl, boolean starttls, String defaultFrom, String defaultFromName, Duration timeout, Duration connectionTimeout, int maxRetries, int poolSize, Duration poolIdleTimeout, boolean debug, DkimConfig dkim)
    Creates an instance of a EmailConfig record class.

  • Method Summary

    Modifier and Type
    Method
    Description
    static EmailConfig.Builder
    builder()
    Create a new builder 创建新的构建器
    Duration
    connectionTimeout()
    Returns the value of the connectionTimeout record component.
    boolean
    debug()
    Returns the value of the debug record component.
    String
    defaultFrom()
    Returns the value of the defaultFrom record component.
    String
    defaultFromName()
    Returns the value of the defaultFromName record component.
    DkimConfig
    dkim()
    Returns the value of the dkim record component.
    final boolean
    equals(Object o)
    Indicates whether some other object is "equal to" this one.
    boolean
    hasDkim()
    Check if DKIM signing is configured 检查是否配置了DKIM签名
    final int
    hashCode()
    Returns a hash code value for this object.
    boolean
    hasOAuth2()
    Check if OAuth2 authentication is configured 检查是否配置了OAuth2认证
    String
    host()
    Returns the value of the host record component.
    int
    maxRetries()
    Returns the value of the maxRetries record component.
    String
    oauth2Token()
    Returns the value of the oauth2Token record component.
    String
    password()
    Returns the value of the password record component.
    Duration
    poolIdleTimeout()
    Returns the value of the poolIdleTimeout record component.
    int
    poolSize()
    Returns the value of the poolSize record component.
    int
    port()
    Returns the value of the port record component.
    boolean
    requiresAuth()
    Check if authentication is required 检查是否需要认证
    boolean
    ssl()
    Returns the value of the ssl record component.
    boolean
    starttls()
    Returns the value of the starttls record component.
    Duration
    timeout()
    Returns the value of the timeout record component.
    String
    toString()
    Return string representation with masked sensitive fields 返回屏蔽敏感字段的字符串表示
    String
    username()
    Returns the value of the username record component.
    EmailConfig
    withCleared()
    Returns a copy of this configuration with credential fields (password and oauth2Token) cleared to null.

    Methods inherited from class Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Constructor Details

    • EmailConfig

      public EmailConfig(String host, int port, String username, String password, String oauth2Token, boolean ssl, boolean starttls, String defaultFrom, String defaultFromName, Duration timeout, Duration connectionTimeout, int maxRetries, int poolSize, Duration poolIdleTimeout, boolean debug, DkimConfig dkim)
      Creates an instance of a EmailConfig record class.
      Parameters:
      host - the value for the host record component
      port - the value for the port record component
      username - the value for the username record component
      password - the value for the password record component
      oauth2Token - the value for the oauth2Token record component
      ssl - the value for the ssl record component
      starttls - the value for the starttls record component
      defaultFrom - the value for the defaultFrom record component
      defaultFromName - the value for the defaultFromName record component
      timeout - the value for the timeout record component
      connectionTimeout - the value for the connectionTimeout record component
      maxRetries - the value for the maxRetries record component
      poolSize - the value for the poolSize record component
      poolIdleTimeout - the value for the poolIdleTimeout record component
      debug - the value for the debug record component
      dkim - the value for the dkim record component

  • Method Details

    • builder

      public static EmailConfig.Builder builder()
      Create a new builder 创建新的构建器
      Returns:
      the builder | 构建器

    • requiresAuth

      public boolean requiresAuth()
      Check if authentication is required 检查是否需要认证
      Returns:
      true if authentication is required | 需要认证返回true

    • hasOAuth2

      public boolean hasOAuth2()
      Check if OAuth2 authentication is configured 检查是否配置了OAuth2认证
      Returns:
      true if OAuth2 is configured | 配置了OAuth2返回true

    • hasDkim

      public boolean hasDkim()
      Check if DKIM signing is configured 检查是否配置了DKIM签名
      Returns:
      true if DKIM is configured | 配置了DKIM返回true

    • withCleared

      public EmailConfig withCleared()
      Returns a copy of this configuration with credential fields (password and oauth2Token) cleared to null. Use after the SmtpEmailSender (or other consumer) has completed authentication, then drop the original reference, to bound the heap-dump exposure window for the credential. See the class-level Security note for the threat model and limits of this mitigation. 返回一份将凭证字段（password 与 oauth2Token）置 null 的配置副本。 在 SmtpEmailSender（或其他消费者）完成认证后调用， 并释放原引用，以缩短凭证在堆 dump 中暴露的窗口。威胁模型与缓解边界详见类级安全说明。
      Returns:
      a new EmailConfig with credentials nulled out | 凭证置空的新 EmailConfig
      Since:
      opencode-base-email V1.0.4

    • toString

      public String toString()
      Return string representation with masked sensitive fields 返回屏蔽敏感字段的字符串表示

      Passwords and OAuth2 tokens are masked to prevent accidental exposure in logs.

      密码和OAuth2令牌被屏蔽以防止在日志中意外暴露。

      Specified by:
      toString in class Record
      Returns:
      the masked string representation | 屏蔽后的字符串表示

    • hashCode

      public final int hashCode()
      Returns a hash code value for this object. The value is derived from the hash code of each of the record components.
      Specified by:
      hashCode in class Record
      Returns:
      a hash code value for this object

    • equals

      public final boolean equals(Object o)
      Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. Reference components are compared with Objects::equals(Object,Object); primitive components are compared with the compare method from their corresponding wrapper classes.
      Specified by:
      equals in class Record
      Parameters:
      o - the object with which to compare
      Returns:
      true if this object is the same as the o argument; false otherwise.

    • host

      public String host()
      Returns the value of the host record component.
      Returns:
      the value of the host record component

    • port

      public int port()
      Returns the value of the port record component.
      Returns:
      the value of the port record component

    • username

      public String username()
      Returns the value of the username record component.
      Returns:
      the value of the username record component

    • password

      public String password()
      Returns the value of the password record component.
      Returns:
      the value of the password record component

    • oauth2Token

      public String oauth2Token()
      Returns the value of the oauth2Token record component.
      Returns:
      the value of the oauth2Token record component

    • ssl

      public boolean ssl()
      Returns the value of the ssl record component.
      Returns:
      the value of the ssl record component

    • starttls

      public boolean starttls()
      Returns the value of the starttls record component.
      Returns:
      the value of the starttls record component

    • defaultFrom

      public String defaultFrom()
      Returns the value of the defaultFrom record component.
      Returns:
      the value of the defaultFrom record component

    • defaultFromName

      public String defaultFromName()
      Returns the value of the defaultFromName record component.
      Returns:
      the value of the defaultFromName record component

    • timeout

      public Duration timeout()
      Returns the value of the timeout record component.
      Returns:
      the value of the timeout record component

    • connectionTimeout

      public Duration connectionTimeout()
      Returns the value of the connectionTimeout record component.
      Returns:
      the value of the connectionTimeout record component

    • maxRetries

      public int maxRetries()
      Returns the value of the maxRetries record component.
      Returns:
      the value of the maxRetries record component

    • poolSize

      public int poolSize()
      Returns the value of the poolSize record component.
      Returns:
      the value of the poolSize record component

    • poolIdleTimeout

      public Duration poolIdleTimeout()
      Returns the value of the poolIdleTimeout record component.
      Returns:
      the value of the poolIdleTimeout record component

    • debug

      public boolean debug()
      Returns the value of the debug record component.
      Returns:
      the value of the debug record component

    • dkim

      public DkimConfig dkim()
      Returns the value of the dkim record component.
      Returns:
      the value of the dkim record component