1 /*
2 * Copyright 2002-2014 the original author or authors.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 package org.springframework.mail.javamail;
18
19 import java.io.InputStream;
20 import javax.mail.internet.MimeMessage;
21
22 import org.springframework.mail.MailException;
23 import org.springframework.mail.MailSender;
24
25 /**
26 * Extended {@link org.springframework.mail.MailSender} interface for JavaMail,
27 * supporting MIME messages both as direct arguments and through preparation
28 * callbacks. Typically used in conjunction with the {@link MimeMessageHelper}
29 * class for convenient creation of JavaMail {@link MimeMessage MimeMessages},
30 * including attachments etc.
31 *
32 * <p>Clients should talk to the mail sender through this interface if they need
33 * mail functionality beyond {@link org.springframework.mail.SimpleMailMessage}.
34 * The production implementation is {@link JavaMailSenderImpl}; for testing,
35 * mocks can be created based on this interface. Clients will typically receive
36 * the JavaMailSender reference through dependency injection.
37 *
38 * <p>The recommended way of using this interface is the {@link MimeMessagePreparator}
39 * mechanism, possibly using a {@link MimeMessageHelper} for populating the message.
40 * See {@link MimeMessageHelper MimeMessageHelper's javadoc} for an example.
41 *
42 * <p>The entire JavaMail {@link javax.mail.Session} management is abstracted
43 * by the JavaMailSender. Client code should not deal with a Session in any way,
44 * rather leave the entire JavaMail configuration and resource handling to the
45 * JavaMailSender implementation. This also increases testability.
46 *
47 * <p>A JavaMailSender client is not as easy to test as a plain
48 * {@link org.springframework.mail.MailSender} client, but still straightforward
49 * compared to traditional JavaMail code: Just let {@link #createMimeMessage()}
50 * return a plain {@link MimeMessage} created with a
51 * {@code Session.getInstance(new Properties())} call, and check the passed-in
52 * messages in your mock implementations of the various {@code send} methods.
53 *
54 * @author Juergen Hoeller
55 * @since 07.10.2003
56 * @see javax.mail.internet.MimeMessage
57 * @see javax.mail.Session
58 * @see JavaMailSenderImpl
59 * @see MimeMessagePreparator
60 * @see MimeMessageHelper
61 */
62 public interface JavaMailSender extends MailSender {
63
64 /**
65 * Create a new JavaMail MimeMessage for the underlying JavaMail Session
66 * of this sender. Needs to be called to create MimeMessage instances
67 * that can be prepared by the client and passed to send(MimeMessage).
68 * @return the new MimeMessage instance
69 * @see #send(MimeMessage)
70 * @see #send(MimeMessage[])
71 */
72 MimeMessage createMimeMessage();
73
74 /**
75 * Create a new JavaMail MimeMessage for the underlying JavaMail Session
76 * of this sender, using the given input stream as the message source.
77 * @param contentStream the raw MIME input stream for the message
78 * @return the new MimeMessage instance
79 * @throws org.springframework.mail.MailParseException
80 * in case of message creation failure
81 */
82 MimeMessage createMimeMessage(InputStream contentStream) throws MailException;
83
84 /**
85 * Send the given JavaMail MIME message.
86 * The message needs to have been created with {@link #createMimeMessage()}.
87 * @param mimeMessage message to send
88 * @throws org.springframework.mail.MailAuthenticationException
89 * in case of authentication failure
90 * @throws org.springframework.mail.MailSendException
91 * in case of failure when sending the message
92 * @see #createMimeMessage
93 */
94 void send(MimeMessage mimeMessage) throws MailException;
95
96 /**
97 * Send the given array of JavaMail MIME messages in batch.
98 * The messages need to have been created with {@link #createMimeMessage()}.
99 * @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 }