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}