001/*
002 * Copyright 2002-2014 the original author or authors.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *      https://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package org.springframework.mail.javamail;
018
019import java.io.InputStream;
020import javax.mail.internet.MimeMessage;
021
022import org.springframework.mail.MailException;
023import org.springframework.mail.MailSender;
024
025/**
026 * Extended {@link org.springframework.mail.MailSender} interface for JavaMail,
027 * supporting MIME messages both as direct arguments and through preparation
028 * callbacks. Typically used in conjunction with the {@link MimeMessageHelper}
029 * class for convenient creation of JavaMail {@link MimeMessage MimeMessages},
030 * including attachments etc.
031 *
032 * <p>Clients should talk to the mail sender through this interface if they need
033 * mail functionality beyond {@link org.springframework.mail.SimpleMailMessage}.
034 * The production implementation is {@link JavaMailSenderImpl}; for testing,
035 * mocks can be created based on this interface. Clients will typically receive
036 * the JavaMailSender reference through dependency injection.
037 *
038 * <p>The recommended way of using this interface is the {@link MimeMessagePreparator}
039 * mechanism, possibly using a {@link MimeMessageHelper} for populating the message.
040 * See {@link MimeMessageHelper MimeMessageHelper's javadoc} for an example.
041 *
042 * <p>The entire JavaMail {@link javax.mail.Session} management is abstracted
043 * by the JavaMailSender. Client code should not deal with a Session in any way,
044 * rather leave the entire JavaMail configuration and resource handling to the
045 * JavaMailSender implementation. This also increases testability.
046 *
047 * <p>A JavaMailSender client is not as easy to test as a plain
048 * {@link org.springframework.mail.MailSender} client, but still straightforward
049 * compared to traditional JavaMail code: Just let {@link #createMimeMessage()}
050 * return a plain {@link MimeMessage} created with a
051 * {@code Session.getInstance(new Properties())} call, and check the passed-in
052 * messages in your mock implementations of the various {@code send} methods.
053 *
054 * @author Juergen Hoeller
055 * @since 07.10.2003
056 * @see javax.mail.internet.MimeMessage
057 * @see javax.mail.Session
058 * @see JavaMailSenderImpl
059 * @see MimeMessagePreparator
060 * @see MimeMessageHelper
061 */
062public interface JavaMailSender extends MailSender {
063
064        /**
065         * Create a new JavaMail MimeMessage for the underlying JavaMail Session
066         * of this sender. Needs to be called to create MimeMessage instances
067         * that can be prepared by the client and passed to send(MimeMessage).
068         * @return the new MimeMessage instance
069         * @see #send(MimeMessage)
070         * @see #send(MimeMessage[])
071         */
072        MimeMessage createMimeMessage();
073
074        /**
075         * Create a new JavaMail MimeMessage for the underlying JavaMail Session
076         * of this sender, using the given input stream as the message source.
077         * @param contentStream the raw MIME input stream for the message
078         * @return the new MimeMessage instance
079         * @throws org.springframework.mail.MailParseException
080         * in case of message creation failure
081        */
082        MimeMessage createMimeMessage(InputStream contentStream) throws MailException;
083
084        /**
085         * Send the given JavaMail MIME message.
086         * The message needs to have been created with {@link #createMimeMessage()}.
087         * @param mimeMessage message to send
088         * @throws org.springframework.mail.MailAuthenticationException
089         * in case of authentication failure
090         * @throws org.springframework.mail.MailSendException
091         * in case of failure when sending the message
092         * @see #createMimeMessage
093         */
094        void send(MimeMessage mimeMessage) throws MailException;
095
096        /**
097         * Send the given array of JavaMail MIME messages in batch.
098         * The messages need to have been created with {@link #createMimeMessage()}.
099         * @param mimeMessages messages to send
100         * @throws org.springframework.mail.MailAuthenticationException
101         * in case of authentication failure
102         * @throws org.springframework.mail.MailSendException
103         * in case of failure when sending a message
104         * @see #createMimeMessage
105         */
106        void send(MimeMessage... mimeMessages) throws MailException;
107
108        /**
109         * Send the JavaMail MIME message prepared by the given MimeMessagePreparator.
110         * <p>Alternative way to prepare MimeMessage instances, instead of
111         * {@link #createMimeMessage()} and {@link #send(MimeMessage)} calls.
112         * Takes care of proper exception conversion.
113         * @param mimeMessagePreparator the preparator to use
114         * @throws org.springframework.mail.MailPreparationException
115         * in case of failure when preparing the message
116         * @throws org.springframework.mail.MailParseException
117         * in case of failure when parsing the message
118         * @throws org.springframework.mail.MailAuthenticationException
119         * in case of authentication failure
120         * @throws org.springframework.mail.MailSendException
121         * in case of failure when sending the message
122         */
123        void send(MimeMessagePreparator mimeMessagePreparator) throws MailException;
124
125        /**
126         * Send the JavaMail MIME messages prepared by the given MimeMessagePreparators.
127         * <p>Alternative way to prepare MimeMessage instances, instead of
128         * {@link #createMimeMessage()} and {@link #send(MimeMessage[])} calls.
129         * Takes care of proper exception conversion.
130         * @param mimeMessagePreparators the preparator to use
131         * @throws org.springframework.mail.MailPreparationException
132         * in case of failure when preparing a message
133         * @throws org.springframework.mail.MailParseException
134         * in case of failure when parsing a message
135         * @throws org.springframework.mail.MailAuthenticationException
136         * in case of authentication failure
137         * @throws org.springframework.mail.MailSendException
138         * in case of failure when sending a message
139         */
140        void send(MimeMessagePreparator... mimeMessagePreparators) throws MailException;
141
142}