001: /*
002: * Copyright (c) 2001 - 2005 ivata limited.
003: * All rights reserved.
004: * -----------------------------------------------------------------------------
005: * ivata groupware may be redistributed under the GNU General Public
006: * License as published by the Free Software Foundation;
007: * version 2 of the License.
008: *
009: * These programs are free software; you can redistribute them and/or
010: * modify them under the terms of the GNU General Public License
011: * as published by the Free Software Foundation; version 2 of the License.
012: *
013: * These programs are distributed in the hope that they will be useful,
014: * but WITHOUT ANY WARRANTY; without even the implied warranty of
015: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
016: *
017: * See the GNU General Public License in the file LICENSE.txt for more
018: * details.
019: *
020: * If you would like a copy of the GNU General Public License write to
021: *
022: * Free Software Foundation, Inc.
023: * 59 Temple Place - Suite 330
024: * Boston, MA 02111-1307, USA.
025: *
026: *
027: * To arrange commercial support and licensing, contact ivata at
028: * http://www.ivata.com/contact.jsp
029: * -----------------------------------------------------------------------------
030: * $Log: Mail.java,v $
031: * Revision 1.4 2005/10/11 18:56:03 colinmacleod
032: * Fixed some checkstyle and javadoc issues.
033: *
034: * Revision 1.3 2005/04/10 18:47:42 colinmacleod
035: * Changed i tag to em and b tag to strong.
036: *
037: * Revision 1.2 2005/04/09 17:20:00 colinmacleod
038: * Changed copyright text to GPL v2 explicitly.
039: *
040: * Revision 1.1.1.1 2005/03/10 17:51:13 colinmacleod
041: * Restructured ivata op around Hibernate/PicoContainer.
042: * Renamed ivata groupware.
043: *
044: * Revision 1.5 2004/11/12 18:16:08 colinmacleod
045: * Ordered imports.
046: *
047: * Revision 1.4 2004/11/12 15:57:22 colinmacleod
048: * Removed dependencies on SSLEXT.
049: * Moved Persistence classes to ivata masks.
050: *
051: * Revision 1.3 2004/11/03 17:15:39 colinmacleod
052: * added addUserEmailAddresses method.
053: * Improved setUesrAliases to check telecom addresses in the person.
054: *
055: * Revision 1.2 2004/07/13 19:48:12 colinmacleod
056: * Moved project to POJOs from EJBs.
057: * Applied PicoContainer to services layer (replacing session EJBs).
058: * Applied Hibernate to persistence layer (replacing entity EJBs).
059: *
060: * Revision 1.1 2004/03/27 10:31:26 colinmacleod
061: * Split off business logic from remote facades to POJOs.
062: * -----------------------------------------------------------------------------
063: */
064: package com.ivata.groupware.business.mail;
065:
066: import java.util.Collection;
067: import java.util.List;
068:
069: import com.ivata.groupware.admin.security.server.SecuritySession;
070: import com.ivata.groupware.admin.security.user.UserDO;
071: import com.ivata.groupware.business.drive.file.FileContentDO;
072: import com.ivata.groupware.business.mail.message.MessageDO;
073: import com.ivata.groupware.business.mail.session.MailSession;
074: import com.ivata.mask.util.SystemException;
075: import com.ivata.mask.validation.ValidationErrors;
076:
077: /**
078: * This mail interface provides a common interface to all mail features and
079: * functionality.
080: *
081: * @author Colin MacLeod
082: * <a href='mailto:colin.macleod@ivata.com'>colin.macleod@ivata.com</a>
083: * @since ivata groupware 0.11 (Mar 27, 2004)
084: * @version $Revision: 1.4 $
085: */
086: public interface Mail {
087: /**
088: * Used to identify the message resources bundle related to system mail.
089: */
090: String BUNDLE_PATH = "mail";
091:
092: /**
093: * <p>Add a composed message to the drafts folder for later sending.</p>
094: *
095: * @param mailSession valid mail session to which the user should already be
096: * logged in.
097: * @param messageDO data object containing full details of the
098: * message to be added to the drafts.
099: * @return new <code>MessageDO</code> with the <code>id</code> set to the
100: * current value in the mail system.
101: * @throws SystemException If the message cannot be added for any reason.
102: */
103: MessageDO addMessageToDraftsFolder(final MailSession mailSession,
104: final MessageDO messageDO) throws SystemException;
105:
106: /**
107: * <p>
108: * Add appropriate user addresses given a list of user aliases.
109: * </p>
110: *
111: * @param securitySession valid security session.
112: * @param userName name of the user who owns teh aliases.
113: * @param userAliases a <code>Collection</code> of <code>String</code>
114: * instances containing the local part of the different email aliases
115: * this user has. If the user has no aliaes, an empty collection should
116: * be provided.
117: * @param telecomAddresses a <code>Collection</code> containing all the
118: * user's existing email addresses, as <code>TelecomAddressDO</code>
119: * instances.
120: * @param emailAddressHost Appended to user aliases plus the at sign to
121: * form email addresses.
122: * @throws SystemException If the alias addresses cannot be added for any
123: * reason.
124: */
125: void addUserAliasEmailAddresses(
126: final SecuritySession securitySession,
127: final String userName, final Collection userAliases,
128: final Collection telecomAddresses,
129: final String emailAddressHost) throws SystemException;
130:
131: /**
132: * <p>Append attachments to a message located in the drafts folder.</p>
133: *
134: * @param mailSession valid mail session to which the user should already be
135: * logged in.
136: * @param id the unique identifier of the message to which we want to append
137: * attachments.
138: * @param attachments <code>Vector</code> of <code>String</code>s -
139: * filenames of files waiting in upload directory.
140: * @return <code>null</code> when the operation failed, otherwise the new
141: * message id.
142: * @exception SystemException if the folder doesn't exist, or there
143: * is no matching mail in this folder.
144: */
145: MessageDO appendAttachments(final MailSession mailSession,
146: final String id, final List attachments)
147: throws SystemException;
148:
149: /**
150: * <p>Create a new mail folder.</p>
151: *
152: * @param mailSession valid mail session to which the user should already be
153: * logged in.
154: * @param folderName the full path name of the folder to create.
155: * @throws SystemException If the folder cannot be created.
156: */
157: void createFolder(final MailSession mailSession,
158: final String folderName) throws SystemException;
159:
160: /**
161: * <p>Create a new message in the drafts folder from an existing one,
162: * based on a 'thread'. The thread indicates that the message is a:<br/>
163: * <ul>
164: * <li>reply to all recipients of a previous message</li>
165: * <li>reply to one recipient of a previous message</li>
166: * <li>previous message(s) forwarded to new recipients</li>
167: * <li>an existing (draft) message being altered for resending</li>
168: * </ul></p>
169: *
170: * <p>This new message in the drafts folder can then be used to store
171: * attachments or for reviewing before sending.</p>
172: *
173: * @param mailSession valid mail session to which the user should already be
174: * logged in.
175: * @param folderName the name of the folder to copy existing messages from.
176: * @param messageIds the unique identifier of the messages to be extended.
177: * Can be <code>null</code> if a new message is requeested. When
178: * forwarding, multiple address identifiers may be specified otherwise
179: * (if editing a draft message or replying) only one message identifier
180: * should be set in the list.
181: * @param thread set to one of the constants in {@link MailConstants
182: * MailConstants}.
183: * @return populated message data object matching the required
184: * message, and with the <code>id</code> set to the message in the
185: * drafts folder.
186: * @throws SystemException if the message cannot be created.
187: */
188: MessageDO createThreadMessage(final MailSession mailSession,
189: final String folderName, final List messageIds,
190: final Integer thread) throws SystemException;
191:
192: /**
193: * <p>Delete a list of messages from the trash folder.</p>
194: *
195: * @param mailSession valid mail session to which the user should already be
196: * logged in.
197: * @param ids the unique identifiers (<code>String</code> instances) of the
198: * messages to be removed.
199: * @exception SystemException if the folder doesn't exist, or there
200: * is no matching mail in this folder.
201: */
202: void deleteMessagesFromTrash(final MailSession mailSession,
203: final List ids) throws SystemException;
204:
205: /**
206: * <p>Check whether or not a given folder pathname exists.</p>
207: *
208: * @param mailSession valid mail session to which the user should already be
209: * logged in.
210: * @param folderName the full path name of the folder to check.
211: * @return <code>true</code> if the folder exists,
212: * otherwise <code>false</code>.
213: * @throws SystemException If the information cannot be accessed.
214: */
215: boolean doesFolderExist(final MailSession mailSession,
216: final String folderName) throws SystemException;
217:
218: /**
219: * <p>This method retrieves the requested message and sets all the
220: * attributes of a MessageDO object for use on client side.</p>
221: *
222: * @param mailSession valid mail session to which the user should already be
223: * logged in.
224: * @param folderName the name of the folder the message is located in.
225: * @param id the unique identifier of the message.
226: * @return a MessageDO instance filled up with the messages attributes,
227: * except the contents of the attachments.
228: * @exception SystemException if the folder doesn't exist, or there
229: * is no matching mail in this folder.
230: */
231: MessageDO findMessageByFolderMessageId(
232: final MailSession mailSession, final String folderName,
233: final String id) throws SystemException;
234:
235: /**
236: * <p>Used in the main folder index page, this method returns the contents
237: * of a folder as a <code>Vector</code> of
238: * <code>MessageDO</code> instances.</p>
239: *
240: * <p><strong>Note:</strong> for efficiency reasons, this method does not
241: * fill the text, format or attachment values of the returned
242: * <code>MessageDO</code> instance. For that, you must call
243: * {@link #findMessageByFolderMessageId findMessageByFolderMessageId}.</p>
244: *
245: * @param mailSession valid mail session to which the user should already be
246: * logged in.
247: * @param folderName the name of the folder to list.
248: * @param sortBy the field to sort the returned list by. Set to one of the
249: * <code>SORT_...</code> constants in {@link MailConstants MailConstants}.
250: * @param sortAscending if <code>true</code> then the messages are sorted in
251: * ascending order, otherwise (<code>false</code>) they are descending.
252: * @return <code>List</code> of
253: * <code>MessageDO</code> instances.
254: * @throws SystemException If the message cannot be accessed for any reason.
255: */
256: List findMessagesInFolder(final MailSession mailSession,
257: final String folderName, final Integer sortBy,
258: final boolean sortAscending) throws SystemException;
259:
260: /**
261: * <p>Retrieve an attachment's content and it's MimeType. This method is
262: * used to by the download servlet.</p>
263: *
264: * @param mailSession valid mail session to which the user should already be
265: * logged in.
266: * @param folderName the name of the folder the message is located in.
267: * @param messageId the unique identifier of the message.
268: * @param attachmentId the unique identifier of the attachment.
269: * @return attachment data object containing attachment content
270: * and mime type.
271: * @exception SystemException if the folder doesn't exist, or there
272: * is no matching mail in this folder.
273: */
274: FileContentDO getAttachment(final MailSession mailSession,
275: final String folderName, final String messageId,
276: final String attachmentId) throws SystemException;
277:
278: /**
279: * <p>Get the time the specified mail folder was last modified as a
280: * <code>long</code>. This can then be saved and compared to subsequent
281: * calls of this method to see if the folder has changed.</p>
282: *
283: * @param securitySession Used to authenticate the current site user.
284: * @param userName the name of the user for whom to locate the folder.
285: * @param folderName the name of the folder to locate.
286: * @return operating system specific timestamp indicating when the
287: * folder was last changed.
288: * @throws SystemException If the messages cannot be accessed for any
289: * reason.
290: */
291: boolean hasNewMessages(final SecuritySession securitySession,
292: final String userName, final String folderName)
293: throws SystemException;
294:
295: /**
296: * <p>Retrieve all of the email aliases for the user provided, on the curent
297: * email server. The aliases returned each one containing just the 'user'
298: * (or 'local') part of the email address, before the '@' sign.</p>
299: *
300: * @param securitySession Used to authenticate the current system user.
301: * @param userName the name of the user for whom to retrieve the email
302: * aliases.
303: * @return a <code>List</code> of <code>String</code> instances containing
304: * the local part of the different email aliases this user has. If the user
305: * has no aliaes, an empty collection is returned.
306: * @throws SystemException if the user name is <code>null</code>, or the
307: * aliases cannot be accessed for any reason.
308: */
309: List getUserAliases(final SecuritySession securitySession,
310: final String userName) throws SystemException;
311:
312: /**
313: * <p>Get the vacation message for the user provided.</p>
314: *
315: * <p>The vacation message is a text the user can set, which will be sent
316: * to all emails received at this address while the user is not present.</p>
317: *
318: * @param securitySession Used to authenticate the current system user.
319: * @param userName the name of the user for whom to get the vacation
320: * message.
321: * @return the vacation message text for this user. If the user has no
322: * vacation message set, <code>null</code> is returned.
323: * @throws SystemException If the vacation message cannot be retrieved for
324: * any reason.
325: */
326: String getVacationMessage(final SecuritySession securitySession,
327: final String userName) throws SystemException;
328:
329: /**
330: * <p>Login to the mail system. This method should be called before any
331: * other, to establish the mail session and store.</p>
332: *
333: * @param user The user who should be logged into the system.
334: * @param password The clear-text password to log into the remote system.
335: * @throws SystemException if the person cannot log in for any reason.
336: * @return the mail session (class <code>Session</code>) in a
337: * <code>SessionSerializer</code>.
338: */
339: MailSession login(final UserDO user, final String password)
340: throws SystemException;
341:
342: /**
343: * <p>Move a list of messages from one folder to another.</p>
344: *
345: * @param mailSession valid mail session to which the user should already be
346: * logged in.
347: * @param folderName the name of the folder the messages are currently
348: * located in.
349: * @param ids the unique identifiers (<code>String</code> instances) of the
350: * messages to be moved.
351: * @param targetFolderName the name of the the folder the message will be
352: * moved to.
353: * @exception SystemException if the folder doesn't exist, or there
354: * is no matching mail in this folder.
355: */
356: void moveMessages(final MailSession mailSession,
357: final String folderName, final List ids,
358: final String targetFolderName) throws SystemException;
359:
360: /**
361: * <p>Send a mime email message that is already composed. If <code>id</code>
362: * has been set in <code>messageDO</code> it is assumed to point to a
363: * message in the drafts folder. Attachments are copied from the message
364: * who match the contents of <code>getAttachmentIds</code>. (All other
365: * attachments are discarded.)</p>
366: *
367: * @param mailSession valid mail session to which the user should already be
368: * logged in.
369: * @param messageDO data object containing full details of the
370: * message to be sent.
371: * @throws SystemException If the message cannot be sent for any reason.
372: */
373: void send(final MailSession mailSession, final MessageDO messageDO)
374: throws SystemException;
375:
376: /**
377: * <p>Send an mime email message without using a data object.</p>
378: *
379: * @param mailSession valid mail session to which the user should already be
380: * logged in.
381: * @param fromAddress the address of the person sending the mail. This must
382: * be formatted according to <a
383: * href='http://www.faqs.org/rfcs/rfc822.HTML'>RFC822</a>.
384: * @param to recipients, a <code>Collection</code> containing instances of
385: * <code>String</code> or <code>UserLocal</code> or
386: * <code>PersonLocal</code>. A mixture of these types is allowed. If the
387: * type of an instance is <code>String</code>, then it must be formatted
388: * according to <a href='http://www.faqs.org/rfcs/rfc822.HTML'>RFC822</a>.
389: * Otherwise, if the type is <code>PersonLocal</code>, the method
390: * <code>getEmailAddress</code> must return a valid address string for
391: * this person.
392: * @param subject clear-text email subject field.
393: * @param content any valid email content type, as defined by
394: * <code>MimeMessage</code>.
395: * @param contentType mime type for the <code>content</code> field, as
396: * defined by <code>MimeMessage</code>.
397: * @param addToSentFolder if set to <code>true</code> then the mail is added
398: * to the sent folder of the current email session.
399: * @throws SystemException If the message cannot be sent for any reason.
400: */
401: void send(final MailSession mailSession, final String fromAddress,
402: final Collection to, final String subject, Object content,
403: String contentType, boolean addToSentFolder)
404: throws SystemException;
405:
406: /**
407: * <p>Set all of the email aliases for the user provided, on the curent
408: * email server. Each alias in the collection should contain just the 'user'
409: * (or 'local') part of the email address, before the '@' sign.</p>
410: *
411: * @param securitySession Used to authenticate the current system user.
412: * @param userName the name of the user for whom to retrieve the email
413: * aliases.
414: * @param userAliases a <code>Collection</code> of <code>String</code>
415: * instances containing the local part of the different email aliases
416: * this user has. If the user has no aliaes, an empty collection should
417: * be provided.
418: * @throws SystemException If the aliases cannot be set for any reason.
419: */
420: void setUserAliases(final SecuritySession securitySession,
421: final String userName, final Collection userAliases)
422: throws SystemException;
423:
424: /**
425: * <p>Set the vacation message for the user provided.</p>
426: *
427: * <p>The vacation message is a text the user can set, which will be sent
428: * to all emails received at this address while the user is not present.</p>
429: *
430: * @param securitySession Used to authenticate the current system user.
431: * @param userName the name of the user for whom to get the vacation
432: * message.
433: * @param vacationMessage vacation message text for this user. If the user
434: * has no vacation message set, set to <code>null</code>.
435: * @throws SystemException If the vacation message cannot be set for any
436: * reason.
437: */
438: void setVacationMessage(final SecuritySession securitySession,
439: final String userName, final String vacationMessage)
440: throws SystemException;
441:
442: /**
443: * <p>Confirm all of the elements of the message are present and valid,
444: * before the message is sent.</p>
445: *
446: * @param securitySession Used to authenticate the current system user.
447: * @param messageDO data object to check for consistency and
448: * completeness.
449: * @return a collection of validation errors if any of the
450: * mandatory fields are missing, or if fields contain invalid values.
451: * @throws SystemException If the message is invalid in any way.
452: */
453: ValidationErrors validate(final SecuritySession securitySession,
454: final MessageDO messageDO) throws SystemException;
455: }
|