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}