JavaMailSender (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

org.springframework.mail.javamail

## Interface JavaMailSender

- All Superinterfaces:
    MailSender
  All Known Implementing Classes:
    JavaMailSenderImpl

      public interface JavaMailSender
      extends MailSender

  Extended `MailSender` interface for JavaMail, supporting MIME messages both as direct arguments and through preparation callbacks. Typically used in conjunction with the `MimeMessageHelper` class for convenient creation of JavaMail `MimeMessages`, including attachments etc.

  Clients should talk to the mail sender through this interface if they need mail functionality beyond `SimpleMailMessage`. The production implementation is `JavaMailSenderImpl`; for testing, mocks can be created based on this interface. Clients will typically receive the JavaMailSender reference through dependency injection.

  The recommended way of using this interface is the `MimeMessagePreparator` mechanism, possibly using a `MimeMessageHelper` for populating the message. See `MimeMessageHelper's javadoc` for an example.

  The entire JavaMail `Session` management is abstracted by the JavaMailSender. Client code should not deal with a Session in any way, rather leave the entire JavaMail configuration and resource handling to the JavaMailSender implementation. This also increases testability.

  A JavaMailSender client is not as easy to test as a plain `MailSender` client, but still straightforward compared to traditional JavaMail code: Just let `createMimeMessage()` return a plain `MimeMessage` created with a `Session.getInstance(new Properties())` call, and check the passed-in messages in your mock implementations of the various `send` methods.

  Since:
    07.10.2003
  Author:
    Juergen Hoeller
  See Also:
    `MimeMessage`, `Session`, `JavaMailSenderImpl`, `MimeMessagePreparator`, `MimeMessageHelper`

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `MimeMessage` | `createMimeMessage()` Create a new JavaMail MimeMessage for the underlying JavaMail Session of this sender.
    `MimeMessage` | `createMimeMessage(InputStream contentStream)` Create a new JavaMail MimeMessage for the underlying JavaMail Session of this sender, using the given input stream as the message source.
    `void` | `send(MimeMessage mimeMessage)` Send the given JavaMail MIME message.
    `void` | `send(MimeMessage[] mimeMessages)` Send the given array of JavaMail MIME messages in batch.
    `void` | `send(MimeMessagePreparator mimeMessagePreparator)` Send the JavaMail MIME message prepared by the given MimeMessagePreparator.
    `void` | `send(MimeMessagePreparator[] mimeMessagePreparators)` Send the JavaMail MIME messages prepared by the given MimeMessagePreparators.

    - ### Methods inherited from interface org.springframework.mail.MailSender

      `send, send`

- - ### Method Detail

    - #### createMimeMessage

          MimeMessage createMimeMessage()

      Create a new JavaMail MimeMessage for the underlying JavaMail Session of this sender. Needs to be called to create MimeMessage instances that can be prepared by the client and passed to send(MimeMessage).
      Returns:
        the new MimeMessage instance
      See Also:
        `send(MimeMessage)`, `send(MimeMessage[])`

    - #### createMimeMessage

          MimeMessage createMimeMessage(InputStream contentStream)
                                        throws MailException

      Create a new JavaMail MimeMessage for the underlying JavaMail Session of this sender, using the given input stream as the message source.
      Parameters:
        `contentStream` - the raw MIME input stream for the message
      Returns:
        the new MimeMessage instance
      Throws:
        `MailParseException` - in case of message creation failure
        `MailException`

    - #### send

          void send(MimeMessage mimeMessage)
                    throws MailException

      Send the given JavaMail MIME message. The message needs to have been created with `createMimeMessage()`.
      Parameters:
        `mimeMessage` - message to send
      Throws:
        `MailAuthenticationException` - in case of authentication failure
        `MailSendException` - in case of failure when sending the message
        `MailException`
      See Also:
        `createMimeMessage()`

    - #### send

          void send(MimeMessage[] mimeMessages)
                    throws MailException

      Send the given array of JavaMail MIME messages in batch. The messages need to have been created with `createMimeMessage()`.
      Parameters:
        `mimeMessages` - messages to send
      Throws:
        `MailAuthenticationException` - in case of authentication failure
        `MailSendException` - in case of failure when sending a message
        `MailException`
      See Also:
        `createMimeMessage()`

    - #### send

          void send(MimeMessagePreparator mimeMessagePreparator)
                    throws MailException

      Send the JavaMail MIME message prepared by the given MimeMessagePreparator.

      Alternative way to prepare MimeMessage instances, instead of `createMimeMessage()` and `send(MimeMessage)` calls. Takes care of proper exception conversion.

      Parameters:
        `mimeMessagePreparator` - the preparator to use
      Throws:
        `MailPreparationException` - in case of failure when preparing the message
        `MailParseException` - in case of failure when parsing the message
        `MailAuthenticationException` - in case of authentication failure
        `MailSendException` - in case of failure when sending the message
        `MailException`

    - #### send

          void send(MimeMessagePreparator[] mimeMessagePreparators)
                    throws MailException

      Send the JavaMail MIME messages prepared by the given MimeMessagePreparators.

      Alternative way to prepare MimeMessage instances, instead of `createMimeMessage()` and `send(MimeMessage[])` calls. Takes care of proper exception conversion.

      Parameters:
        `mimeMessagePreparators` - the preparator to use
      Throws:
        `MailPreparationException` - in case of failure when preparing a message
        `MailParseException` - in case of failure when parsing a message
        `MailAuthenticationException` - in case of authentication failure
        `MailSendException` - in case of failure when sending a message
        `MailException`