KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > cocoon > mail > MailSender


1 /*
2  * Copyright 2004 The Apache Software Foundation.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 package org.apache.cocoon.mail;
17
18 import org.apache.cocoon.environment.SourceResolver;
19 import javax.mail.MessagingException JavaDoc;
20 import javax.mail.internet.AddressException JavaDoc;
21
22 /**
23  * A helper component used by the {@link org.apache.cocoon.acting.Sendmail}
24  * and the <code>sendmail.xsl</code> logicsheet for sending an email message.
25  *
26  * @since 2.1.5
27  * @author <a HREF="mailto:haul@apache.org">Christian Haul</a>
28  * @version CVS $Id: MailSender.java 155031 2005-02-23 17:32:37Z vgritsenko $
29  */
30 public interface MailSender {
31
32     String JavaDoc ROLE = MailSender.class.getName();
33
34     //
35 // Configure Component
36 //
37
38     /**
39      * Set SMTP hostname to use for mail sending.
40      */
41     void setSmtpHost(String JavaDoc hostname);
42
43     /**
44      * Set SMTP hostname, username, and password to use for mail sending.
45      */
46     public void setSmtpHost(String JavaDoc hostname, String JavaDoc username, String JavaDoc password);
47
48     //
49 // Compose Message
50 //
51
52     /**
53      * Set the <code>from</code> address of the message.
54      * @param from The address the message appears to be from.
55      */
56     void setFrom(String JavaDoc from);
57
58     /**
59      * Sets the destination address(es) for the message. The address
60      * is in the format, that
61      * {@link javax.mail.internet.InternetAddress#parse(String)} can handle
62      * (one or more email addresses separated by a commas).
63      * @param to the destination address(es)
64      * @see javax.mail.internet.InternetAddress#parse(String)
65      */
66     void setTo(String JavaDoc to);
67
68     /**
69      * Sets the reply-to address(es) for the message. The address
70      * is in the format, that
71      * {@link javax.mail.internet.InternetAddress#parse(String)} can handle
72      * (one or more email addresses separated by a commas).
73      * @param replyTo the address(es) that replies should be sent to
74      * @see javax.mail.internet.InternetAddress#parse(String)
75      */
76     void setReplyTo(String JavaDoc replyTo);
77
78     /**
79      * Sets the address(es), which should receive a carbon copy of the
80      * message. The address is in the format, that
81      * {@link javax.mail.internet.InternetAddress#parse(String)} can handle
82      * (one or more email addresses separated by a commas).
83      * @param cc the address(es), which should receive a carbon copy.
84      * @see javax.mail.internet.InternetAddress#parse(String)
85      */
86     void setCc(String JavaDoc cc);
87
88     /**
89      * Sets the address(es), which should receive a black carbon copy of
90      * the message. The address is in the format, that
91      * {@link javax.mail.internet.InternetAddress#parse(String)} can handle
92      * (one or more email addresses separated by a commas).
93      * @param bcc the address(es), which should receive a black carbon copy.
94      * @see javax.mail.internet.InternetAddress#parse(String)
95      */
96     void setBcc(String JavaDoc bcc);
97
98     /**
99      * Sets the character set for encoding the message. This has no effect,
100      * if any attachments are send in the message.
101      * @param charset the character set to be used for enbcoding the message
102      */
103     void setCharset(String JavaDoc charset);
104
105     /**
106      * Sets the subject line of the message.
107      * @param subject the subject line of the message
108      */
109     void setSubject(String JavaDoc subject);
110
111     /**
112      * Sets the body text of the email message.
113      * If both a text body and a body read from a source are set,
114      * only the latter will be used.
115      * @param body The body text of the email message
116      */
117     void setBody(String JavaDoc body);
118
119     /**
120      * Sets the body source URL of the email message.
121      * If both a text body and a body read from a source are set,
122      * only the latter will be used.
123      * @param src The body source URL of the email message
124      */
125     void setBodyFromSrc(String JavaDoc src);
126
127     /**
128      * Sets the optional body source Mime Type of the email message.
129      * @param srcMimeType The optional body source Mime Type of the email message
130      */
131     void setBodyFromSrcMimeType(String JavaDoc srcMimeType);
132
133     /**
134      * Add an attachement to the message to be send. The attachment can
135      * be of type <CODE>org.apache.excalibur.source.Source</CODE> or
136      * {@link org.apache.cocoon.servlet.multipart.Part} or its
137      * subclasses.
138      * @param attachment to be send with the message
139      * @see org.apache.excalibur.source.Source
140      */
141     void addAttachment(Object JavaDoc attachment);
142
143     /**
144      * Add an attachement to the message to be send. The attachment can
145      * be of type <CODE>org.apache.excalibur.source.Source</CODE> or
146      * {@link org.apache.cocoon.servlet.multipart.Part} or its
147      * subclasses.
148      * @param attachment to be send with the message
149      * @param type mime type (optional)
150      * @param name attachment name (optional)
151      * @see org.apache.excalibur.source.Source
152      */
153     void addAttachment(Object JavaDoc attachment, String JavaDoc type, String JavaDoc name);
154
155     /**
156      * Add an attachement to the message to be send. The attachment can
157      * be of type <CODE>org.apache.excalibur.source.Source</CODE> or
158      * {@link org.apache.cocoon.servlet.multipart.Part} or its
159      * subclasses.
160      * @param url URL to attach to the message
161      * @see org.apache.excalibur.source.Source
162      */
163     void addAttachmentURL(String JavaDoc url);
164
165     /**
166      * Add an attachement to the message to be send. The attachment can
167      * be of type <CODE>org.apache.excalibur.source.Source</CODE> or
168      * {@link org.apache.cocoon.servlet.multipart.Part} or its
169      * subclasses.
170      * @param url URL to attach to the message
171      * @param type mime type (optional)
172      * @param name attachment name (optional)
173      * @see org.apache.excalibur.source.Source
174      */
175     void addAttachmentURL(String JavaDoc url, String JavaDoc type, String JavaDoc name);
176
177     //
178 // Send Message
179 //
180
181     /**
182      * Assemble the message from the defined fields and send it. The source resolver
183      * is obtained from the hosting component container.
184      * @throws AddressException when problems with email addresses are found
185      * @throws MessagingException when message could not be send.
186      */
187     void send()
188     throws AddressException JavaDoc, MessagingException JavaDoc;
189
190     /**
191      * Assemble the message from the defined fields and send it.
192      * @throws AddressException when problems with email addresses are found
193      * @throws MessagingException when message could not be send.
194      * @deprecated Since 2.1.5. Use {@link #send()} which doesn't require passing the source resolver
195      */
196     void send(SourceResolver resolver)
197     throws AddressException JavaDoc, MessagingException JavaDoc;
198
199     /**
200      * Invokes the {@link #send()} method but catches any exception thrown. This
201      * method is intended to be used from the sendmail logicsheet. The source
202      * resolver is obtained from the hosting component container.
203      * @return true when successful
204      */
205     boolean sendIt();
206
207     /**
208      * Invokes the {@link #send(SourceResolver)} method but catches any exception thrown.
209      * This method is intended to be used from the sendmail logicsheet.
210      * @return true when successful
211      * @deprecated Since 2.1.5. Use {@link #sendIt()} which doesn't require passing the source resolver
212      */
213     boolean sendIt(SourceResolver resolver);
214
215     /**
216      * Accesses any Exception caught by {@link #sendIt(SourceResolver)}.
217      * @return AddressException or MessagingException
218      */
219     Exception JavaDoc getException();
220 }
221
Popular Tags