I've been thinking a bit more on the mailSender component, and here's the APIs I have in mind : The component API would have the following methods : - void prepareMail(String from, String to, String cc, String bcc, String subject) - void addToContent(String contentType, String content) //To add a part to the mail, contentType being the Mime Type of this part - void addAttachment(Attachment file) - int sendMail() //Returns 1 on success and 0 otherwise And the scripting API would have the following : - void prepareMail(String from, String to, String cc, String bcc, String subject) - void addToContent(String contentType, String content) - void addHtml(String content) - void addCalendar(String vCalendar) - int sendMail() - int sendHtmlMail(String from, String to, String subject, String html, String alternativeText) //Simple method for non-experienced users sending a simple html mail { this.mailSender.prepareMail(from, to, null, null, subject) ; this.mailSender.addToContent("text/html", html) ; this.mailSender.addToContent("text/plain", alternativeText); return this.mailSender.sendMail() ; } So, a simple use-case would look something like : {{velocity}} $services.mailSender.prepareMail("[email protected]", "[email protected]", "", "", "Subject") $services.mailSender.addHtml("<strong>This is an email with a calendar</strong>") $services.mailSender.addCalendar($calendar) $services.mailSender.sendMail() {{/velocity}} What do you think ? Is there anything you think is missing ? In peticular, I'm wondering whether it would be useful to recreate methods similar to the parseRawMessage() and sendMailFromTemplate() methods that were implemented in the former mailSender ? Cheers, Thomas On Thu, Dec 20, 2012 at 7:00 PM, Sergiu Dumitriu <[email protected]> wrote:
On 12/20/2012 06:55 AM, Thomas Delafosse wrote:
Hi all,
I would be happy to work on the mailSender plugin. I propose to make it a component and add it a few functionalities. Namely, I was thinking about adding an API like: public int sendMultiContentMessage (String from, String to, String cc, String bcc, String subject, String[] contents, List<Attachment> attachments) (1)
Methods with too many arguments are not recommended. It even breaks our checkstyle, which allows at most 7 parameters (which I think is too much, anyway). Listing possible mail tokens is bad, since in most cases not all of them are needed, and in some cases others will be needed with no way of specifying them, other than writing the whole message including headers by hand.
Either use a typed object, or a generic map.
where contents would be a string array containing all the contents to be embed in the mail (text, html but also a vCalendar for example) along with their MIME type. So for example, if you want to send a mail containing some html part and a vCalendar, "contents" would look something like : contents = ['text/html', Your Html code, 'text/calendar', Your vCalendar] .
This is an untyped convention. You're hoping that all users will read the documentation and know that they're supposed to provide pairs of values, MIME + content. That's not a nice thing to do. A list of typed objects would be better, since it doesn't allow mistakes.
Another way to achieve this would be to use a single String "body" instead of "contents", with a specific syntax indicating each part MIME type, thus allowing us to parse it. For example we could imagine having something like : public int sendMultiContentMessage (String from, String to, String cc, String bcc, String subject, String body, List<Attachment> attachments) with body = "{{html}}HTML code{{/html}} {{calendar}}Calendar code{{/calendar}}" (2) or even body = "{{mailPart type='text/html'}}HTML code{{/mailPart}} {{mailPart type="text/calendar"}}Calendar code{{/mailPart}}" (3). This would be easier to use ((2) most of all), but probably trickier, slower and for (2), less flexible.
I don't like this either, it's even more error prone.
Java is an OOP language, use good OOP design as much as possible.
WDYT ? And of course, if there is anything else you would like to change in the mailSender, let me know !
Thomas
-- Sergiu Dumitriu http://purl.org/net/sergiu _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs