1 package org.apache.fulcrum.commonsemail;
2
3 /*
4 * Licensed to the Apache Software Foundation (ASF) under one
5 * or more contributor license agreements. See the NOTICE file
6 * distributed with this work for additional information
7 * regarding copyright ownership. The ASF licenses this file
8 * to you under the Apache License, Version 2.0 (the
9 * "License"); you may not use this file except in compliance
10 * with the License. You may obtain a copy of the License at
11 *
12 * http://www.apache.org/licenses/LICENSE-2.0
13 *
14 * Unless required by applicable law or agreed to in writing,
15 * software distributed under the License is distributed on an
16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17 * KIND, either express or implied. See the License for the
18 * specific language governing permissions and limitations
19 * under the License.
20 */
21
22 import java.util.Hashtable;
23
24 import javax.mail.Address;
25 import javax.mail.MessagingException;
26 import javax.mail.Session;
27 import javax.mail.internet.MimeMessage;
28
29 import org.apache.commons.mail.Email;
30 import org.apache.commons.mail.EmailException;
31 import org.apache.commons.mail.HtmlEmail;
32 import org.apache.commons.mail.MultiPartEmail;
33 import org.apache.commons.mail.SimpleEmail;
34
35 /**
36 * A service taking care of most of the commons-email configuration such as
37 *
38 * <ul>
39 * <li>authentication</li>
40 * <li>mail session</li>
41 * <li>mail headers</li>
42 * </ul>
43 *
44 * @author <a href="mailto:siegfried.goeschl@it20one.at">Siegfried Goeschl</a>
45 */
46
47 public interface CommonsEmailService
48 {
49 /**
50 * Determines if any email for the given domain name will
51 * be sent or silently consumed by the service without
52 * delivering it.
53 *
54 * @param domainName the domain name
55 * @return true if the email will not be sent by the service
56 */
57 boolean isMailDoNotSend(String domainName);
58
59 /**
60 * Factory method to create a mail session based on the domain configuration.
61 *
62 * @param domainName the domain name
63 * @return a mail session
64 */
65 Session createSmtpSession(String domainName);
66
67 /**
68 * Factory method to create a mail session based on the domain configuration
69 * and a user-supplied username and password. We assume that SMTP AUTH is
70 * used.
71 *
72 * @param domainName the domain name
73 * @param username the user name used for SMTP authentication
74 * @param password the password used for SMTP authentication
75 * @return a mail session
76 */
77 Session createSmtpSession(String domainName, String username, String password);
78
79 /**
80 * Factory method for creating a SimpleEmail with fully
81 * configured mail session based on the domain configuration.
82 *
83 * @param domainName the sender of the email
84 * @return a SimpleEmail
85 * @throws EmailException creation failed
86 */
87 SimpleEmail createSimpleEmail(String domainName)
88 throws EmailException;
89
90 /**
91 * Factory method for creating a SimpleEmail
92 *
93 * @param domainName the sender of the email
94 * @param content the content of the email
95 * @return a SimpleEmail
96 * @throws EmailException creation failed
97 */
98 SimpleEmail createSimpleEmail(String domainName, Hashtable content)
99 throws EmailException;
100
101 /**
102 * Factory method for creating a MultiPartEmail with fully
103 * configured mail session based on the domain configuration.
104 *
105 * @param domainName the sender of the email
106 * @return a MultiPartEmail
107 * @throws EmailException creation failed
108 */
109 MultiPartEmail createMultiPartEmail(String domainName)
110 throws EmailException;
111
112 /**
113 * Factory method for creating a MultiPartEmail
114 *
115 * @param domainName the sender of the email
116 * @param content the content of the email
117 * @return a MultiPartEmail
118 * @throws EmailException creation failed
119 */
120 MultiPartEmail createMultiPartEmail(String domainName, Hashtable content)
121 throws EmailException;
122
123 /**
124 * Factory method for creating a HtmlEmail with fully
125 * configured mail session based on the domain configuration.
126 *
127 * @param domainName the sender of the email
128 * @return a MultiPartEmail
129 * @throws EmailException creation failed
130 */
131 HtmlEmail createHtmlEmail(String domainName)
132 throws EmailException;
133
134 /**
135 * Factory method for creating a HtmlEmail
136 *
137 * @param domainName the sender of the email
138 * @param content the content of the email
139 * @return a MultiPartEmail
140 * @throws EmailException creation failed
141 */
142 HtmlEmail createHtmlEmail(String domainName, Hashtable content)
143 throws EmailException;
144
145 /**
146 * Sends an email using the service instead of calling send()
147 * directly on the Email. This allows to overwrite the receivers
148 * of the email as an additional security measure for sending
149 * thousands of emails using real-world email addresses.
150 *
151 * @param domainName the sender of the email
152 * @param email the email to be sent
153 * @return the MimeMessage being sent
154 * @throws EmailException sending the email failed
155 */
156 MimeMessage send(String domainName, Email email)
157 throws EmailException;
158
159 /**
160 * Sends an email using the service instead of calling send()
161 * directly on the Email. The implementation uses the
162 * the from email address as domain name.
163 *
164 * @param email the email to be sent
165 * @return the MimeMessage being sent
166 * @throws EmailException sending the email failed
167 */
168 MimeMessage send(Email email) throws EmailException;
169
170 /**
171 * Sends a MimeMessage using the service instead of calling
172 * Transport.send(). This allows to overwrite the receivers
173 * of the email as an additional security measure for sending
174 * thousands of emails using real-world email addresses.
175 *
176 * @param domainName the sender of the email
177 * @param session the email session
178 * @param mimeMessage the email to be sent
179 * @return the MimeMessage being sent
180 * @throws MessagingException sending the email failed
181 */
182 MimeMessage send(String domainName, Session session, MimeMessage mimeMessage)
183 throws MessagingException;
184
185 /**
186 * Sends a MimeMessage using the service instead of calling
187 * Transport.send(). This allows to overwrite the receivers
188 * of the email as an additional security measure for sending
189 * thousands of emails using real-world email addresses.
190 *
191 * @param domainName the sender of the email
192 * @param session the email session
193 * @param mimeMessage the email to be sent
194 * @param recipients the list of recipients
195 * @return the MimeMessage being sent
196 * @throws MessagingException sending the email failed
197 */
198 MimeMessage send(String domainName, Session session, MimeMessage mimeMessage, Address[] recipients)
199 throws MessagingException;
200
201 /**
202 * Sends a MimeMessage using the service instead of calling
203 * Transport.send(). This allows to overwrite the receivers
204 * of the email as an additional security measure for sending
205 * thousands of emails using real-world email addresses.
206 *
207 * @param session the email session
208 * @param mimeMessage the email to be sent
209 * @return the MimeMessage being sent
210 * @throws MessagingException sending the email failed
211 */
212 MimeMessage send(Session session, MimeMessage mimeMessage)
213 throws MessagingException;
214
215 /**
216 * Get the delivery status of the previously sent email. This
217 * allows to do something sensible if email delivery failed.
218 *
219 * @param mimeMessage the email sent
220 * @return the delivery status
221 * @throws MessagingException getting the delivery status failed
222 */
223 SendDeliveryStatus getSendDeliveryStatus(MimeMessage mimeMessage)
224 throws MessagingException;
225 }