001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017: package org.apache.cocoon.mail;
018:
019: import javax.mail.MessagingException;
020: import javax.mail.internet.AddressException;
021:
022: import org.apache.cocoon.environment.SourceResolver;
023:
024: /**
025: * A helper component used by the {@link org.apache.cocoon.acting.Sendmail}
026: * action and the <code>sendmail.xsl</code> logicsheet for sending email messages.
027: *
028: * <p>Please note that this component is not (and can not) be
029: * {@link org.apache.avalon.framework.thread.ThreadSafe}, so you need to lookup
030: * new instance in each processing thread.
031: *
032: * @since 2.1.5
033: * @version $Id: MailSender.java 469258 2006-10-30 20:21:40Z vgritsenko $
034: */
035: public interface MailSender {
036:
037: String ROLE = MailSender.class.getName();
038:
039: //
040: // Configure Component
041: //
042:
043: /**
044: * Set SMTP hostname to use for mail sending.
045: */
046: void setSmtpHost(String hostname);
047:
048: /**
049: * Set SMTP hostname, username, and password to use for mail sending.
050: */
051: void setSmtpHost(String hostname, String username, String password);
052:
053: //
054: // Compose Message
055: //
056:
057: /**
058: * Set the <code>from</code> address of the message.
059: *
060: * @param from The address the message appears to be from.
061: */
062: void setFrom(String from);
063:
064: /**
065: * Sets the destination address(es) for the message. The address
066: * is in the format, that
067: * {@link javax.mail.internet.InternetAddress#parse(String)} can handle
068: * (one or more email addresses separated by a commas).
069: *
070: * @param to the destination address(es)
071: * @see javax.mail.internet.InternetAddress#parse(String)
072: */
073: void setTo(String to);
074:
075: /**
076: * Sets the reply-to address(es) for the message. The address
077: * is in the format, that
078: * {@link javax.mail.internet.InternetAddress#parse(String)} can handle
079: * (one or more email addresses separated by a commas).
080: *
081: * @param replyTo the address(es) that replies should be sent to
082: * @see javax.mail.internet.InternetAddress#parse(String)
083: */
084: void setReplyTo(String replyTo);
085:
086: /**
087: * Sets the address(es), which should receive a carbon copy of the
088: * message. The address is in the format, that
089: * {@link javax.mail.internet.InternetAddress#parse(String)} can handle
090: * (one or more email addresses separated by a commas).
091: *
092: * @param cc the address(es), which should receive a carbon copy.
093: * @see javax.mail.internet.InternetAddress#parse(String)
094: */
095: void setCc(String cc);
096:
097: /**
098: * Sets the address(es), which should receive a black carbon copy of
099: * the message. The address is in the format, that
100: * {@link javax.mail.internet.InternetAddress#parse(String)} can handle
101: * (one or more email addresses separated by a commas).
102: *
103: * @param bcc the address(es), which should receive a black carbon copy.
104: * @see javax.mail.internet.InternetAddress#parse(String)
105: */
106: void setBcc(String bcc);
107:
108: /**
109: * Sets the subject line of the message.
110: * @param subject the subject line of the message
111: */
112: void setSubject(String subject);
113:
114: //
115: // Set the Body
116: //
117:
118: /**
119: * Sets the character set for encoding the message. This has effect
120: * only on text set via {@link #setBody(String)}.
121: *
122: * @param charset the character set to be used for encoding the message
123: * @deprecated Since 2.1.10. Use {@link #setBody(Object, String)}
124: */
125: void setCharset(String charset);
126:
127: /**
128: * Sets the body text of the email message.
129: * If both a text body and a body read from a source are set,
130: * only the latter will be used.
131: *
132: * @param body The body text of the email message
133: * @deprecated Since 2.1.10. Use {@link #setBody(Object)}
134: */
135: void setBody(String body);
136:
137: /**
138: * Sets the body source URL of the email message.
139: * If both a text body and a body read from a source are set,
140: * only the latter will be used.
141: *
142: * @param src The body source URL of the email message
143: * @deprecated Since 2.1.10. Use {@link #setBodyURL(String)}
144: */
145: void setBodyFromSrc(String src);
146:
147: /**
148: * Sets the optional body source Mime Type of the email message.
149: *
150: * @param srcMimeType The optional body source Mime Type of the email message
151: * @deprecated Since 2.1.10. Use {@link #setBodyURL(String, String)}
152: */
153: void setBodyFromSrcMimeType(String srcMimeType);
154:
155: /**
156: * Sets the body content of the email message.
157: *
158: * <p>The body can be any of: {@link org.apache.excalibur.source.Source},
159: * {@link org.apache.cocoon.servlet.multipart.Part}, {@link java.io.InputStream},
160: * <code>byte[]</code>, {@link String}, or a subclass.
161: *
162: * @param body The body text of the email message
163: */
164: void setBody(Object body);
165:
166: /**
167: * Sets the body content of the email message.
168: *
169: * <p>The body can be any of: {@link org.apache.excalibur.source.Source},
170: * {@link org.apache.cocoon.servlet.multipart.Part}, {@link java.io.InputStream},
171: * <code>byte[]</code>, {@link String}, or a subclass.
172: *
173: * @param body The body text of the email message
174: * @param type mime type (optional)
175: */
176: void setBody(Object body, String type);
177:
178: /**
179: * Sets the body content of the email message.
180: *
181: * @param url URL to use as message body
182: * @see org.apache.excalibur.source.Source
183: */
184: void setBodyURL(String url);
185:
186: /**
187: * Sets the body content of the email message.
188: *
189: * @param url URL to use as message body
190: * @param type mime type (optional)
191: * @see org.apache.excalibur.source.Source
192: */
193: void setBodyURL(String url, String type);
194:
195: //
196: // Add Attachments
197: //
198:
199: /**
200: * Add an attachement to the message to be send.
201: *
202: * <p>The attachment can be any of: {@link org.apache.excalibur.source.Source},
203: * {@link org.apache.cocoon.servlet.multipart.Part}, {@link java.io.InputStream},
204: * <code>byte[]</code>, {@link String}, or a subclass.
205: *
206: * @param attachment to be send with the message
207: */
208: void addAttachment(Object attachment);
209:
210: /**
211: * Add an attachement to the message to be send.
212: *
213: * <p>The attachment can be any of: {@link org.apache.excalibur.source.Source},
214: * {@link org.apache.cocoon.servlet.multipart.Part}, {@link java.io.InputStream},
215: * <code>byte[]</code>, {@link String}, or a subclass.
216: *
217: * @param attachment to be send with the message
218: * @param type mime type (optional)
219: * @param name attachment name (optional)
220: */
221: void addAttachment(Object attachment, String type, String name);
222:
223: /**
224: * Add an attachement to the message to be send.
225: *
226: * @param url URL to attach to the message
227: * @see org.apache.excalibur.source.Source
228: */
229: void addAttachmentURL(String url);
230:
231: /**
232: * Add an attachement to the message to be send.
233: *
234: * @param url URL to attach to the message
235: * @param type mime type (optional)
236: * @param name attachment name (optional)
237: * @see org.apache.excalibur.source.Source
238: */
239: void addAttachmentURL(String url, String type, String name);
240:
241: //
242: // Send Message
243: //
244:
245: /**
246: * Assemble the message from the defined fields and send it. The source resolver
247: * is obtained from the hosting component container.
248: * @throws AddressException when problems with email addresses are found
249: * @throws MessagingException when message could not be send.
250: */
251: void send() throws AddressException, MessagingException;
252:
253: /**
254: * Assemble the message from the defined fields and send it.
255: * @throws AddressException when problems with email addresses are found
256: * @throws MessagingException when message could not be send.
257: * @deprecated Since 2.1.5. Use {@link #send()} which doesn't require passing the source resolver
258: */
259: void send(SourceResolver resolver) throws AddressException,
260: MessagingException;
261:
262: /**
263: * Invokes the {@link #send()} method but catches any exception thrown. This
264: * method is intended to be used from the sendmail logicsheet. The source
265: * resolver is obtained from the hosting component container.
266: * @return true when successful
267: */
268: boolean sendIt();
269:
270: /**
271: * Invokes the {@link #send(SourceResolver)} method but catches any exception thrown.
272: * This method is intended to be used from the sendmail logicsheet.
273: * @return true when successful
274: * @deprecated Since 2.1.5. Use {@link #sendIt()} which doesn't require passing the source resolver
275: */
276: boolean sendIt(SourceResolver resolver);
277:
278: /**
279: * Accesses any Exception caught by {@link #sendIt(SourceResolver)}.
280: * @return AddressException or MessagingException
281: */
282: Exception getException();
283: }
|