KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > ivata > groupware > business > mail > Mail


1 /*
2  * Copyright (c) 2001 - 2005 ivata limited.
3  * All rights reserved.
4  * -----------------------------------------------------------------------------
5  * ivata groupware may be redistributed under the GNU General Public
6  * License as published by the Free Software Foundation;
7  * version 2 of the License.
8  *
9  * These programs are free software; you can redistribute them and/or
10  * modify them under the terms of the GNU General Public License
11  * as published by the Free Software Foundation; version 2 of the License.
12  *
13  * These programs are distributed in the hope that they will be useful,
14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
16  *
17  * See the GNU General Public License in the file LICENSE.txt for more
18  * details.
19  *
20  * If you would like a copy of the GNU General Public License write to
21  *
22  * Free Software Foundation, Inc.
23  * 59 Temple Place - Suite 330
24  * Boston, MA 02111-1307, USA.
25  *
26  *
27  * To arrange commercial support and licensing, contact ivata at
28  * http://www.ivata.com/contact.jsp
29  * -----------------------------------------------------------------------------
30  * $Log: Mail.java,v $
31  * Revision 1.3 2005/04/10 18:47:42 colinmacleod
32  * Changed i tag to em and b tag to strong.
33  *
34  * Revision 1.2 2005/04/09 17:20:00 colinmacleod
35  * Changed copyright text to GPL v2 explicitly.
36  *
37  * Revision 1.1.1.1 2005/03/10 17:51:13 colinmacleod
38  * Restructured ivata op around Hibernate/PicoContainer.
39  * Renamed ivata groupware.
40  *
41  * Revision 1.5 2004/11/12 18:16:08 colinmacleod
42  * Ordered imports.
43  *
44  * Revision 1.4 2004/11/12 15:57:22 colinmacleod
45  * Removed dependencies on SSLEXT.
46  * Moved Persistence classes to ivata masks.
47  *
48  * Revision 1.3 2004/11/03 17:15:39 colinmacleod
49  * added addUserEmailAddresses method.
50  * Improved setUesrAliases to check telecom addresses in the person.
51  *
52  * Revision 1.2 2004/07/13 19:48:12 colinmacleod
53  * Moved project to POJOs from EJBs.
54  * Applied PicoContainer to services layer (replacing session EJBs).
55  * Applied Hibernate to persistence layer (replacing entity EJBs).
56  *
57  * Revision 1.1 2004/03/27 10:31:26 colinmacleod
58  * Split off business logic from remote facades to POJOs.
59  * -----------------------------------------------------------------------------
60  */

61 package com.ivata.groupware.business.mail;
62
63 import java.util.Collection JavaDoc;
64 import java.util.List JavaDoc;
65
66 import javax.ejb.EJBException JavaDoc;
67
68 import com.ivata.groupware.admin.security.server.SecuritySession;
69 import com.ivata.groupware.admin.security.user.UserDO;
70 import com.ivata.groupware.business.drive.file.FileContentDO;
71 import com.ivata.groupware.business.mail.message.MessageDO;
72 import com.ivata.groupware.business.mail.message.MessageNotFoundException;
73 import com.ivata.groupware.business.mail.session.MailSession;
74 import com.ivata.mask.util.SystemException;
75 import com.ivata.mask.validation.ValidationErrors;
76
77
78 /**
79  * @author Colin MacLeod
80  * <a HREF='mailto:colin.macleod@ivata.com'>colin.macleod@ivata.com</a>
81  * @since Mar 27, 2004
82  * @version $Revision: 1.3 $
83  */

84 public interface Mail {
85
86     public final static String JavaDoc BUNDLE_PATH = "mail";
87
88     /**
89      * <p>Add a composed message to the drafts folder for later sending.</p>
90      *
91      * @param mailSession valid mail session to which the user should already be
92      * logged in.
93      * @param messageDO data object containing full details of the
94      * message to be added to the drafts.
95      * @return new <code>MessageDO</code> with the <code>id</code> set to the
96      * current value in the mail system.
97      */

98     MessageDO addMessageToDraftsFolder(final MailSession mailSession,
99             final MessageDO messageDO) throws SystemException;
100     /**
101      * <p>
102      * Add appropriate user addresses given a list of user aliases.
103      * </p>
104      *
105      * @param securitySession valid security session.
106      * @param userName name of the user who owns teh aliases.
107      * @param userAliases a <code>Collection</code> of <code>String</code>
108      * instances containing the local part of the different email aliases
109      * this user has. If the user has no aliaes, an empty collection should
110      * be provided.
111      * @param telecomAddresess a <code>Collection</code> containing all the
112      * user's existing email addresses, as <code>TelecomAddressDO</code>
113      * instances.
114      */

115     void addUserAliasEmailAddresses(final SecuritySession securitySession,
116             final String JavaDoc userName,
117             final Collection JavaDoc userAliases,
118             final Collection JavaDoc telecomAddresses,
119             final String JavaDoc emailAddressHost)
120             throws SystemException;
121
122     /**
123      * <p>Append attachments to a message located in the drafts folder.</p>
124      *
125      * @param mailSession valid mail session to which the user should already be
126      * logged in.
127      * @param id the unique identifier of the message to which we want to append
128      * attachments.
129      * @param attachments <code>Vector</code> of <code>String</code>s -
130      * filenames of files waiting in upload directory.
131      * @return <code>null</code> when the operation failed, otherwise the new
132      * message id.
133      * @exception MessageNotFoundException if the folder doesn't exist, or there
134      * is no matching mail in this folder.
135      */

136     MessageDO appendAttachments(final MailSession mailSession,
137             final String JavaDoc id,
138             final List JavaDoc attachments) throws SystemException;
139
140     /**
141      * <p>Create a new mail folder.</p>
142      *
143      * @param mailSession valid mail session to which the user should already be
144      * logged in.
145      * @param folderName the full path name of the folder to create.
146      */

147     void createFolder(final MailSession mailSession,
148             final String JavaDoc folderName)
149         throws SystemException;
150
151     /**
152      * <p>Create a new message in the drafts folder from an existing one,
153      * based on a 'thread'. The thread indicates that the message is a:<br/>
154      * <ul>
155      * <li>reply to all recipients of a previous message</li>
156      * <li>reply to one recipient of a previous message</li>
157      * <li>previous message(s) forwarded to new recipients</li>
158      * <li>an existing (draft) message being altered for resending</li>
159      * </ul></p>
160      *
161      * <p>This new message in the drafts folder can then be used to store
162      * attachments or for reviewing before sending.</p>
163      *
164      * @param mailSession valid mail session to which the user should already be
165      * logged in.
166      * @param folderName the name of the folder to copy existing messages from.
167      * @param messageIds the unique identifier of the messages to be extended.
168      * Can be <code>null</code> if a new message is requeested. When
169      * forwarding, multiple address identifiers may be specified otherwise
170      * (if editing a draft message or replying) only one message identifier
171      * should be set in the list.
172      * @param thread set to one of the constants in {@link MailConstants
173      * MailConstants}.
174      * @return populated message data object matching the required
175      * message, and with the <code>id</code> set to the message in the
176      * drafts folder.
177      */

178     MessageDO createThreadMessage(final MailSession mailSession,
179             final String JavaDoc folderName,
180             final List JavaDoc messageIds,
181             final Integer JavaDoc thread)
182         throws SystemException;
183
184     /**
185      * <p>Delete a list of messages from the trash folder.</p>
186      *
187      * @param mailSession valid mail session to which the user should already be
188      * logged in.
189      * @param ids the unique identifiers (<code>String</code> instances) of the
190      * messages to be removed.
191      * @exception MessageNotFoundException if the folder doesn't exist, or there
192      * is no matching mail in this folder.
193      */

194     void deleteMessagesFromTrash(final MailSession mailSession,
195             final List JavaDoc ids)
196         throws SystemException;
197
198     /**
199      * <p>Check whether or not a given folder pathname exists.</p>
200      *
201      * @param mailSession valid mail session to which the user should already be
202      * logged in.
203      * @param folderName the full path name of the folder to check.
204      * @return <code>true</code> if the folder exists, otherwise <code>false</code>.
205      *
206      * @ejb.interface-method
207      * view-type = "remote"
208      */

209     public boolean doesFolderExist(final MailSession mailSession,
210             final String JavaDoc folderName)
211         throws SystemException;
212
213     /**
214      * <p>This method retrieves the requested message and sets all the
215      * attributes of a MessageDO object for use on client side.</p>
216      *
217      * @param mailSession valid mail session to which the user should already be
218      * logged in.
219      * @param folderName the name of the folder the message is located in.
220      * @param id the unique identifier of the message.
221      * @return a MessageDO instance filled up with the messages attributes,
222      * except the contents of the attachments.
223      * @exception MessageNotFoundException if the folder doesn't exist, or there
224      * is no matching mail in this folder.
225      */

226     MessageDO findMessageByFolderMessageId(final MailSession mailSession,
227             final String JavaDoc folderName,
228             final String JavaDoc id) throws SystemException;
229
230     /**
231      * <p>Used in the main folder index page, this method returns the contents
232      * of a folder as a <code>Vector</code> of
233      * <code>MessageDO</code> instances.</p>
234      *
235      * <p><strong>Note:</strong> for efficiency reasons, this method does not fill the
236      * text, format or attachment values of the returned <code>MessageDO</code>
237      * instance. For that, you must call
238      * {@link #findMessageByFolderMessageId findMessageByFolderMessageId}.</p>
239      *
240      * @param mailSession valid mail session to which the user should already be
241      * logged in.
242      * @param folderName the name of the folder to list.
243      * @param sortBy the field to sort the returned list by. Set to one of the
244      * <code>SORT_...</code> constants in {@link MailConstants MailConstants}.
245      * @param sortAscending if <code>true</code> then the messages are sorted in
246      * ascending order, otherwise (<code>false</code>) they are descending.
247      * @return <code>Vector</code> of
248      * <code>MessageDO</code> instances.
249      */

250     List JavaDoc findMessagesInFolder(final MailSession mailSession,
251             final String JavaDoc folderName,
252             final Integer JavaDoc sortBy,
253             final boolean sortAscending)
254         throws SystemException;
255
256     /**
257      * <p>Retrieve an attachment's content and it's MimeType. This method is
258      * used to by the download servlet.</p>
259      *
260      * @param mailSession valid mail session to which the user should already be
261      * logged in.
262      * @param folderName the name of the folder the message is located in.
263      * @param messageId the unique identifier of the message.
264      * @param attachmentId the unique identifier of the attachment.
265      * @return attachment data object containing attachment content
266      * and mime type.
267      * @exception MessageNotFoundException if the folder doesn't exist, or there
268      * is no matching mail in this folder.
269      */

270     FileContentDO getAttachment(final MailSession mailSession,
271             final String JavaDoc folderName,
272             final String JavaDoc messageId,
273             final String JavaDoc attachmentId)
274         throws SystemException;
275
276     /**
277      * <p>Get the time the specified mail folder was last modified as a
278      * <code>long</code>. This can then be saved and compared to subsequent
279      * calls of this method to see if the folder has changed.</p>
280      *
281      * @param userName the name of the user for whom to locate the folder.
282      * @param folderName the name of the folder to locate.
283      * @return operating system specific timestamp indicating when the
284      * folder was last changed.
285      */

286     boolean hasNewMessages(final SecuritySession securitySession,
287             final String JavaDoc userName,
288             final String JavaDoc folderName) throws SystemException;
289
290     /**
291      * <p>Retrieve all of the email aliases for the user provided, on the curent
292      * email server. The aliases returned each one containing just the 'user' (or
293      * 'local') part of the email address, before the '@' sign.</p>
294      *
295      * @param userName the name of the user for whom to retrieve the email aliases.
296      * @return a <code>Collection</code> of <code>String</code> instances containing
297      * the local part of the different email aliases this user has. If the user
298      * has no aliaes, an empty collection is returned.
299      * @throws MandatoryFieldException if the user name is <code>null</code>.
300      *
301      * @ejb.interface-method
302      * view-type = "remote"
303      */

304     public List JavaDoc getUserAliases(final SecuritySession securitySession,
305             final String JavaDoc userName) throws SystemException;
306
307     /**
308      * <p>Get the vacation message for the user provided.</p>
309      *
310      * <p>The vacation message is a text the user can set, which will be sent
311      * to all emails received at this address while the user is not present.</p>
312      *
313      * @param userName the name of the user for whom to get the vacation message.
314      * @return the vacation message text for this user. If the user has no
315      * vacation message set, <code>null</code> is returned.
316      * @throws MandatoryFieldException if the user name is <code>null</code>.
317      */

318     String JavaDoc getVacationMessage(final SecuritySession securitySession,
319             final String JavaDoc userName) throws SystemException;
320     /**
321      * <p>Login to the mail system. This method should be called before any other,
322      * to establish the mail session and store.</p>
323      *
324      * @param userName this user name is used to log into the remote system.
325      * @param password the clear-text password to log into the remote system.
326      * @throws EJBException if the person cannot log in.
327      * @return the mail session (class <code>Session</code>) in a
328      * <code>SessionSerializer</code>.
329      */

330     MailSession login(final UserDO user,
331             final String JavaDoc password)
332         throws SystemException;
333
334     /**
335      * <p>Move a list of messages from one folder to another.</p>
336      *
337      * @param mailSession valid mail session to which the user should already be
338      * logged in.
339      * @param folderName the name of the folder the messages are currently located in.
340      * @param ids the unique identifiers (<code>String</code> instances) of the
341      * messages to be moved.
342      * @param targetFolderName the name of the the folder the message will be moved
343      * to.
344      * @exception MessageNotFoundException if the folder doesn't exist, or there
345      * is no matching mail in this folder.
346      */

347     void moveMessages(final MailSession mailSession,
348             final String JavaDoc folderName,
349             final List JavaDoc ids,
350             final String JavaDoc targetFolderName) throws SystemException;
351
352     /**
353      * <p>Send a mime email message that is already composed. If <code>id</code>
354      * has been set in <code>messageDO</code> it is assumed to point to a
355      * message in the drafts folder. Attachments are copied from the message
356      * who match the contents of <code>getAttachmentIds</code>. (All other
357      * attachments are discarded.)</p>
358      *
359      * @param mailSession valid mail session to which the user should already be
360      * logged in.
361      * @param messageDO data object containing full details of the
362      * message to be sent.
363      */

364     void send(final MailSession mailSession,
365             final MessageDO messageDO)
366         throws SystemException;
367
368     /**
369      * <p>Send an mime email message without using a data object.</p>
370      *
371      * @param mailSession valid mail session to which the user should already be
372      * logged in.
373      * @param fromAddress the address of the person sending the mail. This must
374      * be formatted according to <a
375      * HREF='http://www.faqs.org/rfcs/rfc822.HTML'>RFC822</a>.
376      * @param to recipients, a <code>Collection</code> containing instances of
377      * <code>String</code> or <code>UserLocal</code> or
378      * <code>PersonLocal</code>. A mixture of these types is allowed. If the
379      * type of an instance is <code>String</code>, then it must be formatted
380      * according to <a HREF='http://www.faqs.org/rfcs/rfc822.HTML'>RFC822</a>.
381      * Otherwise, if the type is <code>PersonLocal</code>, the method
382      * <code>getEmailAddress</code> must return a valid address string for
383      * this person.
384      * @param cc cc recipients. For format, see <code>to</code> parameter.
385      * @param bcc bcc recipients. For format, see <code>to</code> parameter.
386      * @param subject clear-text email subject field.
387      * @param content any valid email content type, as defined by
388      * <code>MimeMessage</code>.
389      * @param contentType mime type for the <code>content</code> field, as
390      * defined by <code>MimeMessage</code>.
391      * @param addToSentFolder if set to <code>true</code> then the mail is added
392      * to the sent folder of the current email session.
393      */

394     void send(final MailSession mailSession,
395             final String JavaDoc fromAddress,
396             final Collection JavaDoc to,
397             final Collection JavaDoc cc,
398             final Collection JavaDoc bcc,
399             final String JavaDoc subject,
400         Object JavaDoc content, String JavaDoc contentType, boolean addToSentFolder)
401         throws SystemException;
402
403     /**
404      * <p>Set all of the email aliases for the user provided, on the curent
405      * email server. Each alias in the collection should contain just the 'user'
406      * (or 'local') part of the email address, before the '@' sign.</p>
407      *
408      * @param userName the name of the user for whom to retrieve the email aliases.
409      * @param userAliases a <code>Collection</code> of <code>String</code>
410      * instances containing the local part of the different email aliases
411      * this user has. If the user has no aliaes, an empty collection should
412      * be provided.
413      * @throws MandatoryFieldException if either input is <code>null</code>.
414      */

415     void setUserAliases(final SecuritySession securitySession,
416             final String JavaDoc userName,
417             final Collection JavaDoc userAliases) throws SystemException;
418
419     /**
420      * <p>Set the vacation message for the user provided.</p>
421      *
422      * <p>The vacation message is a text the user can set, which will be sent
423      * to all emails received at this address while the user is not present.</p>
424      *
425      * @param userName the name of the user for whom to get the vacation message.
426      * @param vacationMessage vacation message text for this user. If the user
427      * has no vacation message set, set to <code>null</code>.
428      * @throws MandatoryFieldException if the user name is <code>null</code>.
429      */

430     void setVacationMessage(final SecuritySession securitySession,
431             final String JavaDoc userName,
432             final String JavaDoc vacationMessage) throws SystemException;
433
434     /**
435      * <p>Confirm all of the elements of the message are present and valid,
436      * before the message is sent.</p>
437      *
438      * @param messageDO data object to check for consistency and
439      * completeness.
440      * @return a collection of validation errors if any of the
441      * mandatory fields are missing, or if fields contain invalid values.
442      */

443     ValidationErrors validate(final SecuritySession securitySession,
444             final MessageDO messageDO) throws SystemException;
445 }
446
Popular Tags