The email sender setup Roo command sets up e-mail sending support in a Roo project by configuring JavaMailSenderImpl in Spring's application context. When the email sender setup command is executed, the following actions are performed by Roo:

The following listing shows the JavaMailSenderImpl configuration in the applicationContext.xml file:

<bean class="org.springframework.mail.javamail.
  JavaMailSenderImpl" id="mailSender">
  <property name="host" value="${email.host}"/>
  <property name="protocol" value="${email.protocol}"/>
  <property name="port" value="${email.port}"/>
  <property name="username" value="${email.username}"/>
  <property name="password" value="${email.password}"/>
  <property name="javaMailProperties">
    <props>
      <prop key="mail.smtp.auth">true</prop>
      <prop key="mail.smtp.starttls.enable">true</prop>
    </props>
  </property>
</bean>

In the given XML, JavaMailSenderImpl is configured with properties such as host, protocol, port, and so on. The values of these properties come from the email.properties file.

The following listing shows the email.properties file:

email.host=smtp.gmail.com
email.password=<password>
email.port=587
email.protocol=smtp
email.username=<username>

Instead of <username> and <password>, you'll see username and password values specified for the email sender setup command. The email.properties file is read by Spring's PropertyPlaceholderConfigurer to fill the placeholders defined in the configuration of JavaMailSender. The applicationContext.xml file uses the <property-placeholder> element of Spring's context to configure a PropertyPlaceholderConfigurer, as shown here:

<context:property-placeholder location="classpath*:META-INF/spring/*.properties"/>

The location attribute specifies that the PropertyPlaceholderConfigurer will look for properties files in the META-INF/spring directory of the project.

Let's now look at how to set up a SimpleMailMessage instance:

The email template setup command configures SimpleMailMessage as a bean in the applicationContext.xml file. The email template setup command accepts two arguments: from and subject, identifying the sender and subject of the email, respectively. When the email sender setup command is executed, the following actions are performed by Roo:

Now that JavaMailSenderImpl and SimpleMailMessage instances are configured in the application context XML file, we'll look at how to send e-mails.

To send an e-mail from your enterprise application you'll require access to both the JavaMailSenderImpl and SimpleMailMessage instances registered with the Spring's application context. Attributes referring to these instances are automatically added to a class by the field email template Roo command. The following code listing shows the FlightController.java class after the field email template command was executed against it:

import org.springframework.mail.MailSender;
....
public class FlightController {

  @Autowired
  private transient MailSender mailTemplate;

  @Autowired
  private transient SimpleMailMessage simpleMailMessage;

  public void sendMessage(java.lang.String mailTo,
   java.lang.String message) {
     simpleMailMessage.setTo(mailTo);
     simpleMailMessage.setText(message);
     mailTemplate.send(simpleMailMessage);
  }
}

In the given code, the mailTemplate attribute refers to the JavaMailSenderImpl instance and the simpleMailMessage attribute refers to the SimpleMailMessage instance registered with the Spring's application context. It is important to note that the type of the mailTemplate attribute is MailSender and not JavaMailSender. Also, a sendMessage method is added to the FlightController.java for sending e-mails. The sendMessage method accepts arguments that identify the e-mail recipient's address and the text content or body of the e-mail. The sendMessage method makes use of the send(SimpleMailMessage) method of MailSender to send e-mails.

You can now call the send method from within the FlightController.java class methods to send e-mails. In our example scenario, we called send method from the create method after a Flight instance was persisted, as shown here:

@RequestMapping(method = RequestMethod.POST)
 public String create(@Valid Flight flight, 
   BindingResult bindingResult, Model uiModel, 
   HttpServletRequest httpServletRequest) {
   ...
   flight.persist();
   sendMessage("<username>@gmail.com", 
   "A new instance of Flight entity with id " 
    + flight.getFlightId() 
    + "has been created.");
   
   return "redirect:/flights/" + 
     encodeUrlPathSegment(flight.getFlightId().toString(),  
     httpServletRequest);
 }

E-mail sending that we have discussed so far in this recipe, is synchronous in nature. Typically, e-mails are sent asynchronously by applications—something which can be achieved in Spring via the @Async annotation. The field email template command supports an async argument, that instructs Roo to do the following:

To send mails asynchronously when a FlightDescription instance is created, execute the following field email template command against the FlightDescriptionController class, as shown here:

.. roo> field email template --class ~.web.FlightDescriptionController --async

Now, copy the create(...) method from FlightDescriptionController_Roo_Controller.aj to FlightDescriptionController.java and add a call to the sendMessage(...) method, as shown here:

@RequestMapping(method = RequestMethod.POST)
public String create(@Valid FlightDescription...) {
  ...
  flightDescription.persist();
  sendMessage("<username>@gmail.com", 
    "FlightDescription instance created");
  return "redirect:/flightdescriptions/" + ..
}

As mentioned earlier, if you want to send mails with attachments, inline images, and so on, then you need to use MimeMessage instead of SimpleMailMessage. The field email template command adds SimpleMailMessage and MailSender type attributes to the Java class, as shown here:

  @Autowired
  private transient MailSender mailTemplate;

  @Autowired
  private transient SimpleMailMessage simpleMailMessage;

Now, MailSender defines methods which accept a SimpleMailMessage or SimpleMailMessage[] object as the argument. JavaMailSender, on the other hand, defines methods which accept a MimeMessage or MimeMessage[] object as the argument. So, we need to change the type of mailTemplate attribute from MailSender to JavaMailSender (a sub-interface of MailSender) to send messages of type MimeMessage. Also, we need to remove the simpleMailMessage attribute from the class because we need mail message of type MimeMessage and not SimpleMailMessage when sending mail messages with attachments or inline images.

So, how do we go about creating a MimeMessage? Spring provides the following utility classes that simplify creating a MimeMessage:

The following code shows modified FlightDescriptionController.java that makes use of MimeMessageHelper to send a mail message with an attachment when a new FlightDescription instance is created:

import javax.mail.MessagingException;
import javax.mail.internet.MimeMessage;
import org.springframework.mail.javamail.JavaMailSender;
import org.springframework.mail.javamail.MimeMessageHelper;
import org.springframework.scheduling.annotation.Async;
...
public class FlightDescriptionController {

  @Autowired
  private transient JavaMailSender mailTemplate;

  @RequestMapping(method = RequestMethod.POST)
  public String create(@Valid FlightDescription 
    flightDescription...) {
    ...
    flightDescription.persist();
    sendMessage(..);
    return "redirect:/flightDescriptions/" + ...);
  }
    
  @Async
  public void sendMessage(java.lang.String mailTo, 
    java.lang.String message) throws MessagingException {
    MimeMessage mimeMessage = 
      mailTemplate.createMimeMessage();

    MimeMessageHelper helper = 
      new MimeMessageHelper(mimeMessage, true);
    helper.setTo(mailTo);
    helper.setText(message);
    helper.addAttachment("logo.gif", 
      new File("C:/logo.gif"));
    mailTemplate.send(mimeMessage);
  }
}

In the FlightDescriptionController.java we made the following changes:

If JavaMail Session is configured in JNDI of your application server, then you'll need to modify the applicationContext.xml file of your Roo project to create the JavaMailSenderImpl instance using JavaMail Session configured in JNDI, as shown here:

<beans ... xmlns:jee="http://www.springframework.org/schema/jee" ... xsi:schemaLocation="http://www.springframework.org/schema/jee http://www.springframework.org/schema/jee/spring-jee-3.0.xsd">
.....
<jee:jndi-lookup id="mailSession" jndi-name="mail/session" />

<bean class="org.springframework.mail.javamail.JavaMailSenderImpl"   
  id="mailSender">
  <property name="session" value="mailSession"/>
</bean>
.....

The jndi-lookup element of Spring's jee namespace, shown in the given code, is responsible for accessing the JavaMail Session configured in JNDI with name "mail/session" (referred to by the jndi-name attribute) and making it available in a Spring application context with bean id as "mailSession".