java.lang.Object

cloud.opencode.base.email.protocol.pop3.Pop3Client

All Implemented Interfaces:: AutoCloseable

public final class Pop3Client extends Object implements AutoCloseable

POP3 Protocol Client (RFC 1939) POP3协议客户端（RFC 1939）

Implements the Post Office Protocol version 3 for retrieving email messages from a remote server. Supports plain USER/PASS authentication, XOAUTH2, and STARTTLS (STLS) connection upgrade.

实现邮局协议第3版，用于从远程服务器检索邮件消息。支持USER/PASS明文认证、XOAUTH2认证以及STARTTLS（STLS）连接升级。

This class is NOT thread-safe. Each thread should use its own Pop3Client instance.

此类非线程安全。每个线程应使用独立的Pop3Client实例。

Since:

JDK 25, opencode-base-email V1.0.3

Author:

Leon Soo

See Also:

Constructor Summary

Constructors

Constructor

Description

Pop3Client(String host, int port, boolean ssl, boolean starttls, Duration connectionTimeout, Duration readTimeout)

Create a new POP3 client 创建新的POP3客户端
Method Summary

Modifier and Type

Method

Description

void

authXOAuth2(String username, String token)

Authenticate using AUTH XOAUTH2 使用AUTH XOAUTH2进行认证

void

close()

Close the connection without sending QUIT 不发送QUIT直接关闭连接

String

connect()

Connect to the POP3 server and read the greeting 连接到POP3服务器并读取问候语

void

dele(int msgNum)

DELE - mark a message for deletion DELE - 标记邮件待删除

boolean

isConnected()

Check if the connection is alive 检查连接是否存活

List<int[]>

list()

LIST - get the size of all messages LIST - 获取所有邮件的大小

int

list(int msgNum)

LIST n - get the size of a specific message LIST n - 获取指定邮件的大小

void

login(String username, String password)

Authenticate using USER/PASS commands 使用USER/PASS命令进行认证

void

noop()

NOOP - keep the connection alive NOOP - 保持连接活跃

void

quit()

QUIT - commit deletions and close the connection QUIT - 提交删除操作并关闭连接

String

retr(int msgNum)

RETR - retrieve a complete message RETR - 检索完整邮件

void

rset()

RSET - unmark all messages marked for deletion RSET - 取消所有标记为删除的邮件

int[]

stat()

STAT - get message count and total mailbox size in octets STAT - 获取邮件数量和邮箱总大小（字节）

String

top(int msgNum, int lines)

TOP - retrieve message headers and the first n lines of the body TOP - 检索邮件头和正文的前n行

List<String[]>

uidl()

UIDL - get unique IDs for all messages UIDL - 获取所有邮件的唯一标识

String

uidl(int msgNum)

UIDL n - get the unique ID of a specific message UIDL n - 获取指定邮件的唯一标识

Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details
- Pop3Client
  
  public Pop3Client(String host, int port, boolean ssl, boolean starttls, Duration connectionTimeout, Duration readTimeout)
  
  Create a new POP3 client 创建新的POP3客户端
  
  Parameters:
  
  host - the server hostname | 服务器主机名
  
  port - the server port | 服务器端口
  
  ssl - true for implicit SSL connection | true使用隐式SSL连接
  
  starttls - true to upgrade via STLS after connect | true在连接后通过STLS升级
  
  connectionTimeout - connection timeout | 连接超时
  
  readTimeout - read timeout | 读取超时
  
  Throws:
  
  NullPointerException - if host, connectionTimeout or readTimeout is null | host、connectionTimeout或readTimeout为null时抛出
Method Details
- connect
  
  public String connect() throws ProtocolException
  
  Connect to the POP3 server and read the greeting 连接到POP3服务器并读取问候语
  If STARTTLS is configured, sends the STLS command and upgrades the connection to TLS before returning.
  
  如果配置了STARTTLS，会发送STLS命令并将连接升级到TLS后返回。
  
  Returns:
  
  the server greeting text | 服务器问候语文本
  
  Throws:
  
  ProtocolException - if connection or greeting fails | 连接或问候失败时抛出
- login
  
  public void login(String username, String password) throws ProtocolException
  
  Authenticate using USER/PASS commands 使用USER/PASS命令进行认证
  
  Parameters:
  
  username - the username | 用户名
  
  password - the password | 密码
  
  Throws:
  
  ProtocolException - if authentication fails | 认证失败时抛出
  
  NullPointerException - if username or password is null | username或password为null时抛出
- authXOAuth2
  
  public void authXOAuth2(String username, String token) throws ProtocolException
  
  Authenticate using AUTH XOAUTH2 使用AUTH XOAUTH2进行认证
  Builds the XOAUTH2 authentication string per the Google XOAUTH2 spec, Base64-encodes it, and sends it with the AUTH command.
  
  按照Google XOAUTH2规范构建认证字符串，进行Base64编码后通过AUTH命令发送。
  
  Parameters:
  
  username - the email address | 邮箱地址
  
  token - the OAuth2 access token | OAuth2访问令牌
  
  Throws:
  
  ProtocolException - if authentication fails | 认证失败时抛出
  
  NullPointerException - if username or token is null | username或token为null时抛出
- stat
  
  public int[] stat() throws ProtocolException
  
  STAT - get message count and total mailbox size in octets STAT - 获取邮件数量和邮箱总大小（字节）
  
  Returns:
  
  an array of [count, totalSize] | 数组 [数量, 总大小]
  
  Throws:
  
  ProtocolException - if the command fails | 命令失败时抛出
- list
  
  public List<int[]> list() throws ProtocolException
  
  LIST - get the size of all messages LIST - 获取所有邮件的大小
  
  Returns:
  
  list of [messageNumber, sizeInOctets] arrays | [邮件编号, 大小（字节）] 数组列表
  
  Throws:
  
  ProtocolException - if the command fails | 命令失败时抛出
- list
  
  public int list(int msgNum) throws ProtocolException
  
  LIST n - get the size of a specific message LIST n - 获取指定邮件的大小
  
  Parameters:
  
  msgNum - the message number (1-based) | 邮件编号（从1开始）
  
  Returns:
  
  the message size in octets | 邮件大小（字节）
  
  Throws:
  
  ProtocolException - if the command fails | 命令失败时抛出
  
  IllegalArgumentException - if msgNum is less than 1 | msgNum小于1时抛出
- uidl
  
  public List<String[]> uidl() throws ProtocolException
  
  UIDL - get unique IDs for all messages UIDL - 获取所有邮件的唯一标识
  
  Returns:
  
  list of [messageNumber, uniqueId] arrays | [邮件编号, 唯一标识] 数组列表
  
  Throws:
  
  ProtocolException - if the command fails | 命令失败时抛出
- uidl
  
  public String uidl(int msgNum) throws ProtocolException
  
  UIDL n - get the unique ID of a specific message UIDL n - 获取指定邮件的唯一标识
  
  Parameters:
  
  msgNum - the message number (1-based) | 邮件编号（从1开始）
  
  Returns:
  
  the unique ID | 唯一标识
  
  Throws:
  
  ProtocolException - if the command fails | 命令失败时抛出
  
  IllegalArgumentException - if msgNum is less than 1 | msgNum小于1时抛出
- retr
  
  public String retr(int msgNum) throws ProtocolException
  
  RETR - retrieve a complete message RETR - 检索完整邮件
  Returns the raw RFC 2822 message content with byte-stuffing removed.
  
  返回去除字节填充后的原始RFC 2822邮件内容。
  
  Parameters:
  
  msgNum - the message number (1-based) | 邮件编号（从1开始）
  
  Returns:
  
  the raw message content | 原始邮件内容
  
  Throws:
  
  ProtocolException - if the command fails | 命令失败时抛出
  
  IllegalArgumentException - if msgNum is less than 1 | msgNum小于1时抛出
- top
  
  public String top(int msgNum, int lines) throws ProtocolException
  
  TOP - retrieve message headers and the first n lines of the body TOP - 检索邮件头和正文的前n行
  This is an optional POP3 extension command. Not all servers support it.
  
  这是一个可选的POP3扩展命令，并非所有服务器都支持。
  
  Parameters:
  
  msgNum - the message number (1-based) | 邮件编号（从1开始）
  
  lines - the number of body lines to retrieve | 要检索的正文行数
  
  Returns:
  
  the message headers and partial body | 邮件头和部分正文
  
  Throws:
  
  ProtocolException - if the command fails | 命令失败时抛出
  
  IllegalArgumentException - if msgNum is less than 1 or lines is negative | msgNum小于1或lines为负数时抛出
- dele
  
  public void dele(int msgNum) throws ProtocolException
  
  DELE - mark a message for deletion DELE - 标记邮件待删除
  The message is not actually removed until a successful QUIT.
  
  邮件在成功执行QUIT之前不会被实际删除。
  
  Parameters:
  
  msgNum - the message number (1-based) | 邮件编号（从1开始）
  
  Throws:
  
  ProtocolException - if the command fails | 命令失败时抛出
  
  IllegalArgumentException - if msgNum is less than 1 | msgNum小于1时抛出
- rset
  
  public void rset() throws ProtocolException
  
  RSET - unmark all messages marked for deletion RSET - 取消所有标记为删除的邮件
  
  Throws:
  
  ProtocolException - if the command fails | 命令失败时抛出
- noop
  
  public void noop() throws ProtocolException
  
  NOOP - keep the connection alive NOOP - 保持连接活跃
  
  Throws:
  
  ProtocolException - if the command fails | 命令失败时抛出
- quit
  
  public void quit() throws ProtocolException
  
  QUIT - commit deletions and close the connection QUIT - 提交删除操作并关闭连接
  Messages marked for deletion are permanently removed by the server when this command completes successfully.
  
  成功执行此命令后，服务器会永久删除标记为删除的邮件。
  
  Throws:
  
  ProtocolException - if the command fails | 命令失败时抛出
- close
  
  public void close()
  
  Close the connection without sending QUIT 不发送QUIT直接关闭连接
  Messages marked for deletion will NOT be removed by the server.
  
  标记为删除的邮件将不会被服务器删除。
  
  Specified by:
  
  close in interface AutoCloseable
- isConnected
  
  public boolean isConnected()
  
  Check if the connection is alive 检查连接是否存活
  
  Returns:
  
  true if connected | 已连接返回true

Class Pop3Client

Constructor Summary

Method Summary

Methods inherited from class Object

Constructor Details

Pop3Client

Method Details

connect

login

authXOAuth2

stat

list

list

uidl

uidl

retr

top

dele

rset

noop

quit

close

isConnected