Re: [xwiki-devs] Future of mailsender plugin

Ok, so I would rather have a component API like - Mail prepareMail(from, to, cc, bcc, subject)

- int sendMail(Mail mail)

while the methods addToContent, addHtml, addAttachment, etc... would be directly used from the Mail class.

So a use-case would rather be : {{velocity}} $mail = $services.mailSender.prepareMail(from, to,...) $mail.addHtml('<p>Blabla</p>')

$mail.addCalendar()

$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 &lt;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 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(&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 some > 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 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 &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 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