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