3.10.2.4. 发送电子邮件

本节包含使用 CUBA 邮件发送机制发送电子邮件的实用指南。

我们看看以下任务：

  • 有 NewsItem 实体和 NewsItemEdit 界面。

  • NewsItem 实体包含以下属性： date 、 caption 、 content。

  • 我们希望每次通过 NewsItemEdit 界面创建新的 NewsItem 实例时向某些地址发送电子邮件。电子邮件应包含 NewsItem.caption 作为主题，并且应该从包含 NewsItem.content 的模板创建邮件消息正文。

  • 将以下代码添加到 NewsItemEdit.java：
  1. public class NewsItemEdit extends AbstractEditor<NewsItem> {
  3.     // Indicates that a new item was created in this editor
  4.     private boolean justCreated;
  6.     @Inject
  7.     protected EmailService emailService;
  9.     // This method is invoked when a new item is initialized
  10.     @Override
  11.     protected void initNewItem(NewsItem item) {
  12.         justCreated = true;
  13.     }
  15.     // This method is invoked after the screen commit
  16.     @Override
  17.     protected boolean postCommit(boolean committed, boolean close) {
  18.         if (committed && justCreated) {
  19.             // If a new entity was saved to the database, ask a user about sending an email
  20.             showOptionDialog(
  21.                     "Email",
  22.                     "Send the news item by email?",
  23.                     MessageType.CONFIRMATION,
  24.                     new Action[] {
  25.                             new DialogAction(DialogAction.Type.YES) {
  26.                                 @Override
  27.                                 public void actionPerform(Component component) {
  28.                                     sendByEmail();
  29.                                 }
  30.                             },
  31.                             new DialogAction(DialogAction.Type.NO)
  32.                     }
  33.             );
  34.         }
  35.         return super.postCommit(committed, close);
  36.     }
  38.     // Queues an email for sending asynchronously
  39.     private void sendByEmail() {
  40.         NewsItem newsItem = getItem();
  41.         EmailInfo emailInfo = new EmailInfo(
  42.                 "john.doe@company.com,jane.roe@company.com", // recipients
  43.                 newsItem.getCaption(), // subject
  44.                 null, // the "from" address will be taken from the "cuba.email.fromAddress" app property
  45.                 "com/company/demo/templates/news_item.txt", // body template
  46.                 Collections.singletonMap("newsItem", newsItem) // template parameters
  47.         );
  48.         emailService.sendEmailAsync(emailInfo);
  49.     }
  50. }

在上面的代码中，在 sendByEmail() 方法中调用 EmailService 并传递描述邮件消息的 EmailInfo 实例给 sendEmailAsync 方法。邮件消息的主体将基于 news_item.txt 模板创建。

  • 在 core 模块的 com.company.demo.templates 包中创建邮件消息主体模板文件 news_item.txt。
  1. The company news:
  2. ${newsItem.content}

这是一个 Freemarker 模板，其使用 EmailInfo 实例中传递的参数（在本例中为 newsItem ）。

  • 运行应用程序，打开 NewsItem 实体浏览界面并点击 Create。编辑界面将被打开。填写字段并点击 OK。将显示一个确认对话框，询问是否发送邮件。点击 Yes。

  • 切换到应用程序的 Administration > Email History 界面。将看到两个处于 Queue 状态的记录（按收件人数量）。这表示电子邮件在队列中但尚未发送。

  • 要处理队列，请设置计划任务。切换到应用程序的 Administration > Scheduled Tasks 界面。创建一个新任务并设置以下参数：

  • Bean Name - cuba_Emailer

  • Method Name - processQueuedEmails()

  • Singleton - yes（这对于中间层服务集群很重要）

  • Period, sec - 10

保存任务并点击 Activate。

如果之前没有为此项目设置定时任务的执行，则此阶段不会发生任何事情 - 在启动整个定时机制之前，任务不会执行。

  • 打开 modules/core/src/app.properties 文件并添加以下 属性：
  1. cuba.schedulingActive = true

重启应用服务。定时机制现在处于激活状态并调用电子邮件队列处理程序。

  • 转到 Administration > Email History 界面。如果发送成功，电子邮件的状态将为 Sent。否则最有可能为 Sending 或 Queue。在后一种情况下，可以在 build/tomcat/logs/app.log 中打开应用程序日志并找出原因。电子邮件发送机制将尝试多次（默认为 10 次）发送邮件消息，如果失败，设置状态为 Not sent。

  • 无法发送电子邮件的最常见原因是没有设置 SMTP 服务器参数。可以通过 app-core.cuba:type=Emailer JMX bean 或中间件中的应用程序属性文件中设置参数。我们看看后者。打开 modules/core/src/app.properties 文件并添加所需的参数。

  1. cuba.email.fromAddress = do-not-reply@company.com
  2. cuba.email.smtpHost = mail.company.com

重启应用程序服务。转到 Administration > JMX Console，找到 Emailer JMX bean 并尝试使用 sendTestEmail() 操作向自己发送测试邮件。

  • 现在发送机制已经正确设置，但它不会发送在 Not sent 状态中的邮件消息。所以必须在编辑界面中创建另一个 NewsItem。执行此操作然后观察在 Email History 界面中新邮件消息的状态如何更改为 Sent。