001: /*
002: * Copyright 2002-2006 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: * http://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:
017: package org.springframework.mail.javamail;
018:
019: import java.io.InputStream;
020:
021: import javax.mail.internet.MimeMessage;
022:
023: import org.springframework.mail.MailException;
024: import 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())</code> call, and check the passed-in
053: * messages in your mock implementations of the various <code>send</code> 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: */
063: public 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)
084: throws MailException;
085:
086: /**
087: * Send the given JavaMail MIME message.
088: * The message needs to have been created with {@link #createMimeMessage()}.
089: * @param mimeMessage message to send
090: * @throws org.springframework.mail.MailAuthenticationException
091: * in case of authentication failure
092: * @throws org.springframework.mail.MailSendException
093: * in case of failure when sending the message
094: * @see #createMimeMessage
095: */
096: void send(MimeMessage mimeMessage) throws MailException;
097:
098: /**
099: * Send the given array of JavaMail MIME messages in batch.
100: * The messages need to have been created with {@link #createMimeMessage()}.
101: * @param mimeMessages messages to send
102: * @throws org.springframework.mail.MailAuthenticationException
103: * in case of authentication failure
104: * @throws org.springframework.mail.MailSendException
105: * in case of failure when sending a message
106: * @see #createMimeMessage
107: */
108: void send(MimeMessage[] mimeMessages) throws MailException;
109:
110: /**
111: * Send the JavaMail MIME message prepared by the given MimeMessagePreparator.
112: * <p>Alternative way to prepare MimeMessage instances, instead of
113: * {@link #createMimeMessage()} and {@link #send(MimeMessage)} calls.
114: * Takes care of proper exception conversion.
115: * @param mimeMessagePreparator the preparator to use
116: * @throws org.springframework.mail.MailPreparationException
117: * in case of failure when preparing the message
118: * @throws org.springframework.mail.MailParseException
119: * in case of failure when parsing the message
120: * @throws org.springframework.mail.MailAuthenticationException
121: * in case of authentication failure
122: * @throws org.springframework.mail.MailSendException
123: * in case of failure when sending the message
124: */
125: void send(MimeMessagePreparator mimeMessagePreparator)
126: throws MailException;
127:
128: /**
129: * Send the JavaMail MIME messages prepared by the given MimeMessagePreparators.
130: * <p>Alternative way to prepare MimeMessage instances, instead of
131: * {@link #createMimeMessage()} and {@link #send(MimeMessage[])} calls.
132: * Takes care of proper exception conversion.
133: * @param mimeMessagePreparators the preparator to use
134: * @throws org.springframework.mail.MailPreparationException
135: * in case of failure when preparing a message
136: * @throws org.springframework.mail.MailParseException
137: * in case of failure when parsing a message
138: * @throws org.springframework.mail.MailAuthenticationException
139: * in case of authentication failure
140: * @throws org.springframework.mail.MailSendException
141: * in case of failure when sending a message
142: */
143: void send(MimeMessagePreparator[] mimeMessagePreparators)
144: throws MailException;
145:
146: }
|