01: /*
02: * Copyright 2001-2007 Geert Bevin <gbevin[remove] at uwyn dot com>
03: * Distributed under the terms of either:
04: * - the common development and distribution license (CDDL), v1.0; or
05: * - the GNU Lesser General Public License, v2.1 or later
06: * $Id: MailQueueManager.java 3634 2007-01-08 21:42:24Z gbevin $
07: */
08: package com.uwyn.rife.mail;
09:
10: import com.uwyn.rife.mail.Email;
11: import com.uwyn.rife.mail.exceptions.MailQueueManagerException;
12: import javax.mail.internet.MimeMessage;
13:
14: /**
15: * This interface defines the methods that classes with
16: * <code>MailQueueManager</code> functionalities have to implement.
17: * <p>A <code>MailQueueManager</code> provides methods that allow you to store
18: * email messages in a queue. That queue is intended to be processed at
19: * regular intervals by a <code>MailQueueExecutor</code>.
20: *
21: * @author Geert Bevin (gbevin[remove] at uwyn dot com)
22: * @version $Revision: 3634 $
23: * @see com.uwyn.rife.mail.MailQueueExecutor
24: * @since 1.0
25: */
26: public interface MailQueueManager {
27: /**
28: * Adds the provided email to the queue. If an identical mail is
29: * already present or any other validation for the <code>Email</code>
30: * instance fails, the data will not be added to the queue.
31: * <p>Details about the failure can be obtained throught the
32: * <code>ValidationError</code>s of the <code>Email</code> instance.
33: *
34: * @param email The <code>Email</code> instance that needs to be
35: * queued.
36: * @return <code>true</code> if the email was successfully queued; or
37: * <p><code>false</code> if an email validation failed (for instance a
38: * duplicate entry)
39: * @exception MailQueueManagerException If an error occurred while
40: * adding the email to the queue
41: * @see #queue(MimeMessage)
42: * @since 1.0
43: */
44: public boolean queue(Email email) throws MailQueueManagerException;
45:
46: /**
47: * Adds a fully setup JavaMail email to the queue. The presence of identical
48: * mails can not be detected due to the fact that each message already contains
49: * a unique message ID. Duplicates with thus be sent as many times as they are
50: * added.
51: * <p>This complements the quick way of adding Email instances by providing
52: * a way to queue even HTML emails, mails with attachments, etc ...
53: *
54: * @param email The <code>MimeMessage</code> instance that needs to be
55: * queued.
56: * @return <code>true</code> if the email was successfully queued; or
57: * <p><code>false</code> otherwise
58: * @exception MailQueueManagerException If an error occurred while
59: * adding the email to the queue
60: * @see #queue(Email)
61: * @since 1.0
62: */
63: public boolean queue(MimeMessage email)
64: throws MailQueueManagerException;
65: }
|