Re: [xwiki-devs] Future of mailsender plugin

On Wed, Dec 26, 2012 at 3:23 PM, Vincent Massol <vincent(a)massol.net>

> > On Dec 26, 2012, at 3:15 PM, Thomas Delafosse <

> wrote: > >> Ok, so I would rather have a component API like >> >> - Mail prepareMail(from, to, cc, bcc, subject) > > createMail is better than prepareMail IMO. > > I'd make the cc and bcc not part of the constructor and instead move

> as setters since they're optional. > >> - int sendMail(Mail mail) > > Either that or add a send() method in Mail.

addToContent (String mimeType, String partToAdd) is more generic : you specify the Mime Type of the part you want to add. So addHtml(String s)

just the same as addToContent("text/html", s). But as most of the time

add only Html or text, I was thinking it was better to have a specific method to add an Html part in the scripting API. I can do the same with a addTextContent method.

Yes, so for example if you want to have an email with an html part and a calendar part, you call addToContent("text/html", html Text) and then addToContent("text/calendar", calendar Code). It is either a vCalendar or an iCalendar (it is used by Gmail to send invitations). It corresponds to the Mime Type "text/calendar". Here again addCalendar(String calendar) is just the same as addToContent("text/calendar", calendar). It's just to make it easier to use.

On Java it would give something like : @Inject private MailSender mailSender Mail mail = this.mailSender.newMail(from,to,subject) ;

String htmlCode = "<p>Blabla</p>" ; String calendar = "BEGIN VCALENDAR... END VCALENDAR" ; mail.addToContent("text/html", htmlCode) ; mail.addToContent("text/calendar", calendar) ; this.mailSender.sendMail(mail) ;

> Thanks > -Vincent > >> $services.mailSender.sendMail($mail) >> {{/velocity}} >> >> Thanks, >> >> Thomas >> >> On Wed, Dec 26, 2012 at 3:04 PM, Vincent Massol &lt;vincent(a)massol.net&gt; > wrote: >> >>> Hi Thomas, >>> >>> On Dec 26, 2012, at 2:58 PM, Thomas Delafosse < > thomas.delafosse(a)xwiki.com&gt; >>> wrote: >>> >>>> 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

>>>> 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(&quot;foo(a)bar.fr&quot;r.fr", &quot;foo2(a)bar.fr&quot;r.fr", "",

>>>> "Subject") >>>> $services.mailSender.addHtml("<strong>This is an email with a >>>> calendar</strong>") >>>> $services.mailSender.addCalendar($calendar) >>>> $services.mailSender.sendMail() >>>> {{/velocity}} >>> >>> This is not very good because you're making the service stateful and >>> services mist absolutely be stateless. They need to be able to be used > by >>> several threads and not hold any state. Your API calls must return

>>> object if you want to have several calls. >>> >>> Thanks >>> -Vincent >>> >>>> >>>> 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

>>> 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 &lt;sergiu(a)xwiki.org&gt; >>> 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

>>> be >>>>>> embed in the mail (text, html but also a vCalendar for example)

>>>>> with >>>>>> their MIME type. >>>>>> So for example, if you want to send a mail containing some html

>>> 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

>>>>> 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

>>>>> 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

>>>>> 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

>>>>>> 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