- Juergen Hoeller
/*
* Copyright 2002-2014 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.springframework.mail.javamail;
import java.io.InputStream;
import javax.mail.internet.MimeMessage;
import org.springframework.mail.MailException;
import org.springframework.mail.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.
Author: Juergen Hoeller See Also: Since: 07.10.2003
/**
* Extended {@link org.springframework.mail.MailSender} interface for JavaMail,
* supporting MIME messages both as direct arguments and through preparation
* callbacks. Typically used in conjunction with the {@link MimeMessageHelper}
* class for convenient creation of JavaMail {@link MimeMessage MimeMessages},
* including attachments etc.
*
* <p>Clients should talk to the mail sender through this interface if they need
* mail functionality beyond {@link org.springframework.mail.SimpleMailMessage}.
* The production implementation is {@link JavaMailSenderImpl}; for testing,
* mocks can be created based on this interface. Clients will typically receive
* the JavaMailSender reference through dependency injection.
*
* <p>The recommended way of using this interface is the {@link MimeMessagePreparator}
* mechanism, possibly using a {@link MimeMessageHelper} for populating the message.
* See {@link MimeMessageHelper MimeMessageHelper's javadoc} for an example.
*
* <p>The entire JavaMail {@link javax.mail.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.
*
* <p>A JavaMailSender client is not as easy to test as a plain
* {@link org.springframework.mail.MailSender} client, but still straightforward
* compared to traditional JavaMail code: Just let {@link #createMimeMessage()}
* return a plain {@link MimeMessage} created with a
* {@code Session.getInstance(new Properties())} call, and check the passed-in
* messages in your mock implementations of the various {@code send} methods.
*
* @author Juergen Hoeller
* @since 07.10.2003
* @see javax.mail.internet.MimeMessage
* @see javax.mail.Session
* @see JavaMailSenderImpl
* @see MimeMessagePreparator
* @see MimeMessageHelper
*/
public interface JavaMailSender extends MailSender {
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).
See Also: Returns: the new MimeMessage instance
/**
* 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).
* @return the new MimeMessage instance
* @see #send(MimeMessage)
* @see #send(MimeMessage[])
*/
MimeMessage createMimeMessage();
Create a new JavaMail MimeMessage for the underlying JavaMail Session
of this sender, using the given input stream as the message source.
Params: - contentStream – the raw MIME input stream for the message
Throws: - MailParseException –
in case of message creation failure
Returns: the new MimeMessage instance
/**
* Create a new JavaMail MimeMessage for the underlying JavaMail Session
* of this sender, using the given input stream as the message source.
* @param contentStream the raw MIME input stream for the message
* @return the new MimeMessage instance
* @throws org.springframework.mail.MailParseException
* in case of message creation failure
*/
MimeMessage createMimeMessage(InputStream contentStream) throws MailException;
Send the given JavaMail MIME message. The message needs to have been created with createMimeMessage(). Params: - mimeMessage – message to send
Throws: - MailAuthenticationException –
in case of authentication failure
- MailSendException –
in case of failure when sending the message
See Also:
/**
* Send the given JavaMail MIME message.
* The message needs to have been created with {@link #createMimeMessage()}.
* @param mimeMessage message to send
* @throws org.springframework.mail.MailAuthenticationException
* in case of authentication failure
* @throws org.springframework.mail.MailSendException
* in case of failure when sending the message
* @see #createMimeMessage
*/
void send(MimeMessage mimeMessage) throws MailException;
Send the given array of JavaMail MIME messages in batch. The messages need to have been created with createMimeMessage(). Params: - mimeMessages – messages to send
Throws: - MailAuthenticationException –
in case of authentication failure
- MailSendException –
in case of failure when sending a message
See Also:
/**
* Send the given array of JavaMail MIME messages in batch.
* The messages need to have been created with {@link #createMimeMessage()}.
* @param mimeMessages messages to send
* @throws org.springframework.mail.MailAuthenticationException
* in case of authentication failure
* @throws org.springframework.mail.MailSendException
* in case of failure when sending a message
* @see #createMimeMessage
*/
void send(MimeMessage... mimeMessages) 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.
Params: - 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
/**
* Send the JavaMail MIME message prepared by the given MimeMessagePreparator.
* <p>Alternative way to prepare MimeMessage instances, instead of
* {@link #createMimeMessage()} and {@link #send(MimeMessage)} calls.
* Takes care of proper exception conversion.
* @param mimeMessagePreparator the preparator to use
* @throws org.springframework.mail.MailPreparationException
* in case of failure when preparing the message
* @throws org.springframework.mail.MailParseException
* in case of failure when parsing the message
* @throws org.springframework.mail.MailAuthenticationException
* in case of authentication failure
* @throws org.springframework.mail.MailSendException
* in case of failure when sending the message
*/
void send(MimeMessagePreparator mimeMessagePreparator) 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.
Params: - 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
/**
* Send the JavaMail MIME messages prepared by the given MimeMessagePreparators.
* <p>Alternative way to prepare MimeMessage instances, instead of
* {@link #createMimeMessage()} and {@link #send(MimeMessage[])} calls.
* Takes care of proper exception conversion.
* @param mimeMessagePreparators the preparator to use
* @throws org.springframework.mail.MailPreparationException
* in case of failure when preparing a message
* @throws org.springframework.mail.MailParseException
* in case of failure when parsing a message
* @throws org.springframework.mail.MailAuthenticationException
* in case of authentication failure
* @throws org.springframework.mail.MailSendException
* in case of failure when sending a message
*/
void send(MimeMessagePreparator... mimeMessagePreparators) throws MailException;
}