JavaMailSender


1   /*
2    * Copyright 2002-2006 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  
21  import javax.mail.internet.MimeMessage  ;
22  
23  import org.springframework.mail.MailException;
24  import org.springframework.mail.MailSender;
25  
26  /**
27   * Extended {@link org.springframework.mail.MailSender} interface for JavaMail,
28   * supporting MIME messages both as direct arguments and through preparation
29   * callbacks. Typically used in conjunction with the {@link MimeMessageHelper}
30   * class for convenient creation of JavaMail {@link MimeMessage MimeMessages},
31   * including attachments etc.
32   *
33   * <p>Clients should talk to the mail sender through this interface if they need
34   * mail functionality beyond {@link org.springframework.mail.SimpleMailMessage}.
35   * The production implementation is {@link JavaMailSenderImpl}; for testing,
36   * mocks can be created based on this interface. Clients will typically receive
37   * the JavaMailSender reference through dependency injection.
38   *
39   * <p>The recommended way of using this interface is the {@link MimeMessagePreparator}
40   * mechanism, possibly using a {@link MimeMessageHelper} for populating the message.
41   * See {@link MimeMessageHelper MimeMessageHelper's javadoc} for an example.
42   *
43   * <p>The entire JavaMail {@link javax.mail.Session} management is abstracted
44   * by the JavaMailSender. Client code should not deal with a Session in any way,
45   * rather leave the entire JavaMail configuration and resource handling to the
46   * JavaMailSender implementation. This also increases testability.
47   *
48   * <p>A JavaMailSender client is not as easy to test as a plain
49   * {@link org.springframework.mail.MailSender} client, but still straightforward
50   * compared to traditional JavaMail code: Just let {@link #createMimeMessage()}
51   * return a plain {@link MimeMessage} created with a
52   * <code>Session.getInstance(new Properties())</code> call, and check the passed-in
53   * messages in your mock implementations of the various <code>send</code> methods.
54   *
55   * @author Juergen Hoeller
56   * @since 07.10.2003
57   * @see javax.mail.internet.MimeMessage
58   * @see javax.mail.Session
59   * @see JavaMailSenderImpl
60   * @see MimeMessagePreparator
61   * @see MimeMessageHelper
62   */
63  public interface JavaMailSender extends MailSender {
64  
65      /**
66       * Create a new JavaMail MimeMessage for the underlying JavaMail Session
67       * of this sender. Needs to be called to create MimeMessage instances
68       * that can be prepared by the client and passed to send(MimeMessage).
69       * @return the new MimeMessage instance
70       * @see #send(MimeMessage)
71       * @see #send(MimeMessage[])
72       */
73      MimeMessage   createMimeMessage();
74  
75      /**
76       * Create a new JavaMail MimeMessage for the underlying JavaMail Session
77       * of this sender, using the given input stream as the message source.
78       * @param contentStream the raw MIME input stream for the message
79       * @return the new MimeMessage instance
80       * @throws org.springframework.mail.MailParseException
81       * in case of message creation failure
82      */
83      MimeMessage   createMimeMessage(InputStream   contentStream) throws MailException;
84  
85      /**
86       * Send the given JavaMail MIME message.
87       * The message needs to have been created with {@link #createMimeMessage()}.
88       * @param mimeMessage message to send
89       * @throws org.springframework.mail.MailAuthenticationException
90       * in case of authentication failure
91       * @throws org.springframework.mail.MailSendException
92       * in case of failure when sending the message
93       * @see #createMimeMessage
94       */
95      void send(MimeMessage   mimeMessage) throws MailException;
96  
97      /**
98       * Send the given array of JavaMail MIME messages in batch.
99       * 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 }
144
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags